@nadicodeai/design-system 0.5.3 → 0.6.0

package/AGENTS.md

@@ -14,7 +14,7 @@ Plain imperatives are the default. The few hard prohibitions below use `never`/`
 - 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 owns standard shadcn role maps for both `:root` and `.dark` using generated `--color-*`/`--radius-*` references, plus a small set of `--nc-*` remaps in the `.dark` block (the `state-*`, `selection-*`, and `cross` 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/token-structural-parity.test.ts` for the `--nc-*` layer; the per-token `@theme` value loops and light/dark role-integrity checks 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 0008 supersedes ADR 0005 D4).
+- 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 owns standard shadcn role maps for both `:root` and `.dark` using generated `--color-*`/`--radius-*` references, plus a small set of `--nc-*` remaps in the `.dark` block (the `state-*`, `selection-*`, and `cross` 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.
@@ -32,21 +32,21 @@ Generated-artifact and runtime-JS prohibitions live in the Forbidden Patterns ta
 - 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.
+- 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 -- 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/writing-craft.md`, `../skills/nadicodeai-brand-copy/references/brand-voice-profile.md`, `../skills/nadicodeai-brand-copy/references/voice-examples.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 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 -- design.md spec` before adding or changing YAML front matter fields.
+- 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.
@@ -89,7 +89,7 @@ Before claiming work complete (from this directory, or with `-w design-system` f
 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.
+`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.
 
@@ -104,11 +104,10 @@ For a visual check, agents use the workspace-local `agent-browser` package (`npm
 | `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 |
+| `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) |
-| `../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 |

package/DESIGN.md

@@ -3,13 +3,17 @@ version: alpha
 name: NadicodeAI Design System
 description: >-
   Reusable design-system contract for NadicodeAI: engineered page geometry,
-  neutral high-contrast surfaces, AI-agent work artifacts, and strict
-  12-column/10-column composition rules for the public website and package
-  token exports.
+  neutral high-contrast product surfaces, AI-agent work artifacts, strict
+  12-column/10-column public-page composition, and the package token exports
+  shared by every NadicodeAI interface.
 
 colors:
   primary: "#008c45"
   on-primary: "#ffffff"
+  action: "#007a3c"
+  action-foreground: "#ffffff"
+  action-hover: "#00602f"
+  action-active: "#00301a"
   ink: "#171717"
   body: "#4d4d4d"
   muted: "#888888"
@@ -17,8 +21,11 @@ colors:
   canvas-soft: "#fafafa"
   canvas-soft-2: "#f5f5f5"
   line: "#e5e5e5"
+  input: "#8f8f8f"
   seam: "#e4e7ec"
   cross: "#a1a1a1"
+  focus-ring: "#007a3c"
+  scrim: "#171717"
   link: "#007a3c"
   link-deep: "#00602f"
   link-bg-soft: "#d9f6e4"
@@ -123,9 +130,15 @@ colors:
   dark-seam: "#1f1f1f"
   dark-primary: "#ededed"
   dark-on-primary: "#0a0a0a"
+  dark-action: "#ededed"
+  dark-action-foreground: "#0a0a0a"
+  dark-action-hover: "#d4d4d4"
+  dark-action-active: "#a3a3a3"
   dark-link: "#9fe6bc"
   dark-link-deep: "#c3f0d4"
   dark-link-bg-soft: "#00301a"
+  dark-focus-ring: "#9fe6bc"
+  dark-scrim: "#f5f5f5"
   dark-error: "#f7b3b5"
   dark-error-soft: "#4a000e"
   dark-error-deep: "#fad3d4"
@@ -270,6 +283,8 @@ rounded:
   md: 6px
   lg: 8px
   xl: 10px
+  2xl: 12px
+  3xl: 16px
   pill-sm: 64px
   pill: 100px
   full: 9999px
@@ -289,6 +304,10 @@ spacing:
   6xl: 128px
   section: 192px
   guide: 1px
+  focus-ring-width: 3px
+  control-height: 32px
+  control-padding-inline: 10px
+  touch-target: 44px
   page-pad: 24px
   page-max-mobile: 448px
   page-max-tablet: 624px
@@ -369,7 +388,7 @@ components:
     backgroundColor: "{colors.canvas-soft}"
     textColor: "{colors.body}"
     typography: "{typography.caption}"
-    rounded: "{rounded.full}"
+    rounded: "{rounded.md}"
     padding: "0px {spacing.xs}"
   filter-chip:
     backgroundColor: "{colors.canvas-soft}"
@@ -502,9 +521,12 @@ Backgrounds are `{colors.background-100}` (page default, white) and `{colors.bac
 
 ### Semantic roles (functional tier)
 
-- **Primary** (`{colors.primary}` = `green-italia-700`): primary actions and primary buttons, always with `{colors.on-primary}` (white) text. Green, not near-black, is now the primary weight; `{colors.ink}` becomes the neutral/secondary button treatment.
-- **Canvas / Line / Cross / Seam** (`{colors.canvas}`, `{colors.line}`, `{colors.cross}`, `{colors.seam}`): white content cells, the universal 1 px divider/seam color, the stronger gray for marks and crosshair markers, and the dashed connector guide. `{colors.line}` is the only token used to tune ordinary seam visibility; do not darken borders, gaps, or dividers locally.
-- **Body / Muted** (`{colors.body}`, `{colors.muted}`): secondary copy and low-priority labels.
+- **Primary brand anchor** (`{colors.primary}` = `green-italia-700`): identity marks and non-text brand accents. It is not the text-bearing action surface; normal-size white text on this green does not clear AA.
+- **Action** (`{colors.action}`, `{colors.action-foreground}`, `{colors.action-hover}`, `{colors.action-active}`): the text-bearing primary-control family. Shadcn `primary` roles map here rather than to the brand anchor. Dark mode uses the corresponding `dark-action-*` roles.
+- **Canvas / Line / Input / Cross / Seam** (`{colors.canvas}`, `{colors.line}`, `{colors.input}`, `{colors.cross}`, `{colors.seam}`): white content cells, the universal decorative 1 px divider, the stronger resting-control boundary, the stronger gray for marks and crosshair markers, and the dashed connector guide. `{colors.line}` owns ordinary seams; `{colors.input}` owns fields and other interactive boundaries that must clear the 3:1 non-text contrast floor. Never darken a decorative border locally to make it behave like a control.
+- **Body / Muted** (`{colors.body}`, `{colors.muted}`): `{colors.body}` is readable supporting copy; `{colors.muted}` is restricted to disabled, inactive, and placeholder content. Do not use muted text for ordinary descriptions, labels, or help text.
+- **Focus ring** (`{colors.focus-ring}` / `{colors.dark-focus-ring}`): the full-opacity `{spacing.focus-ring-width}` keyboard-focus indicator with no offset. It is independent of the resting border and clears the 3:1 non-text contrast floor against the adjacent canvas.
+- **Scrim** (`{colors.scrim}` / `{colors.dark-scrim}`): the semantic modal-overlay foreground. Its opacity is the generated material token declared in `Elevation & Depth`; it is never combined with backdrop blur.
 - **Link** (`{colors.link}` = `green-italia-800`, `{colors.link-deep}` = `green-italia-900`, `{colors.link-bg-soft}` = `green-italia-200`): inline links, navigational accents, and approved/example proof states. Intentionally green, keeping the Italian signal without turning the interface into flag decoration.
 - **Semantic feedback** (`{colors.success}`, `{colors.error}` + `{colors.error-soft}`/`{colors.error-deep}`, `{colors.warning}` + `{colors.warning-soft}`/`{colors.warning-deep}`, `{colors.info}`): validation, caution, approval, and operational feedback. `success` uses `green-italia-700`; `error` uses `red-italia-800` with soft/deep on `red-italia-200`/`red-italia-900`; `warning` uses `amber-600` with soft/deep on `amber-200`/`amber-900`; `info` (`blue-cobalto-700`) is the new informational role.
 - **Accent** (`{colors.accent}` = `red-italia-700`): UI highlights, badges, and selected markers. Flag red is now an active accent — the former "decoration-only" restriction on flag red is retired. Do not conflate this functional Italia `accent` with the identically-named shadcn surface role `accent`: the latter is a neutral (mapped to `{colors.canvas-soft-2}` in light and `{colors.dark-canvas-soft-2}` in dark) and carries no flag-red hue despite the shared word.
@@ -533,7 +555,7 @@ Four campo rules govern their use:
 
 ### Dark primitives
 
-**Dark Primitives** (`{colors.dark-canvas}`, `{colors.dark-ink}`, `{colors.dark-line}`, and siblings) are the source tokens for the generated shadcn `.dark` role map — mode-bearing primitives, not a separate palette; consuming apps opt in by applying a `.dark` ancestor through their runtime theme provider. The dark neutrals (`dark-canvas`, `dark-canvas-soft`, `dark-canvas-soft-2`, `dark-ink`, `dark-body`, `dark-muted`, `dark-line`, `dark-input`, `dark-seam`, `dark-primary`, `dark-on-primary`) are true neutrals: each is a pure gray (equal channels) so the interface carries no ambient tint, and they step in clear elevation planes (`dark-canvas` → `dark-canvas-soft` → `dark-canvas-soft-2`). `dark-input` is the resting text-input boundary, held one gray brighter than the decorative `dark-line` border so a field edge clears non-text contrast before the focus ring appears. Chroma lives only in the intentional accents: the dark semantic ramps ride the same Italia scales as their light counterparts, moved to lighter steps where they are text-bearing — `dark-link`/`dark-link-deep` on `green-italia-400`/`green-italia-300`, `dark-error`/`dark-error-deep` on `red-italia-400`/`red-italia-300`, `dark-warning`/`dark-warning-deep` on `amber-400`/`amber-300`, with the `*-soft` tinted grounds on each scale's `1000` step, plus `dark-success` on `green-italia-500` for the positive-feedback green. The `dark-state-*` workflow family is not a text role; it preserves the matching ready/running/review/blocked/complete rail colors for 3 px state accents while text stays on neutral foreground roles. The remaining dark-ramp members stay true-neutral: `dark-selection-bg`/`dark-selection-fg` invert the light selection (a bright neutral ground with dark text) and `dark-cross` is the visible mark gray, brighter than the decorative `dark-line`. Never reintroduce hue into the neutral set.
+**Dark Primitives** (`{colors.dark-canvas}`, `{colors.dark-ink}`, `{colors.dark-line}`, and siblings) are the source tokens for the generated shadcn `.dark` role map — mode-bearing primitives, not a separate palette; consuming apps opt in by applying a `.dark` ancestor through their runtime theme provider. The dark neutrals (`dark-canvas`, `dark-canvas-soft`, `dark-canvas-soft-2`, `dark-ink`, `dark-body`, `dark-muted`, `dark-line`, `dark-input`, `dark-seam`, `dark-primary`, `dark-on-primary`, `dark-action`, `dark-action-foreground`, `dark-action-hover`, `dark-action-active`, and `dark-scrim`) are true neutrals: each is a pure gray (equal channels) so the interface carries no ambient tint, and they step in clear elevation planes (`dark-canvas` → `dark-canvas-soft` → `dark-canvas-soft-2`). `dark-input` is the resting-control boundary, held one gray brighter than the decorative `dark-line` border so a field edge clears non-text contrast before `{colors.dark-focus-ring}` appears. Chroma lives only in the intentional accents: the dark semantic ramps ride the same Italia scales as their light counterparts, moved to lighter steps where they are text-bearing — `dark-link`/`dark-link-deep` on `green-italia-400`/`green-italia-300`, `dark-error`/`dark-error-deep` on `red-italia-400`/`red-italia-300`, `dark-warning`/`dark-warning-deep` on `amber-400`/`amber-300`, with the `*-soft` tinted grounds on each scale's `1000` step, plus `dark-success` on `green-italia-500` for the positive-feedback green. The `dark-state-*` workflow family is not a text role; it preserves the matching ready/running/review/blocked/complete rail colors for 3 px state accents while text stays on neutral foreground roles. The remaining dark-ramp members stay true-neutral: `dark-selection-bg`/`dark-selection-fg` invert the light selection, `dark-scrim` supplies the modal foreground, and `dark-cross` is the visible mark gray, brighter than the decorative `dark-line`. Never reintroduce hue into the neutral set.
 
 This grayscale-only discipline is not dark-specific: it governs the whole generated shadcn surface-role bridge in both the light `:root` and dark `.dark` maps. The surface-role family — `background`, `card`, `popover`, `muted`, `secondary`, the `sidebar` roles and their `-foreground`/`-border` variants, plus `border` and `input` — resolves only to pure grays (equal channels) in both themes; hue in the role bridge is reserved for `primary`, `destructive`, and the focus rings (`ring`/`sidebar-ring`). In dark product shells, `background`, `card`, `popover`, and `sidebar` share `{colors.dark-canvas}` so page chrome, cards, tables, overlays, and nav rails read as one black console. `muted`, `secondary`, and `accent` retain the `dark-canvas-soft` steps for small interaction states such as hover, selected rows, keycaps, and inline controls. Large product surfaces never take a tinted or soft-panel fill by default.
 
@@ -681,19 +703,46 @@ These live helpers are part of the kept page-grammar layout layer. They are not
 
 ## Elevation & Depth
 
-NadicodeAI website depth is flat and architectural. Hairlines, contrast, dotted fields, diagonal fills, and dark action bands create hierarchy. Shadows are optional for small artifact cards only and must stay subtle.
+NadicodeAI website depth is flat and architectural. Hairlines, contrast, dotted fields, diagonal fills, and dark action bands create hierarchy. The public website does not use floating card stacks as its main structure; the page frame and row grid remain dominant.
+
+Product UI uses explicit material roles. Resting content surfaces use no shadow; hierarchy comes from one owned border, spacing, and surface contrast. Shadows identify genuinely floating UI only. The same low-opacity black shadow stacks are used in light and dark themes so elevation does not change character between modes.
+
+The Google design schema does not define elevation or opacity groups. These declarations are therefore the authored material-token source inside this contract. The build reads this block strictly, emits generated `--nc-*` hooks, and maps Tailwind's named opacity and shadow utilities to them; consumers never repeat these values.
+
+```css material-tokens
+--nc-material-scrim-opacity: 10%;
+--nc-material-shadow-tooltip: 0 1px 1px rgb(0 0 0 / 2%), 0 4px 8px rgb(0 0 0 / 4%);
+--nc-material-shadow-menu: 0 1px 1px rgb(0 0 0 / 2%), 0 4px 8px -4px rgb(0 0 0 / 4%), 0 16px 24px -8px rgb(0 0 0 / 6%);
+--nc-material-shadow-dialog: 0 1px 1px rgb(0 0 0 / 2%), 0 8px 16px -4px rgb(0 0 0 / 4%), 0 24px 32px -8px rgb(0 0 0 / 6%);
+--nc-material-shadow-sheet: 0 2px 2px rgb(0 0 0 / 4%), 0 8px 16px -4px rgb(0 0 0 / 4%);
+```
+
+| Material role | Border / radius | Elevation | Internal spacing |
+| --- | --- | --- | --- |
+| Resting content surface | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.md}` (6 px) | none | 24 px, or 16 px only for an explicitly compact surface |
+| Resting control | 1 px `{colors.input}` / `{colors.dark-input}`; `{rounded.md}` (6 px) | none | `{spacing.control-padding-inline}` inline; `{spacing.xs}` block for textareas; minimum height `{spacing.control-height}` |
+| Tooltip | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.md}` (6 px) | tooltip shadow | 6 px block / 12 px inline |
+| Menu | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.2xl}` (12 px) | menu shadow | 4 px |
+| Popover | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.2xl}` (12 px) | menu shadow | 10 px |
+| Dialog | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.2xl}` (12 px) | dialog shadow | 24 px body / 16 px footer |
+| Inset sheet | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.3xl}` (16 px) | sheet shadow | 12 px outer inset / 24 px sections |
+| Takeover | 1 px `{colors.line}` / `{colors.dark-line}`; `{rounded.3xl}` (16 px) | dialog shadow | 24 px |
+
+Modal overlays use `{colors.scrim}` / `{colors.dark-scrim}` at the generated `scrim` opacity with no blur. Focus is not elevation: controls use a full-opacity `{spacing.focus-ring-width}` `{colors.focus-ring}` / `{colors.dark-focus-ring}` ring with no offset. Avoid nested decorative borders: one container owns containment, while child groups use spacing, headings, or dividers only when those dividers clarify structure.
 
-The public website should not rely on floating card stacks as the main structure. Cards may exist inside a cell as an artifact, but the page frame and row grid must remain the dominant structure.
+On coarse or non-hover input capability, every interactive target is at least 44 × 44 px at every viewport width. A compact visual mark such as a checkbox or radio stays compact while its label or hit area supplies the target size. Fine, hover-capable pointers may use the compact control scale.
 
 ## Shapes
 
-Corners are restrained.
+Corners are restrained and assigned by material role.
 
 - Use `{rounded.none}` for page rows, frame edges, grid cells, and structural modules.
-- Use `{rounded.sm}` to `{rounded.lg}` for buttons, chips, status tags, chat bubbles, and small artifacts.
-- Use `{rounded.full}` only for truly circular identity or avatar chrome.
+- Use `{rounded.md}` (6 px) for resting content surfaces, controls, buttons, chips, status tags, tooltips, chat bubbles, and small artifacts.
+- Use `{rounded.2xl}` (12 px) for menus, popovers, and dialogs.
+- Use `{rounded.3xl}` (16 px) for inset sheets and takeovers.
+- Use `{rounded.full}` only for intrinsically circular identity/avatar chrome and compact control marks whose geometry is inherently round or pill-shaped. It never turns a content surface, button, badge, or navigation item into a pill by default.
 
-Cards are not rounded by default. A cell is usually square because its parent frame supplies the visual system.
+Public page-grammar cells are not cards and remain square because their parent frame supplies the visual system. Product cards are resting content surfaces and use the 6 px role above; they do not gain thicker borders, nested frames, or a shadow merely because they contain grouped settings.
 
 ## Components
 
@@ -703,7 +752,7 @@ Component entries are grouped by design-system family so the decision model stay
 
 Interface CSS components provide small metadata, label, and link chrome. They inherit NadicodeAI tokens and stay subordinate to the page grammar; they must not create independent layout systems or repair structural seams. The generic interactive controls (navigation, buttons, inputs, footer chrome, the marketing card/code/pricing/proof surfaces, the standard sections) ship as React shadcn components from `@nadicodeai/ui`; this contract keeps only the brand/display CSS components and primitives that belong in the framework-agnostic package.
 
-Interactive CSS components must expose a visible `:focus-visible` state using the NadicodeAI link/accent family or a contrast-safe inverse on dark surfaces. Do not remove outlines without an equivalent replacement.
+Interactive CSS components must expose a visible `:focus-visible` state using the `{spacing.focus-ring-width}` full-opacity `{colors.focus-ring}` / `{colors.dark-focus-ring}` role with no offset. Do not remove outlines without that contrast-safe equivalent.
 
 **`label-mono`** — mono eyebrow/label text for section labels and low-priority metadata.
 
@@ -737,7 +786,7 @@ Agentic work surfaces are the NadicodeAI-specific layer. They show people and ag
 
 **`tool-call-trace`** — compact code/trace row. Use only when tool use is relevant to the explanation.
 
-State-tag variants share the same shape — a compact rectangular pill at `{typography.caption-mono}` — and differentiate by a 3 px colored `border-left` consuming the matching `{colors.state-*}` token. Shape carries meaning; color carries variant. State is never conveyed through swatches, dots, pulses, breathing animations, or loading spinners.
+State-tag variants share the same compact rectangular shape at `{typography.caption-mono}` and differentiate by a 3 px colored `border-left` consuming the matching `{colors.state-*}` token. Shape carries meaning; color carries variant. State is never conveyed through swatches, dots, pulses, breathing animations, or loading spinners.
 
 **`state-tag-ready`** — workflow state tag for work that is ready or waiting to start. Uses `{colors.state-ready}` for the left edge.
 
@@ -769,6 +818,8 @@ State-tag variants share the same shape — a compact rectangular pill at `{typo
 - Do keep centered content in the 10-column `active-lane` while preserving visible ownership of columns 1 and 12.
 - Do use `side-fill`, guide strips, or component-owned fillers whenever content does not occupy the outer columns.
 - Do use `{spacing.guide}` and `{colors.line}` for ordinary seams.
+- Do use `{colors.input}` / `{colors.dark-input}` for resting control boundaries and the dedicated focus-ring roles for keyboard focus.
+- Do use exactly one material role per container: resting surfaces are border-only; menus, popovers, dialogs, sheets, and takeovers use their specified floating treatment.
 - Do tune line visibility by changing `{colors.line}` at the token contract, then rebuilding generated exports.
 - Do use `{colors.cross}` for crosshair color while keeping crosshair weight equal to `{spacing.guide}`.
 - Do use fixed height tokens for default component/specimen height and let content grow only when required.
@@ -783,6 +834,8 @@ State-tag variants share the same shape — a compact rectangular pill at `{typo
 - Don't create naked centered 10-column sections without visible ownership of columns 1 and 12.
 - Don't draw the same seam from two adjacent elements.
 - Don't add borders inside cells to fix visual seams; fix the owner layer.
+- Don't use a 1 px decorative line as an input boundary, or locally increase card border weight to manufacture hierarchy.
+- Don't stack borders around nested groups, add shadows to resting cards, or blur modal scrims.
 - Don't tune seam contrast with local opacity, raw colors, or component-specific border colors.
 - Don't use viewport-scaled typography.
 - Don't use negative letter spacing in the website kernel.

package/README.md

@@ -120,4 +120,4 @@ For motion, the package ships exactly one optional, vanilla, dependency-free enh
 
 Use the monorepo's `brand/brand-book/` for NadicodeAI story, positioning, buyer, promise, method, use cases, technology story, trust doctrine, identity, voice, visual direction, sales behavior, language, and boundaries.
 
-The archived `design-canvas/` prototype source-of-record (the chat motion and component prototypes the kernel re-expresses) lives in the monorepo's `docs/experiments` and is not package runtime or current brand canon.
+The `design-canvas/` prototypes the kernel re-expresses (chat motion and component prototypes) are deleted from the tree; git history retains them under `docs/experiments/design-canvas/`. They are not package runtime or current brand canon.

package/dist/css/components/approval-gate.css

@@ -96,6 +96,6 @@
 }
 
 .nc-approval-gate-actions button:focus-visible {
-  outline: var(--nc-guide) solid var(--nc-link);
-  outline-offset: 2px;
+  outline: var(--nc-focus-ring-width) solid var(--nc-focus-ring);
+  outline-offset: 0;
 }

package/dist/css/primitives.css

@@ -305,8 +305,8 @@
 }
 
 .nc-filter-chip:focus-visible {
-  outline: 2px solid var(--nc-link);
-  outline-offset: 2px;
+  outline: var(--nc-focus-ring-width) solid var(--nc-focus-ring);
+  outline-offset: 0;
 }
 
 /* nc-link-inline — the inline body link style (DESIGN.md link-inline). It reads
@@ -332,9 +332,9 @@
 }
 
 .nc-link-inline:focus-visible {
-  outline: 2px solid var(--nc-link);
-  outline-offset: 2px;
-  border-radius: var(--nc-rounded-xs);
+  outline: var(--nc-focus-ring-width) solid var(--nc-focus-ring);
+  outline-offset: 0;
+  border-radius: var(--nc-rounded-md);
 }
 
 /* nc-label-mono — the mono eyebrow/kicker for section labels and low-priority

package/dist/css/tokens.generated.css

@@ -7,6 +7,10 @@
   /* Colors */
   --nc-primary: #008c45;
   --nc-on-primary: #ffffff;
+  --nc-action: #007a3c;
+  --nc-action-foreground: #ffffff;
+  --nc-action-hover: #00602f;
+  --nc-action-active: #00301a;
   --nc-ink: #171717;
   --nc-body: #4d4d4d;
   --nc-muted: #888888;
@@ -14,8 +18,11 @@
   --nc-canvas-soft: #fafafa;
   --nc-canvas-soft-2: #f5f5f5;
   --nc-line: #e5e5e5;
+  --nc-input: #8f8f8f;
   --nc-seam: #e4e7ec;
   --nc-cross: #a1a1a1;
+  --nc-focus-ring: #007a3c;
+  --nc-scrim: #171717;
   --nc-link: #007a3c;
   --nc-link-deep: #00602f;
   --nc-link-bg-soft: #d9f6e4;
@@ -120,9 +127,15 @@
   --nc-dark-seam: #1f1f1f;
   --nc-dark-primary: #ededed;
   --nc-dark-on-primary: #0a0a0a;
+  --nc-dark-action: #ededed;
+  --nc-dark-action-foreground: #0a0a0a;
+  --nc-dark-action-hover: #d4d4d4;
+  --nc-dark-action-active: #a3a3a3;
   --nc-dark-link: #9fe6bc;
   --nc-dark-link-deep: #c3f0d4;
   --nc-dark-link-bg-soft: #00301a;
+  --nc-dark-focus-ring: #9fe6bc;
+  --nc-dark-scrim: #f5f5f5;
   --nc-dark-error: #f7b3b5;
   --nc-dark-error-soft: #4a000e;
   --nc-dark-error-deep: #fad3d4;
@@ -171,6 +184,10 @@
   --nc-6xl: 128px;
   --nc-section: 192px;
   --nc-guide: 1px;
+  --nc-focus-ring-width: 3px;
+  --nc-control-height: 32px;
+  --nc-control-padding-inline: 10px;
+  --nc-touch-target: 44px;
   --nc-page-pad: 24px;
   --nc-page-max-mobile: 448px;
   --nc-page-max-tablet: 624px;
@@ -225,6 +242,8 @@
   --nc-rounded-md: 6px;
   --nc-rounded-lg: 8px;
   --nc-rounded-xl: 10px;
+  --nc-rounded-2xl: 12px;
+  --nc-rounded-3xl: 16px;
   --nc-rounded-pill-sm: 64px;
   --nc-rounded-pill: 100px;
   --nc-rounded-full: 9999px;
@@ -315,4 +334,11 @@
   --nc-type-button-lg-font-weight: 500;
   --nc-type-button-lg-line-height: 24px;
   --nc-type-button-lg-letter-spacing: 0px;
+
+  /* Material opacity and shadows (strictly parsed from DESIGN.md prose) */
+  --nc-material-scrim-opacity: 10%;
+  --nc-material-shadow-tooltip: 0 1px 1px rgb(0 0 0 / 2%), 0 4px 8px rgb(0 0 0 / 4%);
+  --nc-material-shadow-menu: 0 1px 1px rgb(0 0 0 / 2%), 0 4px 8px -4px rgb(0 0 0 / 4%), 0 16px 24px -8px rgb(0 0 0 / 6%);
+  --nc-material-shadow-dialog: 0 1px 1px rgb(0 0 0 / 2%), 0 8px 16px -4px rgb(0 0 0 / 4%), 0 24px 32px -8px rgb(0 0 0 / 6%);
+  --nc-material-shadow-sheet: 0 2px 2px rgb(0 0 0 / 4%), 0 8px 16px -4px rgb(0 0 0 / 4%);
 }

package/dist/tailwind/nadicode.tailwind.json

@@ -4,6 +4,10 @@
       "colors": {
         "primary": "#008c45",
         "on-primary": "#ffffff",
+        "action": "#007a3c",
+        "action-foreground": "#ffffff",
+        "action-hover": "#00602f",
+        "action-active": "#00301a",
         "ink": "#171717",
         "body": "#4d4d4d",
         "muted": "#888888",
@@ -11,8 +15,11 @@
         "canvas-soft": "#fafafa",
         "canvas-soft-2": "#f5f5f5",
         "line": "#e5e5e5",
+        "input": "#8f8f8f",
         "seam": "#e4e7ec",
         "cross": "#a1a1a1",
+        "focus-ring": "#007a3c",
+        "scrim": "#171717",
         "link": "#007a3c",
         "link-deep": "#00602f",
         "link-bg-soft": "#d9f6e4",
@@ -117,9 +124,15 @@
         "dark-seam": "#1f1f1f",
         "dark-primary": "#ededed",
         "dark-on-primary": "#0a0a0a",
+        "dark-action": "#ededed",
+        "dark-action-foreground": "#0a0a0a",
+        "dark-action-hover": "#d4d4d4",
+        "dark-action-active": "#a3a3a3",
         "dark-link": "#9fe6bc",
         "dark-link-deep": "#c3f0d4",
         "dark-link-bg-soft": "#00301a",
+        "dark-focus-ring": "#9fe6bc",
+        "dark-scrim": "#f5f5f5",
         "dark-error": "#f7b3b5",
         "dark-error-soft": "#4a000e",
         "dark-error-deep": "#fad3d4",
@@ -351,6 +364,8 @@
         "md": "6px",
         "lg": "8px",
         "xl": "10px",
+        "2xl": "12px",
+        "3xl": "16px",
         "pill-sm": "64px",
         "pill": "100px",
         "full": "9999px"
@@ -370,6 +385,10 @@
         "6xl": "128px",
         "section": "192px",
         "guide": "1px",
+        "focus-ring-width": "3px",
+        "control-height": "32px",
+        "control-padding-inline": "10px",
+        "touch-target": "44px",
         "page-pad": "24px",
         "page-max-mobile": "448px",
         "page-max-tablet": "624px",

package/dist/tailwind/nadicode.theme.css

@@ -10,19 +10,22 @@
   --card-foreground: var(--color-ink);
   --popover: var(--color-canvas);
   --popover-foreground: var(--color-ink);
-  --primary: var(--color-nadicode-primary);
-  --primary-foreground: var(--color-on-primary);
+  --primary: var(--color-action);
+  --primary-foreground: var(--color-action-foreground);
+  --primary-hover: var(--color-action-hover);
+  --primary-active: var(--color-action-active);
   --secondary: var(--color-canvas-soft);
   --secondary-foreground: var(--color-ink);
   --muted: var(--color-canvas-soft);
-  --muted-foreground: var(--color-nadicode-muted);
+  --muted-foreground: var(--color-body);
   --accent: var(--color-canvas-soft-2);
   --accent-foreground: var(--color-ink);
   --destructive: var(--color-error);
   --destructive-foreground: var(--color-on-primary);
   --border: var(--color-line);
-  --input: var(--color-line);
-  --ring: var(--color-link);
+  --input: var(--color-nadicode-input);
+  --ring: var(--color-focus-ring);
+  --scrim: var(--color-nadicode-scrim);
   --chart-1: var(--color-nadicode-chart-1);
   --chart-2: var(--color-nadicode-chart-2);
   --chart-3: var(--color-nadicode-chart-3);
@@ -35,7 +38,7 @@
   --sidebar-accent: var(--color-canvas-soft-2);
   --sidebar-accent-foreground: var(--color-ink);
   --sidebar-border: var(--color-line);
-  --sidebar-ring: var(--color-link);
+  --sidebar-ring: var(--color-focus-ring);
 }
 
 .dark {
@@ -46,19 +49,22 @@
   --card-foreground: var(--color-dark-ink);
   --popover: var(--color-dark-canvas);
   --popover-foreground: var(--color-dark-ink);
-  --primary: var(--color-dark-primary);
-  --primary-foreground: var(--color-dark-on-primary);
+  --primary: var(--color-dark-action);
+  --primary-foreground: var(--color-dark-action-foreground);
+  --primary-hover: var(--color-dark-action-hover);
+  --primary-active: var(--color-dark-action-active);
   --secondary: var(--color-dark-canvas-soft);
   --secondary-foreground: var(--color-dark-ink);
   --muted: var(--color-dark-canvas-soft);
-  --muted-foreground: var(--color-dark-muted);
+  --muted-foreground: var(--color-dark-body);
   --accent: var(--color-dark-canvas-soft-2);
   --accent-foreground: var(--color-dark-ink);
   --destructive: var(--color-dark-error);
   --destructive-foreground: var(--color-dark-on-primary);
   --border: var(--color-dark-line);
   --input: var(--color-dark-input);
-  --ring: var(--color-dark-link);
+  --ring: var(--color-dark-focus-ring);
+  --scrim: var(--color-dark-scrim);
   --chart-1: var(--color-dark-chart-1);
   --chart-2: var(--color-dark-chart-2);
   --chart-3: var(--color-dark-chart-3);
@@ -71,10 +77,17 @@
   --sidebar-accent: var(--color-dark-canvas-soft-2);
   --sidebar-accent-foreground: var(--color-dark-ink);
   --sidebar-border: var(--color-dark-line);
-  --sidebar-ring: var(--color-dark-link);
+  --sidebar-ring: var(--color-dark-focus-ring);
 }
 
 :root.dark {
+  --nc-action: var(--nc-dark-action);
+  --nc-action-foreground: var(--nc-dark-action-foreground);
+  --nc-action-hover: var(--nc-dark-action-hover);
+  --nc-action-active: var(--nc-dark-action-active);
+  --nc-input: var(--nc-dark-input);
+  --nc-focus-ring: var(--nc-dark-focus-ring);
+  --nc-scrim: var(--nc-dark-scrim);
   --nc-state-ready: var(--nc-dark-state-ready);
   --nc-state-running: var(--nc-dark-state-running);
   --nc-state-review: var(--nc-dark-state-review);
@@ -114,6 +127,10 @@
   --nadicode-spacing-6xl: var(--spacing-nadicode-6xl);
   --nadicode-spacing-section: var(--spacing-nadicode-section);
   --nadicode-spacing-guide: var(--spacing-nadicode-guide);
+  --nadicode-spacing-focus-ring-width: var(--spacing-nadicode-focus-ring-width);
+  --nadicode-spacing-control-height: var(--spacing-nadicode-control-height);
+  --nadicode-spacing-control-padding-inline: var(--spacing-nadicode-control-padding-inline);
+  --nadicode-spacing-touch-target: var(--spacing-nadicode-touch-target);
   --nadicode-spacing-page-pad: var(--spacing-nadicode-page-pad);
   --nadicode-spacing-page-max-mobile: var(--spacing-nadicode-page-max-mobile);
   --nadicode-spacing-page-max-tablet: var(--spacing-nadicode-page-max-tablet);
@@ -166,6 +183,10 @@
 @theme {
   --color-primary: #008c45;
   --color-on-primary: #ffffff;
+  --color-action: #007a3c;
+  --color-action-foreground: #ffffff;
+  --color-action-hover: #00602f;
+  --color-action-active: #00301a;
   --color-ink: #171717;
   --color-body: #4d4d4d;
   --color-muted: #888888;
@@ -173,8 +194,11 @@
   --color-canvas-soft: #fafafa;
   --color-canvas-soft-2: #f5f5f5;
   --color-line: #e5e5e5;
+  --color-input: #8f8f8f;
   --color-seam: #e4e7ec;
   --color-cross: #a1a1a1;
+  --color-focus-ring: #007a3c;
+  --color-scrim: #171717;
   --color-link: #007a3c;
   --color-link-deep: #00602f;
   --color-link-bg-soft: #d9f6e4;
@@ -279,9 +303,15 @@
   --color-dark-seam: #1f1f1f;
   --color-dark-primary: #ededed;
   --color-dark-on-primary: #0a0a0a;
+  --color-dark-action: #ededed;
+  --color-dark-action-foreground: #0a0a0a;
+  --color-dark-action-hover: #d4d4d4;
+  --color-dark-action-active: #a3a3a3;
   --color-dark-link: #9fe6bc;
   --color-dark-link-deep: #c3f0d4;
   --color-dark-link-bg-soft: #00301a;
+  --color-dark-focus-ring: #9fe6bc;
+  --color-dark-scrim: #f5f5f5;
   --color-dark-error: #f7b3b5;
   --color-dark-error-soft: #4a000e;
   --color-dark-error-deep: #fad3d4;
@@ -314,8 +344,10 @@
   --color-dark-chart-div-warm: #ffd97d;
   --color-dark-chart-div-mid: #e6e6e6;
   --color-dark-chart-div-cool: #cdd9fd;
+  --color-nadicode-input: #8f8f8f;
   --color-nadicode-muted: #888888;
   --color-nadicode-primary: #008c45;
+  --color-nadicode-scrim: #171717;
   --color-nadicode-chart-1: #2743d8;
   --color-nadicode-chart-2: #008c45;
   --color-nadicode-chart-3: #f5a623;
@@ -463,9 +495,17 @@
   --radius-md: 6px;
   --radius-lg: 8px;
   --radius-xl: 10px;
+  --radius-2xl: 12px;
+  --radius-3xl: 16px;
   --radius-pill-sm: 64px;
   --radius-pill: 100px;
   --radius-full: 9999px;
+  --ring-width-focus: var(--spacing-nadicode-focus-ring-width);
+  --opacity-scrim: var(--nc-material-scrim-opacity);
+  --shadow-tooltip: var(--nc-material-shadow-tooltip);
+  --shadow-menu: var(--nc-material-shadow-menu);
+  --shadow-dialog: var(--nc-material-shadow-dialog);
+  --shadow-sheet: var(--nc-material-shadow-sheet);
   --spacing-nadicode-xxs: 4px;
   --spacing-nadicode-filter-chip-gap: 6px;
   --spacing-nadicode-xs: 8px;
@@ -480,6 +520,10 @@
   --spacing-nadicode-6xl: 128px;
   --spacing-nadicode-section: 192px;
   --spacing-nadicode-guide: 1px;
+  --spacing-nadicode-focus-ring-width: 3px;
+  --spacing-nadicode-control-height: 32px;
+  --spacing-nadicode-control-padding-inline: 10px;
+  --spacing-nadicode-touch-target: 44px;
   --spacing-nadicode-page-pad: 24px;
   --spacing-nadicode-page-max-mobile: 448px;
   --spacing-nadicode-page-max-tablet: 624px;
@@ -526,4 +570,7 @@
   --spacing-nadicode-h-bento-strip: 20px;
   --spacing-nadicode-filter-chip-height: 28px;
   --spacing-nadicode-filter-chip-icon: 14px;
+  --spacing-control-height: var(--spacing-nadicode-control-height);
+  --spacing-control-padding-inline: var(--spacing-nadicode-control-padding-inline);
+  --spacing-touch-target: var(--spacing-nadicode-touch-target);
 }

package/dist/tokens/nadicode.dtcg.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
-  "$description": "Reusable design-system contract for NadicodeAI: engineered page geometry, neutral high-contrast surfaces, AI-agent work artifacts, and strict 12-column/10-column composition rules for the public website and package token exports.",
+  "$description": "Reusable design-system contract for NadicodeAI: engineered page geometry, neutral high-contrast product surfaces, AI-agent work artifacts, strict 12-column/10-column public-page composition, and the package token exports shared by every NadicodeAI interface.",
   "nadicode": {
     "color": {
       "$type": "color",
@@ -26,6 +26,50 @@
           "hex": "#ffffff"
         }
       },
+      "action": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0,
+            0.478,
+            0.235
+          ],
+          "hex": "#007a3c"
+        }
+      },
+      "action-foreground": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            1,
+            1,
+            1
+          ],
+          "hex": "#ffffff"
+        }
+      },
+      "action-hover": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0,
+            0.376,
+            0.184
+          ],
+          "hex": "#00602f"
+        }
+      },
+      "action-active": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0,
+            0.188,
+            0.102
+          ],
+          "hex": "#00301a"
+        }
+      },
       "ink": {
         "$value": {
           "colorSpace": "srgb",
@@ -103,6 +147,17 @@
           "hex": "#e5e5e5"
         }
       },
+      "input": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.561,
+            0.561,
+            0.561
+          ],
+          "hex": "#8f8f8f"
+        }
+      },
       "seam": {
         "$value": {
           "colorSpace": "srgb",
@@ -125,6 +180,28 @@
           "hex": "#a1a1a1"
         }
       },
+      "focus-ring": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0,
+            0.478,
+            0.235
+          ],
+          "hex": "#007a3c"
+        }
+      },
+      "scrim": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.09,
+            0.09,
+            0.09
+          ],
+          "hex": "#171717"
+        }
+      },
       "link": {
         "$value": {
           "colorSpace": "srgb",
@@ -1269,6 +1346,50 @@
           "hex": "#0a0a0a"
         }
       },
+      "dark-action": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.929,
+            0.929,
+            0.929
+          ],
+          "hex": "#ededed"
+        }
+      },
+      "dark-action-foreground": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.039,
+            0.039,
+            0.039
+          ],
+          "hex": "#0a0a0a"
+        }
+      },
+      "dark-action-hover": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.831,
+            0.831,
+            0.831
+          ],
+          "hex": "#d4d4d4"
+        }
+      },
+      "dark-action-active": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.639,
+            0.639,
+            0.639
+          ],
+          "hex": "#a3a3a3"
+        }
+      },
       "dark-link": {
         "$value": {
           "colorSpace": "srgb",
@@ -1302,6 +1423,28 @@
           "hex": "#00301a"
         }
       },
+      "dark-focus-ring": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.624,
+            0.902,
+            0.737
+          ],
+          "hex": "#9fe6bc"
+        }
+      },
+      "dark-scrim": {
+        "$value": {
+          "colorSpace": "srgb",
+          "components": [
+            0.961,
+            0.961,
+            0.961
+          ],
+          "hex": "#f5f5f5"
+        }
+      },
       "dark-error": {
         "$value": {
           "colorSpace": "srgb",
@@ -1741,6 +1884,30 @@
           "unit": "px"
         }
       },
+      "focus-ring-width": {
+        "$value": {
+          "value": 3,
+          "unit": "px"
+        }
+      },
+      "control-height": {
+        "$value": {
+          "value": 32,
+          "unit": "px"
+        }
+      },
+      "control-padding-inline": {
+        "$value": {
+          "value": 10,
+          "unit": "px"
+        }
+      },
+      "touch-target": {
+        "$value": {
+          "value": 44,
+          "unit": "px"
+        }
+      },
       "page-pad": {
         "$value": {
           "value": 24,
@@ -2056,6 +2223,18 @@
           "unit": "px"
         }
       },
+      "2xl": {
+        "$value": {
+          "value": 12,
+          "unit": "px"
+        }
+      },
+      "3xl": {
+        "$value": {
+          "value": 16,
+          "unit": "px"
+        }
+      },
       "pill-sm": {
         "$value": {
           "value": 64,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/design-system",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "build": "tsx scripts/build.ts",
     "generate:icons": "tsx scripts/generate-icons.ts",
     "generate:favicons": "tsx scripts/generate-favicons.ts",
-    "lint:design": "npm exec -- design.md lint DESIGN.md",
+    "lint:design": "design.md lint DESIGN.md",
     "test": "vitest run",
     "test:visual": "vitest run --config vitest.visual.config.ts",
     "prepublishOnly": "npm run build"