npm package: @seehub/ds-foundation
Description: Not reduced. Revealed. — A constraint-driven monotone design system. 8 structural constraints, 19-axis parametric model, single YAML source generates CSS, TS, JSON, and DTCG tokens.
Author: SEEHUB
Latest version: 0.3.0

# @seehub/ds-foundation

**Not reduced. Revealed.**

A constraint-driven design system where structure reveals essence. 8 structural constraints, 0 chromatic colors, 19-axis parametric model. A single YAML file generates CSS custom properties, TypeScript constants, JSON data, and DTCG-format tokens.

## Philosophy

Form is primary. Color is secondary. We don't subtract — we define constraints, and structure reveals what matters.

- **Monotone Maxxing** — grayscale palette, no chromatic colors. Form speaks, color follows
- **Structurally enforced** — gate scripts make violations impossible at build time
- **Single source of truth** — `tokens.yaml` drives all outputs
- **Accessibility built-in** — all semantic colors meet WCAG AA or AA Large contrast ratios

## Install

```bash
npm install @seehub/ds-foundation
```

## Usage

### CSS Custom Properties

Import the generated CSS to get all design tokens as CSS variables:

```css
/* In your global CSS */
@import "@seehub/ds-foundation/css";
```

This provides `:root` variables for colors, typography, motion, and spacing, with automatic dark mode support via `.dark`, `[data-theme="dark"]`, and `prefers-color-scheme: dark`.

### TypeScript Constants

Import type-safe token values:

```typescript
import {
  palette,
  color,
  font,
  fontWeight,
  fontSize,
  spacing,
  radius,
  motion,
  easing,
  shadow,
} from "@seehub/ds-foundation";

// Type-safe font weight — only 400, 500, 700, 800 allowed
import type { FontWeight, FontSize, Spacing } from "@seehub/ds-foundation";
```

### JSON / DTCG

```typescript
// Raw JSON data (for tooling, /design-system pages, etc.)
import tokens from "@seehub/ds-foundation/json";

// W3C Design Token Community Group format
import dtcg from "@seehub/ds-foundation/dtcg";
```

### Tailwind Integration

```css
/* In your Tailwind CSS file */
@import "@seehub/ds-foundation/tailwind";
```

## Token Reference

### Colors

Monotone palette from `white` to `black` with 12 stops (gray-50 through gray-900).

Semantic roles with light/dark/high-contrast modes:

| Role              | Light    | Dark     | Purpose                |
| ----------------- | -------- | -------- | ---------------------- |
| `--background`    | white    | gray-900 | Page background        |
| `--foreground`    | gray-900 | gray-50  | Primary text           |
| `--color-muted`   | gray-600 | gray-400 | Secondary text (AAA)   |
| `--color-subtle`  | gray-500 | gray-450 | Tertiary text (AA)     |
| `--color-faint`   | gray-450 | gray-500 | Placeholder (AA Large) |
| `--color-border`  | gray-200 | gray-700 | Dividers               |
| `--color-surface` | gray-50  | gray-900 | Card background        |

### Typography

**Font families** (use CSS variables, never raw font names):

- `--font-base` — Noto Sans JP (body text)
- `--font-accent` — Montserrat (headings, labels)
- `--font-mono` — JetBrains Mono (code)

**Allowed weights**: 400, 500, 700, 800 (600 and 900 are prohibited)

**Allowed sizes** (px): 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72, 96

**Typography roles** (available as `.typo-*` CSS classes):

| Role           | Size           | Weight | Family | Use                            |
| -------------- | -------------- | ------ | ------ | ------------------------------ |
| `display`      | clamp(36-84px) | 800    | accent | Hero sections                  |
| `headline`     | 36px           | 800    | accent | Page titles                    |
| `title`        | 24px           | 700    | accent | Section headings               |
| `title-sm`     | 20px           | 700    | accent | Subsection headings            |
| `heading-sm`   | 16px           | 700    | accent | Minor headings                 |
| `dashboard`    | 24px           | 800    | accent | Dashboard headings             |
| `subtitle`     | 16px           | 500    | base   | Descriptions below headings    |
| `body`         | 16px           | 400    | base   | Default body text (lh 1.75)    |
| `body-relaxed` | 16px           | 400    | base   | Long-form Japanese (lh 2.0)    |
| `body-sm`      | 14px           | 400    | base   | Secondary body text            |
| `label`        | 12px           | 500    | accent | Labels, tags (tracking 0.15em) |

**Tag defaults** (generated as CSS rules):

- `h1` → headline (24px/800/accent)
- `h2` → title (20px/700/accent)
- `h3` → title-sm (18px/700/accent)
- `h4` → heading-sm (16px/700/accent)

### Spacing

4px base grid: `0, 2, 4, 8, 12, 16, 24, 32, 48, 64, 96`

Semantic aliases: `xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48) 3xl(64) 4xl(96)`

### Border Radius

Binary only — `0` (sharp: containers, cards) or `9999px` (pill: buttons, tags).

### Motion

Three-tier duration system:

- `--duration-t1` (150ms) — micro interactions (color, border, scale)
- `--duration-t2` (200ms) — component transitions (accordion, dropdown)
- `--duration-t3` (300ms) — page transitions (fade-in, section-enter)

### Layout

`max-width` is prohibited. Always full-width with padding and fluid grid.

## Customization

### Editing tokens

1. Edit `tokens.yaml`
2. Run `node generate.mjs` to regenerate all outputs
3. Run `./ds-sync.sh` to distribute to consuming projects

### Multi-project sync

The package includes `ds-sync.sh` for distributing `ds-tokens.css` across multiple projects. Configure project paths in `ds-consumers.yaml`:

```yaml
consumers:
  - path: my-project/src/app
    canary: true
  - path: other-project/src/app
```

Run `./ds-sync.sh --canary` to sync to canary projects first, verify, then `./ds-sync.sh` for all.

## Gate Scripts

The companion package `@seehub/ds-gates` provides structural verification scripts:

- `check-font-family` — no raw font names (must use CSS variables)
- `check-font-size-scale` — only permitted sizes
- `check-typography-weight` — only 400/500/700/800
- `check-monotone` — no chromatic colors
- `check-spacing-scale` — only permitted spacing values

## Contrast Verification

Import `@seehub/ds-foundation/contrast` for pre-computed contrast ratios of all semantic color pairs, verified against WCAG AA/AAA thresholds.

## Dark Mode

Dark mode activates automatically via:

- CSS class `.dark` on any ancestor
- Data attribute `[data-theme="dark"]`
- OS preference `prefers-color-scheme: dark`

High-contrast mode via `[data-theme="high-contrast"]` and `@media (forced-colors: active)`.

## License

MIT