Mitchell Hou

# DESIGN.md

## 1. Visão geral

Interface orientada por hierarquia visual clara, superfícies consistentes e uma paleta semântica controlada.
Use os tokens e contratos abaixo como fonte normativa para implementação responsiva e acessível.

> Contrato normativo de implementação: preserve os nomes semânticos dos tokens, regras de responsividade e estados de interação ao estender a interface.

## 2. Cores e acessibilidade

### Tokens semânticos de cor

| Token | Valor Hex | Finalidade |
|---|---|---|
| background | `#d5d7da` | Canvas principal |
| surface | `#d5d7da` | Superfícies elevadas |
| text-primary | `#181d27` | Texto principal |
| text-secondary | `#414651` | Texto secundário |
| text-muted | `#414651` | Texto auxiliar |
| text-on-brand | `#ffffff` | Texto sobre a marca |
| border | `#e9eaeb` | Bordas e divisores |
| brand | `#7f56d9` | Ação principal da marca |
| success | `#166534` | Estado positivo |
| danger | `#b91c1c` | Estado destrutivo |
| warning | `#92400e` | Estado de alerta |
| info | `#075985` | Estado informativo |
| focus | `#1d4ed8` | Anel de foco |

### Regras WCAG AA

- Texto normal deve atingir contraste mínimo de 4,5:1.
- Texto grande e elementos de interface devem atingir contraste mínimo de 3:1.
- O foco visível deve manter contraste mínimo de 3:1 e nunca depender apenas de cor.
- Use somente combinações entre tokens semânticos que cumpram essas taxas.

## 3. Tipografia

### Família

| Token | Família | Uso |
|---|---|---|
| font-bodyfont | `'union', sans-serif` | Body and interface text |
| font-monofont | `'Roboto Mono', sans-serif` | Metadata and code |

### Escala tipográfica

| Token | Família | Tamanho | Peso | Altura de linha |
|---|---|---:|---:|---:|
| 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 e espaçamento

### Breakpoints

- **Mobile:** `< 768px` — grid de 1 coluna, gutters de 16px/24px e navegação empilhada.
- **Tablet:** `768px–1023px` — grid adaptativo e gutters de 32px/48px.
- **Desktop:** `>= 1024px` — gutters de 120px e container com largura máxima definida pelo layout.

### Regras responsivas

- **Header:** empilhe navegação e ações no mobile; mantenha a navegação principal em linha a partir do tablet.
- **Hero:** use uma coluna no mobile, composição equilibrada em duas colunas no tablet e o container completo no desktop.
- **Cards:** ocupe a largura do grid no mobile, use duas colunas no tablet e o grid definido no desktop.
- **Grid de navegação: use uma coluna no mobile, colunas adaptativas no tablet e a composição completa no desktop.

### Escala de espaçamento

| Token | Valor | Uso |
|---|---:|---|
| space-xs | `4px` | Escala de layout |
| space-sm | `8px` | Escala de layout |
| space-md | `12px` | Escala de layout |
| space-lg | `16px` | Escala de layout |
| space-xl | `20px` | Escala de layout |

## 5. Formas, bordas e profundidade

### Raios

| Token | Valor | Uso |
|---|---:|---|
| radius-sm | `4px` | Controles compactos |
| radius-md | `12px` | Cards e superfícies |
| radius-full | `9999px` | Pills e controles circulares |

### Bordas e profundidade

- Largura da borda: `var(--ds-border-width)`.
- Estilo da borda: `solid`.
- Cor da borda: `var(--ds-color-border)`.
- Use `var(--ds-shadow-sm)` para elevação baixa e `var(--ds-shadow-inner)` para separação interna.

## 6. Especificação de componentes

### Nav

- **Componente:** Reusable nav pattern.
- **Tipografia:** `var(--ds-type-body)`
- **Cores:** `var(--ds-color-text-primary)` e `var(--ds-color-text-on-brand)` sobre a marca
- **Geometria:** `var(--ds-radius-md)` e `var(--ds-space-sm)` de espaçamento interno
- **Borda:** `var(--ds-border-width) solid var(--ds-color-border)`

### Button — Variant A

- **Componente:** Direct interface action.
- **Tipografia:** `var(--ds-type-body)`
- **Cores:** `var(--ds-color-brand)` e `var(--ds-color-text-on-brand)` sobre a marca
- **Geometria:** `var(--ds-radius-full)` e `var(--ds-space-sm)` de espaçamento interno
- **Borda:** `var(--ds-border-width) solid var(--ds-color-border)`

### Footer

- **Componente:** Reusable footer pattern.
- **Tipografia:** `var(--ds-type-body)`
- **Cores:** `var(--ds-color-text-primary)` e `var(--ds-color-text-on-brand)` sobre a marca
- **Geometria:** `var(--ds-radius-md)` e `var(--ds-space-sm)` de espaçamento interno
- **Borda:** `var(--ds-border-width) solid var(--ds-color-border)`

### Form

- **Componente:** Reusable form pattern.
- **Tipografia:** `var(--ds-type-body)`
- **Cores:** `var(--ds-color-text-primary)` e `var(--ds-color-text-on-brand)` sobre a marca
- **Geometria:** `var(--ds-radius-md)` e `var(--ds-space-sm)` de espaçamento interno
- **Borda:** `var(--ds-border-width) solid var(--ds-color-border)`

### Header

- **Componente:** Reusable header pattern.
- **Tipografia:** `var(--ds-type-body)`
- **Cores:** `var(--ds-color-text-primary)` e `var(--ds-color-text-on-brand)` sobre a marca
- **Geometria:** `var(--ds-radius-md)` e `var(--ds-space-sm)` de espaçamento interno
- **Borda:** `var(--ds-border-width) solid var(--ds-color-border)`

## 7. Contrato de interação

### Regras universais de estado

| Estado | Comportamento visual |
|---|---|
| Estado inicial | Use `var(--ds-color-surface)`, `var(--ds-color-text-primary)`, `var(--ds-color-border)`, `var(--ds-type-body)` e `var(--ds-radius-md)`. |
| `:hover` | Aumente a ênfase com `var(--ds-color-brand-hover)` ou `var(--ds-color-surface-hover)`; preserve geometria e layout. |
| `:active` | Aplique `var(--ds-color-brand-active)` ou `var(--ds-color-surface-active)`; preserve dimensões. |
| `:focus-visible` | Exiba anel de `var(--ds-focus-ring-width)` usando `var(--ds-color-focus)`, com afastamento `var(--ds-focus-ring-offset)`. |
| `:disabled` | Use `var(--ds-state-disabled-opacity)`, `cursor: not-allowed` e `pointer-events: none`; remova eventos de ponteiro. |

## 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;
}
```