Apple Creative Design System

A comprehensive design system inspired by macOS, iOS, and VisionOS

Built with Framer Motion + Radix UI + Tailwind CSS

Installation • CLI • Components • Versioning • Storybook

Installation

npm install -D @smart-coder-labs/apple-design-system

CLI

The design system ships with a CLI inspired by shadcn/ui — it copies component source code directly into your project instead of importing a black-box package. You own the code.

init

Detects your framework automatically and sets up design-system.json.

npx @smart-coder-labs/apple-design-system init

Apple Design System — Initialization

Detected framework: Next.js (App Router — RSC enabled)
Is this correct? › Yes

Where to install components? › ./src/components/ui
Global CSS file path? › ./src/index.css
Install required dependencies now? › Yes

Supported frameworks: Next.js (App Router and Pages Router), Vite, Astro, Remix / React Router.

Configuration is saved to design-system.json:

{
  "framework": "next",
  "rsc": true,
  "componentsDir": "./src/components/ui",
  "globalCss": "./src/index.css",
  "components": {}
}

rsc: true — Next.js App Router. Components keep 'use client'. rsc: false — Vite, Astro, Remix, Pages Router. 'use client' is stripped automatically.

add

Adds one or more components. Resolves inter-component dependencies automatically.

npx @smart-coder-labs/apple-design-system add Button Card

Running without arguments opens an interactive selector (install all or pick specific ones).

After install, design-system.json tracks each component with its version and full history:

{
  "components": {
    "Button": {
      "version": "1.1.0",
      "status": "stable",
      "type": "folder",
      "installedAt": "2025-05-10T12:00:00.000Z",
      "updatedAt": "2025-05-17T09:30:00.000Z",
      "history": [
        { "version": "1.0.0", "action": "install", "date": "2025-05-10T12:00:00.000Z" },
        { "version": "1.1.0", "action": "update",  "date": "2025-05-17T09:30:00.000Z" }
      ]
    }
  }
}

update

Updates installed components to the latest version from the registry.

npx @smart-coder-labs/apple-design-system update
npx @smart-coder-labs/apple-design-system update Button Card

rollback

Rolls back a component to any previously published version. Uses the exact git SHA recorded in the registry — no manual tagging required.

npx @smart-coder-labs/apple-design-system rollback Button 1.0.0

The CLI reads the version history from the registry, finds the git SHA for that version, and fetches the component files from that specific commit.

status

Shows installed components, their versions, and whether they are outdated.

# Overview table for all tracked components
npx @smart-coder-labs/apple-design-system status

# Full detail for one component
npx @smart-coder-labs/apple-design-system status Button

Table output:

Registry version: 1.3.1

Component                            Installed    Latest       Status        Outdated
────────────────────────────────────────────────────────────────────────────────────
Button                               1.0.0        1.1.0        stable        yes
Card                                 1.1.0        1.1.0        stable        no
AnimatedCounter                      1.0.0        1.0.0        beta          no

Detail output:

Button
  Installed version : 1.0.0
  Registry version  : 1.1.0
  Status            : stable
  Installed at      : 2025-05-10T12:00:00.000Z
  Last updated      : 2025-05-10T12:00:00.000Z
  History:
    install   v1.0.0  2025-05-10T12:00:00.000Z

Component Architecture

Each component lives in its own folder under components/ui/:

components/ui/
└── Button/
    ├── Button.tsx          # Component implementation
    ├── Button.types.ts     # TypeScript interfaces and types
    ├── Button.styles.ts    # Tailwind variant definitions
    ├── index.ts            # Barrel export
    └── CHANGELOG.md        # Per-component changelog

This structure means:

• You import from @/components/ui/Button — clean, no deep paths
• Each file has a single responsibility
• Types are co-located and always up to date
• You can edit any piece without touching the others

Component Versioning

Each component in the registry is versioned independently from the CLI package. A change to Button only bumps Button's version — untouched components stay at their current version.

Registry schema

{
  "Button": {
    "version": "1.1.0",
    "status": "stable",
    "added": "1.0.0",
    "breakingChanges": [],
    "history": [
      { "version": "1.0.0", "sha": "abc123f", "files": ["Button.tsx", "Button.types.ts", "Button.styles.ts", "index.ts"] },
      { "version": "1.1.0", "sha": "d9f3a12", "files": ["Button.tsx", "Button.types.ts", "Button.styles.ts", "index.ts"] }
    ],
    "dependencies": ["framer-motion"],
    "files": [...]
  }
}

Stability tags

| Status | Meaning | |--------|---------| | stable | Production-ready. Breaking changes are documented. | | beta | Functional but API may have minor changes. | | experimental | New feature under active development. |

Automatic version bumps

The registry is updated automatically on every push to main via GitHub Actions. The bump type is derived from the commit message using Conventional Commits:

| Commit type | Bump | |-------------|------| | fix:, chore:, refactor: | patch — 1.0.0 → 1.0.1 | | feat: | minor — 1.0.0 → 1.1.0 | | feat!: or BREAKING CHANGE in body | major — 1.0.0 → 2.0.0 |

Only components whose files changed in that commit are bumped.

Quick Start

# 1. Initialize your project
npx @smart-coder-labs/apple-design-system init

# 2. Add components
npx @smart-coder-labs/apple-design-system add Button Card Modal

# 3. Use them

import { Button } from "@/components/ui/Button";
import { Card, CardHeader, CardContent } from "@/components/ui/Card";

function App() {
  return (
    <Card variant="glass" hoverable>
      <CardHeader>Getting started</CardHeader>
      <CardContent>
        <Button variant="primary">Click me</Button>
      </CardContent>
    </Card>
  );
}

Components

214 components across all UI categories. A few highlights:

| Component | Description | Notes | |-----------|-------------|-------| | Button | Animated buttons | 4 variants, loading state | | Card | Glass and elevated cards | Compound component | | Modal | VisionOS-style dialogs | Backdrop blur, spring animation | | DataGrid | Advanced table with filters | TanStack Table | | Command | CMD+K command palette | CMDK | | Kanban | Drag-and-drop board | Dnd Kit | | Calendar | Full calendar | React Day Picker | | SearchInput | Search with dropdown | Compound component | | Tabs | iOS segmented control | Framer Motion | | Switch | iOS toggle with spring | Framer Motion |

All 214 components are documented in Storybook with interactive examples.

View all components in Storybook →

Tailwind Setup

The package exports a Tailwind preset that must be included in consuming projects:

// tailwind.config.js
import preset from '@smart-coder-labs/apple-design-system/tailwind.preset';

export default {
  presets: [preset],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@smart-coder-labs/apple-design-system/dist/**/*.js',
  ],
};

Dark Mode

const [dark, setDark] = useState(false);

useEffect(() => {
  document.documentElement.classList.toggle('dark', dark);
}, [dark]);

<Switch checked={dark} onCheckedChange={setDark} label="Dark Mode" />

All components adapt automatically via Tailwind's dark: classes and design tokens.

Accessibility

• WCAG 2.1 AA
• Full keyboard navigation
• Visible focus indicators
• ARIA labels throughout
• Touch targets 40×40px minimum
• Built on Radix UI primitives

Migration

From v1.0.2 or earlier

From v1.0.3, the Tailwind preset is required. Update your config as shown in Tailwind Setup and reinstall:

npm install -D @smart-coder-labs/apple-design-system@latest

Full migration guide →

License

MIT © 2025