---
name: amicro-design-system
description: Rules, design tokens, card structures, motion physics, and component architecture for the Amicro UI library. Use whenever creating or modifying UI components, page sections, micro-interactions, or transition features in the Amicro repository.
---
# Amicro Design System & Component Guidelines
This skill defines the authoritative design tokens, component architecture, styling rules, and layout standards for the **Amicro** repository. All new features, micro-interactions, cards, loaders, and page transitions **MUST** strictly follow these rules to maintain perfect visual harmony and quality.
---
## 1. Core Design Tokens & Palette
### Font Family
- **Font**: `'Outfit', sans-serif` (configured in `index.css` under `@theme { --font-sans: 'Outfit', sans-serif; }`).
- **Headings**: `font-medium` or `font-semibold` with tight tracking (`tracking-[-0.01em]` or `tracking-[-0.019em]`).
### Color Palette (Dark & Light Theme)
| Token | Dark Mode (`.dark`) | Light Mode |
|---|---|---|
| **Page Background** | `#121212` | `#f8f9fa` |
| **Card Container BG** | `#161616` | `bg-white` |
| **Card Container Border** | `border-white/[0.07] hover:border-white/[0.18]` | `border-neutral-200/80 hover:border-neutral-300` |
| **Card Container Elevation** | `shadow-[0_4px_24px_-4px_rgba(0,0,0,0.5),inset_0_1px_0_0_rgba(255,255,255,0.06)]` | `shadow-[0_2px_8px_rgba(0,0,0,0.04),0_12px_28px_-6px_rgba(0,0,0,0.05)]` |
| **Preview Stage Canvas** | `#0d0d0d` + `shadow-[inset_0_2px_6px_rgba(0,0,0,0.5)]` | `#f5f6f8` + `shadow-[inset_0_1px_3px_rgba(0,0,0,0.03)]` |
| **Primary Text** | `#ffffff` / `#f0f0f0` | `#000000` |
| **Secondary / Muted Text** | `text-neutral-400` / `text-neutral-500` | `text-neutral-600` / `text-neutral-750` |
| **Pill / Button Inactive** | `bg-[rgba(255,255,255,0.07)]` | `bg-neutral-200/80` |
| **Pill / Button Active** | `bg-[#2a2a2a] text-white` | `bg-white text-black shadow-sm` |
---
## 2. Standard Card Architecture (Minimal Expanded Layout)
Every component entry in the catalog grid (Buttons, Card Spreads, 3D Carousels, Loaders, Page Transitions) **MUST** use the minimal, optimized card layout architecture:
### Gallery Container
```tsx
{/* Island Filter Bar & Secondary Controls */}
...
{/* Responsive Grid */}
{/* Component Cards */}
```
### Component Card Architecture
```tsx
{/* Expanded Borderless Playground Stage filling completely with black background */}
{/* Component Live Interactive Preview Component Here */}
{/* Minimal Card Footer: Only Title & Description, Hover Copy Button */}
{/* Action Copy Button - Fades in on card hover */}
{isCopied ? : }
```
---
## 3. Catalog Navigation & Pill Styling
- **Desktop Filter Pill Bar**:
- Container: `hidden sm:flex items-center p-1 rounded-full border shadow-inner transition-colors duration-300 bg-[#181818] border-white/5` (Dark) / `bg-neutral-200/50 border-neutral-300/30` (Light).
- Active Pill: `bg-[#2a2a2a] text-white` (Dark) / `bg-white text-black shadow-sm` (Light).
- Inactive Pill: `text-[#767676] hover:text-white` (Dark) / `text-black opacity-70 hover:opacity-100` (Light).
- **Mobile Dropdown**:
- Backdrop blur modal dropdown (`backdrop-blur-xl bg-[#181818]/95 border-white/5`).
---
## 4. Component Micro-Interactions & Haptics
- **Motion**: Use `motion/react` (`framer-motion`) with cubic bezier easing `[0.16, 1, 0.3, 1]` for exponential smooth reveals.
- **Timing budget (hard rule): every one-shot animation is < 300ms.** This covers hovers, presses, enters, exits, page transitions, toasts, menus, chart draw-ins and component interactions.
- Durations: hover/press `0.15–0.2s`, enter `0.25s`, exit `~0.14s` (exits are shorter than entries), absolute max `0.28s`. Tailwind: `duration-150` / `duration-200` / `duration-250` (never `duration-300`+).
- Springs: settle within 0.29s. Underdamped settle ≈ `8 × mass / damping`, so with `mass: 1` use `damping >= 28` (hover default: `{ type: 'spring', stiffness: 400, damping: 28 }`). Duration-style springs: `{ type: 'spring', duration: 0.25, bounce: 0.1–0.2 }`.
- Stagger: `delay: Math.min(index * 0.015, 0.05)` so a whole grid entrance finishes inside the budget.
- Recharts: `animationDuration={280}` (its default is 1500ms).
- Multi-step CSS choreographies: each step ≤ 0.28s; scale delays with the durations so the sequence stays in sync.
- Exempt: infinite loops (spinners, loaders, ambient `repeat: Infinity` motion), where the value is a loop period, not a transition.
- **Easing**: entrances/exits use `[0.16, 1, 0.3, 1]` (ease-out); exits may use `[0.25, 0.46, 0.45, 0.94]`. Never `easeIn` on UI.
- **Reduced motion**: the app is wrapped in ``; CSS animations are neutralised by the `prefers-reduced-motion` block in `index.css`.
- **Haptics**: Always trigger `useWebHaptics` hook:
- Copy Code: `triggerHaptic('success')`
- Button Click / Tab Change: `triggerHaptic('medium')` or `triggerHaptic('light')`
- Error: `triggerHaptic('error')`
- **Toast Notifications**: Always trigger `showToast("Copied ... code!")`.
---
## 5. CLI Registry Integration Rules
Whenever adding a new component or transition:
1. Add the component source file in `registry/ui//.tsx`.
2. Register the component item in `registry/registry.json` with dependencies (`framer-motion`, etc.).
3. Provide copy CLI command snippet: `npx @subhanhq/amicro@latest add `.