@nadicodeai/design-system 0.1.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# @nadicodeai/design-system
+
+The `@nadicodeai/design-system` npm workspace. `DESIGN.md` is the normative implementation contract for reusable design tokens and package output; the package owns tokens, CSS (structural geometry + framework-agnostic brand display components), assets, and examples. Since ADR 0007 the standard/interactive/section UI ships as React shadcn components from `@nadicodeai/ui`, not as a pure-CSS section layer here. The canonical human brand book lives at `../brand/brand-book/index.html` (see `../brand/AGENTS.md`) and consumes the public CSS bundle.
+
+**Path convention:** every path in this file is relative to `design-system/` (this directory). Repo-root paths are written with a leading `../`. Commands run from inside `design-system/`; from the repo root, use `npm run <script> -w design-system` (the root scripts delegate the same way).
+
+## Boundaries
+
+Plain imperatives are the default. The few hard prohibitions below use `never`/`do not`; treat those as load-bearing.
+
+- Treat `DESIGN.md` as the only reusable implementation contract for colors, tokens, typography, layout doctrine (the `## Layout` page grammar), component behavior, and package exports.
+- Keep `DESIGN.md` contract-only and `@google/design.md` spec-shaped: edit only reusable brand tokens, design rationale, layout doctrine, component semantics, and do/don't guardrails; do not add implementation notes, showcase content, page-specific details, examples, or non-essential narrative.
+- Read `DESIGN.md` before stating colors, tokens, typography, layout doctrine, or component behavior.
+- Preserve approved `DESIGN.md` token and component families unless the user explicitly approves a palette/component migration. Website/kernel CSS is implementation evidence, not the complete palette authority; never delete tokens because current prototypes do not use them or because `@google/design.md lint` reports them as unused.
+- Name implemented grids, components, modules, and page elements as NadicodeAI-owned primitives; source brands such as Vercel or Attio may appear only in reference notes, never in component names, CSS comments, `data-module` values, or public-facing contracts.
+- Calculate page grids, module spans, seams, borders, and element placement from explicit grid math; never hand-place visual structure by eye.
+- Author CSS-bundle work as a reusable design-system component architecture first, not as showcase/page-specific code. The design-system CSS lives in `src/css/` (`tokens.generated` [built from `DESIGN.md`] + `tokens.local` [hand-authored] / `reset`/`foundation`/`motion`/`layout`/`primitives` + `components/*`, mirrored to `dist/css/` and exported as `@nadicodeai/design-system/css`). Since the Tailwind+shadcn migration (ADR 0007) the bundle ships only framework-agnostic brand/display CSS components: the cascade is `@layer tokens, reset, foundation, motion, layout, primitives, components;` (no `sections` layer), and `components/*` holds the agent-chat CSS component family, the run-state `state-tag` family, and `image` — the generic marketing/SaaS component CSS and the whole `sections/*` layer retired to React shadcn components in `@nadicodeai/ui`. The delivery tiers map to real authoring homes: tokens → `tokens.generated`/`tokens.local`; page grammar → `layout.css`; CSS primitives/components → `primitives.css` + `components/*`; specimens → `examples/`. Contracted CSS components are paired with `DESIGN.md components:` entries; the three named CSS-internal components are deliberate no-token exceptions. Pages, site-specific page assemblies, and the standard/interactive/section UI belong to consuming surfaces (`../website/`, `../portal/`, sibling Nadia apps) and to the React package (`@nadicodeai/ui`), not this package. Study current source HTML/CSS for approved external references before implementing similar NadicodeAI primitives, then adapt the structure into NadicodeAI-owned tokens, primitives, and components. Specimen HTML demonstrates only already-defined primitives/components; it never invents component geometry, seams, borders, fillers, heights, or responsive behavior inline. The generated token layer (`tokens.generated.css`) and the Tailwind adapter (`nadicode.theme.css`) are emitted by Style Dictionary (`scripts/sd/`, driven from `scripts/build.ts`) as a complete projection of the `@google/design.md` export — never an allowlist or subset; responsive `@media` switching and composed/`calc` vars live in `layout.css`/`tokens.local.css` and reference emitted `--nc-*` tokens only, while the `.nc-type-*` utility classes live in `foundation.css`. Emitted-but-unreferenced tokens are intentional (the contract drives emission, not consumption), and the generated Tailwind adapter ships light roles only with no `.dark` block; `@nadicodeai/ui/globals.css` may layer semantic `.dark` remaps from generated tokens without adding a new source-token group. Correctness is enforced by export-derived structural parity (`tests/token-structural-parity.test.ts` for the `--nc-*` layer; the per-token `@theme` value loops in `tests/tailwind-v4-theme.test.ts` for the adapter), the narrowed two-way parity between `DESIGN.md` component YAML/prose and the retained CSS component surface (`tests/components-yaml-matches-css.test.ts`, ADR 0007 D4), plus consumer discipline (`tests/consumer-css-discipline.test.ts`), not a byte snapshot (ADR 0006 supersedes ADR 0005 D1–D3/D5; ADR 0005 D4 keeps the generated-adapter no-dark-palette rule).
+- Follow a source-first reference workflow for external visual references: inspect live/source DOM, stylesheet/CSSOM rules, inline styles, custom properties, computed styles, grid tracks, spans, seam ownership, colors, heights, and breakpoints before writing NadicodeAI code. Screenshots are verification evidence only after implementation; never use them as the source for authoring structure, geometry, or CSS.
+- Never derive reusable kernel geometry from screenshots, eyeballing, one-off browser coordinates, or local patch experiments. Browser measurements may verify an implementation after the source CSS/DOM model is understood, but they do not replace reading the source rules that create the behavior.
+- Map every imported visual behavior to either `DESIGN.md`, an existing kernel token/primitive, or an explicit user-approved change before implementation. If the reference leaves a required decision open, or if `DESIGN.md` does not decide it, ask before coding the missing decision, including height/row span, surface color, visual payload, content slots, crosshair placement, and responsive behavior.
+- Never import reference mood, illustration, decorative geometry, dark/light polarity, animation, logo-like shapes, or atmosphere unless the user explicitly asked for that exact trait and it is compatible with `DESIGN.md`. External references provide structure and math first; NadicodeAI tokens and brand rules decide the visual language.
+- Stop and re-read source CSS/DOM before a second visual/CSS patch to the same component. Repeated corrections mean the primitive model is not understood; do not keep stacking patches on top of a guessed model.
+- Enforce single-owner seam geometry in `src/css/` components (the CSS bundle): each visible border, seam, guide, connector, crosshair, and filler edge is drawn by exactly one primitive/component layer at a given coordinate. Keep decorative rules and connector SVGs dimension-bounded to their owning strip/cell so they never overlap cell seams. When a line looks thicker than expected, investigate overlapping ownership with rendered DOM/CSS geometry before changing token color, opacity, or line weight.
+- Treat the design-system kit (`src/css/components/` + the structural-geometry layers) as the consumable CSS surface that consumers compose with their React UI; `examples/` holds static specimens that demonstrate already-defined primitives and CSS components and never invent geometry, seams, heights, or responsive behavior inline. Kit tests and validators assert the current positive surface only — the kit files exist, the `examples/` specimens load, and the `./css` export is wired; they never name or police removed draft routes, page names, copy frames, mock sites, retired sections, or rejected concepts unless the user explicitly asks for a migration window.
+- Do not add `examples/` process docs, composition contracts, proof documents, or planning layers before a working visual draft unless explicitly requested.
+
+Generated-artifact and runtime-JS prohibitions live in the Forbidden Patterns table; per-domain process conventions (CSS/kernel authoring, reference-import workflow) are dispatched by the Task Routing table.
+
+## Package Surface
+
+- Keep package exports aligned with `package.json`.
+- Treat `dist/tokens/nadicode.dtcg.json` and `dist/tailwind/nadicode.tailwind.json` as generated, tracked consumer artifacts.
+- Treat `src/assets/` as the source for exported brand SVG assets.
+- Treat `dist/icons/` as a generated icon set baked from the pinned `lucide-static` dependency by `npm run generate:icons` (also run inside `npm run build`) and exported via `./icons/*`; regenerate by bumping `lucide-static`, never hand-edit.
+- Treat `../docs/experiments/**` as the archived `design-canvas/` prototype source-of-record (the chat-motion/component prototypes that `src/css/motion.css`, `src/js/chat-autoplay.js`, and `tests/chat-showcase.test.ts` re-express); never treat it as the package build, runtime component surface, or normative brand contract.
+
+## Task Routing
+
+| Task | Read first | Then read | Verify |
+| --- | --- | --- | --- |
+| Design token, contract, or token-pipeline change | `DESIGN.md`, `scripts/sd/config.ts`, `scripts/sd/transforms.ts`, `scripts/sd/format-token-layer.ts`, `scripts/sd/format-tailwind-v4-theme.ts` | `npx @google/design.md spec`, `scripts/build.ts`, `tests/token-structural-parity.test.ts`, `tests/consumer-css-discipline.test.ts`, `tests/tailwind-v4-theme.test.ts` | `npm run lint:design && npm run build && npm run test` |
+| Kernel geometry or component work | `DESIGN.md` Layout and Components | `src/css/index.css`, `src/css/layout.css`, `src/css/primitives.css`, `src/css/components/*.css`, `src/css/motion.css`, `tests/kernel-css-architecture.test.ts`, `tests/kernel-rendered-geometry.test.ts` | from design-system/: `npx vitest run tests/kernel-css-architecture.test.ts tests/kernel-rendered-geometry.test.ts` |
+| CSS component or `examples/` specimen work | `DESIGN.md` Layout and Components | `src/css/components/`, `examples/`, `../skills/nadicodeai-brand-copy/SKILL.md`, `../skills/nadicodeai-brand-copy/references/brand-voice-profile.md`, `../skills/nadicodeai-brand-copy/references/voice-examples.md`, `../skills/nadicodeai-brand-copy/references/anti-slop-patterns.md` | `npm run test -- tests/examples-package-coherence.test.ts` |
+| Package consumption or export surface | `README.md` | `package.json`, `scripts/build.ts`, `dist/tailwind/`, `dist/tokens/` | `npm run build && npm run test -- tests/build-produces-exports.test.ts tests/tailwind-v4-theme.test.ts` |
+
+## DESIGN.md Authoring
+
+- Check `npx @google/design.md spec` before adding or changing YAML front matter fields.
+- Put exact reusable values in YAML when they should export through `npm run build`: colors, typography, rounded, spacing, and component fields listed by the current spec.
+- Put application guidance in prose when it describes how to use values: borders, gradients, grid placement, motion, state behavior, responsive composition, markup shape, and accessibility.
+- Keep component identity paired inside `## Components`: every named YAML `components:` entry needs a matching Markdown `**\`component-name\`**` entry in the Components section, and every Markdown component entry in that section needs a matching YAML `components:` entry. YAML carries machine-readable component style hooks; Markdown carries usage, variants, constraints, and judgment.
+- Keep page grammar and composition-pattern semantics in `## Layout`, not in YAML `components:`. The `## Layout` section is the home for the structural page-grammar names; the section-level compositions that arrange them ship as React shadcn components from `@nadicodeai/ui` (ADR 0007), not as a pure-CSS section layer here. Layout and composition names may use exact values from `colors`, `spacing`, `rounded`, and `typography`, but never encode them as component tokens unless the user explicitly approves a spec/export migration.
+- Add a non-spec YAML field only when repo code, a test, or an explicit downstream consumer reads that field.
+- Treat `@google/design.md` warnings as portability signals. Understand whether a warning is a real mistake or a knowingly non-portable contract field before changing the contract.
+
+| WRONG | CORRECT | Why |
+| --- | --- | --- |
+| Add `components.form-input.borderColor` just to say the input has a border | State in prose: `form-input` uses a 1 px solid `{colors.line}` border | `borderColor` is outside the current spec fields, warns, and is not exported as a native component token |
+| Add a semantic color token for a one-off use | Reuse the existing color token in prose unless the new token must vary independently | Avoid orphaned aliases that do not add a real contract boundary |
+
+## Forbidden Patterns
+
+| WRONG | CORRECT | Why |
+| --- | --- | --- |
+| Editing `dist/**` or `src/css/tokens.generated.css` directly | Edit `DESIGN.md`, then run `npm run build`; hand-authored token CSS goes in `src/css/tokens.local.css` | Both are generated from `DESIGN.md`; hand edits are overwritten on the next build |
+| Hand-listing which tokens reach the CSS layer (an allowlist, "runtime subset", rename, or any `@media`/`calc` in `tokens.generated.css`) | Style Dictionary (`scripts/sd/`) emits a complete projection of the `@google/design.md` export: every token `--nc-<exact-name>: <exact-value>`, each name once. Responsive switching and composed/`calc` vars are hand-authored in `layout.css`/`tokens.local.css` and reference emitted `--nc-*` only | The export is the contract; a differing subset is drift. `token-structural-parity.test.ts` (export-derived) fails on any dropped/renamed/added/modified/duplicated var, a name collision, a non-px line-height, or any `@media`/`calc` in the generated layer (ADR 0006) |
+| Hardcoding a color/radius/dimension in `src/css`, `examples/`, or the Tailwind adapter that duplicates or extends a token — including a `var(--token, <hex==its value>)` fallback | Reference the emitted token: `var(--nc-<name>)` / `var(--color-<name>)`. A new value goes to `DESIGN.md` first. There is no exception island: the system ships zero out-of-contract values, and the generated Tailwind adapter ships no dark palette or `.dark` block; UI package `.dark` remaps must reference generated tokens or semantic roles | No second value source may exist; the no-raw-literal and no-second-value-source guards in `consumer-css-discipline.test.ts` forbid duplicate values, fallback-encoded or not (ADR 0006; generated-adapter no-dark per ADR 0005 D4) |
+| "Cleaning up" emitted-but-unreferenced tokens or the responsive alias block | Leave them. Emitted-unreferenced tokens (orphans) are the intended steady state — the contract drives emission, not consumption. Never add an orphan-detection test or delete a token/alias because no prototype uses it | The contract is the palette authority; consumption is not. Deleting unused tokens is the exact silent-removal the boundary rules forbid (ADR 0006) |
+| Adding `render:showcase`, e2e, examples, registry, AI-Elements, or a second runtime JS file | Keep the package to `DESIGN.md`, assets, token/CSS exports, and the single vanilla `src/js/chat-autoplay.js` enhancer (exported via `./css/*`) | Those surfaces were intentionally removed; only the one dependency-free chat auto-play enhancer is carved out |
+| Inventing token or component behavior | Read `DESIGN.md` | The brand contract is single-source |
+| Changing package exports from memory | Read and update `package.json` | Consumers depend on the declared package surface |
+
+## Commands
+
+| Command | When |
+| --- | --- |
+| `npm run lint:design` | After any `DESIGN.md` edit |
+| `npm run build` | After any `DESIGN.md` edit; regenerates `dist/tokens/nadicode.dtcg.json` and `dist/tailwind/nadicode.tailwind.json` |
+| `npm run generate:icons` | After bumping `lucide-static`; rebakes `dist/icons/` (also runs inside `npm run build`) |
+| `npm run test` | Before handoff. Browser-free by design — safe for agents and CI |
+| `npm run test:visual` | OPERATOR-ONLY, run in the foreground. The opt-in browser/`agent-browser` suite (`tests/**/*.visual.ts`) |
+
+## Verification
+
+Before claiming work complete (from this directory, or with `-w design-system` from the repo root):
+
+```bash
+npm run lint:design && npm run build && npm run test
+```
+
+`npm run test` MUST stay browser-free: browser-driven tests live in `tests/**/*.visual.ts` (outside the default `*.test.ts` glob) and run only via `npm run test:visual`. Never add a browser test to the default suite — parallel headless sessions inside the gate are what orphaned Chrome and hung it; that is the real constraint, not `agent-browser` itself.
+
+For a visual check, agents drive `agent-browser` directly: open the rendered page, save a screenshot into the ignored evidence folder (`../tmp/visual-evidence/`), inspect it, confirm it looks right, and **close the session** so no Chrome daemon is left running. Run these checks **sequentially, one page at a time** — never as a parallel suite. The screenshots persist in `../tmp/visual-evidence/` as evidence for the operator to review.
+
+## References
+
+| Path | Purpose |
+| --- | --- |
+| `README.md` | Human-facing package overview and shipped artifact summary |
+| `DESIGN.md` | Normative implementation contract for reusable design tokens and package output |
+| `package.json` | Package name, exports, files, and scripts |
+| `STRATEGY.md` | Design-system project strategy: target problem, approach, key metrics, and active tracks |
+| `scripts/build.ts` | Exports DTCG + Tailwind tokens from `DESIGN.md`, runs the Style Dictionary build for the CSS token layer + Tailwind v4 theme, generates the icon set, then mirrors `dist/css` |
+| `scripts/sd/` | Style Dictionary build: `config.ts` (entrypoints), `transforms.ts` (`name/nc`/`color/nc-hex`/`dimension/nc-px` + FORK-A line-height), `format-token-layer.ts` (OUTPUT 1), `format-tailwind-v4-theme.ts` (OUTPUT 2). See ADR 0006 |
+| `scripts/generate-icons.ts` | Bakes the NadicodeAI icon set into `dist/icons/` from the pinned `lucide-static` dependency |
+| `tests/` | Vitest gate for design lint, build exports, and accepted repo-local validators |
+| `src/assets/` | Package logo SVG exports |
+| `dist/` | Generated token exports tracked for package consumers |
+| `dist/icons/` | Generated Lucide-derived icon set, exported via `./icons/*` |
+| `../docs/adr/` | Decision records (ADR 0005/0006 govern the token pipeline) |
+| `../docs/experiments/` | Archived `design-canvas/` prototype source-of-record for the kernel chat motion and CSS components |
+| `src/css/motion.css` | The brand motion contract: register, the four moves, craft rules, banned moves — read before any animation work |