@nadicodeai/ui 0.10.2 → 0.11.0

package/docs/agents/nadicodeai-ui.md

@@ -1,275 +1,44 @@
 # NadicodeAI UI Agent Guide
 
-This file is shipped with `@nadicodeai/ui` so coding agents can use the package correctly after installation.
-
-## What This Package Provides
-
-`@nadicodeai/ui` is the shared NadicodeAI React UI surface:
-
-- shadcn source components compiled into package exports
-- Vercel AI Elements source components compiled into package exports
-- React adapters over the design-system grammar and assets
-- reusable NadicodeAI marketing/section compositions
-- presentational Nadia product components for settings, dashboard shells,
-  installer states, plugin boundaries, agent chat, artifacts,
-  files, diffs, and redacted terminal summaries
-- Tailwind v4 global CSS that bridges shadcn roles to NadicodeAI design tokens
-- package-local agent instructions in `AGENTS.md`, `llms.txt`,
-  `docs/migration/nadia-consumer-readiness.md`, and
-  `skills/nadicodeai-ui/SKILL.md`
-
-The package surface is source-backed. `src/components/` is flat shadcn-style
-source; do not infer or create folders or package namespaces that do not exist.
-Do not add top-level exports for recipes, blocks, agent, or terminal groupings
-until a concrete package API decision adds source, built files, docs, and tests
-together. Product components ship only when the source, public subpath export,
-tests, and docs exist together.
-
-Consuming apps own routes, persistence, auth behavior, server state, runtime
-adapters, app-specific copy, and app-owned product features/use cases. Names
-such as `operator-login`, portal activation, and customer credential control are
-consumer-owned product flows, not package component names. Reusable UI structure
-belongs in this package only after a second concrete consumer, a plan-approved
-shared component, or a named validation slice proves the package boundary.
-
-## Required App Setup
-
-Import the package CSS once at the app root:
-
-```tsx
-import "@nadicodeai/ui/globals.css";
-import "@nadicodeai/design-system/css";
-```
-
-For Next.js App Router apps, put those imports in the root layout.
-
-The consuming app still owns Tailwind/PostCSS configuration. This package does not install a PostCSS config.
-
-## Imports
-
-Prefer explicit component subpaths in app code:
-
-```tsx
-import { Button } from "@nadicodeai/ui/components/button";
-import { PageFrame } from "@nadicodeai/ui/components/page-frame";
-import { Message } from "@nadicodeai/ui/components/ai-elements/message";
-```
-
-Use barrels when they are more ergonomic:
-
-```tsx
-import { Button, PageFrame } from "@nadicodeai/ui";
-import { Message, PromptInput } from "@nadicodeai/ui/ai-elements";
-```
-
-Product UI uses the same public component subpaths:
-
-```tsx
-import { SettingsSection } from "@nadicodeai/ui/components/settings-section";
-import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell";
-import { AgentChat } from "@nadicodeai/ui/components/agent-chat";
-```
-
-Current shipped product subpaths:
-
-- `@nadicodeai/ui/components/agent-chat`
-- `@nadicodeai/ui/components/agent-composer`
-- `@nadicodeai/ui/components/agent-message`
-- `@nadicodeai/ui/components/agent-thread`
-- `@nadicodeai/ui/components/agent-tool-approval`
-- `@nadicodeai/ui/components/artifact-panel`
-- `@nadicodeai/ui/components/automation-section`
-- `@nadicodeai/ui/components/chart-breakdown-table`
-- `@nadicodeai/ui/components/chart-bullet-bar`
-- `@nadicodeai/ui/components/chart-date-range`
-- `@nadicodeai/ui/components/chart-date-range-control`
-- `@nadicodeai/ui/components/chart-delta`
-- `@nadicodeai/ui/components/chart-entity-colors`
-- `@nadicodeai/ui/components/chart-kpi-stat`
-- `@nadicodeai/ui/components/chart-sparkline`
-- `@nadicodeai/ui/components/chart-time-series`
-- `@nadicodeai/ui/components/confirm-dialog`
-- `@nadicodeai/ui/components/dashboard-shell`
-- `@nadicodeai/ui/components/desktop-shell`
-- `@nadicodeai/ui/components/feedback-state`
-- `@nadicodeai/ui/components/files-preview`
-- `@nadicodeai/ui/components/installer-shell`
-- `@nadicodeai/ui/components/plugin-slot-boundary`
-- `@nadicodeai/ui/components/settings-section`
-
-`StateNotice` (`@nadicodeai/ui/components/state-notice`) is the supported
-low-level state-banner primitive behind `AgentMessageStateNotice` and
-`AgentThreadStateBanner`; it requires a `title` and owns the shared
-`role="status"`/`role="alert"` skeleton.
-
-## Product Components And Migration
-
-Product components are presentational. Use them for shared settings, shell,
-installer, plugin-boundary, agent chat, artifact, file, diff, and redacted
-terminal summary UI. Keep route state, server state, auth,
-persistence, runtime adapters, permission decisions, analytics, and
-product-specific copy in the consuming app.
-
-Generic data tables, command palettes, and chart cards are app-owned shadcn
-registry adaptations. Start from `@shadcn/data-table-demo`,
-`@shadcn/command-dialog`, `@shadcn/chart`, or the relevant `@shadcn/chart-*`
-block/example instead of importing a NadicodeAI product abstraction. The
-console chart kit subpaths (`chart-*`) are the plan-approved exception
-(issue #166, ADR 0010): use them for KPI stats, sparklines, stacked
-time-series, cap meters, breakdown tables, entity-color assignment, and the
-date-range control; the chart cards that arrange those widgets stay app-owned.
-The URL codec in `chart-date-range` is server-safe; import it (not
-`chart-date-range-control`) from Server Components.
-
-Every data-shaped chart names a data alternative so its data is reachable
-without vision: the time-series charts ship a visually hidden `<table>` twin,
-`BreakdownTable` is itself a real `<table>`, and a standalone `Sparkline`
-renders an sr-only ordered list of its point values beside the `role="img"`
-svg. `BulletBar` (data fully in `aria-valuetext` plus the visible value) and
-`KpiStat` (data fully in visible text) carry no separate table twin by design;
-this narrowing is deliberate, not a gap.
-
-Recommended migration order:
-
-1. Web admin or portal validation slice.
-2. Installer and bootstrap flows.
-3. Desktop shell and plugin boundary surfaces.
-4. Desktop chat and runtime work surfaces.
-5. TUI consumers through `docs/terminal-tui-semantics.md`.
-
-Read `docs/migration/nadia-consumer-readiness.md` before migrating a consumer.
-It lists the CSS imports, public subpaths, fixture redaction rules, and readiness
-gates.
-
-## Layout Primitives
-
-`SeamGrid` (`@nadicodeai/ui/components/seam-grid`) is a supported low-level layout
-primitive: the single owner of the "gap-as-seam" grid that backs the bordered
-section grids (stats band, testimonials, logo band, and siblings). It renders a
-`div` with the invariant `grid gap-px` base, so borderless, square-cornered cells
-paint one shared hairline seam at every boundary instead of doubling lines.
-
-Its only seam-specific prop is `surface`: `"canvas"` (default) paints the brand
-`line` via `bg-border`, and `"ink"` mixes the line toward the ink role for darker
-panels; the value is also mirrored on a `data-surface` attribute. Pass
-`className`, `children`, and any `div` props to keep a bespoke column map,
-heights, and `data-*` attributes. Reach for `SeamGrid` and its `surface` prop
-when building a new bordered grid rather than hand-copying the seam colour: the
-seam class helper is an internal `src/lib/seam` detail with no public subpath
-export, so nothing should couple to the raw arbitrary Tailwind class string.
-
-## Forms
-
-Use the package's shadcn form stack as one model:
-
-- Controls: `Input`, `Textarea`, `Select`, `Checkbox`, and similar primitives.
-- Layout and accessible field structure: `FieldGroup`, `Field`, `FieldLabel`,
-  `FieldDescription`, and `FieldError`.
-- React Hook Form integration: `Form`, `FormField`, `FormItem`, `FormControl`,
-  `FormLabel`, `FormDescription`, and `FormMessage`.
-
-Do not introduce `FormInput`, `FormTextarea`, or other parallel form-control
-families. Extend the canonical control or field primitive when a new size or
-behavior is truly needed.
-
-## Styling Rules
-
-This package is token-only and dark-ready through semantic globals. The package
-CSS owns `:root` and `.dark` remaps for shadcn roles plus UI-local product
-aliases such as `--nc-app-surface`, `--nc-chat-tool-surface`, and
-`--nc-terminal-bg`. Components consume those roles/aliases; they do not add
-one-off dark styling locally.
-
-Use semantic utilities:
-
-```tsx
-className="border border-border bg-background text-foreground"
-```
-
-Use UI-local aliases when a product role is needed:
-
-```tsx
-className="bg-[var(--nc-app-surface)] text-[var(--nc-app-text-primary)]"
-```
-
-Use brand tokens through Tailwind arbitrary values only when a semantic role or
-UI alias is not precise enough:
-
-```tsx
-className="text-[var(--nc-link-deep)]"
-```
-
-Do not add:
-
-- Tailwind `dark:` utilities
-- `.dark` blocks outside package globals/theme files
-- OS dark-mode branching
-- raw `#hex`, `rgb()`, or `hsl()` values
-- raw palette utilities like `text-blue-600`, `bg-zinc-950`, `text-white`, or `bg-black/50`
-
-## shadcn And AI Elements
-
-The package consumes shadcn and AI Elements as source components in this
-repository, then publishes built JavaScript/declarations. Consumers should
-normally install `@nadicodeai/ui` and import package exports.
-
-Use shadcn MCP or the CLI for live discovery and install guidance during
-maintenance. Do not maintain committed upstream registry inventories, generated
-registry snapshots, or inventory update scripts in this package. The committed
-truth is the source that has been reviewed, exported, documented, and tested.
-
-For Codex-capable local runtimes, initialize shadcn MCP from `@nadicodeai/ui`
-when MCP is available:
-
-```bash
-npx shadcn@latest mcp init --client codex
-```
-
-Use CLI fallbacks when MCP is unavailable or when you need copyable command
-output:
-
-```bash
-npx shadcn@latest info --json
-npx shadcn@latest search @shadcn -q "select" --json
-npx shadcn@latest search @ai-elements -q "message" --json
-npx shadcn@latest docs button select dialog --json
-npx shadcn@latest view @shadcn/button
-npx shadcn@latest add @shadcn/button --dry-run
-npx shadcn@latest add @shadcn/button --diff src/components/button.tsx
-npx shadcn@latest add @ai-elements/message --dry-run
-```
-
-`info --json` is the project-aware source for `tailwindVersion`, `base`,
-`iconLibrary`, aliases, `resolvedPaths`, and configured registries. Current
-package context should report Tailwind v4, Base UI primitives, lucide icons,
-source paths under `src/*`, and configured `@shadcn`/`@ai-elements` registry
-access. Use `search` to find current registry items, `docs` to fetch component
-documentation and example/API links, `view` to inspect item contents, and
-`add --dry-run` or `add --diff` to preview source changes before editing.
-
-When maintaining installed source:
-
-```bash
-npx shadcn@latest info --json
-npx shadcn@latest add <component> --dry-run
-npx shadcn@latest add @ai-elements/all --dry-run
-```
-
-The package `components.json` must resolve aliases to `src/*`, not `dist/*`. Build output rewrites `@/` aliases to relative package imports.
-
-Do not run shadcn `--overwrite` unless the maintainer explicitly asks for an upstream primitive refresh and the diff is reviewed.
-
-## Verification
-
-Before considering package work complete:
-
-```bash
-npm run build -w @nadicodeai/ui
-npm run test -w @nadicodeai/ui
-```
-
-For repo completion, run the root gate:
-
-```bash
-npm run quality
-```
+This map ships with `@nadicodeai/ui` so coding agents can find the package's
+authoritative interfaces without carrying a second copy of them.
+
+## Start here
+
+- Consumer installation and stylesheet setup:
+  [`../consuming-cross-repo.md`](../consuming-cross-repo.md).
+- Package/consumer boundary, styling invariants, admission rules, and
+  accessibility: [`../contract.md`](../contract.md).
+- Current component modules and named exports: `src/components/`,
+  `src/index.ts`, `src/ai-elements.ts`, and `package.json` in a source checkout;
+  package exports and declarations in an installed package.
+- Import examples, form-stack guidance, `SeamGrid` usage, and live shadcn/AI
+  Elements discovery commands: [`../../README.md`](../../README.md).
+
+Do not maintain component, chart, form, section, export, or registry inventories
+in agent prose. Follow the owning source or document above.
+
+## Product work
+
+- Agent work surfaces: [`../agent-work-surfaces.md`](../agent-work-surfaces.md).
+- Product compositions and sections:
+  [`../product-compositions.md`](../product-compositions.md) and
+  [`../product-sections.md`](../product-sections.md).
+- Consumer order, fixture redaction, and readiness gates:
+  [`../migration/nadia-consumer-readiness.md`](../migration/nadia-consumer-readiness.md).
+- Terminal and TUI semantics:
+  [`../terminal-tui-semantics.md`](../terminal-tui-semantics.md).
+
+Routes, persistence, authentication, server state, runtime adapters,
+permissions, analytics, and product-specific copy stay in the consuming app.
+The package admits presentational structure according to its contract.
+
+## Maintenance
+
+Use shadcn MCP or the CLI live; never commit an upstream registry inventory.
+`components.json` is the project configuration authority, and reviewed source is
+the committed package surface. Preview upstream changes before applying them;
+do not overwrite maintained source without explicit maintainer direction.
+
+The package [`AGENTS.md`](../../AGENTS.md) maps scoped commands. Repository
+completion is the root `npm run quality` gate.

package/docs/consuming-cross-repo.md

@@ -6,52 +6,45 @@ from published npm rather than the workspace source.
 
 ## Version pinning
 
-Pin both packages to an exact version, never `latest` or a caret/tilde range:
+Pin the UI package to an exact version, never `latest` or a caret/tilde range:
 
 ```bash
 npm view @nadicodeai/ui version
-npm view @nadicodeai/design-system version
-npm install @nadicodeai/design-system@<exact-version> @nadicodeai/ui@<exact-version> react@^19 react-dom@^19 tailwindcss@^4 @tailwindcss/postcss@^4
+npm install @nadicodeai/ui@<exact-version> react@^19 react-dom@^19 tailwindcss@^4 @tailwindcss/postcss@^4
 ```
 
-`@nadicodeai/ui` pins its `@nadicodeai/design-system` dependency exactly; the
-consumer's own `package.json` must match that same version for both packages.
-A version bump in either package requires re-pinning both together.
+`@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.
 
-## CSS import order
+Declare `@nadicodeai/design-system` directly only when the app intentionally
+uses a separate public design-system API, such as a font/logo asset, the static
+CSS interface for a separate non-React surface, or the optional agent-chat
+enhancer. Pin that direct dependency to the version required by the installed
+UI release:
 
-Import order is load-bearing. Import both `@nadicodeai/design-system` CSS
-entrypoints before `@nadicodeai/ui/globals.css`: the fonts, so the
-`Geist`/`Geist Mono` `@font-face` declarations that the generated theme's
-`--font-*` roles reference are already registered, and `@nadicodeai/design-system/css`
-itself, which owns the kept `nc-*` geometry, type scale, chat CSS components,
-motion, and display components that `@nadicodeai/ui` components render
-against. `@nadicodeai/ui/globals.css` pulls in the generated theme and
-tokens but not this `nc-*` layer, so skipping it leaves package components
-unstyled:
-
-```ts
-import "@nadicodeai/design-system/assets/fonts/geist.css";
-import "@nadicodeai/design-system/css";
-import "@nadicodeai/ui/globals.css";
+```bash
+npm view @nadicodeai/ui@<exact-version> dependencies.@nadicodeai/design-system
 ```
 
-Both `@nadicodeai/design-system` and `@nadicodeai/ui` are required
-dependencies of every consumer, not just `@nadicodeai/ui` — see the version
-pinning section above.
+## CSS interface
 
-## Tailwind v4 source scanning
+Import one stylesheet once at the React app root:
 
-Tailwind v4's automatic content detection does not scan `node_modules`. Add an
-explicit `@source` directive in the consumer's Tailwind entry CSS (wherever
-`@import "tailwindcss"` lives) pointing at the package's built `dist`:
-
-```css
-@source "../node_modules/@nadicodeai/ui/dist";
+```ts
+import "@nadicodeai/ui/globals.css";
 ```
 
-Adjust the relative path to match the consumer's directory depth from its
-Tailwind entry file to `node_modules`.
+`@nadicodeai/ui/globals.css` is the complete React style interface. It composes
+Tailwind v4, shadcn, and the complete design-system CSS module.
+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.
+
+If the app needs bundled Geist files rather than its framework's font loader,
+that asset import is one of the intentional direct-API cases described above.
+Font loading is an asset decision, not a second design stylesheet.
 
 ## Base UI API breaks (migrating from Radix-era components)
 

package/docs/contract.md

@@ -0,0 +1,43 @@
+# @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 `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 `@nadicodeai/ui/tests/guards/no-raw-literal.test.ts`, `@nadicodeai/ui/tests/guards/dark-semantic-roles.test.ts`, and `@nadicodeai/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 `@nadicodeai/ui/tests/guards/no-dark.test.ts`, `@nadicodeai/ui/tests/guards/dark-semantic-roles.test.ts`, and `@nadicodeai/ui/tests/guards/token-reference-integrity.test.ts`. The generated mode and theme architecture lives only in [`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).
+- **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: `design-system/DESIGN.md` "## Layout").
+
+## Package Shape Invariants
+
+- **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.** `src/components/` is intentionally flat shadcn-style source. Do not document folders or package namespaces that do not exist, and do not add top-level exports for recipes, blocks, agent, or terminal groupings unless a later package API decision adds concrete source, built files, docs, and tests in the same change.
+- **shadcn and AI Elements are package surface.** Installed shadcn and AI Elements modules under `src/components/` are intentional ready-to-use exports. The source tree owns the component inventory; `src/index.ts` and `src/ai-elements.ts` own the barrels, and `package.json` owns the public export shape. Guards derive the consumer surface from those owners. Prose routes to them instead of maintaining another component list.
+- **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.
+- **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.
+- **Public surface changes require a release decision.** Any change to exported components, `src/index.ts`, `src/ai-elements.ts`, package `exports`, `globals.css`, theme behavior, package docs, package skills, or design-system token/CSS/theme output consumed by this package must end with an explicit npm release decision before handoff: bump the relevant version(s) and run `npm pack --dry-run -w @nadicodeai/ui` per `../../../docs/internal/npm-publishing.md`, or include a `[no-publish]` commit marker with the reason in the commit body. The pre-push gate requires one of the two. When the UI change depends on modified `@nadicodeai/design-system` output, bump and publish `@nadicodeai/design-system` first, then update this package's dependency and publish UI. Never claim a UI package change is shipped until `npm view @nadicodeai/ui version` reports the intended version.
+
+## Admission Rules
+
+Agent work surfaces (chat, composer, tool approval, artifacts, threads, diffs, terminal/file preview, and the underlying agent state models) are NadicodeAI core domain. They belong in this package outright, not behind a named consumer. Any other new product composition (a shell, a settings surface, a generic section) is admitted only with a named consuming surface landing in the same change. Genuinely app-bespoke UI (window chrome, boot/install overlays, mascots, PTY/xterm embeds) stays in the consuming app; it never becomes a package abstraction. A component left unconsumed after its target migration ships gets removed.
+
+- **Standard components, not app-owned product features.** This package ships primitives, standard UI components, AI Elements, 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. Generic data tables, command palettes, and chart cards are app-owned shadcn registry adaptations. The source-backed `chart-*` package surface is the plan-approved exception per issue #166 and ADR 0010; chart cards remain app-owned. Every data-shaped chart exposes an equivalent non-visual data alternative. A component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
+- **Auth routes are consumer-owned shadcn block work.** Login, signup, OTP, two-factor, magic-link, and provider-button flows start from the selected shadcn block/example in the consuming app, with app-owned Better Auth behavior. Do not ship generic auth, signup, OTP, federated-login, or provider abstractions from this package unless a later explicit boundary decision replaces the selected shadcn block.
+- **Reusable sections and compositions live here after proof.** Bento grids, media mounts, demo surfaces, page frames, section intros, CTA bands, proof slots, benefits grids, generic shells, and homepage/use-case sections belong in `@nadicodeai/ui` when a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary. Website, portal, and sibling Nadia routes pass data and media children into existing compositions instead of rebuilding layout locally.
+- **Brand renderers live here for React consumers.** Logo geometry, asset generation, and usage semantics are owned by [`design-system/DESIGN.md`, "Brand media authority"](../../../design-system/DESIGN.md#brand-media-authority). `BrandMark` and `BrandWordmark` render that 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.
+- **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.
+
+## Accessibility Invariant
+
+**Tier-1 accessibility is tested, browser-free.** Every rendering component test uses the package `expectAccessible` helper; the coverage guard derives the applicable test set and fails omissions. 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.
+
+## Consumer Boundary
+
+Consumers own routing, auth, app data, server actions, runtime adapters, permission decisions, analytics, and app-specific copy. The package owns the presentational structure and state vocabulary only. [`migration/nadia-consumer-readiness.md`](migration/nadia-consumer-readiness.md) owns migration order and readiness; [`terminal-tui-semantics.md`](terminal-tui-semantics.md) owns TUI semantics.
+
+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.

package/docs/migration/nadia-consumer-readiness.md

@@ -7,15 +7,10 @@ decisions, analytics, and product-specific copy.
 
 ## Required Setup
 
-Import both stylesheets once at the app root:
+Complete [`../consuming-cross-repo.md`](../consuming-cross-repo.md) before
+starting a migration; it owns consumer setup. Component styling must satisfy
+[`../contract.md`](../contract.md).
 
-```tsx
-import "@nadicodeai/ui/globals.css";
-import "@nadicodeai/design-system/css";
-```
-
-Do not add local token overrides, component-level `dark:` utilities, raw colors,
-raw Tailwind palette utilities, or app-local copies of package shell/product UI.
 Use public package subpaths:
 
 ```tsx
@@ -141,8 +136,8 @@ mirror `docs/terminal-tui-semantics.md` instead of importing a DOM runtime.
 
 ## Readiness Gates
 
-- The consumer imports `@nadicodeai/ui/globals.css` and
-  `@nadicodeai/design-system/css` at the root.
+- The consumer satisfies the canonical setup in
+  [`../consuming-cross-repo.md`](../consuming-cross-repo.md).
 - Product components are imported from `@nadicodeai/ui/components/*` public
   subpaths, not `src/*`.
 - At least one local shell, bento, settings, installer, plugin, or chat