veza/packages/design-system/README.md

# @veza/design-system

**SUMI Design System v2.0** — "L'encre et la lumière" (Ink and Light)

The centralized design system for the Veza platform. Provides design tokens, component type registry, and utilities.

## Structure

```
packages/design-system/
├── src/
│   ├── index.ts           # Barrel exports
│   ├── utils.ts           # cn() utility
│   ├── tokens/
│   │   ├── index.ts       # All token exports
│   │   ├── colors.ts      # Background, surface, text, pigment, semantic colors
│   │   ├── typography.ts  # Font families, sizes, weights, line heights
│   │   ├── spacing.ts     # Spacing scale, border radius, z-index, layout
│   │   └── motion.ts      # Duration and easing tokens
│   └── components/
│       └── index.ts       # Component type registry
└── package.json
```

## Usage

### Design Tokens (TypeScript)

```typescript
import { pigments, fontFamilies, spacing } from '@veza/design-system/tokens';

// Colors
pigments.accent.base    // '#7c9dd6'
pigments.vermillion.base // '#d4634a'

// Typography
fontFamilies.heading    // "'Space Grotesk', 'Inter', sans-serif"

// Spacing
spacing['4']            // '16px'
```

### Design Tokens (CSS)

The CSS custom properties are the primary token interface, defined in `apps/web/src/index.css`:

```css
color: var(--sumi-accent);
padding: var(--sumi-space-4);
font-family: var(--sumi-font-heading);
border-radius: var(--sumi-radius-md);
```

### Components

Components are implemented in `apps/web/src/components/ui/` and imported via path alias:

```typescript
import { Button } from '@/components/ui/button';
import { Card } from '@/components/ui/card';
import { Dialog } from '@/components/ui/dialog';
```

See `apps/web/.storybook/` for Storybook documentation of all components.

## Themes

- **Dark** (default) — Ink on void
- **Light** — Washi paper aesthetic (`[data-theme="light"]`)
- **High Contrast** — WCAG AA 4.5:1+ (`[data-contrast="high"]`)
- **Compact Density** — Reduced spacing (`[data-density="compact"]`)

## Color System — The 4 Pigments

| Pigment | Hex | Usage |
|---------|-----|-------|
| **Accent** (Indigo) | `#7c9dd6` | Primary actions, links, focus |
| **Vermillion** | `#d4634a` | Errors, destructive, live |
| **Sage** | `#7a9e6c` | Success, online |
| **Gold** | `#c9a84c` | Warnings, achievements |

## References

- Design tokens source: `apps/web/src/index.css`
- Token documentation: `apps/web/docs/DESIGN_TOKENS.md`
- Storybook: `apps/web/.storybook/`
- Component source: `apps/web/src/components/ui/`