@nadicodeai/ui 8.0.1 → 8.2.0

package/dist/styles/components.css

@@ -0,0 +1,126 @@
+/*
+ * @nadicodeai/ui/components.css — what the components need from a stylesheet,
+ * and nothing that styles a page.
+ *
+ * `globals.css` owns an application: it imports Tailwind, the complete design
+ * system with its reset and base layer, and this file. A host that already
+ * runs Tailwind over base styles of its own cannot take it, because the reset
+ * and the base layer would restyle the host. Such a host takes this file
+ * instead, after its own `@import "tailwindcss"`:
+ *
+ *   @import "@nadicodeai/design-system/css/host";
+ *   @import "@nadicodeai/ui/components.css";
+ *
+ * It carries the three things without which a component renders unstyled: the
+ * `@source` lines that let the host's Tailwind see the components' class names
+ * (Tailwind never scans node_modules), the `nc-*` utilities those names use,
+ * and the few rules that belong to a component and not to a page.
+ *
+ * What the host must already have: the shadcn role names in its own theme
+ * (`--color-popover`, `--color-border`, `--color-muted-foreground`, …), mapped
+ * to whatever it likes. The components name those roles (`bg-popover`), and a
+ * host without them gets no CSS for those classes. The roles are the host's so
+ * that its theming, skins included, reaches our components unchanged.
+ */
+
+/*
+ * The one glass material (DESIGN.md "Elevation & Depth"): floating chrome —
+ * menus, popovers, selects, comboboxes, the command palette, and bars — may
+ * carry it; content surfaces stay solid. Glass composites only over our own
+ * content, and its elevation falloff's edge ring stays its one separator.
+ * Declared as a utility so variant prefixes can gate it (navigation-menu's
+ * non-viewport popup). Reduced transparency falls back to the same solid
+ * surface at the same elevation.
+ */
+@utility nc-glass {
+  background: color-mix(in srgb, var(--popover) var(--nc-material-glass-opacity), transparent);
+  backdrop-filter: blur(var(--nc-material-glass-blur)) saturate(var(--nc-material-glass-saturation));
+
+  @media (prefers-reduced-transparency: reduce) {
+    background: var(--popover);
+    backdrop-filter: none;
+  }
+}
+
+/*
+ * The four elevation rungs. Each utility paints the whole recipe of its rung
+ * from the generated --nc-elevation-* token, whose last layer is the rung's
+ * own optical ring in the current mode (design-system DESIGN.md
+ * "core.elevation"). An elevated surface therefore draws no second edge:
+ * never pair one of these with border-*, ring-*, or another box-shadow
+ * (`nadicodeai/no-elevated-edge` enforces it). Declared as utilities so
+ * variant prefixes can gate them.
+ */
+@utility nc-elevation-resting {
+  box-shadow: var(--nc-elevation-resting);
+}
+
+@utility nc-elevation-raised {
+  box-shadow: var(--nc-elevation-raised);
+}
+
+@utility nc-elevation-floating {
+  box-shadow: var(--nc-elevation-floating);
+}
+
+@utility nc-elevation-modal {
+  box-shadow: var(--nc-elevation-modal);
+}
+
+/*
+ * The proxy focus outline: the one restatement of the canonical treatment
+ * above, for an element that carries the indicator on another element's
+ * behalf (the input group around its control, the OTP slot for the hidden
+ * input, the chart wrapper for its svg, the slider thumb). The call site adds
+ * the hue with outline-ring or outline-destructive and nothing else.
+ * Declared as a utility so variant prefixes can gate it, and so the style is
+ * literally `solid` rather than Tailwind's `--tw-outline-style`, which any
+ * outline-none or outline-hidden on the same element sets to `none` for good.
+ */
+@utility nc-focus-outline {
+  outline-style: solid;
+  outline-width: var(--outline-width-focus);
+  outline-offset: var(--outline-offset-focus);
+}
+
+@layer components {
+  .nc-toast {
+    border: 0 !important;
+  }
+}
+
+/*
+ * The canonical design-system module owns raw --nc-* mode aliases, semantic
+ * roles, and their Tailwind utility bridge for both root and scoped `.dark`
+ * surfaces.
+ */
+
+.toaster [data-sonner-toast][data-styled="true"] [data-description] {
+  color: var(--muted-foreground);
+}
+
+.toaster [data-sonner-toast][data-styled="true"] [data-button] {
+  background: var(--popover-foreground);
+  color: var(--popover);
+}
+
+.toaster [data-sonner-toast][data-styled="true"] [data-cancel] {
+  background: var(--muted);
+  color: var(--popover-foreground);
+}
+
+.toaster [data-sonner-toast][data-styled="true"] [data-close-button] {
+  background: var(--popover);
+  border-color: var(--border);
+  color: var(--popover-foreground);
+}
+
+.toaster [data-sonner-toast][data-styled="true"] [data-close-button]:hover {
+  background: var(--accent);
+  border-color: var(--border);
+  color: var(--accent-foreground);
+}
+
+@source "../components";
+@source "../internal";
+@source "../lib";

package/dist/styles/globals.css

@@ -1,8 +1,9 @@
 /*
  * @nadicodeai/ui — Tailwind v4 + shadcn entry stylesheet.
  *
- * Tailwind and the complete design-system CSS module are composed here, behind
- * the package's one public stylesheet interface. The generated raw-token theme,
+ * Tailwind and the complete design-system CSS module are composed here, for an
+ * application this package styles whole. A host with base styles of its own
+ * takes `components.css`, which this file imports, and never this file. The generated raw-token theme,
  * :root/.dark semantic role maps, and Tailwind semantic bridge come from
  * DESIGN.md, so shadcn utilities (bg-background, text-foreground,
  * border-border, …) resolve to brand tokens through one generated owner.
@@ -19,6 +20,7 @@
 @import "@assistant-ui/react-markdown/styles/dot.css";
 @import "./shadcn.tailwind.css";
 @import "@nadicodeai/design-system/css";
+@import "./components.css";
 
 /*
  * Tailwind v4's dark: variant defaults to an OS media query. Match shadcn's
@@ -76,105 +78,3 @@
     stroke-linejoin: round;
   }
 }
-
-/*
- * The one glass material (DESIGN.md "Elevation & Depth"): floating chrome —
- * menus, popovers, selects, comboboxes, the command palette, and bars — may
- * carry it; content surfaces stay solid. Glass composites only over our own
- * content, and its elevation falloff's edge ring stays its one separator.
- * Declared as a utility so variant prefixes can gate it (navigation-menu's
- * non-viewport popup). Reduced transparency falls back to the same solid
- * surface at the same elevation.
- */
-@utility nc-glass {
-  background: color-mix(in srgb, var(--popover) var(--nc-material-glass-opacity), transparent);
-  backdrop-filter: blur(var(--nc-material-glass-blur)) saturate(var(--nc-material-glass-saturation));
-
-  @media (prefers-reduced-transparency: reduce) {
-    background: var(--popover);
-    backdrop-filter: none;
-  }
-}
-
-/*
- * The four elevation rungs. Each utility paints the whole recipe of its rung
- * from the generated --nc-elevation-* token, whose last layer is the rung's
- * own optical ring in the current mode (design-system DESIGN.md
- * "core.elevation"). An elevated surface therefore draws no second edge:
- * never pair one of these with border-*, ring-*, or another box-shadow
- * (`nadicodeai/no-elevated-edge` enforces it). Declared as utilities so
- * variant prefixes can gate them.
- */
-@utility nc-elevation-resting {
-  box-shadow: var(--nc-elevation-resting);
-}
-
-@utility nc-elevation-raised {
-  box-shadow: var(--nc-elevation-raised);
-}
-
-@utility nc-elevation-floating {
-  box-shadow: var(--nc-elevation-floating);
-}
-
-@utility nc-elevation-modal {
-  box-shadow: var(--nc-elevation-modal);
-}
-
-/*
- * The proxy focus outline: the one restatement of the canonical treatment
- * above, for an element that carries the indicator on another element's
- * behalf (the input group around its control, the OTP slot for the hidden
- * input, the chart wrapper for its svg, the slider thumb). The call site adds
- * the hue with outline-ring or outline-destructive and nothing else.
- * Declared as a utility so variant prefixes can gate it, and so the style is
- * literally `solid` rather than Tailwind's `--tw-outline-style`, which any
- * outline-none or outline-hidden on the same element sets to `none` for good.
- */
-@utility nc-focus-outline {
-  outline-style: solid;
-  outline-width: var(--outline-width-focus);
-  outline-offset: var(--outline-offset-focus);
-}
-
-@layer components {
-  .nc-toast {
-    border: 0 !important;
-  }
-}
-
-/*
- * The canonical design-system module owns raw --nc-* mode aliases, semantic
- * roles, and their Tailwind utility bridge for both root and scoped `.dark`
- * surfaces.
- */
-
-.toaster [data-sonner-toast][data-styled="true"] [data-description] {
-  color: var(--muted-foreground);
-}
-
-.toaster [data-sonner-toast][data-styled="true"] [data-button] {
-  background: var(--popover-foreground);
-  color: var(--popover);
-}
-
-.toaster [data-sonner-toast][data-styled="true"] [data-cancel] {
-  background: var(--muted);
-  color: var(--popover-foreground);
-}
-
-.toaster [data-sonner-toast][data-styled="true"] [data-close-button] {
-  background: var(--popover);
-  border-color: var(--border);
-  color: var(--popover-foreground);
-}
-
-.toaster [data-sonner-toast][data-styled="true"] [data-close-button]:hover {
-  background: var(--accent);
-  border-color: var(--border);
-  color: var(--accent-foreground);
-}
-
-@source "../components";
-@source "../internal";
-@source "../lib";

package/docs/activity.md

@@ -2,7 +2,9 @@
 
 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.
+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 |
 | --- | --- | --- |

package/docs/agent-orb.md

@@ -0,0 +1,82 @@
+# Agent orbs
+
+`AgentOrb` is the abstract Agent identity family requested on 2026-09-19:
+seven structures from `thinking-orbs` 0.3.1, each painted in one configurable
+colour. These are persistent appearance choices, not activity states. They
+apply equally to Nadia and other Agents; this family assigns no face or
+special character to Nadia. Existing Forma consumers are not migrated by
+this component slice.
+
+| Form | Structure | Upstream preset |
+| --- | --- | --- |
+| `ribbon` | Flowing dotted bands | `composing` |
+| `lattice` | Rotating particle bands | `solving` |
+| `orbit` | Particles on tilted orbits | `working` |
+| `globe` | Dotted globe and scanning meridian | `searching` |
+| `network` | Connected constellation | `connecting` |
+| `braid` | Interwoven strands | `weaving` |
+| `morph` | Changing geometric contour | `shaping` |
+
+The form does not select a job, tools or runtime status. Do not switch it when
+an Agent starts searching or solving. Applications own the persisted form,
+colour, name and status; names beside avatars provide exact identification.
+
+## Component
+
+```tsx
+import { AgentOrb } from "@nadicodeai/ui/components/agent-orb";
+
+<AgentOrb form="ribbon" color="var(--nc-identity-cobalto)" size={32} label="Nadia" />;
+```
+
+`form` is required. `color` accepts one CSS colour, including a customer-chosen
+colour or a canonical token. Omit it to inherit text colour. This configurable
+artwork is not a new palette for controls or status. Every particle and line
+uses the same pigment; opacity, not another colour, creates depth. Working
+releases occasional coloured flourishes; Done repeats the same arcs,
+arrowheads, rings and sparkles in a short celebration around
+that single-colour identity, using the existing chart and warning tokens. Choose a
+colour visible on the intended background. A deliberately black pigment on a
+black surface is not automatically recoloured.
+
+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
+accessible image requires `label`; use `decorative` beside an existing name.
+The component is Canvas 2D, not WebGL. It reuses the vendor's portable geometry
+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.
+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,
+fold or emit copies of the orb to convey either state. Working uses one open,
+tapered multicoloured ribbon passing behind and in front of the orb on a
+7.2-second loop. Thinking uses three persistent coloured dots above the orb,
+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.
+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.
+
+The [Portal Agent workspace](../../../apps/portal/src/components/agent-workspace/agent-workspace.tsx)
+uses the shared component. Inspect its Agent list and detail views in the
+running local Portal for compact and full-size appearances. Development
+profiles provide example orb choices; their preview edits do not change
+stored Agent records.
+
+[Upstream library and presets](https://libraries.dev/orbs), MIT licensed.

package/docs/agent-visual.md

@@ -1,5 +1,10 @@
 # Agent Visual System
 
+Legacy API for existing consumers. New Agent workspace surfaces use
+[AgentOrb](agent-orb.md) and the shared
+[product language](../../design-system/PRODUCT_LANGUAGE.md#agent-section-contract).
+The multicolour recipes below do not govern new Portal agent representations.
+
 The Agent visual is the decorative identity for a persistent Agent in Nadia.
 It is a living, multicolour metaball form whose recipe is assigned by Agent
 type. It does not represent status, capability, runtime activity, or work

package/docs/contract.md

@@ -6,7 +6,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). `@nadicodeai/ui/globals.css` is the only stylesheet this package ships; a surface that loads no Tailwind layer takes the design system's token artifact and writes its own rules against it.
+- **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").
 
 ### Persistent notices
@@ -21,7 +21,7 @@ read-only and stale-data notices use this shared composition directly.
 
 ### Material surfaces
 
-`globals.css` declares the four elevation utilities, `nc-elevation-resting`,
+`components.css`, which `globals.css` imports, declares the four elevation utilities, `nc-elevation-resting`,
 `nc-elevation-raised`, `nc-elevation-floating`, and `nc-elevation-modal`. Each
 sets `box-shadow` to the generated `--nc-elevation-<rung>` token, pinned by
 `packages/design-system/DESIGN.md` "core.elevation": one recipe per rung per
@@ -148,11 +148,11 @@ states to the orb.
 - **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`, and `chart-bar-multiple` 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).
 
 - **Named shadcn blocks stay named.** When a user, plan, or issue selects a shadcn block/example such as `login-02`, `signup-02`, `dashboard-01`, or `sidebar-*`, use that registry item as the source of truth through shadcn CLI/MCP. Do not replace it with a package-authored abstraction unless the plan explicitly records the substitution, the reason, and the true consumer route that proves it.
-- **A change to what the package ships bumps the version.** Any change to exported components, `src/index.ts`, package `exports`, `globals.css`, theme behavior, package docs, or design-system token, CSS, or theme output this package consumes bumps both package versions in lockstep before handoff, and `npm pack --dry-run -w @nadicodeai/ui` shows exactly what consumers receive (procedure: `../../../docs/agents/publish.md`).
+- **A change to what the package ships bumps the version.** Any change to exported components, `src/index.ts`, package `exports`, `globals.css`, `components.css`, theme behavior, package docs, or design-system token, CSS, or theme output this package consumes bumps both package versions in lockstep before handoff, and `npm pack --dry-run -w @nadicodeai/ui` shows exactly what consumers receive (procedure: `../../../docs/agents/publish.md`).
 
 ## Admission Rules
 
-Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-card`, `@nadicodeai/ui/components/agent-visual`, and the Forma avatars in `@nadicodeai/ui/components/forma-avatar` (owned by [`forma-avatar.md`](forma-avatar.md)). 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-card`, `@nadicodeai/ui/components/agent-orb`, `@nadicodeai/ui/components/agent-visual`, and the Forma avatars in `@nadicodeai/ui/components/forma-avatar` (owned by [`forma-avatar.md`](forma-avatar.md)). 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
 
@@ -166,6 +166,17 @@ where [`apps/nadia/docs/entry-screen.md`](../../../apps/nadia/docs/entry-screen.
 owns their contract. `packages/ui/tests/guards/product-placement.test.ts`
 refuses a product's name in either package.
 
+### Abstract Agent identities
+
+`AgentOrb` is the seven-form, single-colour abstract family in
+[`agent-orb.md`](agent-orb.md), exposed through
+`@nadicodeai/ui/components/agent-orb`. Its consuming validation surface is
+`examples/agent-orbs`: the built component at detail, menu and conversation
+sizes, with independently editable colours. The application stores appearance;
+upstream activity names select geometry only and never infer an Agent role or
+change its identity with runtime work. Customer-selected artwork colours are
+inputs, not component palette literals or interface colour roles.
+
 ### Agent identity presentation
 
 The visual system (the closed recipes, motion, fallbacks, and licensing) is
@@ -190,7 +201,6 @@ product-domain `agent` object prop in the shared package.
 - **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.
 - **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 two explicit allow-lists: platform marks out of the Iconify `logos` set (CC0-1.0), and model makers' marks out of the LobeHub icon set (MIT, `@lobehub/icons-static-svg`), both as `devDependencies`. The emitted components are plain SVG, so neither icon data package belongs in the runtime dependency set or reaches a consumer bundle. The artwork itself does ship, so every upstream whose licence asks for one travels with a 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.
 - **No fake proof APIs.** Components may support future testimonials, logos, stats, and proof slots, but they must render nothing public when the proof is absent. Do not ship placeholder customer names, metrics, or logos.
 
@@ -230,7 +240,9 @@ comparison line and a note, both in the caller's language. There is no grouped o
 row of KPIs is a `CardRow` of `KpiCard`s, each its own card. Apps supply the
 figures and bind links through `render`. Charts expose `size` (`default` or
 `lg`), which selects a fixed plot height, so consumers never select internal
-chart elements.
+chart elements. `ChartSummary` owns a chart's measured value, trend badge,
+status and comparison line inside the chart card; consumers provide typed
+content instead of rebuilding that presentation beside the plot.
 
 `CollectionToolbar` owns the collection-control layout: compact filters at the
 leading edge, a flexible search field, and trailing actions. Its slot order is
@@ -284,9 +296,24 @@ and status retain their column headers. Missing values retain their place.
 `standard` retains full columns at 768px of container width, `wide` at 1024px,
 and `spacious` at 1152px for schemas with additional operational columns.
 The same owner switches column visibility, detail visibility, and row boundaries.
+`TableRecordGroup` wraps the primary row and its compact detail row in one
+native row group, so hovering, focusing, expanding, or selecting either half
+highlights one record. A consumer does not render the two rows as independent
+siblings. Portal `DataTable` chooses a layout from its column count by default;
+a comparison whose columns remain readable longer may select one of these
+shared layouts instead of adding route-owned width rules.
 Two supporting facts use two columns; additional facts can use three when they fit.
 The cell renderer supplies the value, leaving the label to the detail row.
 
+### Missing table values
+
+`TableValue` owns the [cross-product missing-value convention](../../design-system/PRODUCT_LANGUAGE.md#missing-values-in-collections).
+Pass the actual scalar or rendered value and a required localized `missingLabel`.
+Null, undefined and empty strings render a muted, visually fixed `—` plus
+screen-reader text; zero and present values pass through unchanged. No custom
+visible fallback is exposed. Do not prefill `value` with absence copy.
+Loading, failure, permission and actionable states remain outside this component.
+
 ## Consumer Boundary
 
 Consumers own routing, auth, app data, server actions, runtime construction and adapters, permission decisions, analytics, and app-specific copy. The package owns reusable React presentation and the public Agent UI dependency boundary. Agent state and behavior come through the Agents interface; non-React and TUI contracts belong to their consuming products.
@@ -342,3 +369,19 @@ The identity row names who is signed in and carries one `DropdownMenuItem
 iconOnly` gear at its trailing edge, linking to the account section; the menu
 does not repeat that section's pages as commands. Consumers bind preference
 persistence, routing, and localized labels.
+
+## Object workspace compositions
+
+`ObjectIdentity`, `ObjectOverview`, `ObjectSection` and `ObjectFacts` compose the
+[shared IA patterns](../../design-system/PRODUCT_LANGUAGE.md#reusable-information-architecture)
+from existing Card and typography foundations. They own identity/action alignment,
+primary/supporting responsive columns, summary boundaries and semantic definition
+pairs. They take slots and values, never domain stores, URLs, permissions or save
+functions. Portal's agent workspace binds them to its scoped routes; Nadia may
+reuse the same presentation within its own shell. Do not ship a second complete
+Agent application inside this package.
+
+`ObjectIdentity.support` adds a small set of stable, labelled context facts to
+the identity header. The facts sit beside the identity when space allows and
+collapse behind the caller's localized disclosure label on compact screens.
+Operational warnings and changing report readings remain in the page body.

package/docs/model-identity.md

@@ -0,0 +1,18 @@
+# Model identity compatibility adapter
+
+`ModelIdentity` is a compatibility adapter for consumers that still pass one
+`provider/model` string. It derives the author prefix and delegates all visual
+rendering to the canonical `ModelMark`; it has no provider registry, generated
+artwork, or presentation of its own. Unknown authors therefore receive the
+same neutral tile as every other `ModelMark` consumer.
+
+```tsx
+import { ModelIdentity } from "@nadicodeai/ui/components/model-identity";
+
+<ModelIdentity model="anthropic/claude-sonnet-5" />;
+```
+
+New consumers should import `ModelMark` and pass its `author` and `name`
+properties directly. The adapter keeps the older `model`, `label`, and
+`markSize` call shape while consumers migrate; a string `label` becomes the
+canonical model name, otherwise the model segment after the slash is shown.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "8.0.1",
+  "version": "8.2.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -14,6 +14,7 @@
       "import": "./dist/index.js"
     },
     "./globals.css": "./dist/styles/globals.css",
+    "./components.css": "./dist/styles/components.css",
     "./eslint": "./dist/eslint/index.js",
     "./agents": {
       "types": "./dist/agents.d.ts",
@@ -35,6 +36,10 @@
       "types": "./dist/lib/theme-mode.d.ts",
       "import": "./dist/lib/theme-mode.js"
     },
+    "./lib/format-token-count": {
+      "types": "./dist/lib/format-token-count.d.ts",
+      "import": "./dist/lib/format-token-count.js"
+    },
     "./components/*": {
       "types": "./dist/components/*.d.ts",
       "import": "./dist/components/*.js"
@@ -65,11 +70,12 @@
     "@assistant-ui/react": "0.15.20",
     "@assistant-ui/react-markdown": "0.14.15",
     "@base-ui/react": "^1.8.0",
-    "@nadicodeai/design-system": "8.0.1",
+    "@nadicodeai/design-system": "8.2.0",
     "@paper-design/shaders": "0.0.81",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
     "embla-carousel-react": "^8.6.0",
     "input-otp": "^1.5.0",
     "lucide-react": "1.47.0",