motion-ui-skill 2.0.0

package/references/guides/style-presets.md

@@ -0,0 +1,115 @@
+---
+title: "Multi-Style Presets & Aesthetic Themes Guide"
+description: "Architecture and guidelines for AI agents to select, switch, and apply shared design tokens across components."
+category: "Design Systems"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/guides/style-presets.md"
+markdown: "references/guides/style-presets.md"
+license: "MIT"
+---
+
+# Multi-Style Presets & Aesthetic Themes
+
+> Architecture and guidelines for AI agents to select, switch, and apply shared design tokens across components in this skill.
+
+Modern web and mobile applications span dramatically different visual aesthetics. Rather than forcing a single rigid look, the Motion UI Skill equips agents with **6 Canonical Style Presets**:
+
+1. **`minimal`** — Clean, flat monochrome, crisp 1px borders, subtle hover transitions (inspired by *shadcn/ui* and *Linear*).
+2. **`origin`** — High-craft, micro-elevation, subtle specular inner borders, precision focus rings, dark-mode luxury (inspired by *Coss* and *Cal.com*).
+3. **`enterprise`** — High information density, compact spacing, clear semantic contrast, sharp geometry, data-heavy (inspired by *KeenThemes ReUI*).
+4. **`glow`** — Luminous radial gradient halos, spotlight cursor highlights, dark ambient glass, metallic beams (inspired by *ibelick/ui-skills*).
+5. **`ios`** — Deep rounded squircle curves (`rounded-2xl` to `rounded-3xl`), translucent blurred glass (`backdrop-blur-2xl`), tactile spring bounce, haptic vibrations (inspired by *Expo* and *Apple iOS*).
+6. **`brutalist`** — Bold 2px/3px black outlines, high-contrast flat fills, hard 4px offset drop-shadows, tactile press translations (Neo-brutalist aesthetic).
+
+---
+
+## The Style Tokens Architecture (`lib/styles.ts`)
+
+Every preset is formalized into reusable Tailwind utility tokens and spring physics configurations:
+
+```ts
+import { STYLE_PRESETS, getStylePreset, type StylePreset } from "@/lib/styles";
+
+const tokens = getStylePreset("origin");
+// tokens.card          -> Card surface classes
+// tokens.buttonPrimary -> Primary action button classes
+// tokens.input         -> Text/search field classes
+// tokens.badge         -> Status badge classes
+// tokens.panel         -> Modal/drawer/popover container classes
+// tokens.radius        -> Corner rounding token
+// tokens.spring        -> Corresponding Motion spring curve
+```
+
+---
+
+## Visual Comparison of the 6 Styles
+
+| Style Preset | Border & Geometry | Surface & Lighting | Shadows & Elevation | Motion Physics | Target Archetype |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **`minimal`** | `border-border`, `rounded-xl` | Flat `bg-card`, monochrome | `shadow-none` / `shadow-sm` | `SPRING_PRESS` (stiff) | Minimalist SaaS, developer tools |
+| **`origin`** | `border-border/70`, `rounded-2xl`, `ring-1 ring-white/5` | Gradient `from-card to-card/90`, glass | Refined micro-shadows | `SPRING_SNAPPY` (velocity) | Cal.com, Stripe, high-craft web apps |
+| **`enterprise`** | `border-border`, `rounded-md`, compact | High contrast, clear cells | Minimal shadow | `SPRING_PRESS` (subtle) | ReUI dashboards, ERP, CRM, data grids |
+| **`glow`** | `border-border/60`, `rounded-2xl` | Radial gradient spotlights, cyan/indigo | `shadow-2xl`, glow blooms | `SPRING_GENTLE` (smooth) | Web3, AI platforms, luxury landing pages |
+| **`ios`** | `border-white/10`, `rounded-3xl` | Translucent glass `backdrop-blur-2xl` | Diffuse ambient soft shadows | `SPRING_BOUNCE` (playful) | Expo mobile apps, consumer iOS PWAs |
+| **`brutalist`** | `border-2 border-foreground`, `rounded-none` | High contrast flat fills, saturated accents | Hard offset `shadow-[4px_4px_0px_0px_currentColor]` | Snappy step transitions | Creative studios, modern editorial, web zines |
+
+---
+
+## How AI Agents Should Select Styles
+
+When generating UI code or answering user prompts, follow these decision heuristics:
+
+### Step 1: Detect User Aesthetic Preference
+- If the user specifies an aesthetic (e.g. *"make it look like Apple"*, *"make a high-craft Stripe/Cal.com interface"*, *"make a compact admin dashboard"*, *"make a cyber glow look"*), map immediately to the preset:
+  - *"Apple / Mobile / Expo"* $\rightarrow$ **`ios`**
+  - *"Stripe / Linear / Cal.com / High Craft"* $\rightarrow$ **`origin`**
+  - *"Shadcn / Minimal / Clean"* $\rightarrow$ **`minimal`**
+  - *"KeenThemes / ReUI / Enterprise / Compact / Admin"* $\rightarrow$ **`enterprise`**
+  - *"Glow / Cyber / Dark Modern / Spotlight"* $\rightarrow$ **`glow`**
+  - *"Retro / Brutalist / Bold / Outline"* $\rightarrow$ **`brutalist`**
+
+### Step 2: If Unspecified, Ask or Default Wisely
+- Default for web apps: **`origin`** (balanced high-craft, works in both dark and light mode).
+- Default for mobile / touch-first: **`ios`**.
+- Default for heavy data tables / Gantt / Kanban: **`enterprise`**.
+
+### Step 3: Implement with Style Preset Props or Utility Tokens
+`MetricCard` accepts a `stylePreset` prop directly. Other components can consume the shared tokens in a wrapper:
+
+```tsx
+<MetricCard
+  title="Monthly Recurring Revenue"
+  value="$48,250"
+  change="+14.2%"
+  stylePreset="origin"
+/>
+```
+
+Or consume `STYLE_PRESETS` in custom wrappers:
+
+```tsx
+import { STYLE_PRESETS, type StylePreset } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+export function CustomCard({ stylePreset = "origin", children }: { stylePreset?: StylePreset; children: React.ReactNode }) {
+  const tokens = STYLE_PRESETS[stylePreset];
+  return <div className={cn(tokens.card)}>{children}</div>;
+}
+```
+
+---
+
+## CLI Style Flag
+
+The CLI component installer supports explicit style selection:
+
+The selected value is reported for the agent and the shared `lib/styles.ts` helper is copied; component class names are not rewritten automatically.
+
+```bash
+# Install a component and include the shared style tokens
+python scripts/install-component.py metric-card --style origin --dest ./src
+
+# List all available styles and tokens
+python scripts/install-component.py --list-styles
+```

package/references/guides/universal-mobile-patterns.md

@@ -0,0 +1,72 @@
+---
+title: "Universal Mobile-First Interaction Patterns"
+description: "Cross-platform touch guidelines, mobile gesture physics, haptic feedback semantics, and responsive adaptive component adaptations inspired by Expo."
+documentation: "references/guides/universal-mobile-patterns.md"
+markdown: "references/guides/universal-mobile-patterns.md"
+---
+
+# Universal Mobile-First Interaction Patterns
+
+> Engineering resilient cross-platform web and mobile interfaces, synthesizing principles from [expo/expo](https://github.com/expo/expo) and Apple HIG / Material Design standards.
+
+---
+
+## 1. Touch Target Ergonomics
+
+On mobile devices, human thumbs and index fingers lack pixel-level precision.
+- **Minimum Interactive Touch Region**:
+  - Apple Human Interface Guidelines: **$44 \times 44\text{pt}$**
+  - Android Material Design: **$48 \times 48\text{dp}$**
+- **Visual vs Tap Target**: An icon button may visually measure $28 \times 28\text{px}$, but its clickable hit area must be expanded via padding or pseudo-elements (`after:absolute after:-inset-2`).
+- **Pointer Media Query Guard**:
+  ```tsx
+  // lib/hooks/use-hover-capable.ts
+  // Only enable hover transforms on devices with a true pointer
+  @media (hover: hover) and (pointer: fine) { ... }
+  ```
+  Prevents mobile browsers from entering sticky tap states where a tapped button permanently retains its desktop `:hover` appearance.
+
+---
+
+## 2. Semantic Haptic Feedback
+
+Haptics bridge the gap between digital software and physical tactile perception.
+
+### Haptic Trigger Taxonomy
+| Haptic Role | Sensation | Use Case |
+| :--- | :--- | :--- |
+| `selection` | 10ms crisp tap | Wheel picker notches, slider steps, tab switching. |
+| `light` | 15ms soft impulse | Button tap, toggle switch, dropdown menu item click. |
+| `medium` | 30ms firm impulse | Long-press activation, reordering item pickup. |
+| `heavy` | 50ms deep thump | Bottom sheet snap to max height, pull-to-refresh trigger threshold. |
+| `success` | Light-pause-medium | Form submission success, transaction confirmed, task completed. |
+| `warning` | Medium-pause-medium | Destructive action confirmation, near limit alert. |
+| `error` | Rapid 3-pulse vibration | Validation failure, unauthorized action, network error. |
+
+---
+
+## 3. Gesture Physics & Sheet Dynamics
+
+### Dragging & Rubber-Banding
+When an overlay or bottom sheet is pulled past its boundary, apply exponential decay rather than hard clamping:
+$$\text{offset}_{\text{damped}} = \text{threshold} + (\text{excess} \times 0.2)$$
+This gives the interface a tactile, elastic physical boundary.
+
+### Velocity Handoff (Flick vs Distance)
+When dismissing a bottom sheet or swipeable row:
+- If velocity $v_y > 400\text{px/s}$, dismiss the sheet regardless of distance moved.
+- If velocity is low, dismiss only if dragged past 40% of the total height.
+- If released before 40% with low velocity, spring back to open state using `SPRING_PANEL`.
+
+---
+
+## 4. Adaptive Responsive Primitives
+
+Universal components gracefully adapt between mobile and desktop form factors:
+
+| Mobile Primitive | Desktop Adaptation | Rationale |
+| :--- | :--- | :--- |
+| **Action Sheet** | Dropdown Menu / Popover | Mobile thumbs reach bottom edge easily; desktop users click near mouse cursor. |
+| **Bottom Sheet** | Center Modal Dialog | Bottom sheet fills mobile viewport ergonomically; modals center on widescreen displays. |
+| **Segmented Control** | Tabs / Underline Bar | Touch thumbs tap wide pills; desktop users navigate compact tab rows. |
+| **Full-Screen Search** | Command Palette (⌘K) | Mobile keyboards need full screen space; desktop keyboards favor centered palettes. |

package/references/motion/action-sheet.md

@@ -0,0 +1,98 @@
+---
+title: "Action Sheet"
+description: "Universal mobile action sheet menu with drag gesture dismissal, rubber-band resistance, haptic feedback, and desktop center modal fallback."
+category: "Blocks"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/action-sheet.md"
+markdown: "references/motion/action-sheet.md"
+license: "MIT"
+---
+
+# Action Sheet
+
+> Universal mobile action sheet menu with drag gesture dismissal, rubber-band resistance, haptic feedback, and desktop center modal fallback. Inspired by Expo and Apple HIG.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py action-sheet --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ActionSheet, type ActionSheetAction } from "@/components/motion/action-sheet";
+import { Copy, Share2, Trash2 } from "lucide-react";
+import { useState } from "react";
+
+export function ActionSheetExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const actions: ActionSheetAction[] = [
+    {
+      id: "share",
+      label: "Share Workflow Link",
+      icon: <Share2 className="size-4" />,
+      onClick: () => console.log("Shared"),
+    },
+    {
+      id: "copy",
+      label: "Copy Configuration JSON",
+      icon: <Copy className="size-4" />,
+      onClick: () => console.log("Copied"),
+    },
+    {
+      id: "delete",
+      label: "Delete Project",
+      icon: <Trash2 className="size-4" />,
+      destructive: true,
+      onClick: () => console.log("Deleted"),
+    },
+  ];
+
+  return (
+    <div className="p-8">
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        className="px-4 py-2.5 rounded-xl bg-primary text-primary-foreground text-xs font-semibold"
+      >
+        Open Action Sheet
+      </button>
+
+      <ActionSheet
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Project Options"
+        description="Choose an action to perform on this workspace."
+        actions={actions}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `isOpen` | `boolean` | required | Visibility state of the action sheet overlay. |
+| `onClose` | `() => void` | required | Callback triggered on backdrop tap, Escape key, or drag dismissal. |
+| `title` | `string` | `undefined` | Header title displayed above action items. |
+| `description` | `string` | `undefined` | Explanatory subtitle below header title. |
+| `actions` | `ActionSheetAction[]` | required | List of action buttons with labels, icons, and destructive flags. |
+| `cancelLabel` | `string` | `"Cancel"` | Label text on the bottom dismissal button. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/action-swap.md

@@ -0,0 +1,339 @@
+---
+title: "Action Swap"
+description: "CTA button and slot primitives for swapping text and icons with blur motion."
+category: "Components"
+publishedAt: "2026-06-10"
+updatedAt: "2026-06-28"
+documentation: "references/motion/action-swap.md"
+markdown: "references/motion/action-swap.md"
+license: "MIT"
+---
+
+# Action Swap
+
+> CTA button and slot primitives for swapping text and icons with blur motion.
+
+## Install
+
+### Cascade
+
+Letter-by-letter slot roll — the old label's letters drop away as the new ones land, left to right.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py action-swap-cascade --dest ./src
+```
+
+### Blur
+
+Copy-button style swap with blur, opacity and scale.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py action-swap-blur --dest ./src
+```
+
+### Roll
+
+The next text or icon rolls in from below with blur.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py action-swap-roll --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Cascade usage
+
+Letter-by-letter slot roll — the old label's letters drop away as the new ones land, left to right.
+
+```tsx
+"use client";
+
+import { Check, Copy } from "lucide-react";
+import {
+  ActionSwapCascadeButton,
+  type ActionSwapItem,
+} from "@/components/motion/action-swap-cascade";
+
+const CTA_ITEMS: ActionSwapItem[] = [
+  {
+    id: "copy",
+    label: "Copy link",
+    icon: <Copy className="h-4 w-4" />,
+    ariaLabel: "Copy link",
+  },
+  {
+    id: "copied",
+    label: "Copied!",
+    icon: <Check className="h-4 w-4" />,
+    ariaLabel: "Copied",
+  },
+];
+
+export function ActionSwapCascadePreview() {
+  return (
+    <div className="flex w-full justify-center">
+      <ActionSwapCascadeButton items={CTA_ITEMS} variant="primary" />
+    </div>
+  );
+}
+```
+
+### Blur usage
+
+Copy-button style swap with blur, opacity and scale.
+
+```tsx
+"use client";
+
+import { Check, Copy, Moon, Sun } from "lucide-react";
+import { useState } from "react";
+import {
+  ActionSwapBlurButton,
+  type ActionSwapItem,
+} from "@/components/motion/action-swap-blur";
+
+const TEXT_ITEMS: ActionSwapItem[] = [
+  { id: "copy", label: "Copy" },
+  { id: "copied", label: "Copied" },
+];
+
+const ICON_ITEMS: ActionSwapItem[] = [
+  {
+    id: "light",
+    label: "Light",
+    icon: <Sun className="h-4 w-4" />,
+    ariaLabel: "Use light theme",
+  },
+  {
+    id: "dark",
+    label: "Dark",
+    icon: <Moon className="h-4 w-4" />,
+    ariaLabel: "Use dark theme",
+  },
+];
+
+const CTA_ITEMS: ActionSwapItem[] = [
+  {
+    id: "copy",
+    label: "Copy link",
+    icon: <Copy className="h-4 w-4" />,
+    ariaLabel: "Copy link",
+  },
+  {
+    id: "copied",
+    label: "Copied",
+    icon: <Check className="h-4 w-4" />,
+    ariaLabel: "Copied",
+  },
+];
+
+export function ActionSwapBlurPreview() {
+  const [textValue, setTextValue] = useState(TEXT_ITEMS[0]?.id);
+  const [iconValue, setIconValue] = useState(ICON_ITEMS[0]?.id);
+  const [ctaValue, setCtaValue] = useState(CTA_ITEMS[0]?.id);
+
+  return (
+    <div className="flex flex-wrap items-center justify-center gap-3">
+      <ActionSwapBlurButton
+        items={TEXT_ITEMS}
+        value={textValue}
+        onValueChange={setTextValue}
+        variant="secondary"
+      />
+      <ActionSwapBlurButton
+        items={ICON_ITEMS}
+        value={iconValue}
+        onValueChange={setIconValue}
+        variant="outline"
+        size="icon"
+        iconOnly
+      />
+      <ActionSwapBlurButton
+        items={CTA_ITEMS}
+        value={ctaValue}
+        onValueChange={setCtaValue}
+        variant="primary"
+      />
+    </div>
+  );
+}
+```
+
+### Roll usage
+
+The next text or icon rolls in from below with blur.
+
+```tsx
+"use client";
+
+import { Moon, Send, Sparkles, Sun } from "lucide-react";
+import { useState } from "react";
+import {
+  type ActionSwapItem,
+  ActionSwapRollButton,
+} from "@/components/motion/action-swap-roll";
+
+const TEXT_ITEMS: ActionSwapItem[] = [
+  { id: "idle", label: "Save" },
+  { id: "done", label: "Saved" },
+];
+
+const ICON_ITEMS: ActionSwapItem[] = [
+  {
+    id: "light",
+    label: "Light",
+    icon: <Sun className="h-4 w-4" />,
+    ariaLabel: "Use light theme",
+  },
+  {
+    id: "dark",
+    label: "Dark",
+    icon: <Moon className="h-4 w-4" />,
+    ariaLabel: "Use dark theme",
+  },
+];
+
+const CTA_ITEMS: ActionSwapItem[] = [
+  {
+    id: "send",
+    label: "Send invite",
+    icon: <Send className="h-4 w-4" />,
+    ariaLabel: "Send invite",
+  },
+  {
+    id: "sent",
+    label: "Invite sent",
+    icon: <Sparkles className="h-4 w-4" />,
+    ariaLabel: "Invite sent",
+  },
+];
+
+export function ActionSwapRollPreview() {
+  const [textValue, setTextValue] = useState(TEXT_ITEMS[0]?.id);
+  const [iconValue, setIconValue] = useState(ICON_ITEMS[0]?.id);
+  const [ctaValue, setCtaValue] = useState(CTA_ITEMS[0]?.id);
+
+  return (
+    <div className="flex flex-wrap items-center justify-center gap-3">
+      <ActionSwapRollButton
+        items={TEXT_ITEMS}
+        value={textValue}
+        onValueChange={setTextValue}
+        variant="secondary"
+      />
+      <ActionSwapRollButton
+        items={ICON_ITEMS}
+        value={iconValue}
+        onValueChange={setIconValue}
+        variant="outline"
+        size="icon"
+        iconOnly
+      />
+      <ActionSwapRollButton
+        items={CTA_ITEMS}
+        value={ctaValue}
+        onValueChange={setCtaValue}
+        variant="primary"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ActionSwapCascadeButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `size` | `"icon" \| "sm" \| "md" \| "lg"` | — | No | — |
+| `className` | `string` | — | No | — |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | — | No | — |
+| `items` | `ActionSwapItem[]` | — | Yes | — |
+| `onValueChange` | `((value: string, item: ActionSwapItem) => void)` | — | No | — |
+| `iconOnly` | `boolean` | — | No | — |
+| `cycle` | `boolean` | — | No | — |
+
+### ActionSwapCascadeText
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+
+### ActionSwapCascadeIcon
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+
+### ActionSwapBlurButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `size` | `"icon" \| "sm" \| "md" \| "lg"` | — | No | — |
+| `className` | `string` | — | No | — |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | — | No | — |
+| `items` | `ActionSwapItem[]` | — | Yes | — |
+| `onValueChange` | `((value: string, item: ActionSwapItem) => void)` | — | No | — |
+| `iconOnly` | `boolean` | — | No | — |
+| `cycle` | `boolean` | — | No | — |
+
+### ActionSwapBlurText
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+
+### ActionSwapBlurIcon
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+
+### ActionSwapRollButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `size` | `"icon" \| "sm" \| "md" \| "lg"` | — | No | — |
+| `className` | `string` | — | No | — |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | — | No | — |
+| `items` | `ActionSwapItem[]` | — | Yes | — |
+| `onValueChange` | `((value: string, item: ActionSwapItem) => void)` | — | No | — |
+| `iconOnly` | `boolean` | — | No | — |
+| `cycle` | `boolean` | — | No | — |
+
+### ActionSwapRollText
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+
+### ActionSwapRollIcon
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `className` | `string` | — | No | — |
+