@nadicodeai/design-system 1.1.1 → 2.1.0

package/AGENTS.md

@@ -4,7 +4,13 @@ The `@nadicodeai/design-system` npm workspace. `DESIGN.md` is the normative cont
 
 ## 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/` specimens are static HTML pages served from the repo root by `../../scripts/lib/static-design-server.ts`, which `npm run test:visual` starts.
+Proof follows [the repository pipeline](../../docs/agents/develop.md#the-pipeline):
+`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/` specimens are
+static HTML pages served from the repo root by
+`../../scripts/lib/static-design-server.ts`, which `npm run test:visual` starts.
 
 | Command | When |
 | --- | --- |
@@ -20,13 +26,14 @@ Proof escalates by the ladder in the root `AGENTS.md` "Commands": `npm run check
 | Shared design-language terms | `CONTEXT.md` |
 | Colors, tokens, typography, layout doctrine, seam ownership, component semantics | `DESIGN.md` (read it before stating any of these) |
 | CSS layers, token pipeline, dark remaps, generated outputs, their guards | `DESIGN.md` "CSS Architecture & Token Pipeline". Decision history in `../../docs/adr/` |
-| Motion direction and runtime | `DESIGN.md` "Motion", `src/css/motion.css`, then the `product-design` skill for agent procedure |
+| Where a token is authored, and what the build publishes | The YAML front matter for the four schema groups, the one `json design-tokens` fence for everything the schema has no group for (`DESIGN.md` "Authored token extension"). `scripts/sd/design-tokens-fence.ts` reads the fence and `scripts/sd/compose-token-graph.ts` merges it with the CLI export into `dist/tokens/nadicode.dtcg.json` (aliases preserved) and `dist/tokens/nadicode.dtcg-resolved.json` (aliases replaced by values) |
+| Motion direction and runtime | `DESIGN.md` "Motion" for the direction and `core.motion` of the fence for the durations and easings, `src/css/motion.css` for the keyframes, the classes, and reduced motion, then the `product-design` skill for agent procedure |
 | Package exports | `package.json` (guard: `../../scripts/check-export-targets.mjs`, run by the root `build` script, so root `npm run check` and the post-merge suite, never the workspace `check` or the required gate) |
 | Static or non-React consumption | `README.md` |
 | React consumption | `../ui/docs/consuming-cross-repo.md` |
 | Logo hierarchy, usage, geometry, and asset delivery | `DESIGN.md` "Brand media authority". Static package routes in `README.md`. Implementation routes through `src/assets/`. `dist/` is generated, never hand-edited |
 | `examples/` specimen work | `examples/` plus the `write-clearly` skill for specimen copy (guard: `tests/guards/examples-package-coherence.test.ts`) |
-| Releasing a change to package-consumed output | `../../docs/agents/npm-publishing.md` |
+| Releasing a change to package-consumed output | `../../docs/agents/publish.md` |
 | Visual test implementation | `playwright.visual.config.ts` and `tests/visual/` |
 
 ## Boundaries
@@ -35,9 +42,9 @@ Proof escalates by the ladder in the root `AGENTS.md` "Commands": `npm run check
 - Token-only CSS: no raw color or radius literal in hand-authored `src/css/` or `examples/`, fallback-encoded or not. A new value enters `DESIGN.md` first (colors and the examples scan: `tests/guards/consumer-css-discipline.test.ts`; kit radius: `tests/guards/kernel-css-architecture.test.ts`).
 - Emitted-but-unreferenced contract tokens are intentional. Runtime aliases and compatibility variables are different: each must have a live caller or be removed (`DESIGN.md` "CSS Architecture & Token Pipeline").
 - `DESIGN.md` `## Components` is the semantic component catalog. CSS is its implementation, and `tests/guards/component-contract-matches-css.test.ts` derives the two-way fence without a copied inventory.
-- `DESIGN.md` stays contract-only and spec-shaped: check `npm exec --package=@google/design.md -- design.md spec` before changing YAML fields. Exact reusable values go in YAML, application guidance in prose. Add a non-spec YAML field only when repo code or a test reads it (spec-shape don'ts: `DESIGN.md` "Do's and Don'ts").
+- `DESIGN.md` stays contract-only and spec-shaped: check `npm exec --package=@google/design.md -- design.md spec` before changing YAML fields. Exact reusable values go in the YAML front matter where the schema has a group for them and in the one `json design-tokens` fence where it does not, application guidance in prose. Add a non-spec YAML field only when repo code or a test reads it (spec-shape don'ts: `DESIGN.md` "Do's and Don'ts").
 - Seams and grids are computed, single-owner, never eyeballed (doctrine home: `DESIGN.md` "## Layout" and "Seam Ownership").
 - 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. 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 never appears in a name, a comment, a contract, or any living design document.
-- 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/agents/npm-publishing.md`).
+- 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/agents/publish.md`).
 - 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

@@ -1,79 +1,46 @@
 # Design Language
 
-NadicodeAI's shared vocabulary for reusable visual decisions and interface structures. This context lets the design system, React UI package, website, and Portal describe the same visual ideas without inventing package-specific synonyms.
+The shared vocabulary for NadicodeAI's reusable visual decisions and interface structures.
 
 ## Language
 
 ### Foundations
 
-**Design contract**:
-The normative specification for reusable design tokens, page grammar, component semantics, and visual-surface meanings. Implementations realize the contract; they do not redefine it.
+**Foundation**:
+The visual values shared by every NadicodeAI product, including colour roles, typography, spacing, shape, material, elevation, motion, icons, and brand assets.
+_Avoid_: Palette, base theme
 
-**Design token**:
-A named reusable visual value from the design contract, such as a color, spacing, radius, or typography value. A one-off component detail is not a token.
-
-**Scale step**:
-One numbered value in a functional color scale whose number carries the same interaction or contrast role across every scale.
-_Avoid_: Shade, tint
+**Register**:
+One product's visual rules for applying the Foundation. NadicodeAI has three Registers: website, Portal, and Nadia desktop.
+_Avoid_: Theme, skin
 
 **Brand tier**:
-The full-strength campi used for identity, imagery, and section grounds. Brand-tier colors are planes, not interface states.
+The Campo fields used for brand identity, imagery, and large surface grounds.
 
 **Functional tier**:
-The numeric color scales and semantic roles used by product UI, charts, and status. Functional-tier colors express interaction and meaning rather than brand fields.
+The semantic colour roles and chart colours used for interface state and data.
 
 **Campo**:
-A named, full-strength brand color field from the design contract. A campo has no steps or hover variants.
+A named, full-strength brand colour field.
 _Avoid_: Swatch, theme color
 
-**One campo per room**:
-The composition rule that one section or image field owns one campo, with adjacent fields separated by a clear luminance change.
-
-**Luminance jump**:
-The perceptual brightness difference that makes the edge between adjacent campi, or between a campo and its text, read clearly.
-
 ### Structure and surfaces
 
 **Page grammar**:
-The shared structural system of frames, rows, lanes, fills, seams, markers, grids, and stages used to compose NadicodeAI pages.
+The shared structural vocabulary of frames, rows, lanes, fills, seams, markers, grids, and stages.
 
 **Seam**:
-A visible structural line in the page grammar: the shared edge where a frame, row, lane, or grid cell meets its neighbour. Exactly one element owns and draws each seam, so no coordinate is ever drawn twice, and seam placement is computed from grid math rather than eyeballed; the rule and the tokens that colour it live in `packages/design-system/DESIGN.md` "Seam Ownership" and "Layout". This is the visual sense of the word only. Its architectural sense, a boundary in code a test can substitute, is general software vocabulary and not part of the design language.
-
-**CSS primitive**:
-A low-level, framework-agnostic CSS helper for geometry, type, seams, fills, or structural behavior. It carries no product-specific meaning.
-
-**CSS component**:
-A framework-agnostic visual component that remains useful on both static and interactive surfaces without owning an app feature.
+The visible structural line where parts of the Page grammar meet.
 
 **Status vocabulary**:
-The one way the product shows a status. What it is, which carrier renders it, and which tone each value takes live in `packages/design-system/DESIGN.md` "Status Vocabulary".
+The shared five-tone visual language for product status. Each product owns its status families, values, and mapping to those tones.
 
 **Content surface**:
-A visual family for presenting a concrete content type, such as an image or artifact, inside the page grammar.
+A visual family for presenting a specific kind of content inside the Page grammar.
 
 **Agentic work surface**:
-A NadicodeAI visual family for showing people and agents working together through conversations, artifacts, approvals, tools, handoffs, traces, and inspectable state.
+A visual family outside the conversation renderer for work output and workflow state, such as memory, run progress, identity, and handoffs.
 
 **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.
+The decorative metaball identity assigned to an Agent type across products.
 _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.
-
-### React composition
-
-**React adapter**:
-A thin typed React interface over approved design-system CSS grammar or assets. It exposes the shared implementation without taking ownership of it.
-
-**Reusable composition**:
-A React component that combines shared grammar, primitives, slots, variants, and responsive behavior into a repeatable product or marketing pattern.
-
-**Reusable section**:
-A reusable composition for one recurring content role, such as an introduction, proof area, media block, or call to action.
-
-**Specimen**:
-A runnable example that assembles shipped pieces for inspection without inventing new design rules.