@nadicodeai/ui 9.2.1 → 10.0.0

package/docs/activity.md

@@ -1,133 +1,113 @@
 # System activity
 
-**Target state** ([the nadicode design system ADR](../../../docs/adr/2026-09-23-the-nadicode-design-system.md), #2261): this family retires. Who does the work decides how it looks: an Agent's work shows that Agent's orb and a sentence; Nadia connecting is her ribbon, working; system work under about a second is a still pending label on the control; beyond a second one 2 px ink waiting line moves linearly on the `wait` token; measurable work is a progress line with a written count; page loads show still placeholders. An orb means an Agent, so an orb for system work is the confusion this change removes. Until #2261, #2262 and #2263 land, this page describes what is built.
-
-The system activity family has three motions. They describe ongoing system
-operations across the website, Portal and Nadia. They do not represent an
-Agent's identity, attention or personality. The separate [AgentOrb](agent-orb.md)
-uses seven of the same upstream geometries for persistent identity, with one
-chosen pigment instead of the system activity palette.
-
-| Activity | Use when | Library motion |
-| --- | --- | --- |
-| `loading` | Retrieving or revealing content: opening a workspace, fetching records, refreshing a view, retrieving search results. | `composing`: flowing dotted bands wrap around a globe, shown as “Thinking…” in the library's large demo. |
-| `connecting` | Actively establishing or restoring communication with an account, service or device. | `connecting`: links form between nodes and carry signals. |
-| `processing` | Carrying out an operation: saving, submitting, applying changes, validating, importing, preparing an export, reconciling a sync, or other unmeasured work. | `working`: particles travel on tilted orbits. |
-
-These are three NadicodeAI activity treatments, not a claim that every design
-system defines these categories. The label names the specific operation;
-people are never expected to decode particle movement alone.
-
-## Choose the feedback
-
-An operation's purpose selects the orb; the endpoint, worker or request type
-does not. Retrieving search results is `loading`. Establishing the connection
-before that request is `connecting`. A working connection remains a settled
-status while data loads. Synchronizing records after connection is
-`processing`; reconnecting during sync temporarily uses `connecting`.
-
-Saving is `processing`, not a fourth activity. Uploading, downloading,
-installing and converting use the existing `Progress` component when the
-completed amount can be measured. For an unmeasured preparation phase, use
-`processing`. When progress will become measurable, reserve a progress
-treatment from the start so the transition does not move the layout. Never
-invent a percentage or surround an indeterminate orb with a simulated fill.
-
-Queued, paused, offline, blocked, successful and failed conditions use the
-existing status or action-feedback treatment. A request waiting for a person
-does not keep an orb moving. A retry uses `connecting` only while an actual
-connection attempt is in progress; its failure or recovery replaces activity
-with the appropriate feedback. An account being active is not an activity.
-
-Use the indicator beside the operation it describes. Keep the rest of the
-interface available. One operation gets one indicator; separately progressing
-operations can each have one. For content with a predictable layout, prefer
-`Skeleton` or retained content over replacing the region with an orb. Do not
-show both a skeleton and a central orb for the same wait.
-
-## Brand treatment
-
-All three reuse `thinking-orbs` 0.3.1 (MIT). Their geometry, depth ordering and
-size-specific density remain the library's. NadicodeAI adapts the palette and
-clock, not the rendering engine.
-
-The structure inherits the surrounding text's neutral ink. Foreground and
-signal particles carry the existing cobalto `--nc-info` role, mixed with that
-ink to preserve contrast in either appearance. Depth fades into the actual
-surface through transparency. There are no activity-specific colours: cobalto
-means work underway throughout the family. Green, amber and red retain their
-settled feedback meanings. Controls and panel backgrounds remain neutral.
-
-The selected clock multipliers are 0.92 for loading, 0.86 for connecting and
-0.92 for processing, applied to each original size-specific preset. The
-connection animation is slightly quieter because its forming links add
-movement as well as its travelling particles. The implementation owns these
-values together; consumers cannot tune speed, density or particle colours.
-
-Use 20 CSS pixels inline, including buttons and rows with room for that size;
-64 for a contained region; 88 on an application's entry screen. The 20 preset is
-separately tuned, and must not be obtained by shrinking the 64 preset. The 88
-extent uses the 64 preset. A 12–16 pixel badge slot keeps its existing compact
-spinner until its surrounding component explicitly accommodates this family.
-Nadia's desktop accommodates it once, in the spinner itself: the spinner's box
-stays one text line tall and at least 20 pixels wide, and the 20 pixel orb sits
-centred in it and overhangs it above and below, so a row keeps its height and
-the orb never meets the text beside it.
-
-## React
+Who does the work decides how it looks.
 
-```tsx
-import { ActivityOrb } from "@nadicodeai/ui/components/activity-orb";
+An Agent's work shows that Agent's orb in its state and a sentence saying what
+it is doing; [AgentOrb](agent-orb.md) owns it, and Nadia connecting is her
+ribbon, working. Everything on this page is the *system's* own work: a save, a
+sign-in, a refresh, a page load. An orb means an Agent, so system work never
+takes one.
 
-<ActivityOrb activity="loading" label="Caricamento progetti" size={64} />;
+| The wait | What it shows |
+| --- | --- |
+| Under about a second | The control's own label changes to its pending word. Nothing else. |
+| Past a second | One `WaitingLine` beside the work, and nothing else moves. |
+| Measurable | `Progress` with a written count ("120 di 240 fatture"). |
+| A page load | `Skeleton` placeholders in the shape of the content, still. |
 
-<div role="status">
-  <ActivityOrb activity="connecting" decorative />
-  <span>Connessione all’account…</span>
-</div>;
+One wait gets one indicator. Separately progressing operations may each have
+one. A request waiting for a person is not a wait: queued, paused, offline,
+blocked, successful and failed conditions take the status or feedback
+treatment. An account being active is not an activity.
+
+## The pending label
+
+The control keeps its place, its size and its icon; only its word changes, and
+the caller marks the control `disabled` and `aria-busy` so the change is
+announced as well as read.
+
+```tsx
+import { PendingLabel } from "@nadicodeai/ui/components/pending-label";
 
-<Button disabled={saving} aria-busy={saving}>
-  {saving ? <ActivityOrb activity="processing" decorative /> : null}
-  Salva modifiche
+<Button aria-busy={saving || undefined} disabled={saving} type="submit">
+  <PendingLabel pending={saving} pendingLabel="Salvataggio…">
+    Salva modifiche
+  </PendingLabel>
 </Button>;
 ```
 
-`activity` is required. `size` defaults to 20. A meaningful standalone orb
-requires `label`; `decorative` removes its accessible name when the adjacent
-text or control already supplies the meaning. `paused` freezes the current
-frame for a user-controlled motion pause or a design specimen. It does not
-mean the underlying operation is paused. Product code unmounts the orb when
-the operation ends or cannot proceed.
-
-Nadia's initial HTML can use `mountActivityOrb(canvas, activity, size)` from
-`@nadicodeai/ui/activity` before React loads. It is the renderer used by
-`ActivityOrb`, with the same motion, palette and accessibility requirements.
-The caller supplies the canvas and adjacent label, and calls `destroy()` when
-the operation fails or React replaces the startup surface.
-
-Import `@nadicodeai/ui/globals.css` as described in the
-[consumer guide](consuming-cross-repo.md). The renderer inherits actual CSS
-ink and reads canonical colour tokens. Nadia's entry screen wraps this renderer
-in its own `Orb`, which fixes a dark appearance the shared renderer knows
-nothing about; that wrapper lives in the desktop, not here.
-
-## Accessibility and runtime
-
-Reduced motion holds one representative frame and makes no animation requests.
-A preference change takes effect while the component is mounted. The
-operation's readable label remains. Pausing and resuming preserves the phase.
-Offscreen or hidden activity stops rendering. Removing a component removes
-its animation request and observers. DPR is capped at two. The renderer uses
-Canvas 2D and requires no WebGL; without a 2D context, the accessible meaning
-remains and the surrounding operation stays usable.
+`pending` and `pendingLabel` are required; the children are the idle label. It
+renders a `span` carrying `data-slot="pending-label"` and, while pending,
+`data-pending="true"`. It adds no mark of its own: a control that had an icon
+keeps that icon, unchanged, throughout the wait.
 
-## Ownership and source
+## The waiting line
+
+A 2 px track of ink with a 32% segment crossing it linearly on the `wait`
+token, after one second of waiting. Before that second the track is there and
+empty, unannounced, so the line arriving moves nothing around it; a wait the
+person barely notices does not deserve movement, and a control that flashed an
+indicator for 200 ms reads as a glitch.
+
+```tsx
+import { WaitingLine } from "@nadicodeai/ui/components/waiting-line";
+
+<WaitingLine label="Caricamento delle fatture" />;
+
+<div>
+  <p>Stiamo preparando il documento.</p>
+  <WaitingLine decorative />
+</div>;
+```
+
+A meaningful standalone line takes `label` and announces itself as a status;
+`decorative` removes its accessible name when the text beside it already says
+what is happening. Width comes from the caller (`className="w-24"`, or the
+full width of the region it belongs to); height, ink, segment and timing are
+the component's and are not tunable. The one-second delay is
+`WAITING_LINE_DELAY_MS`, exported so a test can name it rather than guess it.
+
+Reduced motion drops the travel and breathes the full line in opacity, so a
+wait still reads as a wait. The rule lives in
+`packages/design-system/src/css/motion.css` as `.nc-anim-wait`, with the rest
+of the motion vocabulary.
 
-The component owns rendering and the closed activity choices. Applications
-own requests, retries, progress measurements, copy, completion and recovery.
-Product-design guidance links here for selection and usage. The foundation's
-colour meanings remain in the design-system contract.
+Product code unmounts the line when the operation ends or cannot proceed.
+
+## Measurable and still
+
+`Progress` carries work whose completed amount is known, always beside a
+written count. When work will become measurable, reserve the progress
+treatment from the start so the transition does not move the layout. Never
+invent a percentage.
+
+`Skeleton` is a still placeholder shaped like the content behind it. It does
+not pulse. Do not show a skeleton and a waiting line for the same wait: the
+placeholders already say the page is arriving.
+
+## What retired
+
+`ActivityOrb` and `mountActivityOrb`, `Spinner`, `GlyphSpinner`, Sonner's
+spinning loading icon, the raw `LoaderCircle` spinners in `feedback-state`,
+`installer-shell`, `automation-section` and `confirm-dialog`, the assistant-ui
+attachment, tool-fallback and tool-group spinners, and the shimmer text on the
+reasoning, tool-fallback and tool-group triggers. With them went the
+`thinking-orbs` system-activity palette, the `tw-shimmer` dependency and the
+duplicate `@utility shimmer`, and the unused `nc-anim-typing` and
+`nc-anim-shimmer` hooks.
+
+Where one of those marked a running state inside a component, the state is now
+said in words and marked with a still glyph: an installer step and an
+automation row take `CircleDotIcon`, and a running tool call says "Running
+tool". A status badge never moves; its word and its mark carry the state.
+
+## Ownership and source
 
-The source selection follows the [library's public engine and presets](https://libraries.dev/orbs).
+The components own the delay, the geometry, the ink and the motion. The
+application owns the request, the retry, the copy, the completion and the
+recovery. The decision behind this page is
+[the nadicode design system ADR](../../../docs/adr/2026-09-23-the-nadicode-design-system.md);
+the design-system side of it is
+[`DESIGN.md`, "## System activity"](../../design-system/DESIGN.md#system-activity).
 The distinction between measured and unmeasured progress follows
 [Apple's progress guidance](https://developer.apple.com/design/human-interface-guidelines/progress-indicators).

package/docs/agent-orb.md

@@ -16,7 +16,6 @@ uploads in Nadia is theirs, not an identity this package draws.
 | `braid` | Interwoven strands | `weaving` |
 | `morph` | Changing geometric contour | `shaping` |
 
-**Target state** ([the nadicode design system ADR](../../../docs/adr/2026-09-23-the-nadicode-design-system.md)): an idle orb holds still and every surface passes the Agent's real state, so only a working Agent moves (#2260); under reduced motion a thinking or working orb breathes in opacity instead of freezing (#2260); the colours a person may choose are cobalto, verde and arancio beside the inherited default, and a stored rosso draws arancio, because rosso equals the error red (#2269). Until those land, the rest of this page describes what is built.
 
 ## Nadia
 
@@ -38,16 +37,30 @@ strings, server-safe so a server can resolve a row before it renders:
 | Field | Stored as |
 | --- | --- |
 | `shape` | `orb:orbit`, `orb:ribbon`, `orb:lattice`, `orb:globe`, `orb:network`, `orb:braid`, `orb:morph` |
-| `color` | The design system's identity hex of cobalto, verde, rosso or arancio, or null |
+| `color` | The design system's identity hex of cobalto, verde or arancio, or null; or a rosso an Agent chose before rosso left the picker |
 
 `resolveAgentOrb(stored, { root })` returns the form and colour to draw. The
 root Agent is Nadia and draws `nadia` whatever is stored. An unknown or empty
 shape draws `orbit`; an unknown or empty colour draws the inherited text
 colour, which is also the default a picker's reset restores. Paint a colour
-with `agentOrbColorTokens[color]`. The four colours clear 3:1 against both the
-white and the black canvas; giallo does not and is not offered. Each retired
-`forma:` spelling resolves to its own orb, so an Agent keeps a distinct look
-until someone changes it.
+with `agentOrbColorTokens[color]`. Each retired `forma:` spelling resolves to
+its own orb, so an Agent keeps a distinct look until someone changes it.
+
+## The three colours
+
+A person chooses cobalto, verde or arancio, or nothing, which leaves the orb
+the inherited text colour. All three clear 3:1 against both the white and the
+black canvas, so a chosen orb stays visible in either theme; giallo does not
+(1.6:1 on white) and is not offered.
+
+Rosso is not offered either. It is exactly the error red, so a red Agent beside
+a red "Bloccato" badge read as a broken Agent rather than a chosen colour.
+Nadia keeps rosso in her own stripes, where it is one of four and says nothing
+on its own. An Agent that chose rosso before it left the picker keeps a colour:
+`resolveAgentOrb` maps a stored `rosso`, by name or by the `#d3302f` hex, to
+arancio, the nearest hue that is not a status. That is a mapping on the way in,
+not an offer on the way out — `agentOrbColors` is what a picker shows, and it
+has three entries.
 
 The appearance is a person's choice, never derived: do not infer it from a name,
 an id hash or a role. A machine check-in is not Agent activity, so a surface that
@@ -62,6 +75,7 @@ import { AgentOrb } from "@nadicodeai/ui/components/agent-orb";
 
 <AgentOrb form="ribbon" color="var(--nc-identity-cobalto)" size={32} label="Research" />;
 <AgentOrb form="nadia" size={32} label="Nadia" />;
+<AgentOrb form="globe" presence="over-picture" size={96} state="working" label="Ricerca" />;
 ```
 
 `form` is required. `color` accepts one CSS colour, including a customer-chosen
@@ -75,6 +89,15 @@ that single-colour identity, using the existing chart and warning tokens. Choose
 colour visible on the intended background. A deliberately black pigment on a
 black surface is not automatically recoloured.
 
+A native startup screen paints an orb before React loads through
+`mountAgentOrb(canvas, { form, size, presence, state, paused })` from
+`@nadicodeai/ui/agent-orb`, the React-free entry beside
+`@nadicodeai/ui/activity`. It is the renderer `AgentOrb` itself mounts, with
+the same motion, states and presence; the caller supplies the canvas and the
+adjacent name, and calls `destroy()` when React replaces the startup surface.
+Import `@nadicodeai/ui/globals.css` with it: the renderer inherits the CSS ink
+and reads the colour tokens from the element.
+
 Sizes are 20, 24, 32, 40, 64, 96 and 160 CSS pixels. Menu sizes through 32 use
 the upstream compact density; larger sizes use its detailed profile. `paused`
 holds the current frame and resumes without resetting the appearance. An
@@ -84,16 +107,42 @@ API because the stock React component only offers monochrome light/dark ink,
 not a configurable pigment.
 
 Motion is limited to 30 painted frames per second. Offscreen and hidden orbs
-stop scheduling animation. Reduced motion freezes the current frame and is
-observed live. Unmount removes the frame request and observers. DPR is capped
-at two. Without Canvas 2D, the accessible name remains available.
-
-`state` accepts idle, working, waiting, blocked, thinking and done. Geometry
-and state gestures have separate clocks: slowing a gesture must not make the
-idle form appear frozen. Each form has its own geometry pace, shared across
-avatar sizes; Morph holds a contour for about 1.6 seconds and changes it over
-one second at idle. Working and Thinking keep the form's base pace.
-Waiting holds its pose; Blocked makes one gentle interrupted effort and stops.
+stop scheduling animation. Unmount removes the frame request and observers.
+DPR is capped at two. Without Canvas 2D, the accessible name remains
+available.
+
+The engine paints the box the canvas occupies, not the `size` it was given: a
+`ResizeObserver` follows the element, and the backing store and the geometry's
+density profile both come from the measured CSS pixels. `size` sets that box
+through `--nc-agent-orb-size` in a class, so a caller whose layout decides the
+size overrides it with its own sizing class and the orb stays sharp at
+whatever width it lands on. The declared size still stands in before layout
+has measured anything, on a server render and in a test environment without
+layout.
+
+`presence` decides how loudly one orb reads on its ground, per mount, never
+as a module setting: two orbs on one page can want different weights.
+`plain`, the default, is the interface's own ink. `over-picture` multiplies
+ink by 2.3 and every dot and line radius by 1.9, for an orb drawn on a
+photograph, where the plain weights sink into the image. Nadia on open sky
+keeps `plain`.
+
+Reduced motion turns movement off and keeps opacity and colour. A thinking or
+working orb breathes between full ink and 0.45 over 1.6 s, ease-in-out, so
+busy still reads as busy; its geometry does not turn, and the state cue
+breathes with the body. Every other state, idle, waiting, blocked and done
+included, holds one still frame. The preference is observed live.
+
+`state` accepts idle, working, waiting, blocked, thinking and done, and every
+surface passes the Agent's real one: only Agents move on their own, so motion
+on a screen means an Agent is working and a still orb means it is not. Idle
+holds one still pose and schedules no frame after its first paint; a surface
+that knows only check-ins draws idle, because a machine check-in is not Agent
+activity. Geometry and state gestures have separate clocks. Each form has its
+own geometry pace, shared across avatar sizes, which Working and Thinking
+keep; Morph holds a contour for about 1.6 seconds and changes it over one
+second. Waiting holds its pose; Blocked makes one gentle interrupted effort
+and stops.
 V7 keeps the material free-standing and intact:
 no gear, thought bubble, pause, exclamation mark or check is cut into the form.
 Working and Thinking preserve the native geometry: do not stretch, flatten,
@@ -104,14 +153,16 @@ with sequential opacity and slight size pulses on a 3.6-second loop.
 The distinct symbols remain visible throughout both cycles. Done repeats
 the ribbon in three celebratory sweeps and then rests. Changing `motionKey`
 replays it. These exterior cues use the celebration palette; the body keeps
-its configured pigment. Reduced motion holds both cues still.
+its configured pigment.
 No state has an enclosing circle. Keep a nearby status label where exact
 state identification matters, including reduced motion and compact sizes.
-Reduced motion holds the state pose and skips the celebration.
 
 In the Portal, [`agent-identity.tsx`](../../../apps/portal/src/components/agent-identity.tsx)
 draws every Agent, in its lists, Agent workspace and the sign-in, sign-up and
-Get Nadia pages. Inspect them in the running local Portal for compact and
-full-size appearances.
+Get Nadia pages, and `src/lib/agent-orb.ts` maps what a machine reported to
+the state drawn. It also gives an orb a `travelId`, which wraps it in React's
+`<ViewTransition>` so the same orb travels from a list row into the Agent's
+page; `apps/portal/docs/design-doctrine.md` owns that rule. Inspect them in
+the running local Portal for compact and full-size appearances.
 
 [Upstream library and presets](https://libraries.dev/orbs), MIT licensed.

package/docs/component-classification.md

@@ -3,7 +3,7 @@
 This file records the ownership class for U4 product compositions. The package may render standard product UI, but consuming apps own app behavior, data, persistence, and product-specific promises.
 
 If first-party shadcn or assistant-ui registry source already covers the same
-generic product UI, do not add a parallel NadicodeAI package API. Use the
+generic product UI, do not add a parallel nadicode package API. Use the
 registry item in the consuming app and adapt it there with app-owned data,
 copy, and behavior.
 
@@ -20,8 +20,8 @@ copy, and behavior.
 | Component | Classification | Built on | Required states | Package-owned accessibility | Fixture |
 | --- | --- | --- | --- | --- | --- |
 | `ActionMenu` | Canonical record-action composition. | shadcn `Button` and `DropdownMenu`. | closed, open, keyboard selection, focus return. | Required accessible trigger name; inherited menu mechanics. | `../src/components/action-menu.test.tsx` |
-| `SettingsSection` | NadicodeAI product composition. | shadcn Card slots, Separator, and FieldGroup. | header, field group, and divided action footer. | Section structure; consumer owns the form transaction. | `../src/components/settings-section.test.tsx` |
-| `SettingsField` | NadicodeAI product composition. | shadcn Field, FieldLabel, FieldDescription, and FieldError. | valid, invalid, required, and disabled field rows. | Render callback supplies the control's label and message associations in server and client components. | `../src/components/settings-section.test.tsx` |
+| `SettingsSection` | nadicode product composition. | shadcn Card slots, Separator, and FieldGroup. | header, field group, and divided action footer. | Section structure; consumer owns the form transaction. | `../src/components/settings-section.test.tsx` |
+| `SettingsField` | nadicode product composition. | shadcn Field, FieldLabel, FieldDescription, and FieldError. | valid, invalid, required, and disabled field rows. | Render callback supplies the control's label and message associations in server and client components. | `../src/components/settings-section.test.tsx` |
 | `FeedbackState` | Net-new central product state composition adapted from shadcn empty-state patterns. | shadcn `Empty` and lucide status icons. | `empty`, `loading`, `saving`, `error`, `permission`, `offline`, `no-results`, `fatal`. | `role="status"` for loading/saving; `role="alert"` for error, permission, offline, and fatal. | `../tests/guards/product-compositions.test.ts` |
 
 ## App-Owned Boundaries
@@ -36,7 +36,7 @@ Keep these out of `@nadicodeai/ui`:
 
 ## Fixture Guidance
 
-U4 fixtures should use NadicodeAI-relevant work objects:
+U4 fixtures should use nadicode-relevant work objects:
 
 - briefing agents, review agents, approval queues, sessions, models, workspace defaults, files, pairing codes, and weekly approvals;
 - controlled state examples for sorting, selection, visibility, validation, loading, saving, offline, permission, and fatal states;

package/docs/consuming-cross-repo.md

@@ -82,22 +82,20 @@ the same value. Consumers may compose domain-specific components from the
 public UI package; the rules govern package boundaries and design values, not
 the shape of a consumer's JSX tree.
 
-## NadicodeAI logo
+## nadicode logo
 
-React surfaces that need both the mark and readable company name use the
-horizontal lockup from the UI package:
+React surfaces name the company with the wordmark from the UI package:
 
 ```tsx
-import { BrandLockup } from "@nadicodeai/ui/components/brand";
+import { BrandWordmark } from "@nadicodeai/ui/components/brand";
 
-<BrandLockup alt="NadicodeAI" />;
+<BrandWordmark alt="nadicode" />;
 ```
 
-Use `BrandMark` where space is tight and `BrandWordmark` where the name must read
-by itself. Do not assemble a new lockup from those two components. Static
-consumers that need files instead of React declare the design-system dependency
-directly and use the documented SVG or PNG package routes in
-`packages/design-system/README.md`.
+Use `BrandMark`, the plain n, where the name does not fit. The n is cut from the
+wordmark, so never place the two together. Static consumers that need files
+instead of React declare the design-system dependency directly and use the
+documented SVG or PNG package routes in `packages/design-system/README.md`.
 
 ## Base UI API breaks (migrating from Radix-era components)
 

package/docs/contract.md

@@ -7,7 +7,7 @@ The normative invariants for the `@nadicodeai/ui` package: what may live here, h
 - **Token-only, no raw literals or shadow aliases.** Components style through semantic shadcn utilities (`bg-background`, `text-foreground`, `border-input`, and the rest), or a canonical generated design-system token when no standard role is precise enough. The UI package does not mint screen-, component-, or product-specific color aliases. No raw `#hex` / `rgb()` / `hsl()` may appear in `.tsx`; a new source value goes to `packages/design-system/DESIGN.md` first and flows through generated output. A narrow protocol adapter may translate third-party classes directly to canonical tokens in `globals.css`, but it must not create another token vocabulary. Enforced by the raw-colour `no-restricted-syntax` selectors in the library ESLint config, `packages/ui/tests/guards/dark-semantic-roles.test.ts`, and `packages/ui/tests/guards/token-reference-integrity.test.ts`.
 - **Dark-ready semantics, no component dark implementation.** Components use the same semantic role or canonical mode-aware token in every mode. They must not ship Tailwind `dark:` color utilities, component-local `.dark` blocks, OS dark-mode branching, or raw dark palette utilities such as `dark:bg-slate-950` and `dark:text-white`. An intentionally fixed-presentation technology surface, such as the dark terminal console, selects canonical fixed-mode tokens as one coherent component treatment rather than branching by app theme. Enforced by `packages/ui/tests/guards/no-dark.test.ts`, `packages/ui/tests/guards/dark-semantic-roles.test.ts`, and `packages/ui/tests/guards/token-reference-integrity.test.ts`. The generated mode and theme architecture lives only in [`packages/design-system/DESIGN.md`](../../design-system/DESIGN.md#css-architecture--token-pipeline).
 - **Components inherit one complete React style interface.** `@nadicodeai/ui/globals.css` composes every style dependency owned by this package, including the complete design-system CSS module. Components carry no theme of their own, and React callers do not compose design-system stylesheets or partials beside it. Installation and source-scanning setup live in the [consumer setup guide](consuming-cross-repo.md). The package ships two stylesheets, split by who owns the page. `@nadicodeai/ui/globals.css` is for an application this design system styles whole: it imports Tailwind, the complete design system with its reset and base layer, and the second file. `@nadicodeai/ui/components.css` is for a host that already runs Tailwind over base styles of its own, such as the Nadia desktop inside Hermes's shell: it carries the `@source` lines, the `nc-*` utilities and the component-owned rules, and nothing that lands on a page. That host imports `@nadicodeai/design-system/css/host` before it, which adds the Tailwind keys only this design system names and leaves the host its shadcn roles, its radius scale and its palette. The components render in both from one source, which is what keeps the products consistent. A surface that loads no Tailwind layer takes the design system's token artifact and writes its own rules against it.
-- **Design-system geometry remains the foundation.** React components compose the kept `nc-*` page grammar and display CSS components; they do not redefine frame math, marker placement, token values, or raw CSS geometry. Use parent-paints-plus-gap for bordered cell grids and keep every visible seam single-owner (doctrine home: `packages/design-system/DESIGN.md` "## Layout").
+- **Design-system geometry remains the foundation.** React components compose the shipped `nc-*` layout and display CSS components; they do not redefine the website's content column, its gutters, its step between sections, token values, or raw CSS geometry. Use parent-paints-plus-gap for bordered cell grids and keep every visible seam single-owner (doctrine home: `packages/design-system/DESIGN.md` "## Layout").
 
 ### Persistent notices
 
@@ -136,14 +136,15 @@ gone, is [`packages/design-system/DESIGN.md`, "## Status Vocabulary"](../../desi
 
 ## Package Shape Invariants
 
-System activity uses `ActivityOrb` for loading, connecting and processing;
-[activity.md](activity.md) owns selection, rendering and accessibility. It
-composes with status feedback and measured progress without adding outcome
-states to the orb.
+System activity is `PendingLabel` under a second, `WaitingLine` past one,
+`Progress` with a written count when the amount is known, and a still
+`Skeleton` for a page load; [activity.md](activity.md) owns selection,
+rendering and accessibility. An orb means an Agent, so no system wait takes
+one, and nothing here carries an outcome state.
 
 - **Source-authored, built package.** Components are authored as shadcn-style source in `src/`, then emitted to `dist/` for consumption by other apps. Package exports must point at built JS, declarations, and CSS, never raw `src/*.tsx`, and `npm pack --dry-run` must include only intentional consumer artifacts.
 - **Package surface is source-backed.** Public components stay flat under `src/components/`. Reviewed registry source under `src/internal/` is implementation, not a package namespace. Do not add top-level exports for recipes, blocks, agent, terminal, or vendor groupings unless a later package API decision adds concrete public source, built files, docs, and tests in the same change.
-- **Agents is the client-only conversation interface.** `@nadicodeai/ui/agents` re-exports the complete `@assistant-ui/react` runtime and primitive API plus the reviewed, branded registry composition held under `src/internal/assistant-ui/`. Its built entry retains `"use client"`. Consumers receive Thread, attachments, Markdown, reasoning, tools, suggestions, providers, runtimes, hooks, and types from that one domain namespace. Agent identity components use their direct component subpaths so server compositions do not import the conversation runtime. The vendor name is not a public NadicodeAI subpath, and the package does not rename, wrap, or rebuild assistant-ui behavior.
+- **Agents is the client-only conversation interface.** `@nadicodeai/ui/agents` re-exports the complete `@assistant-ui/react` runtime and primitive API plus the reviewed, branded registry composition held under `src/internal/assistant-ui/`. Its built entry retains `"use client"`. Consumers receive Thread, attachments, Markdown, reasoning, tools, suggestions, providers, runtimes, hooks, and types from that one domain namespace. Agent identity components use their direct component subpaths so server compositions do not import the conversation runtime. The vendor name is not a public nadicode subpath, and the package does not rename, wrap, or rebuild assistant-ui behavior.
 - **Base UI is the active primitive base.** `components.json` must resolve through a Base style, currently `base-nova`, and `npx shadcn@latest info --json` must report `base: "base"`. Do not reintroduce `radix-ui`, `@radix-ui/*`, or `vaul` to package source, dependencies, or app optimizer configuration. Registry-owned shadcn primitives stay aligned with current `shadcn@latest` Base UI output; use Base UI `render` composition instead of Radix `asChild`. `cmdk` is allowed only for the stock shadcn Command component while the current `base-nova` registry declares that dependency; do not use it elsewhere or replace it without a shadcn/compatibility decision and tests.
 - **Charts are stock shadcn charts.** Every chart and KPI here is a registry item, changed as little as possible: `chart.tsx` is shadcn's `chart` over Recharts; `chart-bar-stacked`, `chart-area-stacked`, `chart-bar-multiple`, and `chart-bar-horizontal` are the blocks of those names; `chart-sparkline` is `chart-line-linear` stripped of its card, axes, grid and tooltip; `kpi-card` is the `dashboard-01` block's section card; `chart-card` is their shared Card frame. Each pulled file names its registry item on line one. `base-nova` does not publish the chart gallery and the CLI search does not list it, so a chart the kit lacks is pulled from `https://ui.shadcn.com/r/styles/new-york-v4/<name>.json` (`files[0].content`) and added here. What deviates from stock, and why, is listed once in [`DESIGN.md`, "Chart source"](../../design-system/DESIGN.md#chart-source); a change to a pulled chart that is not on that list is drift. There is no hidden table twin, no mark inside a legend, and no second axis. Every chart component renders the whole card — `Card > CardHeader(CardTitle, CardDescription, CardAction) > CardContent(ChartContainer) > CardFooter?` — at a fixed plot height (`h-64`, `h-80` at `size="lg"`), legend below the plot, left-aligned and wrapping. An app composes these, never builds a chart card frame by hand, and never imports `recharts`, which this package alone declares. Which chart a reading question deserves is owned by [`skills/design/product-design/references/charts.md`](../../../skills/design/product-design/references/charts.md).
 
@@ -152,7 +153,7 @@ states to the orb.
 
 ## Admission Rules
 
-Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-orb`, its stored-appearance resolver `@nadicodeai/ui/components/agent-orb-appearance` (both owned by [`agent-orb.md`](agent-orb.md)), and `@nadicodeai/ui/components/agent-card`. The consuming application still constructs the runtime and owns transport, persistence, permissions, tools, approvals, and failure policy. Shared non-Agent product components (a shell, a settings surface, a generic section, a diff, or a file preview) are admitted only with a named consuming surface landing in the same change. App-bespoke UI and behavior (window chrome, PTY/xterm embeds, queues, approvals, and persistence) stay in the consuming app; they never become package abstractions. A component left unconsumed after its target migration ships gets removed.
+Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-orb`, its stored-appearance resolver `@nadicodeai/ui/components/agent-orb-appearance` (both owned by [`agent-orb.md`](agent-orb.md)), and `@nadicodeai/ui/components/agent-card`. `@nadicodeai/ui/agent-orb` and `@nadicodeai/ui/activity` are the two React-free entries: each exports the canvas renderer its component mounts, for a native startup screen that paints before React loads, and neither may import React. The consuming application still constructs the runtime and owns transport, persistence, permissions, tools, approvals, and failure policy. Shared non-Agent product components (a shell, a settings surface, a generic section, a diff, or a file preview) are admitted only with a named consuming surface landing in the same change. App-bespoke UI and behavior (window chrome, PTY/xterm embeds, queues, approvals, and persistence) stay in the consuming app; they never become package abstractions. A component left unconsumed after its target migration ships gets removed.
 
 ### Placement
 
@@ -177,8 +178,8 @@ product-domain `agent` object prop in the shared package.
 
 - **Standard components, not app-owned product features.** This package ships primitives, standard UI components, assistant-ui compositions, brand adapters, React adapters, reusable sections, and presentational product components. It must not ship app-specific feature/use-case screens or names such as operator-login, portal activation, customer credential control, or customer management. Domain registries, command search providers, and chart dashboards bind app data and routes in the app; that binding is not a reason to copy reusable presentation. Portal's DataTable owns its Next.js query and registry protocol once, while consuming the shared UI foundation. Product-independent compositions belong here with a real consumer. The source-backed `chart-*` and `kpi-card` package surface is the plan-approved exception per issue #166; apps select charts and bind their titles, data, and navigation. A chart is named by the card title above it and navigated through Recharts' own accessibility layer; the kit ships no hidden table twin, because a component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
 - **Auth routes are consumer-owned shadcn block work.** Login, signup, OTP, two-factor, magic-link, and provider-button flows start from the selected shadcn block/example in the consuming app, with app-owned Better Auth behavior. Do not ship generic auth, signup, OTP, federated-login, or provider abstractions from this package unless a later explicit boundary decision replaces the selected shadcn block.
-- **Reusable sections and compositions live here after proof.** Bento grids, media mounts, demo surfaces, page frames, section intros, CTA bands, proof slots, benefits grids, generic shells, and homepage/use-case sections belong in `@nadicodeai/ui` when a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary. Website, portal, and sibling Nadia routes pass data and media children into existing compositions instead of rebuilding layout locally.
-- **Brand renderers live here for React consumers.** Logo geometry, asset generation, and usage semantics are owned by [`packages/design-system/DESIGN.md`, "Brand media authority"](../../design-system/DESIGN.md#brand-media-authority). `BrandLockup` supplies the approved horizontal lockup. `BrandMark` serves tight spaces and `BrandWordmark` serves placements where the name must read by itself. All three render the package's public neutral geometry seam with React-scoped SVG ids, dynamic theme paint, and accessible names. Consuming routes use these adapters; they never import raw logo assets, draw brand SVG inline, mask or recolor assets, or create another lockup rule.
+- **Reusable sections and compositions live here after proof.** Media mounts, demo surfaces, section intros, CTA bands, proof slots, generic shells, and homepage/use-case sections belong in `@nadicodeai/ui` when a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary. Website, portal, and sibling Nadia routes pass data and media children into existing compositions instead of rebuilding layout locally.
+- **Brand renderers live here for React consumers.** Logo geometry, asset generation, and usage semantics are owned by [`packages/design-system/DESIGN.md`, "Brand media authority"](../../design-system/DESIGN.md#brand-media-authority). `BrandWordmark` names the company and `BrandMark` is the plain n, for placements where the name does not fit. There is no lockup adapter: the n is cut from the wordmark, so a placement carrying both would draw the letter twice, and `tests/brand-logo-usage.test.ts` fails on one. Both render the package's public neutral geometry seam, which emits no DOM id, with dynamic theme paint and accessible names. Consuming routes use these adapters; they never import raw logo assets, draw brand SVG inline, mask or recolor assets, or compose a new logo form.
 - **Third-party brand marks are generated, never hand-drawn and never hand-edited.** Other companies' marks live in `packages/ui/src/components/brand-icons/`, emitted from an explicit allow-list by `packages/ui/scripts/build-brand-icons.mjs` and exported through the `@nadicodeai/ui/components/brand-icons` subpath. They are identity images, not UI icons: a brand mark is exempt from the currentColor stroke system and from the raw-literal rule, it never stands in for a UI icon, and a UI icon never stands in for a brand. Marks drawn as one silhouette are stripped to `currentColor` by the generator; every other mark keeps its official colors verbatim. To add a brand, edit the generator's allow-list and run `npm run generate:brand-icons -w @nadicodeai/ui`; hand edits to the generated directory are lost and `packages/ui/tests/guards/brand-icons-codegen.test.ts` fails on them. Use is nominative only — naming a platform, an integration, or a provider — never adjacent to endorsement or partnership wording; that nominative posture is the licensing and trademark position, so a mark never appears where the copy implies endorsement.
   The one script reads platform and app marks from the Iconify `logos` set (CC0-1.0), model identities from the LobeHub icon set (MIT, `@lobehub/icons-static-svg`), and a small reviewed supplemental set from the official or OpenRouter-published source recorded beside each input. Raster supplements are embedded into generated SVG components, so a consumer never fetches a logo at runtime. The emitted components carry no icon-data runtime dependency. The artwork itself does ship, so every upstream travels with its applicable licence or provenance notice in `LICENSES/` and `NOTICE`, and `tests/guards/brand-icons-codegen.test.ts` holds the allow-list to that: a new source cannot ship unattributed.
 - **The house's own icons are Lucide components.** `@nadicodeai/ui/components/house-icons` exports `ArchIcon`, `ApprovalsIcon` and `AgentIcon`, built with lucide-react's `createLucideIcon` from the one geometry in `@nadicodeai/design-system/assets/house-icons`, so they take the `svg.lucide` house render and fit any `LucideIcon` slot. They name the company and its doors, work waiting on a person, and an Agent; a Lucide glyph never stands in for them. The render itself, a 1.5 px line held on screen and 1.25 px at 12 px, is `DESIGN.md` "Iconography".

package/docs/icon-assets.md

@@ -0,0 +1,106 @@
+# Icons as files
+
+`@nadicodeai/ui` draws icons as React components. The same icons also ship as
+plain SVG files, for a consumer that renders without React: a desktop shell, a
+CSS mask, a mail template, an `<img>` tag.
+
+Nothing in this set is drawn twice. Each brand file is its own committed
+component rendered once at build time, and the house icons come from the static
+set the design system generates, so a file and the component a page renders are
+the same shapes.
+
+## Where they are
+
+| What | Path |
+| --- | --- |
+| Third-party brand marks | `@nadicodeai/ui/assets/brand/<slug>.svg` |
+| The index over them | `@nadicodeai/ui/assets/brand/index.json` |
+| The house's three icons | `@nadicodeai/design-system/icons/{arch,approvals,agent}.svg` |
+| Lucide, under the house render | `@nadicodeai/design-system/icons/<name>.svg` |
+
+`index.json` lists every brand mark, so the set's size is read from it rather
+than copied into prose.
+
+The house and Lucide icons live in the design system because that package owns
+the static icon set (DESIGN.md `## Iconography`). `@nadicodeai/ui` pins it
+exactly, so installing UI installs those files too. They are 24 px on Lucide's
+24-unit grid, `fill="none"`, `stroke="currentColor"`, drawn with the house line
+weight held on screen by `vector-effect="non-scaling-stroke"`.
+
+A brand mark is an identity image, not a UI icon: it carries a third party's
+artwork and is exempt from the stroke system. Each file is 24 px square, keeps
+the brand's own colours, and names itself with `data-brand="<slug>"`. A mark the
+set draws as one silhouette paints with `currentColor` instead, so it stays
+visible on a dark surface; `index.json` says which marks those are. The files
+carry no `aria-*` attributes: whoever places a mark labels it, or leaves it
+decorative beside the text that names it.
+
+## Resolving an app name
+
+`index.json` is the set as data:
+
+```json
+{
+  "marks": [
+    {
+      "slug": "google-calendar",
+      "name": "Google Calendar",
+      "set": "app",
+      "mono": false,
+      "file": "google-calendar.svg",
+      "aliases": ["googlecalendar"]
+    }
+  ]
+}
+```
+
+`set` says which allow-list the artwork was listed in: `platform`, `app`, or
+`model`. `mono` is the silhouette rule above. `aliases` are the connector
+spellings `appMarkFor` resolves to that mark, already squashed to lowercase
+letters and digits.
+
+To resolve a connector name the way `AppMark` does, squash the name the same
+way and take an exact alias match; failing that, take the longest alias the
+squashed name contains, so `GitHub MCP` is GitHub and never a shorter
+accidental match. A name that matches nothing has no mark: show the app's
+initial, never an invented logo and never a fetched favicon.
+
+```js
+import index from "@nadicodeai/ui/assets/brand/index.json" with { type: "json" };
+
+const aliases = new Map(
+  index.marks.flatMap((mark) => mark.aliases.map((alias) => [alias, mark])),
+);
+const squash = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, "");
+
+export function markFor(app) {
+  const target = squash(app);
+  if (!target) return undefined;
+  if (aliases.has(target)) return aliases.get(target);
+
+  const alias = [...aliases.keys()]
+    .filter((key) => target.includes(key))
+    .sort((a, b) => b.length - a.length)[0];
+  return alias ? aliases.get(alias) : undefined;
+}
+```
+
+The table both sides read is `src/components/app-mark-aliases.ts`. Adding a
+connector spelling there puts it in the next release's index.
+
+## Keeping them true
+
+`scripts/build-icon-assets.mjs` writes `dist/assets/brand/` as a build step, from
+the built components and that alias table. There is nothing to regenerate by
+hand and nothing committed to review: a new mark arrives by the ordinary route,
+the allow-list in `scripts/build-brand-icons.mjs` and
+`npm run generate:brand-icons -w @nadicodeai/ui`, and the files follow the
+components it emits. `tests/guards/icon-assets.test.ts` rebuilds the set and
+fails when the shipped files are not what the components render, when the index
+does not name exactly the files beside it, or when an alias it publishes does
+not resolve the way `appMarkFor` does.
+
+## Nadia
+
+Nadia's desktop reads these files by moving its exact pin on `@nadicodeai/ui` to
+the release that carries them; nothing else in the package changes for it.