@nadicodeai/design-system 0.21.0 → 1.0.0

package/AGENTS.md

@@ -1,18 +1,17 @@
 # @nadicodeai/design-system
 
-The `@nadicodeai/design-system` npm workspace. `DESIGN.md` is the normative contract for reusable design tokens and package output; the package ships tokens, the CSS kit (structural geometry plus framework-agnostic brand display components), and assets. Repo-only `examples/` specimens prove that public surface. Standard, interactive, and section UI ships as React components from `@nadicodeai/ui`, not from here. Paths here are relative to `design-system/`; run commands from this directory, or with `-w design-system` from the repo root.
+The `@nadicodeai/design-system` npm workspace. `DESIGN.md` is the normative contract for reusable design tokens and package output; the package ships tokens, the CSS kit (structural geometry plus framework-agnostic brand display components), and assets. Repo-only `examples/` specimens prove that public surface. Standard, interactive, and section UI ships as React components from `@nadicodeai/ui`, not from here. Paths here are relative to `design-system/`; run commands from this directory, or with `-w @nadicodeai/design-system` from the repo root.
 
 ## Commands
 
+Proof escalates by the ladder in the root `AGENTS.md` "Commands": `npm run check -w @nadicodeai/design-system` and `npm run test -w @nadicodeai/design-system` before pushing. `check` carries the `DESIGN.md` contract lint, so a contract edit needs no separate command. This workspace has no app to boot: it ships a package, and `examples/` renders through the website's verification routes.
+
 | Command | When |
 | --- | --- |
-| `npm run lint:design` | After any `DESIGN.md` edit |
-| `npm run build` | After any `DESIGN.md` edit; regenerates every `dist/` artifact (tokens, Tailwind data, icons, complete CSS bundle) |
-| `npm run generate:icons` | After bumping `lucide-static`; rebakes `dist/icons/` (also runs inside `build`) |
-| `npm run lint` / `npm run test` | After TS/JS changes / before handoff (browser-free) |
-| `npm run test:visual` | Rendered CSS checks (`playwright.visual.config.ts`, `tests/visual/`) |
-
-Handoff gate: `npm run lint:design && npm run lint && npm run build && npm run test`.
+| `npm run build -w @nadicodeai/design-system` | After any `DESIGN.md` edit; regenerates every `dist/` artifact (tokens, Tailwind data, icons, complete CSS bundle) |
+| `npm run generate:icons -w @nadicodeai/design-system` | After bumping `lucide-static`; rebakes `dist/icons/` (also runs inside `build`) |
+| `npm run generate:favicons -w @nadicodeai/design-system` | After a favicon source change; the output is git-tracked and the build does not regenerate it |
+| `npm run test:visual -w @nadicodeai/design-system` | Rendered CSS checks (`playwright.visual.config.ts`, `tests/visual/`), outside the browser-free default suite |
 
 ## Routing
 
@@ -41,4 +40,4 @@ Handoff gate: `npm run lint:design && npm run lint && npm run build && npm run t
 - Authoring is contract-first: a visual behavior comes from `DESIGN.md`, from our own shipped surfaces, or from an explicit user approval — never from another product's rendered output (ADR 0047). Screenshots verify, they never author. Ask when the contract leaves a decision open, and stop and re-read `DESIGN.md` before a second visual patch to the same component.
 - Name everything as NadicodeAI-owned primitives. A source brand appears only in a `../docs/adr/` decision record, as the history of what once inspired a choice; never in a name, a comment, a contract, or any living design document (ADR 0047).
 - Any change to package-consumed output ends with an explicit release decision, a version bump or a `[no-publish]` commit marker (enforced by the pre-push release gate; procedure: `../docs/internal/npm-publishing.md`).
-- The deleted `design-canvas/` prototypes live only in git history. `src/css/motion.css` owns shared runtime motion primitives, while `src/js/chat-autoplay.js` is the single allowed runtime JS enhancer; never reconstruct the prototypes or add a second runtime JS surface.
+- The deleted `design-canvas/` prototypes and static chat/autoplay surface live only in git history. `src/css/motion.css` owns shared runtime motion primitives; never reconstruct the prototypes or add a runtime JS surface.

package/CONTEXT.md

@@ -60,6 +60,12 @@ A visual family for presenting a concrete content type, such as an image or arti
 **Agentic work surface**:
 A NadicodeAI visual family for showing people and agents working together through conversations, artifacts, approvals, tools, handoffs, traces, and inspectable state.
 
+**Agent visual**:
+The decorative metaball identity assigned explicitly to a persistent Agent by
+type. It identifies the Agent across products without carrying status, runtime
+activity, capability, or work output.
+_Avoid_: Agent glyph, Agent avatar
+
 **App-owned product feature**:
 A product-specific route, screen, use case, or behavior owned by the consuming app rather than by the reusable design or UI packages.
 

package/DESIGN.md

@@ -20,6 +20,8 @@ colors:
   canvas: "#ffffff"
   canvas-soft: "#fafafa"
   canvas-soft-2: "#f5f5f5"
+  material-workspace: "#f7f7f7"
+  material-solid: "#ffffff"
   line: "#e5e5e5"
   input: "#757575"
   seam: "#d4d4d4"
@@ -79,6 +81,8 @@ colors:
   dark-canvas: "#000000"
   dark-canvas-soft: "#111111"
   dark-canvas-soft-2: "#1a1a1a"
+  dark-material-workspace: "#000000"
+  dark-material-solid: "#000000"
   dark-ink: "#ededed"
   dark-body: "#c7c7c7"
   dark-muted: "#8f8f8f"
@@ -356,7 +360,7 @@ Every value a role needs is carried by the role token itself; there are no ten-s
 - **Semantic feedback** (`{colors.success}` = verde with `{colors.success-soft}`/`{colors.success-deep}`; `{colors.error}` = rosso funzionale `#d3302f` with `{colors.error-soft}`/`{colors.error-deep}`; `{colors.warning}` = giallo `#ffc220` with `{colors.warning-soft}`/`{colors.warning-deep}`; `{colors.info}` = cobalto `#1e3cff` with `{colors.info-soft}`/`{colors.info-deep}`): validation, caution, approval, and operational feedback. In each pair the `-soft` value is the tinted tag/banner ground and the `-deep` value is the AA-clearing text on it. On a solid `error` fill (the shadcn `destructive` role) text is white; on a solid `warning` or `success` fill text is ink. The success pair intentionally reuses the link pair's AA-safe verde values; its feedback meaning remains distinct from inline navigation and entity-status semantics.
 - **Accent** (`{colors.accent}` = arancio `#ff5a1f`): the attention accent for highlights, exception flags, and emphasis marks. It is an accent only — never a fill, background, or body-text colour, and it never carries text. Do not conflate this functional `accent` with the identically-named shadcn surface role: that role is a neutral (`{colors.canvas-soft-2}` in light, `{colors.dark-canvas-soft-2}` in dark) and carries no hue despite the shared word.
 - **Flag Red** (`{colors.flag-red}` = `#d3302f`): the identity-mark red alias. It shares its hex with `{colors.error}` but stays a distinct role name — `flag-red` is identity, `error` is validation feedback. The attention accent is arancio, not flag red.
-- **Workflow States** (`{colors.state-ready}` neutral, `{colors.state-running}` cobalto, `{colors.state-review}` giallo, `{colors.state-blocked}` rosso, `{colors.state-complete}` verde): the left-border/state vocabulary for agentic work surfaces — cobalto means in motion, verde means done. The dark counterparts (`{colors.dark-state-ready}`, `{colors.dark-state-running}`, `{colors.dark-state-review}`, `{colors.dark-state-blocked}`, `{colors.dark-state-complete}`) keep the same functional identity. These colours are carried only by the `state-tag` 3 px `border-left` rail and related non-text state accents; label text stays on the neutral foreground roles for contrast in both themes. The `{colors.state-*}` tokens stay rail-only for run-state surfaces; entity status is a separate vocabulary carried by the `status-tag` family's background+text pairs (see `## Components`), and the two token sets never cross.
+- **Workflow States** (`{colors.state-ready}` neutral, `{colors.state-running}` cobalto, `{colors.state-review}` giallo, `{colors.state-blocked}` rosso, `{colors.state-complete}` verde): the left-border/state vocabulary for agentic work surfaces — cobalto means in motion, verde means done. The dark counterparts (`{colors.dark-state-ready}`, `{colors.dark-state-running}`, `{colors.dark-state-review}`, `{colors.dark-state-blocked}`, `{colors.dark-state-complete}`) keep the same functional identity. These colours are carried by non-text state accents only — meter and bullet segments, delta marks, and the brand book's own rails; label text stays on the neutral foreground roles for contrast in both themes. Status is not one of their jobs: every status the product renders is the Badge status vocabulary (see `## Status Vocabulary`), which reads from the semantic feedback and link pairs, and the two token sets never cross.
 
 ### Chart categoricals (functional tier)
 
@@ -438,8 +442,8 @@ All body, title, caption, and code typography uses `letterSpacing: 0px`. Do not
 | `{typography.body-sm}`        | 14px | 400    | 20px        | Secondary copy, nav, compact cell copy.                                    |
 | `{typography.body-sm-strong}` | 14px | 500    | 20px        | Emphasised secondary copy and compact labels.                              |
 | `{typography.caption}`        | 12px | 400    | 16px        | Footer secondary lines and badge labels.                                   |
-| `{typography.caption-strong}` | 12px | 500    | 16px        | Entity-status `status-tag` labels.                                         |
-| `{typography.caption-mono}`   | 12px | 500    | 16px        | Eyebrows, identifiers and code, run-state `state-tag` labels.              |
+| `{typography.caption-strong}` | 12px | 500    | 16px        | Compact emphasised labels on chrome and chips.                             |
+| `{typography.caption-mono}`   | 12px | 500    | 16px        | Eyebrows, identifiers and code.                                            |
 | `{typography.code}`           | 13px | 400    | 20px        | Tool calls, snippets, traces.                                              |
 | `{typography.button-lg}`      | 16px | 500    | 24px        | Marketing-scale button labels.                                             |
 | `{typography.button-md}`      | 14px | 500    | 18px        | Standard button and control labels.                                        |
@@ -482,7 +486,7 @@ Kernel compositions arrange approved primitives for a content role. They must no
 Each reusable concern has one home and one authoring surface, so a member is documented and shipped in exactly one place:
 
 - **Tokens** — exact reusable values live in this contract's `colors`, `spacing`, `rounded`, and `typography`; they export to the generated token layer (with a hand-authored local token layer beside it). No component or section may re-encode a token value.
-- **Framework-agnostic CSS components** — the brand/display CSS components that remain in this package (the agent-chat family, the run-state `state-tag` family, the entity-status `status-tag` family, `image`, and the small label/badge/link metadata components). Their names and semantics live once in `## Components`; design-system CSS realises that catalog without a second recipe or component-token hierarchy.
+- **Framework-agnostic CSS components** — the brand/display CSS components that remain in this package (agent-work artifacts, `image`, and the small label/badge/link metadata components). Their names and semantics live once in `## Components`; design-system CSS realises that catalog without a second recipe or component-token hierarchy.
 - **Reusable compositions and sections** — patterns that arrange the page grammar and lower tiers for a content role. They ship as React shadcn compositions from `@nadicodeai/ui`, composed over the kept page grammar; they are not a pure-CSS section layer and do not add a second component catalog here.
 - **Layout grammar** — the page-frame, row, lane, seam, stage, and marker system documented across this `## Layout` section, carried by the layout CSS layer.
 - **Specimens** — static demonstrations of already-defined primitives. They invent no geometry, seams, heights, or responsive behavior; they only assemble shipped tiers for inspection.
@@ -531,28 +535,33 @@ These live helpers are part of the kept page-grammar layout layer. They support
 
 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.
+Product UI uses one shared material ladder. The workspace is one continuous ground (`{colors.material-workspace}` / `{colors.dark-material-workspace}`); every solid object uses the same fill (`{colors.material-solid}` / `{colors.dark-material-solid}`). In dark mode, both are true black. The workspace remains legible because it carries the existing `dotted-field` texture and solid objects occlude it. Elevation never means progressively greyer cards. Physical distance changes only the `shadow-plugin` falloff: `smooth-shadow-ring-md` for resting content, then `lg`, `xl`, and `2xl` when an object is physically raised, floating, or modal. Each utility already integrates the plugin's adaptive optical ring, including the plugin's 18% white dark-mode ring, so an elevated root never adds a border, second ring, local ring tint, or opacity override. Product code chooses only the semantic role.
 
-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.
+Glass is a material variant, not an elevation step. It is reserved for compact control chrome floating over legible content. Cards, KPIs, tables, inspectors, and ordinary modal bodies remain solid. Reduced-transparency mode replaces glass with the same solid material at the same elevation.
+
+The Google design schema does not define opacity groups. These declarations are therefore the authored material-token source inside this contract. The build reads this block strictly and emits generated `--nc-*` hooks. The UI package owns the exact `shadow-plugin` dependency and maps semantic component roles to its utilities without copying the vendor shadow values into this contract.
 
 ```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%);
+--nc-material-glass-opacity: 76%;
+--nc-material-glass-blur: 28px;
+--nc-material-glass-saturation: 116%;
 ```
 
-| 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 |
+| Material role | Construction                                                                                                       | Use                                                                                                                                                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Workspace     | `dotted-field` on `{colors.material-workspace}` / `{colors.dark-material-workspace}`; no edge or shadow            | The continuous work area behind product objects                                                                                                                                                                          |
+| Resting       | Solid fill; plugin-default integrated ring; `smooth-shadow-ring-md`; `{rounded.3xl}` (16 px)                       | KPI, card, table, setting, and persistent content surfaces                                                                                                                                                               |
+| Raised        | Same solid fill and ring; `smooth-shadow-ring-lg`; `{rounded.3xl}` (16 px)                                         | Active work, a selected object, or an attached inspector above resting siblings                                                                                                                                          |
+| Floating      | Same solid fill and ring; `smooth-shadow-ring-xl`; role-specific corner radius                                     | Compact menus, popovers, dropdowns, and anchored surfaces use `{rounded.2xl}` (12 px); small artifacts such as tooltips and toasts keep `{rounded.md}` (6 px); detached product surfaces may use `{rounded.3xl}` (16 px) |
+| Modal         | Same solid fill and ring; `smooth-shadow-ring-2xl`; `{rounded.3xl}` (16 px)                                        | Dialog, sheet, drawer, and takeover                                                                                                                                                                                      |
+| Glass control | Translucent solid fill at 76%, 28 px backdrop blur, integrated plugin ring, and the falloff for its physical level | Compact control chrome floating above content; never a content container                                                                                                                                                 |
+
+`Card` is the fundamental product container. Its content does not create a second material family: KPIs, Agent cards, settings, and ordinary grouped content use the resting role unless the object is physically raised. Interaction variants may change state or emphasis without changing the material role.
+
+Absence follows the container that owns it. A page-level or region-level empty state is an opaque solid region with a dashed boundary. An empty state inside a Card is transparent and unframed so it does not draw a second container inside the first.
+
+Resting form controls are not elevated material planes. They keep the 1 px `{colors.input}` / `{colors.dark-input}` boundary, `{rounded.md}` (6 px), and no shadow. Their inline padding is `{spacing.control-padding-inline}`, textareas use `{spacing.xs}` block padding, and every default control is at least `{spacing.control-height}` high.
 
 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.
 
@@ -563,12 +572,12 @@ On coarse or non-hover input capability, every interactive target is at least 44
 Corners are restrained and assigned by material role.
 
 - Use `{rounded.none}` for page rows, frame edges, grid cells, and structural modules.
-- 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.md}` (6 px) for controls, buttons, chips, status tags, and small artifacts.
+- Use `{rounded.2xl}` (12 px) for compact menus, popovers, dropdowns, and anchored floating surfaces.
+- Use `{rounded.3xl}` (16 px) for resting and raised product content surfaces, detached inspectors, modal dialogs, 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.
 
-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.
+Public page-grammar cells are not cards and remain square because their parent frame supplies the visual system. Product cards use the resting material role; they do not gain a second border, nested ring, or stronger elevation merely because they contain grouped settings.
 
 ## Motion
 
@@ -596,55 +605,15 @@ Interactive CSS components must expose a visible `:focus-visible` state using th
 
 Content surfaces display specific content types inside the grammar. They are valid when the content exists; they do not replace the page frame, row model, or seam rules.
 
-**`image`** — editorial media mount, the single home for art-directed imagery inside the grammar. A bounded media fill (img, picture, video, or inline SVG) with an optional mono tag chip overlaid on the media and an optional body-tone caption bar below it, both typed by the generated caption utilities applied in markup. Square-cornered (`{rounded.none}`): a mounted print, not a floating card — the parent frame supplies the visual system. With `data-frame="true"` it draws exactly one hairline (its own `{colors.line}` border), so it sits inside a borderless `panel-cell` or a visual slot without repairing or stacking onto any grid seam. The aspect ratio is the per-instance `--nc-image-ratio` knob (default 4 / 3) — set the prop on the element, never re-derive geometry inline. Variant: `data-strip="true"` is the full-width divider form for thin editorial bands between page rows (thread, texture, panorama) — the ratio unlocks and the height resolves from the responsive `{spacing.h-strip-*}` tokens through the layout-layer collapsed alias. Use `image` for every illustrated image, photographic surface, or image divider; use `artifact-preview` when the visual is an agent-produced document surface.
+**`image`** — editorial media mount, the single home for art-directed imagery inside the grammar. A bounded media fill (img, picture, video, or inline SVG) with an optional mono tag chip overlaid on the media and an optional body-tone caption bar below it, both typed by the generated caption utilities applied in markup. Square-cornered (`{rounded.none}`): a mounted print, not a floating card — the parent frame supplies the visual system. With `data-frame="true"` it draws exactly one hairline (its own `{colors.line}` border), so it sits inside a borderless `panel-cell` or a visual slot without repairing or stacking onto any grid seam. The aspect ratio is the per-instance `--nc-image-ratio` knob (default 4 / 3) — set the prop on the element, never re-derive geometry inline. Variant: `data-strip="true"` is the full-width divider form for thin editorial bands between page rows (thread, texture, panorama) — the ratio unlocks and the height resolves from the responsive `{spacing.h-strip-*}` tokens through the layout-layer collapsed alias. Use `image` for every illustrated image, photographic surface, or image divider. Conversation artifacts render through assistant-ui rather than a design-system CSS family.
 
 ### Agentic Work Surfaces
 
-Agentic work surfaces are the NadicodeAI-specific layer. They show people and agents working together through conversations, artifacts, approvals, memory, state, tools, and handoffs. Use these when there is concrete work output or workflow state to inspect.
-
-**`artifact-surface`** — inspectable output area. Use for proposal previews, reports, plans, spreadsheets, schedules, approval states, source traces, run logs, workflow maps, and conversation artifacts.
-
-**`artifact-preview`** — compact inspectable artifact card for an agent-produced document, sheet, report, or code excerpt. The header identifies the artifact kind and the body carries the preview; use `artifact-surface` for a larger work area.
-
-Status-tag variants share the same compact sans rectangle at `{typography.caption-strong}`, `{rounded.md}` — a small subtle-tinted rectangle, never a capsule — and differentiate by tone: a paired background+text ramp step, not a border-left rail. Tone is `[data-tone]`, not BEM modifiers. Gray is the default tone; color is reserved for marking health and exceptions, so every terminal or no-action entity status (inactive, archived, rejected, canceled, expired, revoked, denied) renders gray. Subtle-only (no solid/filled variant), no icons inside the badge, no text-transform; labels render verbatim from the source's own i18n dictionary. `status-tag` is the entity-status vocabulary — agent, credential, activation, customer, invitation, subscription, and health values that live on a record — and stays a sibling of `state-tag`: the two families never blend, and `status-tag` never touches the `{colors.state-*}` tokens.
-
-**`status-tag-gray`** — default and terminal entity status: no action pending, nothing to watch (inactive, archived, rejected, canceled, expired, revoked, denied).
-
-**`status-tag-green`** — a healthy, active, or successfully completed entity status.
-
-**`status-tag-red`** — a failed, blocked, or otherwise exceptional entity status that needs attention.
-
-**`status-tag-amber`** — a degrading, retiring, or past-due entity status between healthy and failed.
-
-**`status-tag-blue`** — an in-progress, pending, or trial entity status still moving toward a resolution.
-
-**`chat-thread`** — conversation container showing how people instruct, correct, review, or approve agents. Static markup always renders the complete conversation. The package's optional `chat-autoplay.js` progressive enhancer activates only on `data-nc-autoplay`, reveals messages in order while keeping the newest turn visible, loops while the thread is in view, and injects its own pause/resume control. It shows the complete thread immediately when reduced motion is requested. Consumers never author the enhancer control in static markup.
+Agentic work surfaces are the NadicodeAI-specific display layer outside the conversation renderer. They show concrete work output or workflow state such as memory, state, run progress, identity, and handoffs. Conversation messages, tools, artifacts, approvals, and pending indicators belong to assistant-ui.
 
-**`chat-bubble-user`** — human message bubble. Dark surface, white text.
+Agent identity is decorative product identity, not a work artifact or a status signal. Its approved metaball form, closed Agent-type recipes, four surface treatments, palette, still frames, and motion rules live in [`brand/visual-design/AGENT-VISUAL-SYSTEM.md`](../brand/visual-design/AGENT-VISUAL-SYSTEM.md). `@nadicodeai/ui` owns the typed React implementation. Consuming apps assign a recipe explicitly and own placement, data, actions, and accessible meaning.
 
-**`chat-bubble-agent`** — agent message bubble. Light surface, ink text.
-
-**`tool-call-trace`** — compact code/trace row. Use only when tool use is relevant to the explanation.
-
-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-tag-ready`** — workflow state tag for work that is ready or waiting to start. Uses `{colors.state-ready}` for the left edge.
-
-**`state-tag-running`** — workflow state tag for work currently being executed by an agent or system. Uses `{colors.state-running}` for the left edge.
-
-**`state-tag-review`** — workflow state tag for human review or approval. Uses `{colors.state-review}` for the left edge.
-
-**`state-tag-blocked`** — workflow state tag for blocked work or failed preconditions. Uses `{colors.state-blocked}` for the left edge.
-
-**`state-tag-complete`** — workflow state tag for completed work. Uses `{colors.state-complete}` for the left edge.
-
-**`state-row`** — full-width workflow-state divider inside an agentic work surface. Its bounded hairlines belong to the row and its dot consumes the same state token as the matching `state-tag` variant.
-
-**`typing-dots`** — compact agent typing indicator. It uses the agent accent rail and the shared motion hooks; reduced-motion behavior comes from the package motion layer.
-
-**`approval-gate`** — human-in-the-loop pause surface. Use when an agent action requires explicit review, correction, approval, or rejection.
-
-**`agent-avatar`** — identity slot for an agent personality or role. The chrome is reusable; the visual asset is project-specific.
+**`artifact-surface`** — inspectable output area outside a conversation. Use for proposal previews, reports, plans, spreadsheets, schedules, run logs, and workflow maps.
 
 **`usage-meter`** — token, cost, latency, or run-count display.
 
@@ -654,6 +623,34 @@ State-tag variants share the same compact rectangular shape at `{typography.capt
 
 **`handoff-banner`** — agent-to-agent or human-to-agent handoff surface. It explains the handoff reason and destination. It carries a 3 px colored `border-left` consuming the matching `{colors.link}` token and a leading direction marker tinted with the same token; the accent edge and arrow carry the handoff direction.
 
+## Status Vocabulary
+
+Status is the one thing every surface in the product says: an agent is active, a
+key is revoked, an invitation is waiting, a run is blocked. It is said one way.
+
+**What it is.** The single status carrier is the React `Badge` from
+`@nadicodeai/ui`, rendered in one of five semantic tones with a small mark in
+its icon slot. It is not a CSS component in this package: there is no
+framework-neutral status class, and a static surface that needs to show a status
+shows it as ordinary text. Its React API — the tone variants, the icon slot, and
+what a consuming app must supply — is contracted in
+[`@nadicodeai/ui/docs/contract.md`](../@nadicodeai/ui/docs/contract.md).
+
+**Why.** A status read by colour alone is not read by everyone, and a product
+that speaks status in three grammars teaches its next surface to invent a
+fourth. One badge, carrying an icon and a word with the tone only reinforcing
+both, is legible without colour and leaves nothing to invent.
+
+**What it does.** Five tones, each a soft ground with its deep label from an
+existing semantic pair: gray on the neutral spine for the default and every
+terminal, no-action state; green on the link pair for healthy and complete; red
+on the error pair for unusable and failed; amber on the warning pair for waiting
+on a decision; blue on the info pair for a step in motion. One mark per tone, so
+the shape repeats the tone rather than adding a second axis. The families —
+which statuses exist and which tone each value takes — belong to the consuming
+app, because they are its domain, not this contract's; the Portal keeps its
+whole map in one module and no surface picks a status colour anywhere else.
+
 ## Do's and Don'ts
 
 ### Do
@@ -663,13 +660,13 @@ State-tag variants share the same compact rectangular shape at `{typography.capt
 - 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 use exactly one material role per product container; structural page-grammar cells remain border-only, while product cards, menus, popovers, dialogs, sheets, and takeovers use their specified material 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.
 - Do separate different story beats into separate rows.
 - Do use the full-lane `stage` geometry for one major use-case/artifact story, not as a container for every page concept.
-- Do make agent visuals show conversations, artifacts, review states, or work output.
+- Do use Agent identity visuals only to identify an Agent or its explicit type; use assistant-ui and the agentic work surfaces above for conversations, artifacts, review states, and work output.
 - Do keep ordinary CSS components compact and subordinate to the page grammar.
 - Do use pricing, logo, banner, and showcase compositions only when the page truly contains that content type.
 
@@ -679,7 +676,7 @@ State-tag variants share the same compact rectangular shape at `{typography.capt
 - 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 stack borders or rings around an elevated surface, promote a resting card because its content is important, 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.
@@ -747,7 +744,7 @@ The NadicodeAI logo has three approved forms:
 
 Other companies' marks are not NadicodeAI company logos and are not governed by anything in this section. They are generated identity images owned by `@nadicodeai/ui/components/brand-icons`, decided in [`docs/adr/0042-third-party-brand-marks-are-generated-identity-images.md`](../docs/adr/0042-third-party-brand-marks-are-generated-identity-images.md). A third-party mark never enters a NadicodeAI logo form, composition, or clear-space measurement.
 
-Nadia's portrait and generated imagery are not NadicodeAI company logos. Their identity and selection rules live in [`brand/visual-design/NADIA-VISUAL-IDENTITY.md`](../brand/visual-design/NADIA-VISUAL-IDENTITY.md); editorial imagery routes through [`brand/visual-design/EDITORIAL-ILLUSTRATION.md`](../brand/visual-design/EDITORIAL-ILLUSTRATION.md). This contract owns only the package delivery interface.
+Nadia's portrait, Agent identity visuals, and generated imagery are not NadicodeAI company logos. Nadia's identity and selection rules live in [`brand/visual-design/NADIA-VISUAL-IDENTITY.md`](../brand/visual-design/NADIA-VISUAL-IDENTITY.md); the Agent identity system lives in [`brand/visual-design/AGENT-VISUAL-SYSTEM.md`](../brand/visual-design/AGENT-VISUAL-SYSTEM.md); editorial imagery routes through [`brand/visual-design/EDITORIAL-ILLUSTRATION.md`](../brand/visual-design/EDITORIAL-ILLUSTRATION.md). This contract owns only the package delivery interface.
 
 The approved transparent Nadia master ships at `assets/nadia-solid-surface`.
 

package/README.md

@@ -84,14 +84,6 @@ Consumer overrides belong in an explicit later layer:
 
 The exact layer order and ownership rules are defined in `DESIGN.md`.
 
-### Optional chat auto-play
-
-Static chat markup needs no JavaScript. To opt a `data-nc-autoplay` thread into
-progressive playback, include the public
-`@nadicodeai/design-system/css/chat-autoplay.js` export. The `chat-thread`
-entry in [`DESIGN.md`](./DESIGN.md#agentic-work-surfaces) owns the behavior and
-accessibility contract.
-
 ### Worked example (static HTML)
 
 ```html
@@ -109,26 +101,13 @@ accessibility contract.
       <div class="nc-page-frame">
         <section class="nc-page-row">
           <div class="nc-row-lane nc-row-lane-active">
-            <!-- A playing chat thread: opt in with data-nc-autoplay -->
-            <div class="nc-chat-thread" data-nc-autoplay>
-              <div class="nc-chat-thread-body">
-                <div class="nc-chat-bubble-user">Which contract template should I use?</div>
-                <div class="nc-chat-bubble-agent" data-accent="green">
-                  Use the approved 2026 revision in Drive · Legal · Templates. It already has the updated privacy clauses.
-                </div>
-              </div>
-            </div>
+            <div class="nc-artifact-surface">Inspectable agent output</div>
           </div>
         </section>
       </div>
     </main>
-
-    <!-- Optional: omit this script and the thread above stays a full static conversation. -->
-    <script src="https://unpkg.com/@nadicodeai/design-system/css/chat-autoplay.js"></script>
   </body>
 </html>
 ```
 
-`examples/chat-showcase.html` is the live proof page for the chat CSS components and auto-play enhancer.
-
 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.