Apple

# 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 | `#ffffff` | Primary canvas |
| surface | `#ffffff` | Raised surfaces |
| text-primary | `#1d1d1f` | Primary text |
| text-secondary | `#000000` | Secondary text |
| text-muted | `#000000` | Supporting text |
| text-on-brand | `#ffffff` | Text on brand |
| border | `#000000` | Borders and dividers |
| brand | `#2563eb` | 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-primaryfont | `'SF Pro Text', sans-serif` | Body and interface text |
| font-displayfont | `'SF Pro Display', sans-serif` | Display hierarchy |

### Type scale

| Token | Family | Size | Weight | Line height |
|---|---|---:|---:|---:|
| type-navigation | `'SF Pro Text', sans-serif` | `17px` | `400` | `25px` |
| type-smallheading | `'SF Pro Text', sans-serif` | `12px` | `400` | `16.0005px` |
| type-caption | `'SF Pro Text', sans-serif` | `12px` | `400` | `12px` |
| type-button | `'SF Pro Text', sans-serif` | `17px` | `400` | `25px` |
| type-body | `'SF Pro Text', sans-serif` | `14px` | `400` | `18.0008px` |
| type-headingmedium | `'SF Pro Display', sans-serif` | `40px` | `600` | `44px` |
| type-bodystrong | `'SF Pro Text', sans-serif` | `14px` | `600` | `18.0008px` |
| type-headinglarge | `'SF Pro Display', sans-serif` | `56px` | `600` | `60px` |

## 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 | `5px` | Layout scale |
| space-md | `8px` | Layout scale |
| space-lg | `11px` | Layout scale |
| space-xl | `15px` | 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

### Navigation Link — Large

- **Component:** Primary navigation between major destinations.
- **Typography:** `var(--ds-type-body)`
- **Colors:** `var(--ds-color-brand)` 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)`

### Navigation Control

- **Component:** Compact control within site navigation.
- **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)`

### Display Heading

- **Component:** Primary page statement.
- **Typography:** `var(--ds-type-heading-medium)`
- **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)`

### Display Section Heading — Variant A

- **Component:** Introduces a content section.
- **Typography:** `var(--ds-type-heading-medium)`
- **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)`

### Supporting Section Heading — Section Heading

- **Component:** Introduces a content section.
- **Typography:** `var(--ds-type-heading-medium)`
- **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: #ffffff;
  --ds-color-surface: #ffffff;
  --ds-color-text-primary: #1d1d1f;
  --ds-color-text-secondary: #000000;
  --ds-color-text-muted: #000000;
  --ds-color-text-on-brand: #ffffff;
  --ds-color-border: #000000;
  --ds-color-brand: #2563eb;
  --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: 'SF Pro Text', sans-serif;
  --ds-type-body: 'SF Pro Text', sans-serif 16px 400 / 24px;
  --ds-type-heading-large: 'SF Pro Display', sans-serif 48px 700 / 1.1;
  --ds-type-heading-medium: 'SF Pro Display', sans-serif 32px 600 / 1.2;
  --ds-type-heading-small: 'SF Pro Display', sans-serif 24px 600 / 1.25;
  --ds-type-caption: 'SF Pro Text', 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;
}
```