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:

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

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

<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):

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

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

Build

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/