@nadicodeai/design-system 0.10.2 → 0.11.0

package/AGENTS.md

@@ -1,114 +1,43 @@
 # @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, the entity-status `status-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 owns standard shadcn role maps for both `:root` and `.dark` using generated `--color-*`/`--radius-*` references, plus a set of `--nc-*` remaps in the `:root.dark` block (the surface palette — `canvas*`, `ink`, `body`, `muted`, `line`, `warning-soft`/`-deep` — and the `state-*`, `selection-*`, `cross`, and chart families → their `--nc-dark-*` counterparts) so design-system CSS components that read those raw brand tokens directly flip on the dark console; `@nadicodeai/ui/globals.css` keeps the Tailwind role bridge plus UI-local product aliases. Correctness is enforced by export-derived structural parity (`tests/guards/token-structural-parity.test.ts` for the `--nc-*` layer; the per-token `@theme` value loops and light/dark role-integrity checks in `tests/guards/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/guards/components-yaml-matches-css.test.ts`, ADR 0007 D4), plus consumer discipline (`tests/guards/consumer-css-discipline.test.ts`), not a byte snapshot (ADR 0006 supersedes ADR 0005 D1–D3/D5; ADR 0008 supersedes ADR 0005 D4).
-- 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.
-- The `design-canvas/` prototypes that `src/css/motion.css`, `src/js/chat-autoplay.js`, and `tests/guards/chat-showcase.test.ts` re-express are deleted from the tree; git history retains them under docs/experiments/design-canvas/. The kernel CSS and its tests are the living expression — never reconstruct the prototypes as a build, runtime component surface, or normative brand contract.
-- Any change to package-consumed output (`DESIGN.md`, generated tokens, CSS bundle, Tailwind theme output, package exports, assets, package docs, or agent instructions) must end with an explicit npm release decision before handoff — enforced by the pre-push release gate: bump the version (merge then auto-publishes; see `../docs/agents/npm-publishing.md`) or mark a commit `[no-publish]`. If the change should reach external consumers, bump `@nadicodeai/design-system` and run `npm pack --dry-run -w @nadicodeai/design-system`. When `@nadicodeai/ui` consumes the changed output, publish `@nadicodeai/design-system` first, then bump/update/publish `@nadicodeai/ui`. Never claim the package is shipped to npm until `npm view @nadicodeai/design-system version` reports the intended version.
-
-## 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` | `npm exec --package=@google/design.md -- design.md spec`, `scripts/build.ts`, `tests/guards/token-structural-parity.test.ts`, `tests/guards/consumer-css-discipline.test.ts`, `tests/guards/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/guards/kernel-css-architecture.test.ts`, `tests/guards/kernel-rendered-geometry.test.ts` | from design-system/: `npx vitest run tests/guards/kernel-css-architecture.test.ts tests/guards/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/writing-craft.md`, `../skills/nadicodeai-brand-copy/references/brand-voice-profile.md`, `../skills/nadicodeai-brand-copy/references/voice-examples.md` | `npm run test -- tests/guards/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/guards/build-produces-exports.test.ts tests/guards/tailwind-v4-theme.test.ts` |
-
-## DESIGN.md Authoring
-
-- Check `npm exec --package=@google/design.md -- 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 may ship light/dark role remaps only when every role value references generated `--color-*`/`--radius-*` tokens. Export-anchored generated aliases such as `--color-nadicode-muted` may duplicate the exported value only when a `var()` reference would collide with a downstream semantic bridge; these aliases must be generated from `DESIGN.md` through `scripts/sd/` and covered by tests. UI package `.dark` aliases must reference generated tokens or semantic roles | No second hand-authored 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, outside the generated export-anchored aliases described here (ADR 0006; light/dark role maps per ADR 0008) |
-| "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 |
+The `@nadicodeai/design-system` npm workspace. `DESIGN.md` is the normative contract for reusable design tokens and package output; the package ships tokens, the CSS kit (structural geometry plus framework-agnostic brand display components), and assets. Repo-only `examples/` specimens prove that public surface. Standard, interactive, and section UI ships as React components from `@nadicodeai/ui`, not from here. Paths here are relative to `design-system/`; run commands from this directory, or with `-w design-system` from the repo root.
 
 ## Commands
 
 | Command | When |
 | --- | --- |
 | `npm run lint:design` | After any `DESIGN.md` edit |
-| `npm run lint` | After editing JavaScript or TypeScript tooling, tests, or the chat enhancer |
-| `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`) |
+| `npm run build` | After any `DESIGN.md` edit; regenerates every `dist/` artifact (tokens, Tailwind data, icons, complete CSS bundle) |
+| `npm run generate:icons` | After bumping `lucide-static`; rebakes `dist/icons/` (also runs inside `build`) |
+| `npm run lint` / `npm run test` | After TS/JS changes / before handoff (browser-free) |
+| `npm run test:visual` | Rendered CSS checks (`playwright.visual.config.ts`, `tests/visual/`) |
 
-## Verification
+Handoff gate: `npm run lint:design && npm run lint && npm run build && npm run test`.
 
-Before claiming work complete (from this directory, or with `-w design-system` from the repo root):
+## Routing
 
-```bash
-npm run lint:design && npm run lint && npm run build && npm run test
-```
-
-`npm run test` MUST stay browser-free: browser-driven tests live in `tests/visual/*.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 use the workspace-local `agent-browser` package (`npm exec -w design-system -- agent-browser ...` from the repo root, or `npm exec -- agent-browser ...` from this directory): 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 repo-level `agent-browser.json` and this directory's `agent-browser.json` set the idle timeout for ad hoc commands, but explicit close is still required. The screenshots persist in `../tmp/visual-evidence/` as evidence for the operator to review.
+| Task | Go to |
+| --- | --- |
+| Shared design-language terms | `CONTEXT.md` |
+| Colors, tokens, typography, layout doctrine, seam ownership, component semantics | `DESIGN.md` (read it before stating any of these) |
+| CSS layers, token pipeline, dark remaps, generated outputs, their guards | `DESIGN.md` "CSS Architecture & Token Pipeline"; decision history in `../docs/adr/` |
+| Package exports | `package.json` (guard: `tests/guards/build-produces-exports.test.ts`) |
+| Static or non-React consumption | `README.md` |
+| React consumption | `../@nadicodeai/ui/docs/consuming-cross-repo.md` |
+| Logo semantics and geometry; other assets and icons | `DESIGN.md` "Brand media authority"; implementation routes through `src/assets/`; `dist/` is generated, never hand-edited |
+| `examples/` specimen work | `examples/` plus `../skills/nadicodeai-brand-copy/SKILL.md` for specimen copy (guard: `tests/guards/examples-package-coherence.test.ts`) |
+| Releasing a change to package-consumed output | `../docs/internal/npm-publishing.md` |
+| Visual test implementation | `playwright.visual.config.ts` and `tests/visual/` |
 
-## References
+## Boundaries
 
-| 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 suites, foldered per ADR 0011: `guards/` (the package-spanning gate — design lint, build exports, accepted repo-local validators), `visual/` (opt-in browser suite), `global-setup.ts`. Unit tests for build modules sit beside them in `scripts/` |
-| `agent-browser.json` | Project-level timeout defaults for workspace-local `agent-browser` visual checks |
-| `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) |
-| `src/css/motion.css` | The brand motion contract: register, the four moves, craft rules, banned moves — read before any animation work |
+- Never edit `dist/**` or `src/css/tokens.generated.css` by hand; both regenerate from `DESIGN.md` via `npm run build` (enforced by `tests/guards/token-structural-parity.test.ts` and the DTCG drift check in `tests/guards/consumer-css-discipline.test.ts`).
+- Token-only CSS: no raw color/radius/dimension literal in `src/css/`, `examples/`, or the Tailwind adapter, fallback-encoded or not; a new value enters `DESIGN.md` first (enforced by `tests/guards/consumer-css-discipline.test.ts`).
+- Emitted-but-unreferenced contract tokens are intentional. Runtime aliases and compatibility variables are different: each must have a live caller or be removed (`DESIGN.md` "CSS Architecture & Token Pipeline").
+- `DESIGN.md` `## Components` is the semantic component catalog; CSS is its implementation, and `tests/guards/component-contract-matches-css.test.ts` derives the two-way fence without a copied inventory.
+- `DESIGN.md` stays contract-only and spec-shaped: check `npm exec --package=@google/design.md -- design.md spec` before changing YAML fields; exact reusable values go in YAML, application guidance in prose; add a non-spec YAML field only when repo code or a test reads it (spec-shape don'ts: `DESIGN.md` "Do's and Don'ts").
+- Seams and grids are computed, single-owner, never eyeballed (doctrine home: `DESIGN.md` "## Layout" and "Seam Ownership").
+- External references are source-first: read live DOM/CSSOM rules before authoring; screenshots verify, they never author. Map every imported behavior to `DESIGN.md` or an explicit user approval, ask when the contract leaves a decision open, and never import reference mood, polarity, decoration, or animation uninvited. Stop and re-read source before a second visual patch to the same component.
+- Name everything as NadicodeAI-owned primitives; source brands (Vercel, Attio) appear only in reference notes, never in names, comments, or contracts.
+- Any change to package-consumed output ends with an explicit release decision, a version bump or a `[no-publish]` commit marker (enforced by the pre-push release gate; procedure: `../docs/internal/npm-publishing.md`).
+- The deleted `design-canvas/` prototypes live only in git history. `src/css/motion.css` preserves current runtime transitions and animations, while `src/js/chat-autoplay.js` is the single allowed runtime JS enhancer; never reconstruct the prototypes or add a second runtime JS surface.

package/CONTEXT.md

@@ -0,0 +1,75 @@
+# Design Language
+
+NadicodeAI's shared vocabulary for reusable visual decisions and interface structures. This context lets the design system, React UI package, website, and Portal describe the same visual ideas without inventing package-specific synonyms.
+
+## Language
+
+### Foundations
+
+**Design contract**:
+The normative specification for reusable design tokens, page grammar, component semantics, and visual-surface meanings. Implementations realize the contract; they do not redefine it.
+
+**Design token**:
+A named reusable visual value from the design contract, such as a color, spacing, radius, or typography value. A one-off component detail is not a token.
+
+**Scale step**:
+One numbered value in a functional color scale whose number carries the same interaction or contrast role across every scale.
+_Avoid_: Shade, tint
+
+**Brand tier**:
+The full-strength campi used for identity, imagery, and section grounds. Brand-tier colors are planes, not interface states.
+
+**Functional tier**:
+The numeric color scales and semantic roles used by product UI, charts, and status. Functional-tier colors express interaction and meaning rather than brand fields.
+
+**Campo**:
+A named, full-strength brand color field from the design contract. A campo has no steps or hover variants.
+_Avoid_: Swatch, theme color
+
+**One campo per room**:
+The composition rule that one section or image field owns one campo, with adjacent fields separated by a clear luminance change.
+
+**Luminance jump**:
+The perceptual brightness difference that makes the edge between adjacent campi, or between a campo and its text, read clearly.
+
+### Structure and surfaces
+
+**Page grammar**:
+The shared structural system of frames, rows, lanes, fills, seams, markers, grids, and stages used to compose NadicodeAI pages.
+
+**CSS primitive**:
+A low-level, framework-agnostic CSS helper for geometry, type, seams, fills, or structural behavior. It carries no product-specific meaning.
+
+**CSS component**:
+A framework-agnostic visual component that remains useful on both static and interactive surfaces without owning an app feature.
+
+**Run-state tag**:
+The visual label for the state of agentic work, such as ready, running, review, blocked, or complete.
+_Avoid_: Status badge
+
+**Entity status tag**:
+The visual label for an entity's lifecycle, health, or exception state. It does not represent the state of agentic work.
+_Avoid_: Run-state tag
+
+**Content surface**:
+A visual family for presenting a concrete content type, such as an image or artifact, inside the page grammar.
+
+**Agentic work surface**:
+A NadicodeAI visual family for showing people and agents working together through conversations, artifacts, approvals, tools, handoffs, traces, and inspectable state.
+
+**App-owned product feature**:
+A product-specific route, screen, use case, or behavior owned by the consuming app rather than by the reusable design or UI packages.
+
+### React composition
+
+**React adapter**:
+A thin typed React interface over approved design-system CSS grammar or assets. It exposes the shared implementation without taking ownership of it.
+
+**Reusable composition**:
+A React component that combines shared grammar, primitives, slots, variants, and responsive behavior into a repeatable product or marketing pattern.
+
+**Reusable section**:
+A reusable composition for one recurring content role, such as an introduction, proof area, media block, or call to action.
+
+**Specimen**:
+A runnable example that assembles shipped pieces for inspection without inventing new design rules.