@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

npm install @seehub/ds-foundation

Usage

CSS Custom Properties

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

/* 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:

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

// 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

/* 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:

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