# Dusk - Complete Design System
> Version 1.0 - Theme 12 in the catalog - slug `dusk`

---

## Table of Contents

1. [System Overview](#1-system-overview)
2. [CSS Custom Properties - Master Token Sheet](#2-css-custom-properties--master-token-sheet)
3. [Color Palette](#3-color-palette)
4. [Typography System](#4-typography-system)
5. [Spacing System](#5-spacing-system)
6. [Border Radius System](#6-border-radius-system)
7. [Shadow & Elevation System](#7-shadow--elevation-system)
8. [Component Specifications](#8-component-specifications)
9. [Layout & Grid System](#9-layout--grid-system)
10. [Animation & Transition Tokens](#10-animation--transition-tokens)
11. [Z-Index System](#11-z-index-system)
12. [Breakpoints](#12-breakpoints)
13. [Icon System](#13-icon-system)
14. [State Definitions](#14-state-definitions)

---

## 1. System Overview

**Design Language:** Dusk
**Mode:** Dark
**Typeface:** Poppins
**Personality:** Twilight purple canvas with frosted surfaces, warm orange actions and Poppins throughout.
**Best Suited For:** Evening-mode apps, music and media players, meditation and journaling products, creative tools

**Core Principles:**
- Gradients live on the page background only. Never put a gradient on text or buttons.
- Surfaces are frosted and calm: one step lighter than the page, 22px radius, soft glow shadow.
- Orange is the single action colour. Pink is a rare accent for badges and charts.
- Everything is Poppins. Hierarchy comes from weight (400, 600, 700) and size, not from a second font.

---

## 2. CSS Custom Properties - Master Token Sheet

All tokens are scoped under `[data-ds="dusk"]`. Nothing is defined at `:root`. The same sheet ships as `tokens.css` in this system's folder.

```css
/*
 * Dusk - scoped design-system tokens (Theme 12 in catalog).
 */

[data-ds="dusk"] {
  --ds-color-bg-base: #1d0b3d;
  --ds-color-bg-surface: #2d1760;
  --ds-color-bg-sunken: #150832;
  --ds-color-bg-secondary: #3a2380;
  --ds-color-bg-overlay: rgba(10,0,30,0.6);

  --ds-color-primary: #ff8a4c;
  --ds-color-primary-hover: #ff9861;
  --ds-color-primary-active: #ffa473;
  --ds-color-primary-fg: #2b1055;

  --ds-color-text-primary: #fdf4ff;
  --ds-color-text-secondary: #d8c8f0;
  --ds-color-text-tertiary: #bba9de;
  --ds-color-text-muted: #bba9de;
  --ds-color-text-disabled: #8f7fb8;
  --ds-color-text-inverse: #2b1055;

  --ds-color-border-light: #4a3190;
  --ds-color-border-medium: #6b4fc0;
  --ds-color-border-strong: #a58ae6;

  --ds-color-success: #4ade80;
  --ds-color-success-bg: #12361f;
  --ds-color-warning: #fbbf24;
  --ds-color-warning-bg: #3b2e08;
  --ds-color-error: #ff7a82;
  --ds-color-error-bg: #40141a;
  --ds-color-info: #60a5fa;
  --ds-color-info-bg: #12294a;

  --ds-font-display: "Poppins", system-ui, sans-serif;
  --ds-font-body: "Poppins", system-ui, sans-serif;
  --ds-font-label: "Poppins", system-ui, sans-serif;
  --ds-label-transform: none;
  --ds-label-tracking: 0em;
  --ds-label-weight: 600;
  --ds-heading-tracking: -0.02em;
  --ds-heading-weight: 700;

  --ds-radius-badge: 999px;
  --ds-radius-sm: 12px;
  --ds-radius-md: 12px;
  --ds-radius-lg: 22px;
  --ds-radius-xl: 28px;
  --ds-radius-full: 9999px;

  --ds-border-width: 1px;

  --ds-shadow-card: 0 20px 50px rgba(10,0,30,0.5);
  --ds-shadow-dropdown: 0 16px 40px rgba(10,0,30,0.6);
  --ds-shadow-modal: 0 30px 80px rgba(10,0,30,0.7);
  --ds-shadow-focus: 0 0 0 3px rgba(255,138,76,0.45);
  --ds-shadow-btn-hover: 0 10px 24px rgba(255,138,76,0.35);

  --ds-btn-text-transform: none;
  --ds-btn-letter-spacing: 0em;
  --ds-btn-font-weight: 600;
  --ds-btn-active-transform: scale(0.97);
  --ds-btn-secondary-bg: #ff5fa2;
  --ds-btn-secondary-text: #2b1055;
  --ds-btn-secondary-border: #ff5fa2;
  --ds-btn-secondary-hover-bg: #ff6fab;
  --ds-btn-outline-text: #fdf4ff;
  --ds-btn-outline-border: #a58ae6;
  --ds-btn-outline-hover-bg: #3a2380;
  --ds-btn-outline-hover-text: #fdf4ff;

  --ds-table-header-bg: #ff8a4c;
  --ds-table-header-text: #2b1055;
  --ds-table-header-border-bottom: 1px solid #6b4fc0;
  --ds-table-container-radius: 22px;
  --ds-table-container-border: 2px solid #ff8a4c;

  --ds-focus-ring: 0 0 0 3px rgba(255,138,76,0.45);

  --ds-ease-standard: cubic-bezier(0.2, 0.8, 0.2, 1);
  --ds-duration-fast: 120ms;
  --ds-duration-base: 200ms;
  --ds-duration-slow: 320ms;
}

[data-ds="dusk"] { background: linear-gradient(160deg, #2b1055 0%, #1d0b3d 55%, #150832 100%); }
[data-ds="dusk"] .ds-card, [data-ds="dusk"] .ds-modal { backdrop-filter: blur(10px); }
```

---

## 3. Color Palette

### 3.1 Core Colors

| Role | Value |
|---|---|
| Page background | `#1d0b3d` |
| Surface | `#2d1760` |
| Sunken | `#150832` |
| Secondary surface | `#3a2380` |
| Primary action | `#ff8a4c` |
| Primary text on action | `#2b1055` |
| Accent / secondary button | `#ff5fa2` |
| Accent text | `#2b1055` |
| Text primary | `#fdf4ff` |
| Text secondary | `#d8c8f0` |
| Text muted | `#bba9de` |
| Border light | `#4a3190` |
| Border strong | `#a58ae6` |

### 3.2 Semantic Colors

| Status | Foreground | Background | Contrast |
|---|---|---|---|
| Success | `#4ade80` | `#12361f` | 7.7:1 |
| Warning | `#fbbf24` | `#3b2e08` | 8.0:1 |
| Error | `#ff7a82` | `#40141a` | 6.3:1 |
| Info | `#60a5fa` | `#12294a` | 5.7:1 |

### 3.3 Contrast Checks

All pairs below meet WCAG AA (4.5:1) for normal text.

| Pair | Colors | Ratio |
|---|---|---|
| Body text | `#fdf4ff` on `#1d0b3d` | 16.8:1 |
| Secondary text | `#d8c8f0` on `#1d0b3d` | 11.5:1 |
| Muted text | `#bba9de` on `#1d0b3d` | 8.4:1 |
| Primary button label | `#2b1055` on `#ff8a4c` | 6.9:1 |
| Accent button label | `#2b1055` on `#ff5fa2` | 5.7:1 |
| Table header | `#2b1055` on `#ff8a4c` | 6.9:1 |

---

## 4. Typography System

### 4.1 Font Families

| Role | Family | Usage |
|---|---|---|
| Display | Poppins | Headings, hero titles, stat numbers |
| Body | Poppins | Body copy, buttons, form fields |
| Label | Poppins | Eyebrows, badges, metadata |

### 4.2 Type Scale

| Token | Size | Weight | Tracking | Use |
|---|---|---|---|---|
| Display | 48-64px | 700 | -0.02em | Hero title |
| H1 | 36px | 700 | -0.02em | Page title |
| H2 | 28px | 700 | -0.02em | Section title |
| H3 | 20px | 700 | -0.02em | Card title |
| Body | 16px | 400 | 0 | Paragraphs |
| Label | 12px | 600 | 0em | Eyebrows, badges (none) |

### 4.3 Google Fonts Import Block

```css
@import url("https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap");
```

The same URL is loaded by `app/design-systems/fonts.ts`.

---

## 5. Spacing System

Base unit: 4px. Use only these steps.

| Token | Value |
|---|---|
| space-1 | 4px |
| space-2 | 8px |
| space-3 | 12px |
| space-4 | 16px |
| space-6 | 24px |
| space-8 | 32px |
| space-12 | 48px |
| space-16 | 64px |

Component padding: card 24px, button 10px 20px (md), input 10px 14px, badge 2px 10px.

---

## 6. Border Radius System

| Element | Radius |
|---|---|
| Badge | 999px |
| Small controls (checkbox) | 12px |
| Buttons, inputs | 12px |
| Cards, modals | 22px |
| Large panels | 28px |
| Avatars, switches | 9999px |

Border width: 1px.

---

## 7. Shadow & Elevation System

| Level | Value |
|---|---|
| Card | `0 20px 50px rgba(10,0,30,0.5)` |
| Dropdown | `0 16px 40px rgba(10,0,30,0.6)` |
| Modal | `0 30px 80px rgba(10,0,30,0.7)` |
| Focus | `0 0 0 3px rgba(255,138,76,0.45)` |
| Button hover | `0 10px 24px rgba(255,138,76,0.35)` |

---

## 8. Component Specifications

### 8.1 Buttons
- Primary: background `--ds-color-primary`, label `--ds-color-primary-fg`. Hover `#ff9861`, active `#ffa473`.
- Secondary: background `#ff5fa2`, label `#2b1055`.
- Outline: transparent, border `#a58ae6`, label `#fdf4ff`.
- Label style: `none` text, weight 600, tracking 0em.
- Active (pressed): `transform: scale(0.97)`.

### 8.2 Form Inputs
Surface background, 1px border `#6b4fc0`, radius 12px. Focus uses the focus shadow. Error border `#ff7a82`.

### 8.3 Labels
Font Poppins, none, weight 600, tracking 0em, colour `#bba9de`.

### 8.4 Card / Surface
Background `#2d1760`, border 1px `#4a3190`, radius 22px, shadow card.

### 8.5 Badge
Pill or 999px radius, label style, semantic backgrounds from section 3.2.

### 8.6 Checkbox, Radio and Switch
Checked fill `#ff8a4c`, mark `#2b1055`. Switch track uses border strong when off.

### 8.7 Table
Header background `#ff8a4c`, header text `#2b1055`. Container border `2px solid #ff8a4c`, radius 22px.

### 8.8 Dropdown Panel
Surface background, border 1px `#6b4fc0`, dropdown shadow, item hover uses `#3a2380`.

---

## 9. Layout & Grid System

| Container | Max width |
|---|---|
| Narrow (forms, articles) | 640px |
| Default | 1040px |
| Wide (dashboards) | 1280px |

12-column grid, 24px gutters on desktop, 16px on mobile.

---

## 10. Animation & Transition Tokens

| Token | Value |
|---|---|
| Easing | `cubic-bezier(0.2, 0.8, 0.2, 1)` |
| Fast | 120ms |
| Base | 200ms |
| Slow | 320ms |

Animate colour, transform, opacity and shadow only. Never animate layout properties.

---

## 11. Z-Index System

| Layer | Value |
|---|---|
| Base | 0 |
| Sticky header | 10 |
| Dropdown | 20 |
| Modal backdrop | 40 |
| Modal | 50 |
| Toast | 60 |

---

## 12. Breakpoints

| Name | Min width |
|---|---|
| sm | 640px |
| md | 768px |
| lg | 1024px |
| xl | 1280px |

Page padding: 16px below md, 24px at md, 32px at lg and up.

---

## 13. Icon System

Use Lucide icons at 16, 20 or 24px, stroke 2px (1.5px for Dusk if the type is light). Icon colour follows text colour. Never use filled multi-colour icons.

---

## 14. State Definitions

| State | Treatment |
|---|---|
| Hover | Darker or lighter primary (see 8.1), shadow `0 10px 24px rgba(255,138,76,0.35)` |
| Active | `scale(0.97)` |
| Focus | `0 0 0 3px rgba(255,138,76,0.45)` |
| Disabled | Text `#8f7fb8`, no shadow, cursor not-allowed |
| Error | Border `#ff7a82`, message in the same colour |
| Success | Border `#4ade80` |