# Design System Specification (`design.md`)

This document is the **single source of truth** for all visual styling, typography, component choices, and design tokens across this project. Any AI agent or developer modifying styling MUST adhere strictly to the directives outlined below.

---

## 1. Core Principle: Web Awesome Only
- **Zero third-party UI libraries**: Do not use Tailwind, Shadcn, Bootstrap, or Material UI components.
- **ZeroPress CSS `@layer` & CLS-Lock Compilation**: `packages/zeropress-engine/src/css-compiler.mjs` parses the dual-mode tokens in this file alongside Web Awesome Pro modular stylesheets (`themes/brutalist.css`, `color/palettes/natural.css`, `utilities.css`, `native.css`) into `@layer` CSS (`wa-theme`, `wa-color-palette`, `zeropress-tokens`, `zeropress-base`, `zeropress-components`, `zeropress-custom`), inlining critical CSS and `:not(:defined)` CLS-lock rules into `<head>` so `CLS = 0.000` before custom-element upgrade.
- **Component Primitives**: Only use native **Web Awesome Pro** custom elements:
  - Cards: `<wa-card>`
  - Buttons: `<wa-button>` (with `variant="brand"`, `variant="neutral"`, or `variant="default"`)
  - Accordions & Collapsibles: `<wa-details>`
  - Drawers & Overlays: `<wa-drawer>`
  - Callouts & Alerts: `<wa-callout>`
  - Badges & Status: `<wa-badge>`
  - Avatars: `<wa-avatar>`
  - Tooltips: `<wa-tooltip>`
  - Icons: `<wa-icon>`
  - Dividers: `<wa-divider>`
  - Form Switches: `<wa-switch>`
  - Tab Groups: `<wa-tab-group>`, `<wa-tab>`, `<wa-tab-panel>`
  - Carousels: `<wa-carousel>`, `<wa-carousel-item>`

---

## 2. Visual Archetype & Theme
- **Archetype**: Brutalist Technical HUD / Developer Terminal
- **Active Web Awesome Theme**: `wa-theme-brutalist`
- **Active Color Palette**: `wa-palette-natural`
- **Dark Mode**: Default (`.wa-dark`) with reactive light mode toggle (`.wa-light`).

---

## 3. Design Tokens & Accessibility Specification (WCAG 2.2 Level AA / AAA)

All visual styling adheres to **WCAG 2.2 AA (minimum 4.5:1 text, 3:1 non-text)** across both dark and light modes. Never use light amber (`#ffb800`) on white backgrounds (1.7:1 failure) or white text on yellow buttons (1.7:1 failure).

### Dual-Mode Token Architecture

```scss
/* Dark Mode (Default HUD - Canvas #14120e) */
html.wa-dark,
body.wa-dark {
  --wa-color-surface-default: #14120e;       /* Deep canvas */
  --wa-color-surface-raised: #1f1d1a;        /* Card & panel */
  --wa-color-surface-lowered: #14120e;       /* Insets */
  --wa-color-surface-border: #5c594f;        /* 3.2:1 UI boundary */

  --wa-color-text-normal: #f5f4f0;           /* 16.8:1 AAA Body text */
  --wa-color-text-quiet: #98958c;            /* 5.7:1 AA Muted text */
  --wa-color-brand-text: #ffb800;            /* 10.5:1 AAA HUD Amber Eyebrow/Accent */

  --wa-color-brand-fill-loud: #ffb800;       /* Amber button fill */
  --wa-color-brand-on-loud: #14120e;         /* 10.5:1 AAA Dark text on amber button */
  --wa-form-control-activated-color: #ffb800; /* Active switch/control indicator */
  --wa-focus-ring-color: #ffb800;            /* 10.5:1 Focus ring */
}

/* Light Mode (Canvas #ffffff) */
html.wa-light,
body.wa-light {
  --wa-color-surface-default: #ffffff;       /* Pure white canvas */
  --wa-color-surface-raised: #ffffff;        /* Raised card */
  --wa-color-surface-lowered: #f1f1f0;       /* Lowered code container */
  --wa-color-surface-border: #1f1d1a;        /* 18.2:1 High-contrast brutalist frame */

  --wa-color-text-normal: #1f1d1a;           /* 18.2:1 AAA Body text */
  --wa-color-text-quiet: #5c594f;            /* 5.8:1 AA Muted text */
  --wa-color-brand-text: #854d0e;            /* 7.1:1 AAA Amber 900 Eyebrow/Accent */

  --wa-color-brand-fill-loud: #854d0e;       /* Amber 900 button fill (7.1:1 on #ffffff) */
  --wa-color-brand-on-loud: #ffffff;         /* 7.1:1 AAA White text on dark amber */
  --wa-form-control-activated-color: #854d0e; /* Active switch/control indicator */
  --wa-focus-ring-color: #854d0e;            /* 7.1:1 Focus ring */
}
```

### Contrast Verification Matrix

| Element | Dark Mode Token & Value | Dark Canvas (`#14120e`) | Light Mode Token & Value | Light Canvas (`#ffffff`) | WCAG Rating |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Primary Body Text** | `--wa-color-text-normal: #f5f4f0` | **16.8:1** | `--wa-color-text-normal: #1f1d1a` | **18.2:1** | **AAA** (> 7:1) |
| **Muted / Secondary** | `--wa-color-text-quiet: #98958c` | **5.7:1** | `--wa-color-text-quiet: #5c594f` | **5.8:1** | **AA** (> 4.5:1) |
| **Brand Eyebrow & Stats** | `--wa-color-brand-text: #ffb800` | **10.5:1** | `--wa-color-brand-text: #854d0e` | **7.1:1** | **AAA** (> 7:1) |
| **Primary Button Text** | `--wa-color-brand-on-loud: #14120e` | **10.5:1** on `#ffb800` | `--wa-color-brand-on-loud: #ffffff` | **7.1:1** on `#854d0e` | **AAA** (> 7:1) |
| **Focus Indicator** | `--wa-focus-ring-color: #ffb800` | **10.5:1** | `--wa-focus-ring-color: #854d0e` | **7.1:1** | **AA** (> 3:1) |
| **Structural Borders** | `--wa-color-surface-border: #5c594f` | **3.2:1** | `--wa-color-surface-border: #1f1d1a` | **18.2:1** | **AA** (> 3:1) |

### Typography Tokens
```scss
:root {
  /* Headings & Metrics: Space Mono with uppercase tracking */
  --wa-font-family-heading: 'Space Mono', monospace;
  /* Body & Longform Prose: IBM Plex Sans Condensed */
  --wa-font-family-body: 'IBM Plex Sans Condensed', -apple-system, sans-serif;
  /* Monospace / Code: Space Mono */
  --wa-font-family-mono: 'Space Mono', monospace;
  --wa-font-family-code: 'Space Mono', monospace;

  --wa-font-weight-regular: 400;
  --wa-font-weight-medium: 500;
  --wa-font-weight-bold: 700;
  --wa-font-weight-black: 900;
}
```

**Typography Design Standard**:
- **Headings & HUD Overlines**: All section headlines, hero statements, card titles, overlines, and table headers are standardized on **Space Mono** (`--wa-font-family-heading`) with uppercase tracking (`text-transform: uppercase`, `letter-spacing: 0.03em`). This delivers a cohesive, industrial Brutalist Terminal HUD design.
- **Body & Longform Copy**: Multi-sentence body paragraphs and descriptions are set in **IBM Plex Sans Condensed** (`--wa-font-family-body`) for superior readability and compact information density.
- **Code & Telemetry Data**: System logs, hashes, telemetry figures, and terminal feeds use **Space Mono** (`--wa-font-family-mono`).

### Geometry & Scale Tokens
```scss
:root {
  /* Brutalist hard edges - zero border radius */
  --wa-border-radius-scale: 0;

  /* Explicit border width */
  --wa-border-width-scale: 1.5;

  /* Maximum layout container width */
  --zeropress-container-max: 1240px;
}
```

---

## 4. Component Usage Guidelines

1. **Section Headers**:
   - Eyebrows: Must use `.text-overline-2` with `color: var(--wa-color-brand-text)`.
   - Headlines: Bold `<h2>` or `<h1>` using `--wa-font-family-heading`.
2. **Cards (`<wa-card>`)**:
   - Title placed in `<div slot="header">`.
   - Action links placed in `<div slot="footer">` as a `<wa-button>`.
3. **Accordions (`<wa-details>`)**:
   - Question passed as `summary="Question text"`.
   - Answer content nested inside element body.
4. **CTAs (`<wa-button>`)**:
   - Primary: `<wa-button variant="brand">`
   - Secondary: `<wa-button variant="neutral">`
   - External links must include `target="_blank" rel="noreferrer noopener"`.
5. **Tab Groups (`<wa-tab-group>`)**:
   - Tab triggers use `<wa-tab slot="nav" panel="...">` with Space Mono uppercase tracking (`--wa-font-family-heading`) and `--indicator-color: var(--wa-color-brand-text)`.
   - Panels use `<wa-tab-panel name="...">` with `--wa-color-surface-raised` and `--wa-color-surface-border`.
6. **Carousels (`<wa-carousel>`)**:
   - Slides use `<wa-carousel-item>` with `--aspect-ratio: auto` for text/card slides so content never clips on mobile viewports.
   - Navigation buttons (`::part(navigation-button)`) and pagination indicators (`::part(pagination-item)`) enforce `border-radius: 0` and `--wa-color-brand-fill-loud` active state.