@nadicodeai/ui

Shared React UI for NadicodeAI ecosystem apps, authored as shadcn-style source and published as a built package.

The package exports ESM JavaScript, TypeScript declarations, and the Tailwind v4 entry stylesheet needed by consuming apps. It is intentionally coupled to @nadicodeai/design-system: the design-system package owns brand tokens, framework-agnostic geometry, fonts, assets, and CSS components; this package owns React components and reusable section compositions on those tokens. Shared product compositions ship when their source, public subpath export, contract, and tests exist together.

The package ships:

• shadcn source components under @nadicodeai/ui/components/*, backed by Base UI primitives where a headless primitive is needed
• the Agent UI interface at @nadicodeai/ui/agents
• React adapters over the design-system grammar and assets
• reusable marketing/section compositions
• presentational product components for shared application surfaces
• package-local agent guidance: AGENTS.md, docs/contract.md, and docs/migration/

The package surface is source-backed and flat under src/components/. Reviewed third-party registry source stays under src/internal/ and is not a package namespace. Do not document 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. Routes, persistence, auth behavior, server state, runtime adapters, and app-owned product features/use cases stay in consuming apps such as apps/website/, apps/portal/, and sibling Nadia apps. The package contract owns the admission boundary; this README does not maintain a second rule set.

Install

Follow docs/consuming-cross-repo.md. It owns the install command, exact-version policy, peer requirements, dependency boundary, and separate-asset exception. The package is scoped for public npm registry publishing.

CSS

The package exposes one complete React stylesheet. Follow docs/consuming-cross-repo.md for the complete consumer setup contract.

Component styling rules live in docs/contract.md. That contract owns token-only styling, canonical role use, and the ban on component-local dark implementations. This README does not restate those rules.

Imports

Prefer direct subpath imports in app code:

import { Button } from "@nadicodeai/ui/components/button";
import { PageFrame } from "@nadicodeai/ui/components/page-frame";
import { Thread } from "@nadicodeai/ui/agents";

The root export is available for tooling and DX, but direct component subpaths keep package use explicit and friendly to bundlers.

Product components use the same public component subpaths:

import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell";
import { Thread } from "@nadicodeai/ui/agents";

Discover components

The component inventory is generated from source instead of maintained in prose. In this repository, src/components/**/*.tsx owns the module set; src/index.ts owns the barrel. package.json exposes that source-backed surface through ./components/*, and the build writes the consumer view to dist/components/**/*.d.ts.

Use the source tree while maintaining this package. In an installed package, use its package.json exports and generated declarations for current subpaths, exports, and prop types.

Product components

docs/contract.md owns the package/consumer boundary, admission rules, and accessibility invariants. Current modules are discovered from source and package exports, not from prose. assistant-ui runtime ownership and migration readiness live in the linked package docs; this README does not summarize them.

Layout primitives

SeamGrid is a supported low-level layout primitive: the single owner of the "gap-as-seam" grid used by the bordered section grids (stats band, testimonials, logo band, and siblings). It renders a div with the invariant grid gap-px base and paints one hairline seam at every cell boundary, so borderless, square-cornered cells never double a line.

import { SeamGrid } from "@nadicodeai/ui/components/seam-grid";

<SeamGrid surface="canvas" className="grid-cols-2 lg:grid-cols-4">
  {/* borderless, square-cornered cells */}
</SeamGrid>;

The only seam-specific prop is surface: "canvas" (default) paints the brand line via bg-border; "ink" mixes the line toward the ink role for darker panels. surface also lands on a data-surface attribute. Pass className, children, and any div props to keep your own column map, heights, and data-* attributes. The seam colour helper itself is an internal implementation detail (no public subpath export); couple to SeamGrid and its surface prop, not to the underlying arbitrary Tailwind class string.

Registry maintenance

Use shadcn MCP or the CLI for live discovery and registry maintenance while working in this package. Do not maintain a committed upstream registry inventory, registry snapshot, or inventory update script in @nadicodeai/ui; the source files and package exports are the committed surface.

From @nadicodeai/ui, Codex-capable environments can initialize the shadcn MCP client configuration when the local runtime supports MCP:

npx shadcn@latest mcp init --client codex

When MCP is unavailable, use the CLI directly:

npx shadcn@latest info --json
npx shadcn@latest search @shadcn -q "select" --json
npx shadcn@latest docs button select dialog --json
npx shadcn@latest view @shadcn/button
npx shadcn@latest add @shadcn/button --dry-run
npx assistant-ui@latest add thread --help

info --json is the project-aware source of truth for aliases, Tailwind version, base primitive library, icon library, resolved source paths, and configured registries. The active primitive base is Base UI; do not add Radix or vaul to package source or dependencies. cmdk is present only for the stock shadcn Command component while the Base UI registry declares it. Use search, docs, and view to inspect current registry items before adding or refreshing source. Review add --dry-run or add --diff output before changing files, and do not use --overwrite unless the maintainer explicitly asks for an upstream refresh.

Forms

Use one form model:

• Input, Textarea, Select, Checkbox, and similar files are controls.
• FieldGroup, Field, FieldLabel, FieldDescription, and FieldError provide field layout and accessible label/error structure.
• Form, FormField, FormItem, FormControl, FormLabel, FormDescription, and FormMessage are the React Hook Form integration.

Do not add or import a separate FormInput/FormTextarea control family. If a new input size or behavior is needed, add it to the canonical shadcn control or field primitive instead of creating a parallel form-control API.

Agent instructions

The npm package ships two agent-facing files on purpose: AGENTS.md, the package map and its rules, and docs/contract.md, the package contract. A consuming repository points its own agent map at node_modules/@nadicodeai/ui/AGENTS.md. They are packaged through npm files; they are not runtime module exports.

Build

npm run build -w @nadicodeai/ui

package.json owns the build and packed-file surface. Use npm pack --dry-run to inspect the consumer artifact rather than maintaining an output list here.