# Design System — [PROJECT_NAME]

> **Template** — copy to `.morph/context/design-system.md` and fill in sections marked `/* CUSTOMIZE */`.

Living document. All agents read this before any UI work. All design decisions land here.

---

## Aesthetic Direction

- **Direction**: [TODO: Minimal Refined / Editorial / Soft Professional / Industrial / Modern Luxury]
- **Tone**: [TODO: 1-2 sentences about the feel]
- **Differentiator**: [TODO: The 1 memorable element of this interface]
- **Font Pair**: Sora Variable (display) + Plus Jakarta Sans Variable (body) /* CUSTOMIZE */
- **Color Philosophy**: Deep indigo dominant + Rose accent — modern, bold, not generic /* CUSTOMIZE */
- **Motion Personality**: spring-based, purposeful /* CUSTOMIZE */
- **Visual Density**: balanced /* CUSTOMIZE */
- **Composition**: [TODO: Layout approach — see Domain Patterns below for guidance]
- **Selected Trends**: [TODO: Fill from Step 1.3 trend research — e.g., Bento Grid, Glassmorphism]

---

## Color Tokens

```css
:root {
  /* Dominant palette — deep indigo /* CUSTOMIZE */ */
  --color-primary: #6366f1;
  --color-primary-light: #818cf8;
  --color-primary-dark: #4f46e5;
  --color-primary-rgb: 99, 102, 241;  /* For colored shadows: rgba(var(--color-primary-rgb), 0.3) */

  /* Sharp accent — rose /* CUSTOMIZE */ */
  --color-accent: #f43f5e;
  --color-accent-hover: #e11d48;

  /* Neutrals (dark-first) */
  --color-neutral-50: #fafafa;
  --color-neutral-100: #f4f4f5;
  --color-neutral-200: #e4e4e7;
  --color-neutral-300: #d4d4d8;
  --color-neutral-400: #a1a1aa;
  --color-neutral-500: #71717a;
  --color-neutral-600: #52525b;
  --color-neutral-700: #3f3f46;
  --color-neutral-800: #27272a;
  --color-neutral-900: #18181b;
  --color-neutral-950: #09090b;

  /* Surfaces (elevation via luminance — dark-first) */
  --color-surface-0: #0a0a0f;         /* Base background */
  --color-surface-1: #12121a;         /* Cards */
  --color-surface-2: #1a1a24;         /* Elevated cards, dropdowns */
  --color-surface-3: #22222e;         /* Modals, popovers */
  --color-surface-4: #2a2a38;         /* Hover states */

  /* Light mode overrides (apply via .light or @media (prefers-color-scheme: light)) */
  /* --color-surface-0: #ffffff;
     --color-surface-1: #fafafa;
     --color-surface-2: #f4f4f5;
     --color-surface-3: #e4e4e7;
     --color-surface-4: #d4d4d8; */

  --color-border: rgba(255, 255, 255, 0.08);

  /* Semantic */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;

  /* Text (luminance hierarchy — dark-first) */
  --color-text-primary: #f0f0f5;      /* 95% luminance */
  --color-text-secondary: #a0a0b0;    /* 65% luminance */
  --color-text-muted: #606070;        /* 40% luminance */
}
```

---

## Typography

```css
:root {
  /* Font families — Variable Fonts /* CUSTOMIZE */ */
  --font-display: 'Sora Variable', 'Sora', sans-serif;
  --font-body: 'Plus Jakarta Sans Variable', 'Plus Jakarta Sans', sans-serif;
  --font-mono: 'JetBrains Mono Variable', 'JetBrains Mono', monospace;

  /* Fluid scale (clamp for responsive without breakpoints) */
  --text-xs: clamp(0.7rem, 0.65rem + 0.25vw, 0.75rem);       /* ~12px */
  --text-sm: clamp(0.8rem, 0.75rem + 0.25vw, 0.875rem);      /* ~14px */
  --text-base: clamp(0.9rem, 0.85rem + 0.25vw, 1rem);        /* ~16px */
  --text-lg: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);          /* ~18px */
  --text-xl: clamp(1.1rem, 1rem + 0.5vw, 1.25rem);           /* ~20px */
  --text-2xl: clamp(1.25rem, 1.1rem + 0.75vw, 1.5rem);       /* ~24px */
  --text-3xl: clamp(1.5rem, 1.25rem + 1.25vw, 1.875rem);     /* ~30px */
  --text-4xl: clamp(1.875rem, 1.5rem + 1.875vw, 2.25rem);    /* ~36px */
  --text-5xl: clamp(2.25rem, 1.75rem + 2.5vw, 3rem);         /* ~48px */

  /* Weights (variable font range) */
  --font-weight-regular: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
  --font-weight-extrabold: 800;

  /* Line heights */
  --leading-tight: 1.2;
  --leading-snug: 1.35;
  --leading-normal: 1.5;
  --leading-relaxed: 1.75;

  /* Variable font features */
  --font-display-hover-weight: 'wght' 800;  /* For interactive headings */
}
```

---

## Motion Tokens

```css
:root {
  /* Durations */
  --duration-instant: 0.05s;
  --duration-fast: 0.15s;
  --duration-base: 0.3s;
  --duration-slow: 0.5s;
  --duration-slower: 0.8s;

  /* Standard easings */
  --easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
  --easing-decelerate: cubic-bezier(0, 0, 0.2, 1);
  --easing-accelerate: cubic-bezier(0.4, 0, 1, 1);

  /* Spring / bounce easings */
  --easing-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
  --easing-spring: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  --easing-elastic: cubic-bezier(0.175, 0.885, 0.32, 1.275);

  /* Scroll-driven (use with animation-timeline: scroll()) */
  --scroll-reveal-distance: 20px;
  --scroll-reveal-duration: var(--duration-slow);
}

/* Accessibility — MANDATORY */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

### Framer Motion mapping (TypeScript)

```typescript
export const durations = {
  instant: 0.05,
  fast: 0.15,
  base: 0.3,
  slow: 0.5,
  slower: 0.8,
} as const;

export const easings = {
  standard: [0.4, 0, 0.2, 1] as const,
  decelerate: [0, 0, 0.2, 1] as const,
  accelerate: [0.4, 0, 1, 1] as const,
  bounce: [0.34, 1.56, 0.64, 1] as const,
  spring: [0.68, -0.55, 0.265, 1.55] as const,
  elastic: [0.175, 0.885, 0.32, 1.275] as const,
};

export const springConfigs = {
  gentle: { stiffness: 120, damping: 14 },
  snappy: { stiffness: 300, damping: 20 },
  bouncy: { stiffness: 400, damping: 10 },
} as const;
```

---

## Spacing Tokens

```css
:root {
  /* 4px base grid */
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-5: 1.25rem;   /* 20px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */
  --space-10: 2.5rem;   /* 40px */
  --space-12: 3rem;     /* 48px */
  --space-16: 4rem;     /* 64px */
  --space-20: 5rem;     /* 80px */
  --space-24: 6rem;     /* 96px */

  /* Container */
  --container-padding: var(--space-8);
  --grid-gap: var(--space-6);
}
```

---

## Border Radius Tokens

```css
:root {
  --radius-none: 0;
  --radius-sm: 0.25rem;    /* 4px */
  --radius-base: 0.375rem; /* 6px */
  --radius-md: 0.5rem;     /* 8px */
  --radius-lg: 0.75rem;    /* 12px */
  --radius-xl: 1rem;       /* 16px */
  --radius-2xl: 1.5rem;    /* 24px */
  --radius-full: 9999px;
}
```

---

## Shadow Tokens

```css
:root {
  /* Standard shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-base: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07), 0 2px 4px rgba(0, 0, 0, 0.06);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05);
  --shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1), 0 10px 10px rgba(0, 0, 0, 0.04);

  /* Layered shadows (more realistic depth) */
  --shadow-layered-sm: 0 1px 1px rgba(0,0,0,0.04), 0 2px 4px rgba(0,0,0,0.04);
  --shadow-layered-md: 0 1px 2px rgba(0,0,0,0.03), 0 4px 8px rgba(0,0,0,0.04), 0 12px 24px rgba(0,0,0,0.05);
  --shadow-layered-lg: 0 2px 4px rgba(0,0,0,0.02), 0 8px 16px rgba(0,0,0,0.04), 0 24px 48px rgba(0,0,0,0.06);

  /* Colored shadows (use element's accent color) */
  --shadow-colored-sm: 0 4px 14px rgba(var(--color-primary-rgb), 0.15);
  --shadow-colored-md: 0 8px 24px rgba(var(--color-primary-rgb), 0.25);
  --shadow-colored-lg: 0 12px 40px rgba(var(--color-primary-rgb), 0.35);

  /* Interaction shadows */
  --shadow-lift: 0 8px 30px rgba(0, 0, 0, 0.12);          /* Card hover lift */
  --shadow-focus: 0 0 0 3px rgba(var(--color-primary-rgb), 0.4);  /* Focus ring */
}
```

---

## Design Trends (Active)

Agents MUST consider modern design techniques when filling this template. Use Context7 MCP or web search for current design trends. Select 2-3 that fit the project's direction and domain:

| Technique | Best For | Direction Fit |
|-----------|----------|---------------|
| Bento Grid | Dashboards, landing pages | Industrial, Editorial |
| Glassmorphism | Navigation, overlays, cards | Soft Professional, Modern Luxury |
| Aurora Gradients | Hero backgrounds, empty states | Editorial, Modern Luxury |
| Variable Fonts | Interactive headings, responsive weight | All directions |
| Scroll-Driven Animations | Narratives, reveals, progress | Editorial, Modern Luxury |
| Perspective Cards (3D) | Product cards, pricing, features | Modern Luxury |
| Noise Texture | Backgrounds, surfaces | Minimal Refined |
| Colored Shadows | CTAs, hover states, cards | Soft Professional, Modern Luxury |
| Dark Mode First | Data-heavy apps, developer tools | Industrial, Minimal Refined |
| Fluid Typography | Responsive headings | All directions |

---

## Domain Patterns

Choose patterns based on the project domain:

| Domain | Layout | Key Components | Visual Approach |
|--------|--------|---------------|----------------|
| **SaaS Dashboard** | Bento grid + sidebar | KPI cards, data tables, charts | Controlled density, skeleton loaders, dark default |
| **E-commerce** | Product grid + asymmetric hero | Product cards, CTA buttons, filters | Image-first, hover lift, colored shadows on CTA |
| **Landing Page** | Full-width sections | Hero, features, testimonials, CTA | Aurora gradients, scroll reveals, fluid typography |
| **Internal Tool** | Dense sidebar + content | Forms, tables, status indicators | Minimal effects, compact spacing, monospace data |
| **Social/Community** | Card feed + drawer nav | Post cards, avatars, notifications | Glassmorphism overlays, spring animations |

---

## Advanced Effects

```css
:root {
  /* Glassmorphism */
  --glass-blur: 12px;
  --glass-saturation: 180%;
  --glass-bg-light: rgba(255, 255, 255, 0.15);
  --glass-bg-dark: rgba(0, 0, 0, 0.25);
  --glass-border: rgba(255, 255, 255, 0.18);

  /* Aurora gradient (animate with @keyframes) */
  --aurora-gradient: conic-gradient(from 0deg at 50% 50%,
    var(--color-primary), var(--color-accent), #fbbf24, var(--color-primary));
  --aurora-speed: 15s;

  /* Noise texture (inline SVG) */
  --noise-texture: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");

  /* 3D / Perspective */
  --perspective-card: perspective(1000px);
  --perspective-hover-rotate: rotateX(-2deg) rotateY(3deg) translateZ(10px);

  /* Container queries */
  --container-sm: 400px;
  --container-md: 600px;
  --container-lg: 800px;

  /* View Transitions (CSS) */
  --view-transition-duration: 0.3s;
  --view-transition-easing: var(--easing-decelerate);
}

/* View Transitions API support */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: var(--view-transition-duration);
  animation-timing-function: var(--view-transition-easing);
}
```

---

## Changelog

> Living record — every agent that adds tokens or design decisions registers here.
> Format: `- YYYY-MM-DD [agent-id] Description of addition/change`

<!-- Entries below this line, newest first -->

---

*MORPH-SPEC by Polymorphism Tech*