🌊 LiqUIdify

Production-ready React component library with 100% Apple Human Interface Guidelines compliance. iOS 17 / macOS 14 calibrated design tokens • 48 accessible components • WCAG 2.1 AA certified

Website • Documentation • npm Package • GitHub

---

Why LiqUIdify?

LiqUIdify is the only React component library calibrated to Apple's exact iOS 17 and macOS 14 design standards. While Material UI, Chakra UI, and Radix UI offer excellent components, none are built specifically for Apple-quality web applications.

Feature	LiqUIdify	Material UI	Chakra UI	Radix UI
Apple HIG Compliance	✅ 100%	❌ Material Design	❌ Custom System	❌ Unstyled
iOS 17/macOS 14 Calibrated	✅ Exact values	❌	❌	❌
44px Touch Targets	✅ HIG Standard	⚠️ Varies	⚠️ Varies	⚠️ Unstyled
Spring Animations	✅ Apple physics	⚠️ Custom	⚠️ Custom	❌ None
Elevation System	✅ 6-level (iOS)	⚠️ Material	⚠️ Custom	❌ None
Reduced Motion	✅ Full support	⚠️ Partial	⚠️ Partial	❌ None
Liquid Glass Effects	✅ Native-like blur	❌	❌	❌
WCAG 2.1 AA	✅ Certified	✅	✅	⚠️ Varies

Choose LiqUIdify if:

• You're building for Apple platforms (iOS, macOS, iPadOS, visionOS web experiences)
• You need pixel-perfect alignment with Apple's design language
• You want users to feel native quality in web apps
• You require production-ready accessibility out of the box

---

✨ Features

🍎 100% Apple HIG Compliance

Every component, animation, and interaction follows Apple's Human Interface Guidelines exactly. Not "inspired by"—compliant with.

• iOS 17 Animation System: Spring physics (mass: 1, stiffness: 180, damping: 20) with Apple-standard timing (0.15s instant, 0.3s quick, 0.5s flow, 0.6s bounce)
• macOS 14 Elevation: 6-level shadow system (0dp → 24dp) matching iOS depth standards
• Touch Targets: All interactive elements meet 44×44pt minimum (Apple HIG requirement)
• Border Radii: iOS 17 calibrated (16px cards, 10px controls, 12px fields)
• SF Pro Typography: Complete dynamic type scale (caption2 → largeTitle) with HIG-exact line heights

♿ WCAG 2.1 AA Accessibility

Production-ready accessibility with zero configuration required.

• 4.5:1 contrast for body text, 3:1 for large text and UI components
• Keyboard navigation with visible focus states on all interactive elements
• Screen reader optimized with proper ARIA labels and live regions
• Reduced motion support via prefers-reduced-motion (all animations disabled or instant)
• High contrast mode via prefers-contrast (enhanced borders and text)
• Reduced transparency support for users with vestibular disorders

🚀 Production-Ready

Battle-tested with enterprise-grade quality.

• 48 Components: Forms, navigation, feedback, advanced interactions
• TypeScript-first: Complete type safety with auto-completion
• Tree-shakeable: Subpath imports minimize bundle size (base: 28KB gzipped)
• Zero runtime errors: Comprehensive test coverage with Vitest
• SSR/RSC safe: Works with Next.js, Remix, and all React frameworks
• Peer dependencies: React, Ark UI, Framer Motion kept as peers to prevent duplicates

🎨 Liquid Glass Design System

Apple's signature visual language adapted for web.

• Glassmorphism effects: Native-like blur with backdrop-filter
• Dynamic accent colors: Runtime theming with CSS custom properties
• Vibrancy modes: Light and dark themes with automatic color adaptation
• Responsive tokens: Design scales beautifully from mobile to desktop
• Panda CSS integration: Atomic styles with recipes for customization

⚡ Performance Optimized

Fast by default with modern build tooling.

• 433KB CSS (base stylesheet, includes all tokens and resets)
• 28KB JS (tree-shaken main bundle, gzipped)
• Subpath imports: import { Button } from "liquidify-react/button" for granular control
• No global CSS conflicts: Panda CSS generates scoped atomic classes
• Lazy-loadable: Import components on-demand for code-splitting

---

🚀 Quick Start

Installation

Install LiqUIdify and peer dependencies in one command:

# Bun (recommended)
bun add liquidify-react react react-dom @ark-ui/react framer-motion lucide-react

# npm
npm install liquidify-react react react-dom @ark-ui/react framer-motion lucide-react

# yarn
yarn add liquidify-react react react-dom @ark-ui/react framer-motion lucide-react

# pnpm
pnpm add liquidify-react react react-dom @ark-ui/react framer-motion lucide-react

Zero-Config Usage

Import the CSS once at your app entry point, then use components immediately:

// main.tsx or App.tsx (import CSS once)
import "liquidify-react/styles";
import { Button, Card, Switch } from "liquidify-react";

function App() {
  return (
    <Card css={{ padding: "24px", maxWidth: "400px" }}>
      <h1>Welcome to LiqUIdify</h1>
      <p>100% Apple HIG compliant components, zero configuration.</p>
      <Button variant="filled" tone="accent">
        Get Started
      </Button>
    </Card>
  );
}

export default App;

💡 CSS Import Required: The "liquidify-react/styles" import loads design tokens, resets, and base styles. Import it once at your app root.

Tree-Shaking (Optimize Bundle Size)

Use subpath imports for granular control:

import { Button } from "liquidify-react/button";
import { Card } from "liquidify-react/card";
// Only Button and Card code is bundled

Dynamic Theming

Add runtime theme and accent color control with ThemeProvider:

import "liquidify-react/styles";
import { ThemeProvider, useTheme, Button } from "liquidify-react";

function ThemeToggle() {
  const { theme, setTheme, accent, setAccent } = useTheme();

  return (
    <div>
      <Button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
        Toggle {theme === "dark" ? "Light" : "Dark"} Mode
      </Button>
      <Button onClick={() => setAccent("#34C759")}>
        Switch to Mint Accent
      </Button>
    </div>
  );
}

export default function App() {
  return (
    <ThemeProvider defaultTheme="light" defaultAccent="#007AFF">
      <ThemeToggle />
    </ThemeProvider>
  );
}

Accent color formats:

• Hex: #007AFF, #34C759
• RGB: rgb(0, 122, 255)
• HSL: hsl(211, 100%, 50%)
• OKLCH: oklch(62% 0.2 236) (recommended for perceptual uniformity)
• CSS variables: var(--brand-accent)

Ark UI Components (Advanced Primitives)

LiqUIdify includes 47+ Ark UI headless components for complex interactions. Import them via nested paths:

// ESM imports
import * as Dialog from "liquidify-react/ark-ui/dialog";
import * as Tooltip from "liquidify-react/ark-ui/tooltip";
import * as Select from "liquidify-react/ark-ui/select";
import * as DatePicker from "liquidify-react/ark-ui/datePicker";

// CJS requires (also supported)
const Accordion = require("liquidify-react/ark-ui/accordion");
const Carousel = require("liquidify-react/ark-ui/carousel");

Available Ark UI components (all with TypeScript types):

• Form controls: checkbox, switch, radioGroup, select, combobox, slider
• Input helpers: datePicker, colorPicker, fileUpload, pinInput, tagsInput
• Navigation: tabs, menu, pagination, steps, carousel
• Overlays: dialog, popover, tooltip, hoverCard, toast
• Containers: accordion, collapsible, splitter, treeView
• Feedback: progress, progressCircular, progressLinear, ratingGroup
• Advanced: signaturePad, qrCode, timer, tour, clipboard

Button Component API

The Button component supports Apple HIG-compliant variants and tones:

import { Button } from "liquidify-react";

// Variants (visual weight)
<Button variant="filled">Primary Action</Button>    // Solid background
<Button variant="tinted">Secondary Action</Button> // Subtle background
<Button variant="plain">Tertiary Action</Button>   // Transparent

// Tones (semantic meaning)
<Button tone="accent">Save</Button>          // Blue (default)
<Button tone="neutral">Cancel</Button>       // Gray
<Button tone="destructive">Delete</Button>   // Red

// Combining variant + tone
<Button variant="filled" tone="destructive">Delete Forever</Button>
<Button variant="tinted" tone="accent">Enable Feature</Button>
<Button variant="plain" tone="neutral">Learn More</Button>

// Sizes (all meet 44px minimum touch target)
<Button size="compact">Compact</Button>   // 44px height
<Button size="regular">Regular</Button>   // 44px height (default)
<Button size="large">Large</Button>       // 52px height

// States
<Button disabled>Disabled</Button>
<Button loading>Processing...</Button>

// Icons
<Button icon={<CheckIcon />} iconPosition="start">
  Confirm
</Button>
<Button icon={<TrashIcon />} aria-label="Delete" /> {/* Icon-only */}

// Polymorphic (renders as different elements)
<Button as="a" href="/docs">Documentation</Button>
<Button as={Link} to="/home">Home</Button>

Legacy variant mapping (for backward compatibility):

• primary → filled + accent
• secondary → tinted + neutral
• ghost → plain + neutral
• danger → filled + destructive

---

🏗️ Architecture

Design Tokens (iOS 17 / macOS 14 Calibrated)

LiqUIdify's design system is calibrated to Apple's exact iOS 17 and macOS 14 specifications:

// Animation durations (Apple HIG standard)
durations: {
  instant: "0.15s",  // Tooltips, switches, immediate feedback
  quick: "0.3s",     // Standard transitions, buttons, tabs
  flow: "0.5s",      // Sheets, modals, page transitions
  bounce: "0.6s"     // Playful spring physics elements
}

// Spring animation physics (Apple standard)
spring: {
  mass: 1,
  stiffness: 180,
  damping: 20
}

// Elevation system (iOS 17 shadows)
elevation: {
  0: "none",                                    // Flat surfaces
  1: "0 1px 2px rgba(0,0,0,0.06), ...",        // Base elevation
  4: "0 4px 12px rgba(0,0,0,0.08), ...",       // Raised elements
  8: "0 8px 24px rgba(0,0,0,0.12), ...",       // Floating panels
  16: "0 16px 32px rgba(0,0,0,0.16), ...",     // Modals
  24: "0 24px 48px rgba(0,0,0,0.20), ..."      // Priority overlays
}

// Border radii (iOS 17 roles)
radii: {
  button: "9999px",     // Full capsule
  buttonCompact: "10px",
  control: "10px",      // Switches, checkboxes
  field: "12px",        // Input fields
  card: "16px",         // Cards and surfaces
  sheet: "16px",        // Modals and sheets
  pill: "9999px"        // Badges and tags
}

// Touch targets (Apple HIG requirement)
minTouchTarget: "44px"  // All interactive elements

Animation System

All animations respect user preferences and follow Apple's motion guidelines:

// Reduced motion compliance
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

// Standard button interaction
button: {
  transition: "all 0.3s cubic-bezier(0.25, 0.1, 0.25, 1.0)",
  _hover: { transform: "scale(1.02)" },    // Subtle growth
  _active: { transform: "scale(0.97)" }    // Press feedback
}

// Modal entrance
modal: {
  animation: "slideUp 0.5s cubic-bezier(0.25, 0.1, 0.25, 1.0)"
}

Component Architecture

• Headless primitives: Powered by Ark UI for robust, accessible behavior
• Style recipes: Panda CSS recipes attach atomic styles at runtime
• Composition: All components expose slots for deep customization
• Type safety: Full TypeScript support with generics where needed

---

📚 Components (48 Total)

Forms & Inputs (15)

Button • IconButton • Checkbox • RadioGroup • Switch • Slider • AngleSlider • NumberInput • PasswordInput • PinInput • TagsInput • Select • Combobox • DatePicker • FileUpload

Navigation & Layout (7)

Tabs • Accordion • Collapsible • Menu • Pagination • Steps • Splitter

Feedback & Display (13)

Toast • Dialog • Modal • Popover • Tooltip • HoverCard • Progress (Linear/Circular) • Avatar • Badge • Card • ScrollArea • FloatingPanel • SymbolTile

Advanced (13)

TreeView • ColorPicker • SignaturePad • Carousel • RatingGroup • SegmentGroup • Toggle • ToggleGroup • QRCode • Timer • Tour • Editable • Clipboard

→ View all components with live examples

---

🎨 Theming & Customization

CSS Custom Properties

Override design tokens globally:

:root {
  /* Accent color */
  --ui-accent: #34C759;  /* Mint green */

  /* Border radii */
  --radii-card: 20px;

  /* Animation durations */
  --durations-quick: 0.2s;

  /* Elevation */
  --shadows-elevation-4: 0 4px 16px rgba(0,0,0,0.1);
}

Panda CSS Integration

Extend styles with Panda CSS recipes:

import { css } from "liquidify-react/css";
import { Button } from "liquidify-react";

const customButton = css({
  background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
  _hover: { boxShadow: "0 8px 24px rgba(102,126,234,0.4)" }
});

<Button className={customButton}>Custom Styled</Button>

Component Slots

Customize specific parts of components:

<Select.Root>
  <Select.Trigger css={{ borderRadius: "20px", padding: "12px 20px" }}>
    <Select.Value />
  </Select.Trigger>
  <Select.Content css={{ background: "rgba(255,255,255,0.95)" }}>
    {/* options */}
  </Select.Content>
</Select.Root>

---

⚡ Performance

Bundle Sizes (Measured)

• Base CSS: 433KB (includes all tokens, resets, and component styles)
• Main JS: 28KB (gzipped, tree-shaken)
• Individual component: ~2-5KB (when using subpath imports)

Tree-Shaking Effectiveness

// Full import: ~28KB (all 48 components)
import { Button, Card, Switch } from "liquidify-react";

// Subpath import: ~6KB (only what you use)
import { Button } from "liquidify-react/button";
import { Card } from "liquidify-react/card";
import { Switch } from "liquidify-react/switch";

Performance Best Practices

1. Use subpath imports for production builds
2. Import CSS once at app root (not per-component)
3. Leverage code-splitting with dynamic imports for large component sets
4. Enable Brotli compression on your server (reduces CSS to ~40KB)

---

🧪 Framework Compatibility

Vite

// main.tsx
import "liquidify-react/styles";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(<App />);

Next.js (App Router)

// app/layout.tsx
import "liquidify-react/styles";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Remix

// app/root.tsx
import liquidifyStyles from "liquidify-react/styles?url";

export const links = () => [
  { rel: "stylesheet", href: liquidifyStyles }
];

SSR/RSC Safety: LiqUIdify has no window access at import time. All components render safely on the server.

---

🛠️ Development

Local Setup

# Clone repository
git clone https://github.com/tuliopc23/LiqUIdify.git
cd LiqUIdify

# Install dependencies
bun install

# Build library
bun run build:lib

# Run type checking
bun run type-check

# Run tests
bun test --run

# Run linting
bun run lint

Scripts

• bun run dev - Start development server
• bun run build:lib - Build library to libs/components/dist
• bun run type-check - TypeScript compilation check
• bun run lint - Biome linting and formatting
• bun run test - Run Vitest test suite
• bun run prepublishOnly - Pre-publish validation (type-check + build)

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting PRs.

Development Process

1. Fork the repository and create a feature branch
2. Make your changes following our code style (Biome)
3. Add tests for new functionality
4. Update documentation if needed
5. Submit a PR with a clear description

Community

• GitHub Discussions: Ask questions, share ideas
• Issues: Report bugs or request features
• Discord: Join our community (coming soon)

---

📖 Resources

• 🌐 Website - Landing page and showcase
• 📚 Documentation - Complete API reference and guides
• 📦 npm Package - Install instructions
• 🛠️ GitHub Repository - Source code
• 🐛 Issues & Feedback - Bug reports and feature requests
• 📝 Changelog - Release history
• 🍎 Apple HIG - Design guidelines reference

---

📄 License

MIT © Tulio Pinheiro Cunha

---

💚 Sponsorship

LiqUIdify is open source and free to use. If you're using it in production, consider sponsoring development to support continued maintenance and new features.

---

Built with ♥︎ for the Apple ecosystem