sar/design-artifacts/D-Design-System/00-design-system.md

# Design System: SAR

> Components, tokens, and patterns that grow from actual usage — not upfront planning.

**Created:** 2026-05-26
**Phase:** 7 — Design System (mantida porque AntD 6.4 não cobre tokens/variações JCS)
**Agent:** Freya (Designer)

---

## What Belongs Here

O Design System captura padrões reutilizáveis que emergem durante o UX Design (Fase 4). Para o SAR, ele camada **sobre Ant Design 6.4**, não substitui:

- **Design Tokens** — paleta JCS (`#004a99`, `#f4f7fa`, etc.), Plus Jakarta Sans, radius 12/20px, sombra `0 4px 25px rgba(0,0,0,0.05)` (já em `brand.md`)
- **AntD theming** — variações via `ConfigProvider` do AntD para refletir a marca JCS
- **Componentes JCS** — padrões além do AntD: sidebar 260px fixa, topbar 80px, gradientes de login `#f0f4f8 → #d9e2ec`, cards 360°, kanban CRM
- **Patterns** — layouts (sidebar+topbar), formulários, blocos de conteúdo
- **Visual Design** — mood boards, color exploration (validação de paleta), typography tests
- **Assets** — logos (já em `frontend/img/`), ícones (Font Awesome 6.4), gráficos (Chart.js)

**What does NOT go here:**
- Page-specific content (lives in `C-UX-Scenarios/`)
- Business logic or API specs (BMM territory)
- Aspirational components nobody uses yet

**Learn more:**
- WDS Course Module 12: Functional Components — Patterns Emerge
- WDS Course Module 13: Design System

---

## Folder Structure

```
D-Design-System/
├── 00-design-system.md          ← This file (hub + guide)
├── 01-Visual-Design/            [Early design exploration]
│   ├── mood-boards/
│   ├── design-concepts/
│   ├── color-exploration/
│   └── typography-tests/
├── 02-Assets/                   [Final production assets]
│   ├── logos/                   [Copiar de frontend/img/ quando consolidado]
│   ├── icons/                   [Subset de FA6 efetivamente usado]
│   ├── images/
│   └── graphics/
└── components/                  [Emerges during Phase 4]
    ├── interactive/
    ├── form/
    ├── layout/
    ├── content/
    ├── feedback/
    └── navigation/
```

---

## For Agents

**Workflow:** `skill:wds-7-design-system`
**Agent trigger:** `DS` (Freya)
**Router:** `./resources/wds-7-design-system/design-system-router.md`
**Templates:** `./resources/wds-7-design-system/templates/`
**Guide:** `./resources/agent-guides/freya/design-system.md`

**Before creating any component:**
1. Verificar se já existe no Ant Design 6.4 — usar AntD nativo sempre que possível
2. Olhar uso real em `C-UX-Scenarios/` page specs — extrair, não inventar
3. Documentar overrides/extensões sobre AntD em vez de recriar do zero

**Harm:** Recriar componentes que o AntD já oferece. Inventar tokens que conflitam com `brand.md`.

**Help:** Extrair padrões reais de page specs. Documentar o tema AntD JCS (cores, radius, fonte). Quando 3 páginas usam mesmo layout → vira componente JCS.

---

## Spacing Scale (preliminar — refinar em Phase 4)

> Base 8px (compatível com AntD). `space-md = 16px` é o baseline.

| Token | Value | Use |
|-------|-------|-----|
| space-3xs | 2px | Hairline gaps |
| space-2xs | 4px | Minimal spacing |
| space-xs | 8px | Tight spacing |
| space-sm | 12px | Small gaps |
| **space-md** | 16px | **Default element spacing** |
| space-lg | 24px | Card padding, form fields |
| space-xl | 32px | Section padding |
| space-2xl | 48px | Section gaps |
| space-3xl | 64px | Page-level breathing room |

---

## Type Scale (preliminar — refinar em Phase 4)

> Tipografia: **Plus Jakarta Sans** (pesos 400, 500, 600, 700, 800).

| Token | Value | Use |
|-------|-------|-----|
| text-3xs | 10px | Fine print |
| text-2xs | 11px | Metadata |
| text-xs | 12px | Captions |
| text-sm | 13px | Labels |
| text-md | 14px | Body text (baseline AntD) |
| text-lg | 16px | Emphasis |
| text-xl | 18px | Subheadings |
| text-2xl | 24px | Section titles |
| text-3xl | 32px | Hero headings |

---

## Tokens

**Cores canônicas** (de `brand.md`):

| Papel | Token | Hex |
|---|---|---|
| Primária | `--jcs-blue` | `#004a99` |
| Primária hover | `--jcs-blue-hover` | `#003a7a` |
| Fundo ativo menu | `--jcs-blue-light` | `#e6eff8` |
| Background app | `--bg-body` | `#f4f7fa` |
| Texto principal | `--text-main` | `#2d3748` |
| Texto secundário | `--text-muted` | `#718096` |
| Sucesso/Faturado | `--green` | `#38a169` |
| Alerta/Em aberto | `--orange` | `#ed8936` |
| Erro/Bloqueado | `--red` | `#e53e3e` |
| WhatsApp | `--whatsapp-green` | `#25d366` |

**Bordas e sombras**: `--radius-md: 12px`, `--radius-lg: 20px`, `--shadow: 0 4px 25px rgba(0,0,0,0.05)`.

---

## Patterns

_Padrões serão documentados aqui conforme objetos de spacing recorrerem entre páginas._

---

## Components

_Componentes serão documentados aqui conforme padrões emergirem nos cenários._

Lista preliminar esperada (a confirmar em Phase 4):
- Sidebar 260px fixa com itens hierárquicos
- Topbar 80px com busca + perfil
- Card 360° (visão do cliente)
- Kanban CRM (funil de vendas)
- Tabela de pedidos (Orçamento → Faturado)
- Modal de lançamento de pedido
- Gráfico de comissão/FLEX (Chart.js)

---

_Created using Whiteport Design Studio (WDS) methodology_