Seed Design System

A package-backed design system for AI-integrated Next.js apps. The repo contains the published package, @vadimcomanescu/nadicode-design-system, and the in-repo showcase app used to exercise it.

Quick Start

npm install
npm run dev

The dev server runs on http://localhost:5001 and serves the showcase routes under src/app/(showcase)/.

Using Seed In Apps

Consumer apps install Seed through an exact released package version. For unpublished local work, stage a tarball under .nadicode/packages/ and install that committed relative artifact instead. Do not point apps at a live DS repo directory.

Component discovery and consumption go through the catalog. Catalog blocks have no individual subpath exports.

All catalog components implement BaseComponentProps<SeedProps<'Name'>> from @json-render/react. Consumer apps wire defineCatalog() (from @json-render/core) and defineRegistry() (from @json-render/react) to render pages from JSON specs. See docs/json-render-contract.md for the full consumer wiring pattern.

Canonical consumer docs:

• docs/nadicode/SCAFFOLDING_PROCESS.md, normative runtime and ownership contract
• docs/nadicode/ADOPTION_PLAYBOOK.md, step-by-step install and wiring flow
• .agents/skills/nadicode/SKILL.md, synced agent-facing usage guide

Canonical Sources

The repo treats structured truth and prose differently.

• Operational truth lives in package.json scripts and .husky/*.
• The catalog is the single machine-readable component surface. Discovery: @vadimcomanescu/nadicode-design-system/catalog. Components: @vadimcomanescu/nadicode-design-system/catalog/components.
• Public package surface lives in package.json exports, src/catalog/catalog.ts, and bin/shipped-files.json.
• Consumer ownership and package-backed runtime rules live in docs/nadicode/SCAFFOLDING_PROCESS.md.
• Release steps live in docs/releasing-package.md.

Use prose docs for guidance and rationale. Use scripts, manifests, and generated artifacts for anything that must stay machine-accurate.

Maintainer Workflow

Start with:

• AGENTS.md
• docs/conventions.md
• docs/workflow.md
• docs/releasing-package.md

Commands

| Command | Purpose | |---------|---------| | npm run dev | Start the showcase dev server | | npm run typecheck | Generate Next types and run tsc --noEmit | | npm run lint | Run ESLint across source, scripts, and custom rules | | npm run test | Run Vitest | | npm run build | Build the showcase app | | npm run build:lib | Build package artifacts, generated CSS, types, and catalog | | npm run contracts:generate | Regenerate the full shipped contract surface from source | | npm run contracts:check | Verify the shipped contract surface is in sync | | npm run ds:check | Run package/scaffold contract checks | | npm run docs:check | Run docs/reference drift checks | | npm run release:check | Full release gate | | npm run test:visual | Playwright visual regression suite |

Theming

Seed uses a 7-axis style profile system with 6 named profiles:

• theme: light, dark, system
• style: arctic, bloom, vault, void, paper, grid

| Profile | Personality | Darkness Model | Inspired By | |---------|------------|----------------|-------------| | arctic | Clean, precise | dual (light + dark) | Default | | bloom | Warm, organic | light-only | -- | | vault | Luxury, restrained | dual | Stripe | | void | Dark-native, immersive | dark-only | Linear | | paper | Readable, tactile | light-only | Notion | | grid | Stark, structural | monochrome | Vercel |

Each profile defines 7 visual axes: font family, typography weight, shadow philosophy, color temperature, darkness model, border radius, and letter-spacing curve. Switching profiles changes CSS custom property values without component code changes.

import { ThemeProvider, type Style } from '@vadimcomanescu/nadicode-design-system/theme-provider'

<ThemeProvider defaultTheme="system" defaultStyle="vault">
  {children}
</ThemeProvider>

Token values and generated CSS are authored in src/lib/tokens.config.js and emitted through the build pipeline, not maintained by hand in docs. See docs/decisions/0015-seven-axis-style-profiles.md for the full architecture decision.

Chart Chrome Tokens

8 dedicated --color-chart-* CSS custom properties control chart chrome (axes, grids, legends, tooltips, cursors) independently from generic UI tokens. This ensures charts maintain WCAG-compliant contrast even on varied backgrounds.

| Token | Purpose | |-------|---------| | --color-chart-surface | Chart canvas background | | --color-chart-axis | Axis tick labels | | --color-chart-grid | Grid lines | | --color-chart-legend | Legend text | | --color-chart-tooltip-bg | Tooltip background | | --color-chart-tooltip-border | Tooltip border | | --color-chart-tooltip-text | Tooltip text | | --color-chart-cursor | Hover cursor fill |

See ADR 0013 for rationale.