feat(ui): share shadcn primitives in @sketchi/ui and lint the Tailwind apps with @shadcn/lint (#601)

The site hand-rolled its buttons in plain CSS while the playground kept its own
copy of the shadcn primitives. The primitives now live once, in packages/ui, with
the stylesheet that maps shadcn's tokens onto the shared theme. The playground
imports them from there and the site uses the same Button: a `brand` variant and
an `xl` size carry the site's call to action, and the mobile menu toggle is an
outline icon button with lucide icons. Both apps have a components.json whose ui
and utils aliases point at the package.

@shadcn/lint and better-tailwindcss now run as Oxlint plugins in `pnpm run
lint`, configured in tools/oxlint/ui-style-policy.json and described in
docs/ui-style-contracts.md. What they found is fixed: classes with no CSS behind
them, inline left/top and animation delays that now go through CSS custom
properties, utility-shaped overrides moved to Tailwind classes, and the
tw-animate-css classes the primitives use, which only the playground imported.

The site now loads Tailwind's preflight; the docs page's numbered steps keep
their numbers.

Author: anandpant

.oxfmtrc.json

@@ -28,7 +28,7 @@
 		"packages/diagram/agent/src/lib/code-mode/fixtures/**",
 		// Vendored shadcn and AI Elements registry components
 		"apps/playground/src/components/ai-elements/**",
-		"apps/playground/src/components/ui/**",
+		"packages/ui/src/components/**",
 		// Raw pipeline artifacts, and state that editor and agent tools rewrite
 		"packages/icons/catalog/pipeline-output/**",
 		".agents/**",

.oxlintrc.json

@@ -18,8 +18,12 @@
 	"jsPlugins": [
 		// Provides @nx/enforce-module-boundaries; ESLint itself is not installed.
 		{ "name": "@nx", "specifier": "@nx/eslint-plugin" },
-		"./tools/oxlint/sketchi-plugin.ts"
+		"./tools/oxlint/sketchi-plugin.ts",
+		"@shadcn/lint",
+		"eslint-plugin-better-tailwindcss"
 	],
+	// Tailwind component contracts: docs/ui-style-contracts.md.
+	"extends": ["./tools/oxlint/ui-style-policy.json"],
 	"categories": {
 		"correctness": "error"
 	},
@@ -229,6 +233,7 @@
 				"packages/diagram/ui/**",
 				"packages/icons/catalog/**",
 				"packages/svg-excalidraw/**",
+				"packages/ui/**",
 				"tools/sketchi-generators/**"
 			],
 			"rules": {

README.md

@@ -147,6 +147,7 @@ model candidate → typed diagram IR → deterministic scene → Excalidraw arti
 | `packages/icons/catalog`      | Icon manifest, ranked search, SVG sources, node-logo rules      |
 | `packages/studio/projects`    | Studio project/diagram contracts and object-bucket persistence  |
 | `packages/svg-excalidraw`     | Native SVG-to-Excalidraw conversion and library serialization   |
+| `packages/ui`                 | Shared shadcn primitives and tokens for the Tailwind apps       |
 
 The first high-reliability target is decision-heavy flowchart generation.
 `flowchart`, `mindmap`, `sequence`, `timeline`, `chart`, `state-machine`, `gantt`, `er`, `class`, `org-chart`, `venn`, `journey`, `sankey`, `wireframe`, and `quadrant` are explicit diagram families; unsupported families do
@@ -213,7 +214,9 @@ lint-rule tests.
   then runs [Oxlint](https://oxc.rs/docs/guide/usage/linter) over the whole
   repository with zero warnings allowed. `.oxlintrc.json` holds the rule set, the
   Nx module boundaries, and the Effect and Zod import policy; Sketchi's own rules
-  live in `tools/oxlint` and run with `pnpm run test:lint-rules`. Every
+  live in `tools/oxlint` and run with `pnpm run test:lint-rules`. `@shadcn/lint`
+  holds the Tailwind apps to their shared primitives; see
+  [UI style contracts](docs/ui-style-contracts.md). Every
   suppression is a single-line `oxlint-disable-next-line <rule> -- <reason>`.
 - `pnpm run format` applies [Oxfmt](https://oxc.rs/docs/guide/usage/formatter):
   tabs, 100 columns, double quotes, semicolons, trailing commas, and spaces in
@@ -294,7 +297,8 @@ apps/
 packages/
 ├── diagram/{agent,core,excalidraw,generation,renderer,scenarios,ui}/
 ├── studio/projects/              persistence contract and service
-└── svg-excalidraw/               native SVG conversion
+├── svg-excalidraw/               native SVG conversion
+└── ui/                           shared shadcn primitives
 tools/sketchi-generators/         Nx generators and tests
 scripts/                          deploy, cutover, and pipeline operations
 plugins/                          Codex and Claude Code distribution payloads
@@ -313,6 +317,7 @@ build configuration; see the
 
 - [Agent plugin quickstart](docs/code-mode-agent-plugins.md)
 - [Architecture](docs/architecture.md)
+- [UI style contracts](docs/ui-style-contracts.md)
 - [Agentic generation](docs/agentic-generation.md)
 - [MCP-first generation](docs/mcp-first-generation.md)
 - [SVG conversion plan](docs/svg-excalidraw-conversion-plan.md)

apps/playground/components.json

@@ -13,8 +13,8 @@
 	"iconLibrary": "lucide",
 	"aliases": {
 		"components": "@/components",
-		"utils": "@/lib/utils",
-		"ui": "@/components/ui",
+		"utils": "@sketchi/ui/lib/utils",
+		"ui": "@sketchi/ui/components",
 		"lib": "@/lib",
 		"hooks": "@/hooks"
 	}

apps/playground/package.json

@@ -18,26 +18,21 @@
 		"@sketchi/icon-catalog": "workspace:*",
 		"@sketchi/observability": "workspace:*",
 		"@sketchi/studio-projects": "workspace:*",
+		"@sketchi/ui": "workspace:*",
 		"@streamdown/cjk": "1.0.4",
 		"@streamdown/code": "2.0.0",
 		"@streamdown/math": "1.0.3",
 		"@tanstack/react-virtual": "3.14.13",
 		"ai": "7.0.130",
-		"class-variance-authority": "0.7.1",
-		"clsx": "2.1.1",
-		"cmdk": "1.1.1",
 		"lucide-react": "1.52.0",
 		"motion": "14.0.0",
 		"nanoid": "6.0.2",
-		"radix-ui": "1.7.0",
 		"shiki": "4.5.0",
 		"streamdown": "2.7.0",
-		"tailwind-merge": "3.7.0",
 		"use-stick-to-bottom": "1.1.6"
 	},
 	"devDependencies": {
 		"@tailwindcss/vite": "4.3.3",
-		"tailwindcss": "4.3.3",
-		"tw-animate-css": "1.4.0"
+		"tailwindcss": "4.3.3"
 	}
 }

apps/playground/src/application-structure.test.ts

@@ -180,10 +180,7 @@ describe("Playground application structure", () => {
 			expect(existsSync(join(libRoot, path)), path).toBe(false);
 		}
 
-		expect(
-			sourceFilesUnder(libRoot)
-				.map((path) => relative(libRoot, path))
-				.sort(),
-		).toEqual(["utils.ts"]);
+		// `cn` and the shadcn primitives come from @sketchi/ui.
+		expect(existsSync(libRoot)).toBe(false);
 	});
 });

apps/playground/src/components/ai-elements/code-block.tsx

@@ -1,14 +1,14 @@
 "use client";
 
-import { Button } from "@/components/ui/button";
+import { Button } from "@sketchi/ui/components/button";
 import {
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "@/components/ui/select";
-import { cn } from "@/lib/utils";
+} from "@sketchi/ui/components/select";
+import { cn } from "@sketchi/ui/lib/utils";
 import { CheckIcon, CopyIcon } from "lucide-react";
 import type { ComponentProps, HTMLAttributes } from "react";
 import {

apps/playground/src/components/ai-elements/conversation.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { Button } from "@/components/ui/button";
-import { cn } from "@/lib/utils";
+import { Button } from "@sketchi/ui/components/button";
+import { cn } from "@sketchi/ui/lib/utils";
 import type { UIMessage } from "ai";
 import { ArrowDownIcon, DownloadIcon } from "lucide-react";
 import type { ComponentProps } from "react";

apps/playground/src/components/ai-elements/message.tsx

@@ -1,17 +1,17 @@
 "use client";
 
-import { Button } from "@/components/ui/button";
+import { Button } from "@sketchi/ui/components/button";
 import {
   ButtonGroup,
   ButtonGroupText,
-} from "@/components/ui/button-group";
+} from "@sketchi/ui/components/button-group";
 import {
   Tooltip,
   TooltipContent,
   TooltipProvider,
   TooltipTrigger,
-} from "@/components/ui/tooltip";
-import { cn } from "@/lib/utils";
+} from "@sketchi/ui/components/tooltip";
+import { cn } from "@sketchi/ui/lib/utils";
 import type { UIMessage } from "ai";
 import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import type { ComponentProps, HTMLAttributes, ReactElement } from "react";

apps/playground/src/components/ai-elements/prompt-input.tsx

@@ -8,38 +8,38 @@ import {
   CommandItem,
   CommandList,
   CommandSeparator,
-} from "@/components/ui/command";
+} from "@sketchi/ui/components/command";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
+} from "@sketchi/ui/components/dropdown-menu";
 import {
   HoverCard,
   HoverCardContent,
   HoverCardTrigger,
-} from "@/components/ui/hover-card";
+} from "@sketchi/ui/components/hover-card";
 import {
   InputGroup,
   InputGroupAddon,
   InputGroupButton,
   InputGroupTextarea,
-} from "@/components/ui/input-group";
+} from "@sketchi/ui/components/input-group";
 import {
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "@/components/ui/select";
-import { Spinner } from "@/components/ui/spinner";
+} from "@sketchi/ui/components/select";
+import { Spinner } from "@sketchi/ui/components/spinner";
 import {
   Tooltip,
   TooltipContent,
   TooltipTrigger,
-} from "@/components/ui/tooltip";
-import { cn } from "@/lib/utils";
+} from "@sketchi/ui/components/tooltip";
+import { cn } from "@sketchi/ui/lib/utils";
 import type { ChatStatus, FileUIPart, SourceDocumentUIPart } from "ai";
 import {
   CornerDownLeftIcon,