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 • Landing Page

---

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