Mitchell Hou

# DESIGN.md

## 1. Overview

Interface guided by clear visual hierarchy, consistent surfaces, and a controlled semantic palette.
Use the tokens and contracts below as the normative source for accessible, responsive implementation.

> Normative implementation contract: preserve semantic token names, responsive rules, and interaction states when extending the interface.

## 2. Colors and accessibility

### Semantic color tokens

| Token | Hex value | Purpose |
|---|---|---|
| background | `#d5d7da` | Primary canvas |
| surface | `#d5d7da` | Raised surfaces |
| text-primary | `#181d27` | Primary text |
| text-secondary | `#414651` | Secondary text |
| text-muted | `#414651` | Supporting text |
| text-on-brand | `#ffffff` | Text on brand |
| border | `#e9eaeb` | Borders and dividers |
| brand | `#7f56d9` | Primary brand action |
| success | `#166534` | Positive state |
| danger | `#b91c1c` | Destructive state |
| warning | `#92400e` | Warning state |
| info | `#075985` | Informational state |
| focus | `#1d4ed8` | Focus ring |

### WCAG AA rules

- Normal text must reach a minimum contrast ratio of 4.5:1.
- Large text and interface elements must reach a minimum contrast ratio of 3:1.
- Visible focus must maintain a minimum contrast ratio of 3:1 and must not rely on color alone.
- Use only semantic token combinations that meet these ratios.

## 3. Typography

### Family

| Token | Family | Usage |
|---|---|---|
| font-bodyfont | `'union', sans-serif` | Body and interface text |
| font-monofont | `'Roboto Mono', sans-serif` | Metadata and code |

### Type scale

| Token | Family | Size | Weight | Line height |
|---|---|---:|---:|---:|
| type-button | `'union', sans-serif` | `16px` | `400` | `24px` |
| type-body | `'Roboto Mono', sans-serif` | `14px` | `400` | `20px` |
| type-bodystrong | `'Roboto Mono', sans-serif` | `14px` | `700` | `20px` |
| type-caption | `'union', sans-serif` | `12px` | `500` | `16px` |

## 4. Layout and spacing

### Breakpoints

- **Mobile:** `< 768px` — one-column grid, 16px/24px gutters, and stacked navigation.
- **Tablet:** `768px–1023px` — adaptive grid and 32px/48px gutters.
- **Desktop:** `>= 1024px` — 120px gutters and a container max-width defined by the layout.

### Responsive rules

- **Header:** stack navigation and actions on mobile; keep primary navigation inline from tablet upward.
- **Hero:** use one column on mobile, a balanced two-column composition on tablet, and the full container on desktop.
- **Cards:** stretch to the grid width on mobile, use two columns on tablet, and the defined card grid on desktop.
- **Navigation grid: use one column on mobile, adaptive columns on tablet, and the complete navigation grid on desktop.

### Spacing scale

| Token | Value | Usage |
|---|---:|---|
| space-xs | `4px` | Layout scale |
| space-sm | `8px` | Layout scale |
| space-md | `12px` | Layout scale |
| space-lg | `16px` | Layout scale |
| space-xl | `20px` | Layout scale |

## 5. Shapes, borders and depth

### Radii

| Token | Value | Usage |
|---|---:|---|
| radius-sm | `4px` | Compact controls |
| radius-md | `12px` | Cards and surfaces |
| radius-full | `9999px` | Pills and circular controls |

### Borders and depth

- Border width: `var(--ds-border-width)`.
- Border style: `solid`.
- Border color: `var(--ds-color-border)`.
- Use `var(--ds-shadow-sm)` for low elevation and `var(--ds-shadow-inner)` for inner separation.

## 6. Component specification

### Nav

- **Component:** Reusable nav pattern.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-text-primary)` and `var(--ds-color-text-on-brand)` on brand surfaces
- **Geometry:** `var(--ds-radius-md)` and `var(--ds-space-sm)` for internal spacing
- **Border:** `var(--ds-border-width) solid var(--ds-color-border)`

### Button — Variant A

- **Component:** Direct interface action.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-brand)` and `var(--ds-color-text-on-brand)` on brand surfaces
- **Geometry:** `var(--ds-radius-full)` and `var(--ds-space-sm)` for internal spacing
- **Border:** `var(--ds-border-width) solid var(--ds-color-border)`

### Footer

- **Component:** Reusable footer pattern.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-text-primary)` and `var(--ds-color-text-on-brand)` on brand surfaces
- **Geometry:** `var(--ds-radius-md)` and `var(--ds-space-sm)` for internal spacing
- **Border:** `var(--ds-border-width) solid var(--ds-color-border)`

### Form

- **Component:** Reusable form pattern.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-text-primary)` and `var(--ds-color-text-on-brand)` on brand surfaces
- **Geometry:** `var(--ds-radius-md)` and `var(--ds-space-sm)` for internal spacing
- **Border:** `var(--ds-border-width) solid var(--ds-color-border)`

### Header

- **Component:** Reusable header pattern.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-text-primary)` and `var(--ds-color-text-on-brand)` on brand surfaces
- **Geometry:** `var(--ds-radius-md)` and `var(--ds-space-sm)` for internal spacing
- **Border:** `var(--ds-border-width) solid var(--ds-color-border)`

## 7. Interaction contract

### Universal state rules

| State | Visual behavior |
|---|---|
| Initial state | Use `var(--ds-color-surface)`, `var(--ds-color-text-primary)`, `var(--ds-color-border)`, `var(--ds-type-body)` and `var(--ds-radius-md)`. |
| `:hover` | Increase emphasis with `var(--ds-color-brand-hover)` or `var(--ds-color-surface-hover)`; preserve geometry and layout. |
| `:active` | Apply `var(--ds-color-brand-active)` or `var(--ds-color-surface-active)`; preserve dimensions. |
| `:focus-visible` | Show a ring of `var(--ds-focus-ring-width)` using `var(--ds-color-focus)`, with offset `var(--ds-focus-ring-offset)`. |
| `:disabled` | Use `var(--ds-state-disabled-opacity)`, `cursor: not-allowed` and `pointer-events: none`; remove pointer events. |

## 8. Design tokens

```css
:root {
  --ds-color-background: #d5d7da;
  --ds-color-surface: #d5d7da;
  --ds-color-text-primary: #181d27;
  --ds-color-text-secondary: #414651;
  --ds-color-text-muted: #414651;
  --ds-color-text-on-brand: #ffffff;
  --ds-color-border: #e9eaeb;
  --ds-color-brand: #7f56d9;
  --ds-color-brand-hover: color-mix(in srgb, var(--ds-color-brand) 86%, var(--ds-color-text-primary));
  --ds-color-brand-active: color-mix(in srgb, var(--ds-color-brand) 72%, var(--ds-color-text-primary));
  --ds-color-surface-hover: color-mix(in srgb, var(--ds-color-surface) 92%, var(--ds-color-text-primary));
  --ds-color-surface-active: color-mix(in srgb, var(--ds-color-surface) 84%, var(--ds-color-text-primary));
  --ds-color-success: #166534;
  --ds-color-danger: #b91c1c;
  --ds-color-warning: #92400e;
  --ds-color-info: #075985;
  --ds-color-focus: #1d4ed8;
  --ds-font-body: 'union', sans-serif;
  --ds-type-body: 'union', sans-serif 16px 400 / 24px;
  --ds-type-heading-large: 'union', sans-serif 48px 700 / 1.1;
  --ds-type-heading-medium: 'union', sans-serif 32px 600 / 1.2;
  --ds-type-heading-small: 'union', sans-serif 24px 600 / 1.25;
  --ds-type-caption: 'Roboto Mono', sans-serif 12px 500 / 16px;
  --ds-space-xs: 4px;
  --ds-space-sm: 8px;
  --ds-space-md: 16px;
  --ds-space-lg: 24px;
  --ds-space-xl: 40px;
  --ds-border-width: 1px;
  --ds-radius-sm: 4px;
  --ds-radius-md: 12px;
  --ds-radius-full: 9999px;
  --ds-shadow-sm: 0 2px 8px rgb(0 0 0 / 0.12);
  --ds-shadow-inner: inset 0 1px 2px rgb(0 0 0 / 0.12);
  --ds-breakpoint-tablet: 768px;
  --ds-breakpoint-desktop: 1024px;
  --ds-gutter-mobile: 16px;
  --ds-gutter-mobile-large: 24px;
  --ds-gutter-tablet: 32px;
  --ds-gutter-tablet-large: 48px;
  --ds-gutter-desktop: 120px;
  --ds-focus-ring-width: 2px;
  --ds-focus-ring-offset: 2px;
  --ds-state-disabled-opacity: 0.5;
  --ds-transition-fast: 150ms ease-out;
}
```