@vadimcomanescu/nadicode-design-system

v10.1.0

Published

5 months ago

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.

0High
0Medium
0Low

vadimcomanescu

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. Server-safe discovery (Zod-only, no React): @vadimcomanescu/nadicode-design-system/catalog. Client-side components via seedComponents: @vadimcomanescu/nadicode-design-system. Mirrors upstream @json-render/shadcn — ADR 0027 supersedes ADR 0011.
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:

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 two independent axes (see ADR 0020):

Style (default, glass, neobrutalism) — surface model, radii, shadow philosophy
Theme (light, dark) — color palette

| Style | Surface | Radii | Dark mode | Personality | |-------|---------|-------|-----------|-------------| | default | Flat, opaque | 6-10 px | light + dark | shadcn baseline — clean and familiar | | glass | Translucent, frosted | 8-16 px | light + dark | Translucent panels, backdrop-filter, ambient glow | | neobrutalism | Flat, solid fills | 0 px | light only | Zero shadows, 2px borders carry structure, heavy weights, uncompromising contrast |

DOM contract: ThemeProvider writes data-style and data-theme attributes on <html>. Absence = default. Nested containers can scope both axes independently using the same attributes.

<html data-style="glass" data-theme="dark">
  <!-- scoped override inside a page section -->
  <div data-style="neobrutalism" data-theme="light">...</div>
</html>

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

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

Consumer brand-accent override: --accent, --accent-foreground, and --ring are consumer-overrideable in seed-palette.css. Derived tokens (shadow-glow-accent, shaders, gradients) follow automatically via oklch(from var(--color-accent) l c h / α) relative-color syntax:

:root {
  --accent: oklch(0.541 0.281 293.0);
  --accent-foreground: oklch(0.985 0 0);
  --ring: oklch(0.541 0.281 293.0);
}

Token values live in one place: src/index.css. Every --token-name is declared there in an allowlisted scope block (:root / [data-style="..."] / [data-theme="..."]), with composites colocated next to their atomic tokens. No codegen, no JS config, no regeneration step. See ADR 0019 for the canonical token vocabulary, ADR 0023 for the move to CSS-as-source, and ADR 0024 for the enforcement suite that locks the invariant.

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme