@nadicodeai/design-system 0.2.0 → 0.3.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 only generated `--color-*`/`--radius-*` references; `@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/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).
 - 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.
@@ -33,20 +33,20 @@ Generated-artifact and runtime-JS prohibitions live in the Forbidden Patterns ta
 - 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.
-- 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. If the change should reach external consumers, bump `@nadicodeai/design-system`, run `npm pack --dry-run -w @nadicodeai/design-system`, and follow `../docs/agents/npm-publishing.md`. 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.
+- 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` | `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` |
+| 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/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.
+- Check `npm exec -- 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.
@@ -91,7 +91,7 @@ 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.
+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.
 
 ## References
 
@@ -105,6 +105,7 @@ For a visual check, agents drive `agent-browser` directly: open the rendered pag
 | `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 |
+| `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/*` |

package/DESIGN.md

@@ -8,7 +8,7 @@ description: >-
   token exports.
 
 colors:
-  primary: "#171717"
+  primary: "#008c45"
   on-primary: "#ffffff"
   ink: "#171717"
   body: "#4d4d4d"
@@ -19,53 +19,125 @@ colors:
   line: "#e5e5e5"
   seam: "#e4e7ec"
   cross: "#a1a1a1"
-  link: "#007a5e"
-  link-deep: "#005d49"
-  link-bg-soft: "#d8f0e9"
+  link: "#007a3c"
+  link-deep: "#00602f"
+  link-bg-soft: "#d9f6e4"
+  accent: "#cd212a"
+  info: "#2743d8"
   success: "#008c45"
   error: "#b80022"
-  error-soft: "#f4d7dc"
-  error-deep: "#820018"
+  error-soft: "#fce4e4"
+  error-deep: "#9c001d"
   warning: "#f5a623"
-  warning-soft: "#ffefcf"
-  warning-deep: "#ab570a"
-  cyan: "#50e3c2"
-  cyan-soft: "#aaffec"
-  cyan-deep: "#29bc9b"
+  warning-soft: "#fff1cf"
+  warning-deep: "#8f4a06"
   flag-red: "#cd212a"
-  gradient-develop-start: "#007a5e"
-  gradient-develop-end: "#00dfd8"
-  gradient-ship-start: "#b80022"
-  gradient-ship-end: "#f9cb28"
   selection-bg: "#171717"
   selection-fg: "#f2f2f2"
-  state-ready: "#171717"
-  state-running: "#007a5e"
+  state-ready: "#4d4d4d"
+  state-running: "#2743d8"
   state-review: "#f5a623"
   state-blocked: "#b80022"
   state-complete: "#008c45"
-  dark-canvas: "#101414"
-  dark-canvas-soft: "#151b19"
-  dark-canvas-soft-2: "#1d2522"
-  dark-ink: "#f5f7f4"
-  dark-body: "#c8d0cb"
-  dark-muted: "#8d9892"
-  dark-line: "#2c3632"
-  dark-seam: "#24302b"
-  dark-primary: "#ecf4ee"
-  dark-on-primary: "#101414"
-  dark-link: "#7ee7c6"
-  dark-link-deep: "#b8ffe5"
-  dark-link-bg-soft: "#163f34"
-  dark-error: "#ff7a8b"
-  dark-error-soft: "#4b1821"
-  dark-error-deep: "#ffb3bd"
-  dark-warning: "#ffd28a"
-  dark-warning-soft: "#4a3219"
-  dark-warning-deep: "#ffe6b8"
-  dark-cyan: "#83f7dc"
-  dark-cyan-soft: "#b8ffe5"
-  dark-cyan-deep: "#49c6a8"
+  background-100: "#ffffff"
+  background-200: "#fafafa"
+  gray-100: "#f2f2f2"
+  gray-200: "#ebebeb"
+  gray-300: "#e6e6e6"
+  gray-400: "#eaeaea"
+  gray-500: "#c9c9c9"
+  gray-600: "#a8a8a8"
+  gray-700: "#8f8f8f"
+  gray-800: "#7d7d7d"
+  gray-900: "#4d4d4d"
+  gray-1000: "#171717"
+  green-italia-100: "#e8faef"
+  green-italia-200: "#d9f6e4"
+  green-italia-300: "#c3f0d4"
+  green-italia-400: "#9fe6bc"
+  green-italia-500: "#62d494"
+  green-italia-600: "#17b568"
+  green-italia-700: "#008c45"
+  green-italia-800: "#007a3c"
+  green-italia-900: "#00602f"
+  green-italia-1000: "#00301a"
+  red-italia-100: "#fdeeee"
+  red-italia-200: "#fce4e4"
+  red-italia-300: "#fad3d4"
+  red-italia-400: "#f7b3b5"
+  red-italia-500: "#f28085"
+  red-italia-600: "#e84e57"
+  red-italia-700: "#cd212a"
+  red-italia-800: "#b80022"
+  red-italia-900: "#9c001d"
+  red-italia-1000: "#4a000e"
+  blue-cobalto-100: "#eef2ff"
+  blue-cobalto-200: "#e2e9fe"
+  blue-cobalto-300: "#cdd9fd"
+  blue-cobalto-400: "#a9befa"
+  blue-cobalto-500: "#7d99f2"
+  blue-cobalto-600: "#4f6ae6"
+  blue-cobalto-700: "#2743d8"
+  blue-cobalto-800: "#1d33ad"
+  blue-cobalto-900: "#16277f"
+  blue-cobalto-1000: "#0a1240"
+  amber-100: "#fff6e1"
+  amber-200: "#fff1cf"
+  amber-300: "#ffe9b3"
+  amber-400: "#ffd97d"
+  amber-500: "#ffc933"
+  amber-600: "#f5a623"
+  amber-700: "#d98800"
+  amber-800: "#b36b00"
+  amber-900: "#8f4a06"
+  amber-1000: "#452301"
+  campo-verde: "#008c45"
+  campo-rosso: "#cd212a"
+  campo-arancio: "#e4530b"
+  campo-giallo: "#f2b705"
+  campo-cobalto: "#2743d8"
+  campo-inchiostro: "#171717"
+  campo-bianco: "#ffffff"
+  chart-1: "#2743d8"
+  chart-2: "#008c45"
+  chart-3: "#f5a623"
+  chart-4: "#cd212a"
+  chart-5: "#00838f"
+  chart-6: "#6f42c1"
+  dark-canvas: "#0a0a0a"
+  dark-canvas-soft: "#171717"
+  dark-canvas-soft-2: "#262626"
+  dark-ink: "#f5f5f5"
+  dark-body: "#d4d4d4"
+  dark-muted: "#a3a3a3"
+  dark-line: "#2e2e2e"
+  dark-input: "#5d5d5d"
+  dark-seam: "#1f1f1f"
+  dark-primary: "#ededed"
+  dark-on-primary: "#0a0a0a"
+  dark-link: "#9fe6bc"
+  dark-link-deep: "#c3f0d4"
+  dark-link-bg-soft: "#00301a"
+  dark-error: "#f7b3b5"
+  dark-error-soft: "#4a000e"
+  dark-error-deep: "#fad3d4"
+  dark-warning: "#ffd97d"
+  dark-warning-soft: "#452301"
+  dark-warning-deep: "#ffe9b3"
+  dark-cyan: "#33d1cb"
+  dark-cyan-soft: "#7ee8de"
+  dark-cyan-deep: "#1f9e9a"
+  dark-success: "#62d494"
+  dark-state-ready: "#d4d4d4"
+  dark-state-running: "#a9befa"
+  dark-state-review: "#ffd97d"
+  dark-state-blocked: "#f7b3b5"
+  dark-state-complete: "#62d494"
+  dark-selection-bg: "#ededed"
+  dark-selection-fg: "#0a0a0a"
+  dark-cross: "#6e6e6e"
+  dark-chart-1: "#7d99f2"
+  dark-chart-6: "#9575cd"
 
 typography:
   display-xl:
@@ -173,11 +245,11 @@ typography:
 
 rounded:
   none: 0px
-  xs: 4px
-  sm: 6px
-  md: 8px
-  lg: 12px
-  xl: 16px
+  xs: 2px
+  sm: 4px
+  md: 6px
+  lg: 8px
+  xl: 10px
   pill-sm: 64px
   pill: 100px
   full: 9999px
@@ -254,14 +326,14 @@ components:
     backgroundColor: "{colors.canvas-soft}"
     textColor: "{colors.body}"
     typography: "{typography.caption-mono}"
-    rounded: "{rounded.lg}"
+    rounded: "{rounded.sm}"
     padding: "5px 9px"
     height: 28px
   status-tag-approved:
     backgroundColor: "{colors.link-bg-soft}"
     textColor: "{colors.link-deep}"
     typography: "{typography.caption-mono}"
-    rounded: "{rounded.lg}"
+    rounded: "{rounded.sm}"
     padding: "5px 9px"
     height: 28px
   image:
@@ -383,23 +455,55 @@ The kernel is the reusable implementation layer. `DESIGN.md` defines the reusabl
 
 ## Colors
 
-The palette keeps the broad neutral, accent, state, and gradient families that NadicodeAI started from, then adds the newer kernel seam vocabulary. The public website may use a restrained subset, but the design-system contract remains broader than any current specimen.
+The Italia color system runs on two tiers that never mix. The **functional tier** (scales + semantic roles + charts) drives every product and interface state; the **brand tier** (the seven campi) paints marketing and identity surfaces. A scale step is never a poster field, and a campo is never a UI state.
+
+### Architecture — step semantics
+
+Colour is organised as two page backgrounds plus five ten-step scales (`gray`, `green-italia`, `red-italia`, `blue-cobalto`, `amber`). Every scale reads the same way, so a step number carries a fixed job across all five families:
 
-- **Ink / Primary** (`{colors.ink}`, `{colors.primary}`): near-black for text, primary actions, and dark action bands.
-- **Canvas** (`{colors.canvas}`): white content cells.
-- **Canvas Soft** (`{colors.canvas-soft}`): page background and diagonal filler base.
-- **Canvas Soft 2** (`{colors.canvas-soft-2}`): subtle filler stripe and inset surface tone.
-- **Line** (`{colors.line}`): the universal 1 px divider and seam color. It is the only token used to tune ordinary seam visibility; keep it visible on `{colors.canvas}` and `{colors.canvas-soft}` while remaining quiet. Do not darken individual borders, gap backgrounds, hatch stripes, or dividers locally.
-- **Cross** (`{colors.cross}`): stronger gray for visible marks, pending nodes, and crosshair markers.
-- **Seam** (`{colors.seam}`): dashed connector and secondary guide color.
+- **100–300** — component backgrounds: default, hover, active.
+- **400–600** — borders: default, hover, active.
+- **700** — the high-contrast solid, the star anchor of the scale (the flag/cobalt tone).
+- **800** — solid hover.
+- **900** — text and icons (AA body weight on white).
+- **1000** — high-contrast text, and the darkest ground for dark-mode tinted panels.
+
+Backgrounds are `{colors.background-100}` (page default, white) and `{colors.background-200}` (soft, used sparingly). `gray` is adopted verbatim as the neutral spine: the existing `{colors.ink}` (= `gray-1000`), `{colors.body}` (= `gray-900`), `{colors.canvas}`, `{colors.canvas-soft}`, `{colors.canvas-soft-2}`, and `{colors.line}` names stay as consumed aliases over the scale — do not rename them. `green-italia` is the brand primary (anchor `{colors.green-italia-700}`, flag green); `red-italia` carries accent and danger (anchor `{colors.red-italia-700}`, flag red); `blue-cobalto` carries info and the cobalt world of the imagery (anchor `{colors.blue-cobalto-700}`); `amber` carries warning and chrome-yellow energy (`{colors.amber-600}` is the operational warning tone).
+
+### 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.
-- **Italian Link Green** (`{colors.link}`): inline links, navigational accents, and approved/example proof states. It is intentionally green, not blue, so NadicodeAI keeps an Italian signal without turning the interface into flag decoration.
-- **Semantic** (`{colors.success}`, `{colors.error}`, `{colors.warning}` plus soft/deep variants): validation, caution, approval, and operational feedback. `success` uses the Italian flag green family; `error` uses a deeper Italian red so destructive and blocked states are visible without defaulting to generic web red.
-- **Accent** (`{colors.cyan}`): high-energy accent available for visuals, states, and generated assets.
-- **Flag Red** (`{colors.flag-red}`): a decorative Italian-flag red reserved for brand-asset decoration only (identity marks such as Nadia's flag-red bar). It is distinct from `{colors.error}`; never use `flag-red` for destructive, blocked, or validation states.
-- **Gradient Pairs** (`{colors.gradient-develop-*}`, `{colors.gradient-ship-*}`): reserved gradient vocabulary for artifact- and asset-level energy; do not use them to repair page structure or seams.
-- **Workflow States** (`{colors.state-ready}`, `{colors.state-running}`, `{colors.state-review}`, `{colors.state-blocked}`, `{colors.state-complete}`): left-border/state vocabulary for agentic work surfaces.
-- **Dark Primitives** (`{colors.dark-canvas}`, `{colors.dark-ink}`, `{colors.dark-line}`, and siblings): the source tokens for the generated shadcn `.dark` role map. They are mode-bearing primitives, not a separate component palette; consuming apps opt into them by applying a `.dark` ancestor through their runtime theme provider.
+- **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.
+- **Flag Red** (`{colors.flag-red}`): kept as a stable alias at the same value as `{colors.accent}` (`red-italia-700`, `#cd212a`). `accent` and `flag-red` are two roles at one hex: `accent` is the interface-highlight role, `flag-red` is the identity-mark alias. `error` (`red-italia-800`) stays a distinct, deeper red; never use it as an accent.
+- **Workflow States** (`{colors.state-ready}`, `{colors.state-running}`, `{colors.state-review}`, `{colors.state-blocked}`, `{colors.state-complete}`): the left-border/state vocabulary for agentic work surfaces. `state-running` is now `blue-cobalto-700` and `state-complete` is `green-italia-700` — blue means in motion, green means done; `state-ready` moves to `gray-900`. The dark counterparts (`{colors.dark-state-ready}`, `{colors.dark-state-running}`, `{colors.dark-state-review}`, `{colors.dark-state-blocked}`, `{colors.dark-state-complete}`) ride the same Italia scales moved to lighter steps for the dark console — ready ink-neutral (`gray` step `#d4d4d4`), running a light `blue-cobalto` (blue = in motion), review `amber-400`, blocked `red-italia-400`, complete `green-italia-500` — carried on the `state-tag` 3 px `border-left`, each clearing 4.5:1 on the dark canvas for its label.
+
+### Chart categoricals (functional tier)
+
+- **Charts** (`{colors.chart-1}`…`{colors.chart-6}`): the categorical series palette — cobalto, verde, ambra, rosso, plus a functional-only teal and viola. Functional only: never place chart colours on marketing surfaces, campi, or generated imagery. On the dark canvas the deep cobalto and viola drop below the 3:1 WCAG 1.4.11 floor for data marks, so they carry dark-tuned steps (`{colors.dark-chart-1}` on `blue-cobalto-500`, `{colors.dark-chart-6}` a lighter viola); the four mid/high-luminance series (verde, ambra, rosso, teal) already clear 3:1 and stay saturated in both modes.
+- **Categorical distinguishability**: the same-family neighbours are held apart — `chart-3`/`chart-4` (ambra/rosso) and `chart-2`/`chart-5` (verde/teal) each clear a CIEDE2000 ≥ 20 normal / ≥ 15 deuteranopia-simulated floor. Two proximities are brand-locked and exempt from the numeric floor: `chart-2`/`chart-4` (verde/rosso, the flag pair, which collapses under red-green deficiency by identity) and `chart-1`/`chart-6` (cobalto/viola, adjacent blue-violet). Charts using the full six must carry redundant encoding (direct labels, position, or pattern), never hue alone, so these two pairs stay readable under colour-vision deficiency.
+
+### Brand tier — i campi
+
+The seven campi are full-strength named brand fields. They carry NO tints, NO steps, and NO hover variants; UI states always come from the scales, never from a campo.
+
+- `{colors.campo-verde}` (Verde Bandiera), `{colors.campo-rosso}` (Rosso Bandiera), and `{colors.campo-cobalto}` pair with `{colors.campo-bianco}` (white) type.
+- `{colors.campo-arancio}` (vermilion) and `{colors.campo-giallo}` (mustard) pair with `{colors.campo-inchiostro}` (ink) type.
+- `{colors.campo-inchiostro}` pairs with white type; `{colors.campo-bianco}` pairs with ink type.
+
+Four campo rules govern their use:
+
+1. **One campo per room.** A section owns exactly one field; adjacent sections must jump in luminance, so two mid-tone rooms never touch.
+2. **Type on a campo is bianco or inchiostro only.** Arancio and Giallo carry ink; Verde, Rosso, Cobalto, and Inchiostro carry white. No tinted text on fields.
+3. **Campi are planes, not chips.** The minimum duty of a campo is a section ground, poster field, or full media mount. UI states come from the scales, never campi.
+4. **One paint box.** Generated imagery draws its flat fields from these seven values; the Visual Law's private palette retires and points at these tokens.
+
+### 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 so each pair clears 4.5:1 on the dark surfaces — `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 and the `dark-state-*` workflow family on their matching Italia scale steps. 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.
 
 Do not delete a color because the current website kernel does not consume it. Prototype usage is not palette authority; removals require an explicit palette migration decision.
 

package/dist/css/components/agent-avatar.css

@@ -36,7 +36,7 @@
 
 /* Optional identity accent — same AC-016 map as chat-bubble-agent. */
 .nc-agent-avatar[data-accent="green"]  { --nc-accent: var(--nc-link); }
-.nc-agent-avatar[data-accent="cyan"]   { --nc-accent: var(--nc-cyan-deep); }
+.nc-agent-avatar[data-accent="cyan"]   { --nc-accent: var(--nc-info); }
 .nc-agent-avatar[data-accent="amber"]  { --nc-accent: var(--nc-warning-deep); }
 .nc-agent-avatar[data-accent="ink"]    { --nc-accent: var(--nc-ink); }
 .nc-agent-avatar[data-accent="red"]    { --nc-accent: var(--nc-error); }

package/dist/css/components/chat-bubble-agent.css

@@ -34,10 +34,10 @@
 }
 
 /* AC-016 accent map → existing --nc-* tokens. Each rule references a token, no
-   hard-coded hex. green→link, cyan→cyan-deep, amber→warning-deep, ink→ink,
-   red→error. */
+   hard-coded hex. green→link, cyan→info (blue-cobalto; the killed cyan token
+   retired per Italia contract §6), amber→warning-deep, ink→ink, red→error. */
 .nc-chat-bubble-agent[data-accent="green"]  { --nc-accent: var(--nc-link); }
-.nc-chat-bubble-agent[data-accent="cyan"]   { --nc-accent: var(--nc-cyan-deep); }
+.nc-chat-bubble-agent[data-accent="cyan"]   { --nc-accent: var(--nc-info); }
 .nc-chat-bubble-agent[data-accent="amber"]  { --nc-accent: var(--nc-warning-deep); }
 .nc-chat-bubble-agent[data-accent="ink"]    { --nc-accent: var(--nc-ink); }
 .nc-chat-bubble-agent[data-accent="red"]    { --nc-accent: var(--nc-error); }

package/dist/css/components/state-tag.css

@@ -31,6 +31,20 @@
               color var(--nc-duration-confirm) var(--nc-ease-out-strong);
 }
 
+/*
+ * Dark console: the tag's neutral surface flips to the dark ramp so the chip is
+ * dark-grounded, not a light chip on the dark canvas. Scoped to the component
+ * because canvas/ink/line are global neutrals that must not be remapped in the
+ * unscoped .dark block. The variant state colors flip separately via the
+ * generated .dark --nc-state-* remap in the Tailwind theme map. Direct
+ * counterparts: the tag stays a canvas-grounded chip in both themes.
+ */
+.dark .nc-state-tag {
+  --nc-canvas: var(--nc-dark-canvas);
+  --nc-ink: var(--nc-dark-ink);
+  --nc-line: var(--nc-dark-line);
+}
+
 .nc-state-tag[data-variant="ready"] {
   border-left-color: var(--nc-state-ready);
 }

package/dist/css/components/typing-dots.css

@@ -28,10 +28,10 @@
 }
 
 /* AC-016 accent map → existing --nc-* tokens; identical to chat-bubble-agent and
-   agent-avatar. green→link, cyan→cyan-deep, amber→warning-deep, ink→ink,
-   red→error. No hard-coded hex. */
+   agent-avatar. green→link, cyan→info (blue-cobalto; killed cyan token retired
+   per Italia contract §6), amber→warning-deep, ink→ink, red→error. No hard-coded hex. */
 .nc-typing-dots[data-accent="green"]  { --nc-accent: var(--nc-link); }
-.nc-typing-dots[data-accent="cyan"]   { --nc-accent: var(--nc-cyan-deep); }
+.nc-typing-dots[data-accent="cyan"]   { --nc-accent: var(--nc-info); }
 .nc-typing-dots[data-accent="amber"]  { --nc-accent: var(--nc-warning-deep); }
 .nc-typing-dots[data-accent="ink"]    { --nc-accent: var(--nc-ink); }
 .nc-typing-dots[data-accent="red"]    { --nc-accent: var(--nc-error); }

package/dist/css/primitives.css

@@ -170,10 +170,9 @@
   min-width: 0;
   border: var(--nc-guide) solid var(--nc-line);
   padding: 18px;
+  /* The retired gradient tokens (Italia color contract §6) are gone; the artifact
+     surface keeps a calm, scale-driven dot-grid atmosphere on canvas. */
   background:
-    radial-gradient(circle at 72% 18%, color-mix(in srgb, var(--nc-gradient-develop-start) 16%, transparent), transparent 30%),
-    radial-gradient(circle at 22% 76%, color-mix(in srgb, var(--nc-gradient-ship-end) 10%, transparent), transparent 34%),
-    radial-gradient(circle at 86% 84%, color-mix(in srgb, var(--nc-gradient-ship-start) 9%, transparent), transparent 28%),
     radial-gradient(var(--nc-line) 0.8px, transparent 0.8px) 0 0 / 12px 12px,
     var(--nc-canvas);
   color: var(--nc-body);
@@ -203,8 +202,8 @@
   align-items: center;
   justify-content: center;
   border: var(--nc-guide) solid var(--nc-line);
-  /* status-tag = {rounded.lg} (DESIGN.md). */
-  border-radius: var(--nc-rounded-lg);
+  /* status-tag = {rounded.sm} (DESIGN.md). */
+  border-radius: var(--nc-rounded-sm);
   padding: 5px 9px;
   background: var(--nc-canvas-soft);
   color: var(--nc-body);

package/dist/css/tokens.generated.css

@@ -5,7 +5,7 @@
 
 :root {
   /* Colors */
-  --nc-primary: #171717;
+  --nc-primary: #008c45;
   --nc-on-primary: #ffffff;
   --nc-ink: #171717;
   --nc-body: #4d4d4d;
@@ -16,53 +16,125 @@
   --nc-line: #e5e5e5;
   --nc-seam: #e4e7ec;
   --nc-cross: #a1a1a1;
-  --nc-link: #007a5e;
-  --nc-link-deep: #005d49;
-  --nc-link-bg-soft: #d8f0e9;
+  --nc-link: #007a3c;
+  --nc-link-deep: #00602f;
+  --nc-link-bg-soft: #d9f6e4;
+  --nc-accent: #cd212a;
+  --nc-info: #2743d8;
   --nc-success: #008c45;
   --nc-error: #b80022;
-  --nc-error-soft: #f4d7dc;
-  --nc-error-deep: #820018;
+  --nc-error-soft: #fce4e4;
+  --nc-error-deep: #9c001d;
   --nc-warning: #f5a623;
-  --nc-warning-soft: #ffefcf;
-  --nc-warning-deep: #ab570a;
-  --nc-cyan: #50e3c2;
-  --nc-cyan-soft: #aaffec;
-  --nc-cyan-deep: #29bc9b;
+  --nc-warning-soft: #fff1cf;
+  --nc-warning-deep: #8f4a06;
   --nc-flag-red: #cd212a;
-  --nc-gradient-develop-start: #007a5e;
-  --nc-gradient-develop-end: #00dfd8;
-  --nc-gradient-ship-start: #b80022;
-  --nc-gradient-ship-end: #f9cb28;
   --nc-selection-bg: #171717;
   --nc-selection-fg: #f2f2f2;
-  --nc-state-ready: #171717;
-  --nc-state-running: #007a5e;
+  --nc-state-ready: #4d4d4d;
+  --nc-state-running: #2743d8;
   --nc-state-review: #f5a623;
   --nc-state-blocked: #b80022;
   --nc-state-complete: #008c45;
-  --nc-dark-canvas: #101414;
-  --nc-dark-canvas-soft: #151b19;
-  --nc-dark-canvas-soft-2: #1d2522;
-  --nc-dark-ink: #f5f7f4;
-  --nc-dark-body: #c8d0cb;
-  --nc-dark-muted: #8d9892;
-  --nc-dark-line: #2c3632;
-  --nc-dark-seam: #24302b;
-  --nc-dark-primary: #ecf4ee;
-  --nc-dark-on-primary: #101414;
-  --nc-dark-link: #7ee7c6;
-  --nc-dark-link-deep: #b8ffe5;
-  --nc-dark-link-bg-soft: #163f34;
-  --nc-dark-error: #ff7a8b;
-  --nc-dark-error-soft: #4b1821;
-  --nc-dark-error-deep: #ffb3bd;
-  --nc-dark-warning: #ffd28a;
-  --nc-dark-warning-soft: #4a3219;
-  --nc-dark-warning-deep: #ffe6b8;
-  --nc-dark-cyan: #83f7dc;
-  --nc-dark-cyan-soft: #b8ffe5;
-  --nc-dark-cyan-deep: #49c6a8;
+  --nc-background-100: #ffffff;
+  --nc-background-200: #fafafa;
+  --nc-gray-100: #f2f2f2;
+  --nc-gray-200: #ebebeb;
+  --nc-gray-300: #e6e6e6;
+  --nc-gray-400: #eaeaea;
+  --nc-gray-500: #c9c9c9;
+  --nc-gray-600: #a8a8a8;
+  --nc-gray-700: #8f8f8f;
+  --nc-gray-800: #7d7d7d;
+  --nc-gray-900: #4d4d4d;
+  --nc-gray-1000: #171717;
+  --nc-green-italia-100: #e8faef;
+  --nc-green-italia-200: #d9f6e4;
+  --nc-green-italia-300: #c3f0d4;
+  --nc-green-italia-400: #9fe6bc;
+  --nc-green-italia-500: #62d494;
+  --nc-green-italia-600: #17b568;
+  --nc-green-italia-700: #008c45;
+  --nc-green-italia-800: #007a3c;
+  --nc-green-italia-900: #00602f;
+  --nc-green-italia-1000: #00301a;
+  --nc-red-italia-100: #fdeeee;
+  --nc-red-italia-200: #fce4e4;
+  --nc-red-italia-300: #fad3d4;
+  --nc-red-italia-400: #f7b3b5;
+  --nc-red-italia-500: #f28085;
+  --nc-red-italia-600: #e84e57;
+  --nc-red-italia-700: #cd212a;
+  --nc-red-italia-800: #b80022;
+  --nc-red-italia-900: #9c001d;
+  --nc-red-italia-1000: #4a000e;
+  --nc-blue-cobalto-100: #eef2ff;
+  --nc-blue-cobalto-200: #e2e9fe;
+  --nc-blue-cobalto-300: #cdd9fd;
+  --nc-blue-cobalto-400: #a9befa;
+  --nc-blue-cobalto-500: #7d99f2;
+  --nc-blue-cobalto-600: #4f6ae6;
+  --nc-blue-cobalto-700: #2743d8;
+  --nc-blue-cobalto-800: #1d33ad;
+  --nc-blue-cobalto-900: #16277f;
+  --nc-blue-cobalto-1000: #0a1240;
+  --nc-amber-100: #fff6e1;
+  --nc-amber-200: #fff1cf;
+  --nc-amber-300: #ffe9b3;
+  --nc-amber-400: #ffd97d;
+  --nc-amber-500: #ffc933;
+  --nc-amber-600: #f5a623;
+  --nc-amber-700: #d98800;
+  --nc-amber-800: #b36b00;
+  --nc-amber-900: #8f4a06;
+  --nc-amber-1000: #452301;
+  --nc-campo-verde: #008c45;
+  --nc-campo-rosso: #cd212a;
+  --nc-campo-arancio: #e4530b;
+  --nc-campo-giallo: #f2b705;
+  --nc-campo-cobalto: #2743d8;
+  --nc-campo-inchiostro: #171717;
+  --nc-campo-bianco: #ffffff;
+  --nc-chart-1: #2743d8;
+  --nc-chart-2: #008c45;
+  --nc-chart-3: #f5a623;
+  --nc-chart-4: #cd212a;
+  --nc-chart-5: #00838f;
+  --nc-chart-6: #6f42c1;
+  --nc-dark-canvas: #0a0a0a;
+  --nc-dark-canvas-soft: #171717;
+  --nc-dark-canvas-soft-2: #262626;
+  --nc-dark-ink: #f5f5f5;
+  --nc-dark-body: #d4d4d4;
+  --nc-dark-muted: #a3a3a3;
+  --nc-dark-line: #2e2e2e;
+  --nc-dark-input: #5d5d5d;
+  --nc-dark-seam: #1f1f1f;
+  --nc-dark-primary: #ededed;
+  --nc-dark-on-primary: #0a0a0a;
+  --nc-dark-link: #9fe6bc;
+  --nc-dark-link-deep: #c3f0d4;
+  --nc-dark-link-bg-soft: #00301a;
+  --nc-dark-error: #f7b3b5;
+  --nc-dark-error-soft: #4a000e;
+  --nc-dark-error-deep: #fad3d4;
+  --nc-dark-warning: #ffd97d;
+  --nc-dark-warning-soft: #452301;
+  --nc-dark-warning-deep: #ffe9b3;
+  --nc-dark-cyan: #33d1cb;
+  --nc-dark-cyan-soft: #7ee8de;
+  --nc-dark-cyan-deep: #1f9e9a;
+  --nc-dark-success: #62d494;
+  --nc-dark-state-ready: #d4d4d4;
+  --nc-dark-state-running: #a9befa;
+  --nc-dark-state-review: #ffd97d;
+  --nc-dark-state-blocked: #f7b3b5;
+  --nc-dark-state-complete: #62d494;
+  --nc-dark-selection-bg: #ededed;
+  --nc-dark-selection-fg: #0a0a0a;
+  --nc-dark-cross: #6e6e6e;
+  --nc-dark-chart-1: #7d99f2;
+  --nc-dark-chart-6: #9575cd;
 
   /* Spacing */
   --nc-xxs: 4px;
@@ -125,11 +197,11 @@
 
   /* Radii */
   --nc-rounded-none: 0px;
-  --nc-rounded-xs: 4px;
-  --nc-rounded-sm: 6px;
-  --nc-rounded-md: 8px;
-  --nc-rounded-lg: 12px;
-  --nc-rounded-xl: 16px;
+  --nc-rounded-xs: 2px;
+  --nc-rounded-sm: 4px;
+  --nc-rounded-md: 6px;
+  --nc-rounded-lg: 8px;
+  --nc-rounded-xl: 10px;
   --nc-rounded-pill-sm: 64px;
   --nc-rounded-pill: 100px;
   --nc-rounded-full: 9999px;