@nadicodeai/design-system 0.10.2 → 0.11.0

package/README.md

@@ -1,19 +1,20 @@
 # NadicodeAI Design System
 
-The `@nadicodeai/design-system` package. [`DESIGN.md`](./DESIGN.md) is the normative implementation contract for reusable design tokens and package output; the canonical human brand book lives in the monorepo at `brand/brand-book/index.html`.
+The `@nadicodeai/design-system` package. [`DESIGN.md`](./DESIGN.md) is the normative contract for reusable design tokens, mode behavior, CSS architecture, and generated output. The canonical human brand book lives in the monorepo at `brand/brand-book/index.html`.
 
-`DESIGN.md` defines the normative NadicodeAI design system contract: tokens, typography, layout, components, do's and don'ts, written to the [@google/design.md](https://github.com/google-labs-code/design.md) spec. `npm run build` emits two consumable exports: `dist/tokens/nadicode.dtcg.json` (DTCG token format) and `dist/tailwind/nadicode.tailwind.json` (Tailwind config).
+This README is a package map and the setup guide for static or non-React consumers. React consumers use the UI package's single stylesheet interface and follow [`@nadicodeai/ui/docs/consuming-cross-repo.md`](../@nadicodeai/ui/docs/consuming-cross-repo.md). They do not compose design-system stylesheets themselves.
 
-For Tailwind CSS v4 CSS-first projects, `npm run build` also emits `dist/tailwind/nadicode.theme.css`, exported as `@nadicodeai/design-system/tailwind/theme.css`. Import it from the consuming app's CSS entry:
+## Static and non-React consumption
+
+Import the complete CSS module once:
 
 ```css
-@import "tailwindcss";
-@import "@nadicodeai/design-system/tailwind/theme.css";
+@import "@nadicodeai/design-system/css";
 ```
 
-The CSS adapter provides shadcn-compatible semantic utilities such as `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `border-border`, and `ring-ring`. It publishes both `:root` light roles and `.dark` dark roles; consuming apps opt into dark mode by applying a `.dark` ancestor, normally through their own theme provider. The raw `--nc-*` brand-token remaps (the state, selection, cross, and chart families) are the one exception: they are emitted at `:root.dark`, so they flip only when the `dark` class sits on the root element itself (the next-themes `attribute="class"` default), not on an inner wrapper. NadicodeAI-specific spacing utilities are namespaced, for example `p-nadicode-lg` and `h-nadicode-h-cell-sm`, so standard Tailwind/shadcn classes such as `max-w-3xl` keep their normal Tailwind behavior. React consumers normally get this through `@nadicodeai/ui/globals.css`.
+That interface includes the generated tokens, mode aliases, semantic role maps, page geometry, type utilities, motion primitives, and framework-agnostic CSS components. Apply `.dark` to the document root or to a scoped static composition to select dark mode. The generation and cascade mechanics live only in [`DESIGN.md`, "CSS Architecture & Token Pipeline"](./DESIGN.md#css-architecture--token-pipeline).
 
-Geist and Geist Mono (SIL Open Font License 1.1) ship inside the package under `src/assets/fonts/`. Consumers can pull the `@font-face` shim directly:
+Geist and Geist Mono (SIL Open Font License 1.1) are optional package assets. A static consumer that does not supply its own font loading can import the `@font-face` shim:
 
 ```css
 @import "@nadicodeai/design-system/assets/fonts/geist.css";
@@ -21,62 +22,36 @@ Geist and Geist Mono (SIL Open Font License 1.1) ship inside the package under `
 
 Individual font files are also exposed under `@nadicodeai/design-system/assets/fonts/*` if the consumer needs to write its own `@font-face` declarations.
 
-## The `/css` bundle
-
-`DESIGN.md` is the token contract (Surface 1, exported as values). The CSS bundle is Surface 2: the hand-authored, framework-agnostic stylesheet that turns those tokens into the actual NadicodeAI website geometry, chrome, and the agent-chat experience. Import it with one line:
-
-```css
-@import "@nadicodeai/design-system/css";
-```
-
-That single import delivers:
-
-- the kernel page geometry — the 12-column page frame, the centered 10-column active lane, and single-owner seams;
-- the framework-agnostic brand display vocabulary: the agent-chat component family, run-state tags, `image`, artifact surfaces, and workflow state chrome;
-- the brand motion contract (`--nc-duration-*` / `--nc-ease-*` tokens, the `nc-msg-in` / `nc-typing` / `nc-pulse` keyframes, and a `prefers-reduced-motion: reduce` block that disables them);
-- the agent-chat CSS components — `nc-chat-thread`, `nc-chat-bubble-user`, `nc-chat-bubble-agent`, `nc-tool-call-trace`, `nc-memory-item`, `nc-handoff-banner`, `nc-approval-gate`, `nc-artifact-preview`, `nc-typing-dots`, `nc-state-row`, plus `nc-agent-avatar` and `nc-usage-meter`.
-
-Everything is token-only (`var(--nc-*)`); there is no hard-coded hex in the CSS components or structural geometry. Individual files are also reachable under `@nadicodeai/design-system/css/*` (for example `@nadicodeai/design-system/css/components/chat-thread.css`).
+## Package surface
 
-The built bundle mirrors every kept partial into `dist/css/`. Generic marketing/SaaS sections and interactive components ship from `@nadicodeai/ui`, not this CSS package.
+`package.json` owns the current public export paths. [`DESIGN.md`](./DESIGN.md)
+owns what those exports mean and how the CSS cascade, modes, tokens, layout,
+components, motion, and assets behave. The runnable [`examples/`](./examples/)
+consume only those public exports and are the inspection surface. This README
+does not maintain a parallel inventory.
 
-### The seven-layer cascade
+CSS partials and generated adapter files are implementation details. React
+components and compositions are discovered through the UI package rather than
+inferred from this CSS package.
 
-The bundle declares one explicit `@layer` order up front, then imports each partial into its own layer:
-
-```css
-@layer tokens, reset, foundation, motion, layout, primitives, components;
-```
-
-Because the order is declared data, consumer overrides are predictable: layer your own rules in a layer that comes *after* the bundle and they win regardless of selector specificity. Open a page-local block with `@layer page;` and write page overrides into `@layer page { … }`, which sits after `components`:
+Consumer overrides belong in an explicit later layer:
 
 ```css
 @layer page;
 @layer page {
-  /* page-specific overrides — always win over the bundle */
+  /* Page-specific overrides. */
 }
 ```
 
-### Relationship to `theme.css` and shadcn
-
-The `/css` bundle and the Tailwind `theme.css` adapter are complementary:
+The exact layer order and ownership rules are defined in `DESIGN.md`.
 
-- `@nadicodeai/design-system/tailwind/theme.css` publishes the shadcn `:root` and `.dark` token variables (the semantic `bg-background` / `text-foreground` / `border-border` family), so interactive shadcn app islands land on-brand when they need JS-driven accessibility behavior such as dialogs or comboboxes.
-- The `/css` bundle ships NadicodeAI's framework-agnostic page grammar, CSS components, brand motion contract, and agent-chat surfaces.
-- `@nadicodeai/ui` ships the React shadcn-style components and reusable section/app compositions on top of those tokens and CSS components.
+### Optional chat auto-play
 
-Use both together: React apps import `@nadicodeai/ui/globals.css` for Tailwind/shadcn utilities and `@import "@nadicodeai/design-system/css"` for NadicodeAI geometry and CSS components.
-
-### The agent-chat CSS components and the optional auto-play enhancer
-
-The chat CSS components render a complete, static agent conversation from CSS alone — no JavaScript required. `nc-chat-bubble-agent` carries a 3px accent edge whose color is switched by `[data-accent]` (for example `data-accent="green"`), mapped to existing `--nc-*` tokens.
-
-For motion, the package ships exactly one optional, vanilla, dependency-free enhancer: `chat-autoplay.js`, exported as `@nadicodeai/design-system/css/chat-autoplay.js`. It is the **only** JavaScript in the package — no React, no framework, no registry, no module/CDN imports. It is pure progressive enhancement:
-
-- add `data-nc-autoplay` to a `nc-chat-thread` and include the script; messages then reveal in scripted order, a typing indicator shows between turns, the thread scrolls to the newest message, and the cycle loops;
-- playback starts when the thread scrolls into view (`IntersectionObserver`);
-- under `prefers-reduced-motion: reduce`, the full thread is shown immediately with no loop;
-- **with the script absent, the full thread renders statically** — the components are usable framework-agnostically, with zero React.
+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)
 
@@ -116,8 +91,6 @@ For motion, the package ships exactly one optional, vanilla, dependency-free enh
 </html>
 ```
 
-`examples/chat-showcase.html` is a live proof page that composes the chat CSS components with the auto-play enhancer across twelve conversations.
+`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.
-
-The `design-canvas/` prototypes the kernel re-expresses (chat motion and component prototypes) are deleted from the tree; git history retains them under `docs/experiments/design-canvas/`. They are not package runtime or current brand canon.

package/dist/assets/logo-mark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160" role="img" aria-label="NadicodeAI mark">
+  <clipPath id="mark-overlap"><rect x="58" y="84" width="26" height="26"/></clipPath>
+  <rect fill="none" stroke="currentColor" stroke-width="10" x="42" y="50" width="46" height="46" rx="13"/>
+  <rect fill="none" stroke="var(--nc-primary, #00a85a)" stroke-width="10" x="72" y="64" width="46" height="46" rx="13"/>
+  <rect fill="none" stroke="currentColor" stroke-width="10" x="42" y="50" width="46" height="46" rx="13" clip-path="url(#mark-overlap)"/>
+</svg>

package/dist/assets/logo-wordmark.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 100" role="img" aria-label="NadicodeAI wordmark">
+  <g fill="currentColor" transform="translate(0 76) scale(0.06 -0.06)"><path transform="translate(0 0)" d="M74 0L74 710L242 710L524 220L524 710L676 710L676 0L506 0L226 473L226 0Z"/><path transform="translate(706.867 0)" d="M225 -12Q142 -12 89.5 26.5Q37 65 37 134Q37 205 81.5 243.5Q126 282 213 300L386 334Q386 386 362.5 412.5Q339 439 295 439Q252 439 228 419.5Q204 400 197 362L46 369Q61 457 125.5 502.5Q190 548 295 548Q415 548 475.5 491Q536 434 536 324L536 141Q536 118 543.5 110.5Q551 103 566 103L581 103L581 0Q574 -2 558.5 -4Q543 -6 528 -6Q496 -6 468.5 5Q441 16 424 42.5Q407 69 407 118L420 108Q410 72 384.5 45Q359 18 318.5 3Q278 -12 225 -12ZM261 91Q298 91 326 105.5Q354 120 370 148Q386 176 386 214L386 240L264 214Q228 207 209.5 190.5Q191 174 191 148Q191 121 209 106Q227 91 261 91Z"/><path transform="translate(1258.133 0)" d="M257 -12Q189 -12 139.5 22.5Q90 57 63.5 119.5Q37 182 37 268Q37 354 64 416.5Q91 479 140.5 513.5Q190 548 257 548Q314 548 355.5 524.5Q397 501 418 460L418 710L568 710L568 0L425 0L422 79Q400 36 356.5 12Q313 -12 257 -12ZM306 103Q342 103 367 122Q392 141 405 177.5Q418 214 418 268Q418 323 405 359.5Q392 396 367 414.5Q342 433 306 433Q253 433 222 388.5Q191 344 191 268Q191 193 222.5 148Q254 103 306 103Z"/><path transform="translate(1844.8 0)" d="M66 0L66 536L216 536L216 0ZM63 602L63 722L218 722L218 602Z"/><path transform="translate(2082.667 0)" d="M309 -12Q227 -12 166 22.5Q105 57 71 120Q37 183 37 268Q37 353 71 415.5Q105 478 166 513Q227 548 309 548Q380 548 436.5 523Q493 498 528 451Q563 404 571 338L416 331Q409 381 380.5 406.5Q352 432 309 432Q253 432 222 389Q191 346 191 268Q191 190 222 146.5Q253 103 309 103Q352 103 381 129.5Q410 156 416 210L571 204Q564 138 529.5 89.5Q495 41 438.5 14.5Q382 -12 309 -12Z"/><path transform="translate(2636.933 0)" d="M309 -12Q227 -12 166 22.5Q105 57 71 120Q37 183 37 268Q37 353 71 415.5Q105 478 166 513Q227 548 309 548Q391 548 452 513Q513 478 547 415.5Q581 353 581 268Q581 183 547 120Q513 57 452 22.5Q391 -12 309 -12ZM309 103Q365 103 396 146.5Q427 190 427 268Q427 346 396 389.5Q365 433 309 433Q253 433 222 389.5Q191 346 191 268Q191 190 222 146.5Q253 103 309 103Z"/><path transform="translate(3211.6 0)" d="M257 -12Q189 -12 139.5 22.5Q90 57 63.5 119.5Q37 182 37 268Q37 354 64 416.5Q91 479 140.5 513.5Q190 548 257 548Q314 548 355.5 524.5Q397 501 418 460L418 710L568 710L568 0L425 0L422 79Q400 36 356.5 12Q313 -12 257 -12ZM306 103Q342 103 367 122Q392 141 405 177.5Q418 214 418 268Q418 323 405 359.5Q392 396 367 414.5Q342 433 306 433Q253 433 222 388.5Q191 344 191 268Q191 193 222.5 148Q254 103 306 103Z"/><path transform="translate(3802.267 0)" d="M307 -12Q225 -12 164.5 22.5Q104 57 70.5 120Q37 183 37 268Q37 353 70.5 415.5Q104 478 164 513Q224 548 306 548Q386 548 445 513Q504 478 536.5 413Q569 348 569 258L569 228L192 228Q195 164 226.5 133Q258 102 310 102Q348 102 373.5 118Q399 134 410 167L561 158Q540 78 472 33Q404 -12 307 -12ZM192 320L415 320Q412 379 382.5 408Q353 437 306 437Q259 437 228.5 406.5Q198 376 192 320Z"/></g>
+  <g fill="var(--nc-primary, #00a85a)" transform="translate(259 76) scale(0.06 -0.06)"><path transform="translate(0 0)" d="M19 0L275 710L455 710L711 0L553 0L501 151L228 151L176 0ZM271 276L459 276L365 550Z"/><path transform="translate(670.467 0)" d="M74 0L74 710L226 710L226 0Z"/></g>
+</svg>

package/dist/css/chat-autoplay.js

@@ -4,24 +4,23 @@
  *
  * It is pure progressive enhancement, framework-free, dependency-free, with no
  * module-loader statements and no third-party runtime. It turns an
- * already-static `.nc-chat-thread` into the auto-playing, looping agent
- * conversation from the archived prototype
- * `docs/experiments/design-canvas/chat-anim.jsx` — re-expressed as plain DOM.
+ * already-static `.nc-chat-thread` into an auto-playing, looping agent
+ * conversation.
  *
- * Contract (mirrors AC-018 and the M5 motion contract):
+ * Runtime behavior:
  *
  *  (a) Motion on: messages are hidden, then revealed in scripted source order by
- *      toggling the M5 `.nc-anim-msg-in` hook (the rise-in). A typing indicator
+ *      toggling the `.nc-anim-msg-in` hook (the rise-in). A typing indicator
  *      (`.nc-typing-dots`) shows between turns, the thread body auto-scrolls to
  *      the newest message, the `.nc-usage-meter-fill` is driven via `--nc-usage`,
- *      and after `loopHold` (default 2400ms) the cycle restarts.
+ *      and after `LOOP_HOLD` the cycle restarts.
  *
  *  (b) `prefers-reduced-motion: reduce`: the FULL thread is shown immediately,
  *      every message visible, NO loop, no typing animation. (We also stop if the
  *      preference changes to reduce mid-play.)
  *
  *  (c) Script absent: the conversation renders FULLY and statically from CSS
- *      alone. The atoms set `animation-name: nc-msg-in` but, without the M5
+ *      alone. The atoms set `animation-name: nc-msg-in` but, without the
  *      `.nc-anim-msg-in` hook supplying a duration, that is inert and every
  *      message is visible. This file is the ONLY thing that ever hides a message
  *      (via the per-element inline `display` it sets while playing). No hidden
@@ -30,13 +29,11 @@
  *  (d) Playback starts on scroll-into-view via `IntersectionObserver`; it pauses
  *      (resets to the static full thread and re-arms) when scrolled fully out.
  *
- * Timing parity with `src/css/motion.css`: the loop reads the M5 duration tokens
+ * Timing parity with `src/css/motion.css`: the loop reads the duration token
  * (`--nc-duration-stagger`) from the thread's computed style and uses the
- * per-role `defaultTiming()` rhythm ported verbatim from the prototype's
- * `defaultTiming` (typingMs / holdMs per role + `loopHold`). The stagger unit
- * comes from CSS, not a re-typed magic number; the per-role typing/hold cadence
- * is the documented constants table below, carried with a parity note because
- * the prototype owns those numbers in JS, not in CSS.
+ * per-role `defaultTiming()` rhythm below. The stagger unit comes from CSS, not
+ * a re-typed magic number; this module owns the sequencing cadence because it
+ * is runtime behavior rather than a reusable visual token.
  *
  * Opt-in: only `.nc-chat-thread[data-nc-autoplay]` elements are enhanced. A
  * thread without the attribute is left fully static.
@@ -51,14 +48,9 @@
 
   if (typeof window === "undefined" || typeof document === "undefined") return;
 
-  // ── Per-role timing, ported verbatim from chat-anim.jsx `defaultTiming`. ──
-  // PARITY NOTE: these (typingMs, holdMs) pairs and `LOOP_HOLD` live in JS in the
-  // prototype (they are sequencing logic, not CSS), so they are mirrored here as
-  // a documented constants table rather than read from motion.css. The CSS owns
-  // the *visual* cadence (the stagger step), which we DO read from motion.css
-  // below; this table owns the *sequencing* cadence.
-  var LOOP_HOLD = 6000; // chat-anim.jsx loopHold default (raised: payoff frame dominates loop duty cycle)
-  var START_DELAY = 240; // chat-anim.jsx `await sleep(startDelay + 240)` with startDelay 0
+  // The CSS token owns visual stagger. These values own runtime sequencing.
+  var LOOP_HOLD = 6000; // Keep the completed state visible for most of the loop.
+  var START_DELAY = 240;
 
   function defaultTiming(role, textLen) {
     var len = textLen || 0;
@@ -255,7 +247,7 @@
 
   ChatThreadPlayer.prototype._reveal = function (msg, index) {
     msg.style.display = "";
-    // Re-trigger the M5 rise-in: the hook supplies duration/easing; the atom
+    // Re-trigger the rise-in: the hook supplies duration/easing; the atom
     // already carries `animation-name: nc-msg-in`. Force a reflow so re-adding
     // the class restarts the animation on a re-loop.
     msg.style.setProperty("--nc-anim-delay", "0ms");
@@ -266,9 +258,8 @@
     this._scrollToBottom();
   };
 
-  // The reveal loop — a vanilla re-expression of chat-anim.jsx's `run()`. A loop
-  // is "stale" once it is cancelled OR a newer epoch has started; either way it
-  // must stop touching the DOM. `myGen` is captured once at start so a queued
+  // A loop is "stale" once it is cancelled OR a newer epoch has started; either
+  // way it must stop touching the DOM. `myGen` is captured once at start so a queued
   // continuation can detect that the player was stopped-and-re-armed underneath
   // it (see the `generation` note in the constructor).
   ChatThreadPlayer.prototype._runLoop = function () {
@@ -406,7 +397,7 @@
   function enhance(thread) {
     if (thread.__ncAutoplayPlayer) return thread.__ncAutoplayPlayer;
     var player = new ChatThreadPlayer(thread);
-    // Read the M5 stagger token off the live thread (parity with motion.css);
+    // Read the stagger token off the live thread (parity with motion.css);
     // fallback equals the motion.css default (160ms) if the bundle is absent.
     player.staggerMs = durationToken(thread, "--nc-duration-stagger", 160);
     thread.__ncAutoplayPlayer = player;
@@ -477,7 +468,7 @@
     for (var j = 0; j < players.length; j++) observer.observe(players[j].thread);
   }
 
-  // ── Settle module — enhancer-armed, run-once scroll entrance ─────────────
+  // ── Enhancer-armed, run-once scroll entrance ─────────────────────────────
   // Arms .nc-settle elements that are fully below the viewport at init.
   // On first IntersectionObserver entry, switches data-nc-settle from "armed"
   // to "in" (triggers the CSS nc-msg-in animation) and immediately unobserves