uds-tailwind-test

uds-tailwind-test is a publishable React UI package built from this Tailwind v4 and shadcn-based design system workspace.

The package contract now has one canonical AI-readable source of truth:

• ai/uds-contract.json

Use that file for machine-readable guidance, then use the human-facing summaries here, in AI_USAGE.md, and in setup.md.

Installation

npm install uds-tailwind-test react react-dom

Import the stylesheet once near the app root:

import "uds-tailwind-test/styles.css"

Development (this repository)

Use Node.js 22 LTS (or 24+) for local installs so npm does not report EBADENGINE for eslint-visitor-keys@5 (its engines field does not list Node 23). Run nvm use (or fnm use) in the repo root; the .nvmrc file pins 22. If you use Volta, the repo’s package.json includes a matching volta.node pin.

You may still see npm warn deprecated node-domexception while installing devDependencies: it is pulled in by the shadcn CLI via node-fetch / fetch-blob. It is safe to ignore for building this package; upstream would need to drop that chain to silence the warning.

Quick start

import {
  AppShell,
  Button,
  Card,
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  TooltipProvider,
} from "uds-tailwind-test"
import "uds-tailwind-test/styles.css"

export function Example() {
  return (
    <TooltipProvider>
      <SidebarProvider>
        <AppShell
          className="min-h-dvh w-full min-w-0"
          sidebarWidth={280}
          showListview={false}
          mainClassName="bg-[var(--uds-color-neutrals-50)]"
          sidebar={
            <Sidebar collapsible="none">
              <SidebarHeader>Workspace</SidebarHeader>
              <SidebarContent>
                <SidebarMenu>
                  <SidebarMenuItem>
                    <SidebarMenuButton isActive>Dashboard</SidebarMenuButton>
                  </SidebarMenuItem>
                </SidebarMenu>
              </SidebarContent>
              <SidebarFooter>
                <Button className="w-full rounded-[4px]">New item</Button>
              </SidebarFooter>
            </Sidebar>
          }
        >
          <Card className="m-6 rounded-[4px] p-6">AppShell is mounted at runtime.</Card>
        </AppShell>
      </SidebarProvider>
    </TooltipProvider>
  )
}

Public API model

The root package entrypoint is src/index.ts. That file is the canonical public API.

Consumers and AI tools should import only from:

• uds-tailwind-test
• uds-tailwind-test/styles.css

Do not infer public API from internal implementation files under src/components/ui.

AI contract

The AI/tooling contract lives in ai/uds-contract.json and includes:

• allowed and forbidden imports
• layout defaults
• public export catalog with recommendations
• current styling and radius policy
• screen recipes
• anti-patterns
• registry metadata

Human-facing summaries:

• AI_USAGE.md
• setup.md
• AGENTS.md
• .cursor/rules/uds-design-system.mdc

Recipes and examples

Recipe docs:

• ai/recipes/auth-shell.md
• ai/recipes/workspace-dashboard.md
• ai/recipes/detail-with-listview.md
• ai/recipes/settings-form.md

Canonical example outputs:

• ai/examples/auth-shell.tsx
• ai/examples/workspace-dashboard.tsx
• ai/examples/detail-with-listview.tsx
• ai/examples/settings-form.tsx

Consumer smoke fixture:

• examples/consumer-react/src/App.tsx

shadcn registry

This repo now ships a local-first custom registry surface:

• source manifest: registry.json
• generated items: public/r
• shadcn namespace in components.json: @uds
• default local URL template: http://localhost:5173/r/{name}.json

Regenerate the AI contract and registry artifacts with:

npm run generate:ai

Local development

npm install
npm run generate:ai
npm run dev

Useful checks:

npm run lint
npm run typecheck
npm run build
npm run pack:check