veza/packages/design-system/README.md

# @veza/design-system

**SUMI Design System v3.0** — "Lavis d'encre" (Ink wash)

Token-only package for the Veza platform. Single source of truth for all design tokens (colors, typography, spacing, motion, elevation), authored as W3C-spec JSON tokens and compiled via Style Dictionary to CSS variables and TypeScript exports.

## Structure

```
packages/design-system/
├── tokens/                          # SOURCE OF TRUTH (edit these)
│   ├── primitive/
│   │   ├── color.json               # ink, washi, void, mizu, kin, viz, functional, alpha
│   │   ├── typography.json          # Space Grotesk + Inter + JetBrains Mono scales
│   │   ├── spacing.json             # 4px scale + radius + z-index
│   │   ├── motion.json              # goutte/trait/lavis/vague/maree + easings
│   │   └── elevation.json           # shadows + blur + opacity
│   └── semantic/
│       ├── dark.json                # default :root, [data-theme="dark"]
│       └── light.json               # [data-theme="light"] (washi paper)
├── dist/                            # GENERATED (do NOT edit, gitignored)
│   ├── tokens.css                   # Unified primitive + dark + light
│   ├── tokens-{primitive,dark,light}.css
│   └── tokens.{ts,d.ts}             # TS exports of resolved hex values
├── style-dictionary.config.mjs      # Build config
└── package.json
```

## Usage

### CSS variables (recommended for UI)

`apps/web/src/index.css` imports the unified file:

```css
@import '@veza/design-system/tokens.css';
```

Then components reference vars via Tailwind arbitrary values or inline styles:

```tsx
<div style={{ color: 'var(--sumi-accent-default)' }}>...</div>
<div className="bg-[var(--sumi-bg-card)] text-[var(--sumi-text-primary)]">...</div>
```

### TypeScript imports (for canvas / runtime needs)

For contexts that can't resolve CSS vars (canvas drawing, programmatic gradients, byte interpolation):

```ts
import { ColorVizIndigo, SumiAccentDefault } from '@veza/design-system/tokens-generated';

ctx.fillStyle = ColorVizIndigo;     // resolved hex string '#7c9dd6'
const accent = SumiAccentDefault;   // '#0098b5'
```

## Build

```bash
npm run build:tokens --workspace=@veza/design-system
```

Triggered automatically via `turbo run build` (the apps/web build depends on this package).

## Color system — Option B palette

Per `CHARTE_GRAPHIQUE_TALAS.md` §4 (canonical brand source) + §4.5 (data viz):

### UI palette (everywhere except data viz)

The cyan **Mizu** (`#0098B5`) is the **sole** accent color. Functional colors (success/error/warning) are always diluted (max 60% opacity), never solid fills.

| Token | Role | Value |
|-------|------|-------|
| `--sumi-accent-default` | Primary actions, links, focus | Mizu cyan `#0098B5` |
| `--sumi-feedback-success` | Success states (subtle) | Diluted sage |
| `--sumi-feedback-error` | Error states (subtle) | Diluted brick |
| `--sumi-feedback-warning` | Warning states (subtle) | Diluted amber |

### Data viz palette (charts, waveforms, analytics ONLY)

For graphs and visualizations needing distinguishable colors, the 4 viz pigments + neutral are authorized:

| Pigment | Hex | Token |
|---------|-----|-------|
| Indigo | `#7c9dd6` | `--sumi-viz-indigo` |
| Vermillion | `#d4634a` | `--sumi-viz-vermillion` |
| Sage | `#7a9e6c` | `--sumi-viz-sage` |
| Gold | `#c9a84c` | `--sumi-viz-gold` |
| Neutral grey | `#a8a4a0` | `--sumi-viz-neutral` |

**These are NEVER allowed in standard UI** (buttons, links, accents). The cyan rule above stays absolute.

## Themes

- **Dark** (default) — Ink on void
- **Light** — Washi paper aesthetic (`[data-theme="light"]`)
- **Circadian + patina + density + contrast** — Runtime modifiers handled by `apps/web/src/components/theme/ThemeProvider.tsx`

## See also

- Brand source of truth: `~/Documents/TG__Talas_Group/05_EXPERIENCE_UTILISATEUR/CHARTE_GRAPHIQUE_TALAS.md`
- Brand decisions: `~/Documents/TG__Talas_Group/05_EXPERIENCE_UTILISATEUR/DECISIONS_IDENTITE.md`
- Veza UI/UX contract: `veza-docs/ORIGIN/ORIGIN_UI_UX_SYSTEM.md`
- Storybook: `apps/web/.storybook/`
- Component source: `apps/web/src/components/ui/`