@nadicodeai/ui 10.1.0 → 12.1.1

package/docs/contract.md

@@ -1,388 +0,0 @@
-# @nadicodeai/ui Package Contract
-
-The normative invariants for the `@nadicodeai/ui` package: what may live here, how it is styled, and what consumers own. `../AGENTS.md` is the map; this file is the contract it routes to.
-
-## Styling Invariants
-
-- **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 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
-
-`NoticeBanner` composes Alert's icon, title, description and optional action.
-Use it for persistent guidance in the affected section or page container;
-transient action feedback uses Toast, and field validation stays with its field.
-The component owns wrapping, typography and the responsive action placement.
-Consumers supply the condition, localized impact and recovery action. Internal
-error codes stay in diagnostics, not notice content. Portal's operational,
-read-only and stale-data notices use this shared composition directly.
-
-### Material surfaces
-
-`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
-mode, whose last layer is that rung's optical ring, black at 5% in light and
-white at 18% in dark. No package or consumer declares a second elevation
-vocabulary. Never pair an `nc-elevation-*` root with `border-*`, a separate
-`ring-*`, or another `box-shadow` (`nadicodeai/no-elevated-edge` enforces it).
-
-Physical role, not content importance, chooses depth:
-
-- `Card surface="resting"` (the default) uses `nc-elevation-resting`.
-- `Card surface="raised"` uses `nc-elevation-raised`; active or selected
-  work chooses it explicitly.
-- `Card surface="plain"` is the explicit structural/auth/website escape and
-  carries no elevation.
-- `Card surface="outlined"` is a flat panel with a single semantic border and
-  compact corners; it carries no elevation ring or shadow. Bounded fact cells
-  use it inside resting record sections. Portal's kit keeps the resting default.
-- Tooltip, menu, popover, select, combobox, navigation popup, hover card,
-  chart tooltip, and toast roots own `nc-elevation-floating` internally.
-- Dialog, alert dialog, drawer, and sheet roots own `nc-elevation-modal`
-  internally.
-
-All solid surfaces use the one semantic fill. Dark mode therefore stays true
-black; depth never comes from progressively greyer cards.
-
-Keyboard focus has one owner: the `globals.css` base layer draws the offset
-ink outline on every `:focus-visible` element, and an invalid control takes
-the same geometry in the destructive hue. A component never repaints focus
-with a box-shadow ring, a raw width, or its own hue
-(`nadicodeai/no-repainted-focus` enforces this). A component may only
-suppress the outline where a proxy target carries it (`InputGroup` shows the
-indicator for its inner control; the OTP active slot for its hidden input) or
-where a highlight ground replaces it (menu and command items). The proxy
-target draws it with `nc-focus-outline`, the one utility that carries the
-outline's style, width, and offset, plus a ring-role color utility. Nothing
-restates those three as separate utilities: an `outline-none` or
-`outline-hidden` on the same element leaves Tailwind's own outline utilities
-painting nothing.
-
-`nc-glass` is the one glass material for floating chrome: popover, select,
-combobox, and navigation-menu popups, the command palette, and `GlassControl`
-bars carry it over our own content. Command dropdowns use a solid popover fill
-so labels stay readable over dense rows; account dropdowns share that surface. Content surfaces stay
-solid: cards, KPIs, tables, inspectors, and dialog, sheet, and drawer bodies.
-Glass keeps exactly one separator, the elevation falloff's integrated edge
-ring. Reduced transparency falls back to the same solid floating surface.
-`GlassControl` remains the control-chrome form, using `shape="control"` for
-compact floating controls and `shape="bar"` for full-width header chrome.
-
-`Empty` makes containment explicit with `scope="page" | "region" | "card"`.
-Page and region states own one opaque dashed boundary. A Card-scoped Empty is
-transparent and unframed because the Card already owns containment.
-
-### Tables
-
-`Table` owns the native table structure, solid semantic background, an overflow
-safety boundary, and one compact density: 36px header rows and 40px body rows. Consumers
-compose `TableHeader`, `TableBody`, `TableRow`, `TableHead`, and `TableCell`; they
-do not replace table layout with grid or flex, hide the header to create another
-presentation, or reconstruct the native semantics with ARIA. Portal collections
-must fit their available width without horizontal scrolling: preserve identity
-and actions in columns and place supporting facts in native detail rows before
-the full schema becomes cramped. Test the table container itself, not only the
-document width; retaining the overflow safety boundary must not conceal a
-layout defect. Body rows use the full `bg-accent` fill on hover, keyboard focus
-within, and while a descendant menu is expanded. Headers and footers do not gain
-the body-row hover treatment. Keep cell backgrounds transparent so they do not
-hide the shared highlight. The design system's interaction states own the
-cross-product table and action affordances.
-
-`CollectionScope` chooses the parent of one record collection. It places the
-scope selector and optional detail action above the collection toolbar. Empty
-parents stay in the selector. Apps bind authorized options and URL state; clearing
-record filters preserves the parent scope. Parent details belong on their detail
-page, not in repeated panels surrounding identical child tables.
-
-A ranked breakdown is not a kit component: the Portal renders it through its
-one table owner, `DataTable`, with a `Progress` cell. The kit composes no second
-table (`tests/chart-kpi-ownership.test.ts`).
-
-### Record action menus
-
-`ActionMenu` is the shared three-dot composition of `Button` and `DropdownMenu`:
-a ghost icon trigger, horizontal ellipsis, and end-aligned popup. The shared
-stylesheet gives enabled buttons a pointer cursor, including this trigger. It inherits the
-menu's opaque surface, elevation, motion, keyboard behavior, and focus return. Supply
-`label` as a localized, record-specific accessible name; `triggerId` supports
-focus return from an app-owned confirmation, and `children` supplies menu items.
-Apps own action selection, permission, placement, and confirmation. Reuse this
-composition instead of drawing another trigger or popup.
-
-## Status Vocabulary
-
-`Badge` is the product's only status carrier. It ships five semantic tone
-variants — `gray`, `green`, `red`, `amber`, `blue` — each one soft/deep pair
-from the generated tokens (`--nc-canvas-soft-2`/`--nc-body`,
-`--nc-link-bg-soft`/`--nc-link-deep`, `--nc-error-soft`/`--nc-error-deep`,
-`--nc-warning-soft`/`--nc-warning-deep`, `--nc-info-soft`/`--nc-info-deep`), so
-a status clears AA in both modes without a call site painting anything. A status
-badge carries a mark in the existing icon slot beside its word, because colour
-must never be the only thing that says what the status is; the mark is
-`aria-hidden`, and the word is the accessible status. The tones are variants,
-not utilities, precisely so `nadicodeai/no-shadcn-appearance-override` can keep
-them here.
-
-What this package does not own: which statuses exist, which tone and which mark
-each value takes, and the words. Those are the consuming app's domain — the
-Portal maps them in one kit module and nothing else picks a status colour. The
-design-system side of the decision, and why the retired CSS status grammars are
-gone, is [`packages/design-system/DESIGN.md`, "## Status Vocabulary"](../../design-system/DESIGN.md#status-vocabulary).
-
-## Package Shape Invariants
-
-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 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).
-
-- **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`, `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-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
-
-`@nadicodeai/ui` and `@nadicodeai/design-system` hold the Foundation and the
-components, assets and styles at least two products use; a component, asset or
-style one product alone needs lives in that product's own directory. Nadia's
-entry screen is the worked example: the room, the presence, the typed line and
-their stylesheet were a package surface no other product imported, and they now
-live in the desktop at `apps/nadia/hermes/apps/desktop/src/plugins/nadia/entry/`,
-where [`apps/nadia/docs/entry-screen.md`](../../../apps/nadia/docs/entry-screen.md)
-owns their contract. `packages/ui/tests/guards/product-placement.test.ts`
-refuses a product's name in either package.
-
-### Agent identity
-
-`AgentOrb` is the only Agent identity the package ships, and
-[`agent-orb.md`](agent-orb.md) owns its rules. `AgentCard` composes the
-fundamental `Card` with explicit `visual`, `name`, `job`, `status`, `meta`, and
-`action` slots and owns presentation only; when it is the page identity, the
-`name` slot carries the page's `h1`. There is no `AgentGlyph`, `AgentRow`, or
-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.** 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".
-- **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.
-
-### Model identity
-
-`ModelMark` is a model's identity: its maker or model-family mark, plus the
-model's name and author when a caller supplies them. It takes `author` — the
-slug a usage read reports — and resolves it against the reviewed catalog
-mapping (rule `model-shown-with-logo`). OpenRouter aliases prefixed with `~`
-resolve to their canonical author's mark. For community author pages where
-OpenRouter publishes the generic Hugging Face image, `ModelMark` uses that same
-fallback and still prints the actual author. A future author outside the mapping
-gets a text monogram, not an invented logo or an empty tile. The tile owns the
-box and scales the artwork inside it; `size` states that box, and the author
-slug prints as reported.
-
-One component has two readings: with `name`, the row a table cell or ranked
-list reads; without one, the bare mark beside text that already names the model.
-The chart kit does not place marks: its legend and tooltip are the stock shadcn
-content, and a chart names a model through the label in its `ChartConfig`. A
-model's row in a table or a ranked list is where `ModelMark` belongs. A mark is
-decoration beside the label that already names it; one standing alone takes
-`label` (`role="img"` with an accessible name) or stays hidden.
-Named marks stay within their containing cell, shortening the visible text when
-space is tight; callers with long model IDs provide the full ID in `title`.
-
-The package owns the reviewed author-to-mark mapping and its generated artwork;
-the live catalog remains the source of which authors exist. The consuming app
-supplies the reported author slug, the model name, and the colors it pairs with
-them.
-
-### App identity
-
-`AppMark` is an app an Agent connects to: Gmail, Google Calendar, Slack,
-GitHub, Notion and the rest of the generated set. It takes `app` — a
-connector's slug, registry id or display name, compared on letters and digits
-alone — and draws the generated mark in the same tile as `ModelMark`, or the
-app's initial when the set has no mark for it. It never fetches a favicon and
-never draws an invented logo. Every product that names a connected app draws it
-through `AppMark` or `appMarkFor`, so the same app looks the same in the Portal
-and in Nadia; a product keeps no folder of logo files of its own.
-
-## Accessibility Invariant
-
-**Tier-1 accessibility is tested, browser-free.** Rendering component tests use the package `expectAccessible` helper to check the rendered DOM. The jsdom tier is structural: rendered contrast, landmark context, focus, and keyboard behavior belong to real-browser Playwright coverage. The shared library ESLint configuration is the executable authority for static JSX accessibility rules, and the repository quality doctrine owns their policy; this contract does not copy the rule inventory.
-
-## Reusable Sections
-
-The source tree, barrels, and package exports own the current reusable section vocabulary. When a page needs a variation, extend the owning source component with a small typed prop or slot; do not fork the layout in a consumer or document a second component inventory here.
-
-`KpiCard` is one measured figure, in the shape of the `dashboard-01` section
-card: label, value, the change as a badge top right, and a footer carrying the
-comparison line and a note, both in the caller's language. There is no grouped or divided variant — a
-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. `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
-also the reading and focus order, including when controls wrap. Consumers supply
-existing controls and own their query state; they do not set independent search
-widths or align filters to table columns. `CollectionFilters` owns the controlled
-field/value picker and applied-filter chips; callers supply options, localized
-copy, and callbacks. The component owns discovery, edit/remove, keyboard focus,
-and empty search results. It does not own routing or fetch state.
-
-`SettingsFactsSection` owns a named record or settings reading section: its
-heading and optional action, header separator, and bounded responsive fact
-cells in two equal columns, stacked on compact screens. Consumers supply labels,
-values, an optional contextual footer, and a Card surface; paragraph facts take a full row. The stable heading remains a programmatic focus target
-when an editor closes. Keep fact labels, order, and cells stable when data is
-missing: null and undefined values use the required localized
-`missingValueLabel`, while zero remains a value. Consumers do not filter out
-unknown facts or replace them with indefinite loading skeletons. Editable
-controls remain in `SettingsSection`.
-
-`ReadingColumn` owns the centered content column a settings region reads in.
-`width="reading"` bounds the measure at `max-w-3xl` for stacked forms and record
-sections; `width="full"` keeps the workspace width for a page whose table needs
-it. Both stay centered, so the column agrees with the centered page heading
-above it at either width. Consumers supply the sections inside it and do not set
-their own container width or centering around them.
-
-`CardRow` owns a row of sibling cards. The grid stretches its cells and every
-direct card child fills the one it lands in, so cards that share a row share one
-height instead of ending on a ragged edge (`rule/card-row-equal-height`).
-`columns` takes 2, 3, 4, or `auto` for an equal share however many cards there
-are, and `from` names the breakpoint the row starts at (`sm`, `md`, `lg`, `xl`);
-below it the row is one column, where each card is its own row. Consumers pass
-layout — the two props, a `gap-*` when the default rhythm is wrong, and `render`
-when the row is a `section` or a list — never appearance. `nadicodeai/card-row-owner`
-reports a multi-column grid or row flex of cards written without it.
-
-`SettingsSection` composes Card's named header, divider, FieldGroup body, and
-optional divided `footer` for local save actions and feedback. The caller owns
-the form transaction and controls; the section owns their shared geometry.
-Header `actions` are optional supporting commands, distinct from footer submission.
-`SettingsField` uses one render callback in server and client components. Spread
-its `controlProps` onto the control to retain the visible label, descriptions,
-error association, and disabled/required state; do not wire another copy by hand.
-
-`TableDetailRow` keeps supporting collection facts readable at compact widths
-inside a native full-width table cell. It shares the owning column labels and
-values rather than requiring another responsive cell implementation. Identity
-and status retain their column headers. Missing values retain their place.
-`Table compactDetails` and `TableDetailRow layout` share `tableCompactLayouts`:
-`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.
-Supporting facts stack below 384px of table width, use two columns when they
-fit, and use three for additional facts at the larger container breakpoint.
-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. Bounded
-object facts use the same owner and retain their labels and slots when sparse;
-the component's name does not restrict it to a table element.
-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.
-
-App source composes layout, data, behavior, and semantic content around package components. It does not restyle an imported component root: appearance changes enter through the component's typed variant or are added to the owning package component. App `className` values on package components arrange and size the component root. Descendant `data-slot` selectors are not a public styling API; internal spacing, type, and sizing belong to the shared component, enforced by `nadicodeai/no-shadcn-appearance-override`. App source uses semantic roles such as `bg-background` and `text-foreground`; canonical `nc-*` color utilities stay behind package-owned primitives such as `BrandField`. Raw Tailwind palette colors are not available to anyone: the generated theme clears the `--color-*` namespace, so `bg-red-500` produces no CSS and `better-tailwindcss/no-unknown-classes` reports it. Visible controls come from `@nadicodeai/ui`, while hidden inputs remain valid form transport. The root ESLint rules `nadicodeai/no-shadcn-appearance-override` and `nadicodeai/no-native-visible-control` enforce the rest of this boundary; each takes a `packageOwnedPrimitives` option (`"exempt"` by default, `"lint"` to hold this package's own source to the same rule).
-
-When this package is read from an installed npm package, follow the [consumer setup guide](consuming-cross-repo.md) for setup and public import paths. The styling invariant above remains the authority for component implementation.
-
-The public strict ESLint config enforces only properties that can be decided
-from one source file and the installed generated tokens. It does not infer
-that two JSX trees represent the same product pattern. Repeated patterns stay
-governed by a named owning component, typed variants or slots, and explicit
-package or Portal-kit imports. A new repeated pattern is consolidated at its
-owner and pinned with a focused source or rendering test; generic JSX
-similarity warnings are outside this contract because they cannot distinguish
-valid domain composition from a fork without false positives.
-
-### Explanations belong to the content they explain
-
-Compose a card or settings section around a real task, collection, or form. Its
-header names that content and can explain scope or consequences; its footer
-can carry secondary guidance or the save action. Field help belongs beside the
-field. Do not create a paragraph-only card to conceal an orphan introduction.
-Portal placement is owned by its [context contract](../../../apps/portal/docs/information-architecture.md#context-breadcrumbs-headings-and-labels);
-`DataTable.heading`, `CardHeader` and `SettingsSection` are its composition
-seams. Empty states and operational notices remain distinct message owners.
-
-### Command popup composition
-
-`DropdownMenuContent` uses comfortable spacing by default. Its content-based
-width is bounded by Base UI's available width; collision padding keeps it off
-screen edges and available height allows vertical scrolling. A command popup
-uses solid `bg-popover` so underlying table text cannot compete with labels.
-Do not size command menus from an icon trigger. `DropdownMenuCommand` requires
-an `icon` element and owns the wrapping label and trailing, decorative icon slot.
-Use it for links, callbacks, native form buttons, and dialog triggers. It retains
-Menu.Item behavior; it is not a new positioning or focus implementation.
-`DropdownMenuItem iconOnly` remains available for the account-settings gear;
-checkbox and radio items retain their selection semantics.
-
-### Account popup composition
-
-`DropdownMenuContent density="comfortable"` supplies roomier command rows
-through the shared owner. Account-menu consumers put the label first and the
-icon at the trailing edge. `MenuChoiceRow` owns a named inline preference row:
-the label reads at the leading edge and the exclusive choices sit together at
-the trailing edge as compact menu radio items, each carrying a glyph or a short
-code. `iconOnly` retains every radio's accessible name and checked state without
-a second checkmark, and selection keeps the menu open. `ThemeModeMenu` is the
-theme row built on it. The account menu shows two such rows, Theme and Language.
-
-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/icon-assets.md

@@ -1,106 +0,0 @@
-# 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.

package/docs/migration/1.0.0.md

@@ -1,75 +0,0 @@
-# Migrating to `@nadicodeai/ui` 1.0.0
-
-This release makes material hierarchy and Agent identity package-owned. It
-also publishes the previously held status-vocabulary break.
-
-## Status
-
-`StatusTag` and `StateTag` are removed. Use `Badge` with one of its five
-semantic tones. The consuming app owns the status word, icon, and tone mapping.
-
-```tsx
-import { Badge } from "@nadicodeai/ui/components/badge";
-
-<Badge variant="green">Ready</Badge>;
-```
-
-The retired `.nc-status-tag`, `.nc-state-tag`, and `.nc-state-row` CSS classes
-have no replacement CSS API.
-
-## Material and Card
-
-Import `@nadicodeai/ui/globals.css` once. It now composes
-`shadow-plugin@1.2.7`; consumers do not install its classes or override its
-ring.
-
-`Card` defaults to `surface="resting"`. Use `surface="raised"` only for work
-that is physically raised or selected, and `surface="plain"` for the explicit
-structural/auth/website escape. `variant` continues to describe interaction.
-Replace the removed `variant="borderless"` with `surface="plain"`.
-
-```tsx
-<Card>Resting content</Card>
-<Card surface="raised">Selected work</Card>
-<Card surface="plain">Structural content</Card>
-```
-
-Overlay primitives now own floating or modal elevation internally. Remove
-caller `border-*`, `ring-*`, `shadow-*`, and `smooth-shadow-*` appearance
-classes from their content roots.
-
-## Empty and glass control
-
-Set Empty containment explicitly when nesting matters:
-
-```tsx
-<Empty scope="region">No agents</Empty>
-<Card><Empty scope="card">No runs</Empty></Card>
-```
-
-Use `GlassControl shape="control"` for compact controls and `shape="bar"` for
-full-width header chrome. Both float over legible content. Cards and modal
-primitives continue to contain page content and dialog bodies.
-
-## Agent identity
-
-Agent identity is available from direct component subpaths. The
-`@nadicodeai/ui/agents` entry remains the client-only assistant conversation
-and runtime interface.
-
-```tsx
-import { AgentCard } from "@nadicodeai/ui/components/agent-card";
-import { AgentVisual } from "@nadicodeai/ui/components/agent-visual";
-
-<AgentCard
-  name={agent.name}
-  job={agent.job}
-  status={<Badge variant="blue">Running</Badge>}
-  visual={<AgentVisual recipe={agent.recipe} presentation="card" />}
-/>;
-```
-
-Recipe assignment is app-owned and explicit. Do not infer it from a free-form
-role, hash an identifier, or randomize it. `AgentVisual` accepts only the five
-closed recipes and three presentations; raw shader controls are intentionally
-not public. `AgentGlyph` and `AgentRow` do not exist in the 1.0.0 API.