@nadicodeai/ui 10.1.0 → 12.1.0

package/dist/styles/components.css

@@ -27,13 +27,17 @@
  * 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.
+ * content. Its edge is the floating rung's recipe, whose inset top highlight
+ * and inner hairline only show once the fill turns translucent. A fine grain
+ * over the fill keeps the blurred colour behind it from banding. 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);
+  background:
+    url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPScxNDAnIGhlaWdodD0nMTQwJz48ZmlsdGVyIGlkPSdnJz48ZmVUdXJidWxlbmNlIHR5cGU9J2ZyYWN0YWxOb2lzZScgYmFzZUZyZXF1ZW5jeT0nLjg1JyBudW1PY3RhdmVzPScyJyBzdGl0Y2hUaWxlcz0nc3RpdGNoJy8+PGZlQ29sb3JNYXRyaXggdHlwZT0nc2F0dXJhdGUnIHZhbHVlcz0nMCcvPjwvZmlsdGVyPjxyZWN0IHdpZHRoPScxMDAlJyBoZWlnaHQ9JzEwMCUnIGZpbHRlcj0ndXJsKCNnKScgb3BhY2l0eT0nLjA1Jy8+PC9zdmc+"),
+    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) {

package/dist/styles/globals.css

@@ -29,6 +29,49 @@
  */
 @custom-variant dark (&:where(.dark, .dark *));
 
+/*
+ * Dark mode carries height in tone (DESIGN.md "Elevation & Depth"): the page
+ * stays true black and each rung's surface is one fixed step lighter. The rung
+ * sets the card and popover roles on its own element, so whichever role that
+ * surface paints with takes the rung's tone, whatever order the classes land
+ * in. A rung behind a variant prefix keeps the page's roles. In light every
+ * tone is the solid white. This belongs to the application
+ * stylesheet, not components.css, because a host keeps its own roles.
+ */
+@layer components {
+  .nc-elevation-resting {
+    --card: var(--nc-material-resting);
+    --popover: var(--nc-material-resting);
+  }
+
+  .nc-elevation-raised {
+    --card: var(--nc-material-raised);
+    --popover: var(--nc-material-raised);
+  }
+
+  .nc-elevation-floating {
+    --card: var(--nc-material-floating);
+    --popover: var(--nc-material-floating);
+  }
+
+  .nc-elevation-modal {
+    --card: var(--nc-material-modal);
+    --popover: var(--nc-material-modal);
+  }
+
+  /*
+   * A lifted dark surface is lighter than the soft steps the hover, selected
+   * and keycap fills take on the black page, so on it those fills step up
+   * from its own tone instead: 8% of the foreground over the surface. Light
+   * surfaces are white, where the soft steps already read.
+   */
+  :where(.dark)
+  :is(.nc-elevation-resting, .nc-elevation-raised, .nc-elevation-floating, .nc-elevation-modal) {
+    --accent: color-mix(in oklab, var(--popover) 92%, var(--foreground));
+    --muted: color-mix(in oklab, var(--popover) 92%, var(--foreground));
+  }
+}
+
 @layer base {
   * {
     @apply border-border outline-ring;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "10.1.0",
+  "version": "12.1.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -52,8 +52,7 @@
     "LICENSES",
     "NOTICE",
     "README.md",
-    "AGENTS.md",
-    "docs"
+    "AGENTS.md"
   ],
   "scripts": {
     "dev": "node scripts/dev-build.mjs --watch",
@@ -72,7 +71,7 @@
     "@assistant-ui/react": "0.15.21",
     "@assistant-ui/react-markdown": "0.14.16",
     "@base-ui/react": "^1.8.0",
-    "@nadicodeai/design-system": "10.1.0",
+    "@nadicodeai/design-system": "12.1.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

package/dist/components/handoff-banner.d.ts

@@ -1,9 +0,0 @@
-import * as React from "react";
-declare function HandoffBanner({ className, reason, destination, children, ...props }: Omit<React.ComponentProps<"div">, "children"> & {
-    reason?: string;
-    destination?: string;
-    /** Escape hatch: rich banner content that replaces the serializable model. */
-    children?: React.ReactNode;
-}): React.JSX.Element;
-export { HandoffBanner };
-//# sourceMappingURL=handoff-banner.d.ts.map

package/dist/components/handoff-banner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"handoff-banner.d.ts","sourceRoot":"","sources":["../../src/components/handoff-banner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,qBAWA;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/components/handoff-banner.js

@@ -1,6 +0,0 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { cn } from "../lib/utils.js";
-function HandoffBanner({ className, reason, destination, children, ...props }) {
-    return (_jsx("div", { "data-slot": "handoff-banner", className: cn("nc-handoff-banner", className), ...props, children: children ?? (_jsxs(_Fragment, { children: [destination != null && _jsx("span", { "data-slot": "handoff-banner-destination", children: destination }), reason != null && _jsx("span", { "data-slot": "handoff-banner-reason", children: reason })] })) }));
-}
-export { HandoffBanner };

package/docs/activity.md

@@ -1,113 +0,0 @@
-# System activity
-
-Who does the work decides how it looks.
-
-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.
-
-| 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. |
-
-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 aria-busy={saving || undefined} disabled={saving} type="submit">
-  <PendingLabel pending={saving} pendingLabel="Salvataggio…">
-    Salva modifiche
-  </PendingLabel>
-</Button>;
-```
-
-`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.
-
-## 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.
-
-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 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

@@ -1,168 +0,0 @@
-# Agent orbs
-
-`AgentOrb` is the one Agent identity in every product: seven structures from
-`thinking-orbs` 0.3.1, each painted in one chosen colour, and Nadia's own
-striped ribbon. These are persistent appearance choices, not activity states.
-No other Agent form, avatar or portrait exists; a custom picture a person
-uploads in Nadia is theirs, not an identity this package draws.
-
-| 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` |
-
-
-## Nadia
-
-`form="nadia"` is the ribbon striped along its whole length, across its width:
-azzurro (`--nc-identity-azzurro`), verde, the orb's own pigment, and rosso.
-The third stripe is the white of the tricolore; it takes the inherited text
-colour so it stays visible as ink on a white ground. The stripes are fixed:
-the same four at every size, in both themes and in every state, and nobody
-chooses them. Each dot keeps its lane through the engine's depth sort, so a
-stripe never changes colour as the ribbon turns. Her motion is the ribbon's.
-
-## Stored appearance
-
-Nadia stores an Agent's look in its profile and reports it to the Portal on
-every check-in; the Portal renders it and never writes it.
-`@nadicodeai/ui/components/agent-orb-appearance` is the one reading of those
-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 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]`. 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
-only knows check-ins draws the orb idle. 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="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
-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
-of a chosen form uses the same pigment, and on Nadia each stripe keeps its own;
-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.
-
-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
-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. 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,
-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.
-No state has an enclosing circle. Keep a nearby status label where exact
-state identification matters, including reduced motion and compact sizes.
-
-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, 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

@@ -1,45 +0,0 @@
-# Component Classification
-
-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 nadicode package API. Use the
-registry item in the consuming app and adapt it there with app-owned data,
-copy, and behavior.
-
-## Removed Direct Reinventions
-
-| Removed API | Registry source to use instead | Reason |
-| --- | --- | --- |
-| Package-level `DataTable`, `DataTableColumnControls`, `DataTableEmptyState`, `DataTableState` | [shadcn Data Table guide](https://ui.shadcn.com/docs/components/base/data-table), `@shadcn/table`, and the table in `@shadcn/dashboard-01` | These are first-party composition sources for sorting, visibility, filtering, and pagination. Portal retains its app-owned `DataTable` adapter for registry and URL behavior. |
-| `CommandPalette`, `ModelPickerCommand`, `SessionPickerCommand` | `@shadcn/command` and its `CommandDialog` export ([Command guide](https://ui.shadcn.com/docs/components/base/command)) | The command primitive and dialog composition are already supplied; model/session execution is app behavior. |
-| `ChartCard`, `MetricChart`, `semanticChartColors` | The package chart kit, owned by [`contract.md`](contract.md) | shadcn already ships the chart primitives and blocks the kit is pulled from; metric aggregation and chart choice are app behavior. |
-
-## Retained Package Compositions
-
-| 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` | 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
-
-Keep these out of `@nadicodeai/ui`:
-
-- data fetching, React Query, routers, server actions, desktop IPC, terminal runtime code, and persistence;
-- login/signup routes, OTP/two-factor flows, auth provider choices, recovery flows, session mutation, and analytics;
-- permission decisions, tenant/customer scoping, and policy enforcement;
-- app-specific product copy, page IA, and route-specific ordering;
-- fake proof, invented customer names, invented metrics, or placeholder testimonials.
-
-## Fixture Guidance
-
-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;
-- no external network, browser, customer PII, signed contracts, financials, or fake proof.
-
-Browser-driven tests stay out of the default Vitest suite. U4 fixtures render through static and SSR-friendly tests only.

package/docs/consuming-cross-repo.md

@@ -1,116 +0,0 @@
-# Consuming `@nadicodeai/ui` Cross-Repo
-
-This is the contract for an external repo — the Nadia repo, sibling Nadia web,
-desktop, or any consumer outside this monorepo — installing `@nadicodeai/ui`
-from published npm rather than the workspace source.
-
-## Version pinning
-
-Pin the UI package to an exact version, never `latest` or a caret/tilde range:
-
-```bash
-npm view @nadicodeai/ui version
-npm install @nadicodeai/ui@<exact-version> react@^19 react-dom@^19 tailwindcss@^4 @tailwindcss/postcss@^4
-```
-
-`@nadicodeai/ui` pins and installs its `@nadicodeai/design-system` runtime
-dependency exactly. A React consumer does not declare that dependency directly
-just to use UI components or the UI stylesheet.
-
-The package installs its Agent UI implementation exactly. Consumers import
-presentation, runtime primitives, providers, hooks, and types through
-`@nadicodeai/ui/agents`; they do not install or import assistant-ui packages
-directly. A protocol-specific runtime adapter remains a direct consumer
-dependency because the application owns transport and message state.
-
-Declare `@nadicodeai/design-system` directly only when the app intentionally
-uses a separate public design-system API, such as a font/logo asset or the
-static CSS interface for a separate non-React surface. Pin that direct
-dependency to the version required by the installed
-UI release:
-
-```bash
-npm view @nadicodeai/ui@<exact-version> dependencies.@nadicodeai/design-system
-```
-
-## CSS interface
-
-Import one stylesheet once at the React app root:
-
-```ts
-import "@nadicodeai/ui/globals.css";
-```
-
-`@nadicodeai/ui/globals.css` is the complete React style interface. It composes
-Tailwind v4, shadcn, and the complete design-system CSS module, and it declares
-the four `nc-elevation-*` utilities over the generated elevation tokens.
-Consumers do not add a second border or ring to package-owned elevated roots.
-Do not import `@nadicodeai/design-system/css`, generated theme files, or CSS
-partials beside it. The package declares its own built component sources; Tailwind's
-normal automatic detection covers the consumer application. The app still owns
-its PostCSS configuration, theme provider, and persisted mode preference.
-
-That stylesheet also delivers the brand typeface. The design-system CSS module
-declares the `@font-face` rules for Geist and Geist Mono and loads the packaged
-woff2 files, so a consuming app must not add its own font loader for those two
-families. A framework loader on top registers a second, differently sourced face
-for the same family names, which downloads the fonts twice and leaves no defined
-winner. Import files under `@nadicodeai/design-system/assets/fonts/*` only when
-the consumer wants the faces without the CSS module; that is one of the
-intentional direct-API cases described above.
-
-## Strict ESLint interface
-
-The package exports the same design-system rules used by this repository. Add
-the flat config after the consumer's framework and TypeScript configs:
-
-```js
-import nadicodeai from "@nadicodeai/ui/eslint";
-
-export default [
-  // Framework, parser, and TypeScript configs first.
-  ...nadicodeai.configs["flat/strict"],
-];
-```
-
-Every rule in this config is an error. The config rejects generated `nc-*`
-utilities that do not exist in the installed design-system release, arbitrary
-radius values that exactly duplicate a generated token, source deep imports,
-raw design values, native visible controls, and appearance overrides on shared
-UI primitives. An arbitrary radius remains valid when no generated radius has
-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.
-
-## nadicode logo
-
-React surfaces name the company with the wordmark from the UI package:
-
-```tsx
-import { BrandWordmark } from "@nadicodeai/ui/components/brand";
-
-<BrandWordmark alt="nadicode" />;
-```
-
-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)
-
-`@nadicodeai/ui@0.5.0+` is Base UI only; the Radix-era compatibility layer is
-gone. Full catalog and rationale: `docs/migration/base-ui-migration.md`. What
-a consumer actually hits when porting call sites:
-
-- No `asChild`. Use Base UI's `render` prop; when the rendered element isn't
-  a native `<button>`, also pass `nativeButton={false}`.
-- Menu items (`DropdownMenuItem`, `ContextMenuItem`, `MenubarItem`) use
-  `onClick`, not `onSelect`.
-- State attributes are `data-checked`/`data-unchecked` and
-  `data-open`/`data-closed`, not a single `data-state` value.
-- `Accordion` and `ToggleGroup` values are always arrays — pass `multiple`
-  for multi-select instead of `type="single" | "multiple"`.
-- `TooltipProvider` takes `delay`, not `delayDuration`.
-- Disclosure panels (`CollapsibleContent`, etc.) take `keepMounted`, not
-  `forceMount`.