@hubbiparts/uikit 0.1.0 → 0.2.1

package/package.json

@@ -1,16 +1,25 @@
 {
   "name": "@hubbiparts/uikit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "HubbiParts React UI kit built with shadcn/ui primitives.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/hubbiparts1/uikit.git"
+  },
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "skills"
   ],
+  "bin": {
+    "hubbiparts-uikit": "./bin/hubbiparts-uikit.mjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,6 +30,7 @@
       "require": "./dist/index.cjs"
     },
     "./style.css": "./dist/style.css",
+    "./skill": "./skills/hubbiparts-uikit/SKILL.md",
     "./package.json": "./package.json"
   },
   "sideEffects": [

package/skills/hubbiparts-uikit/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: hubbiparts-uikit
+description: Installs, uses, updates and audits the @hubbiparts/uikit React component package (HubbiParts design system built on shadcn/ui + Radix + Tailwind v4). Applies whenever a project depends on @hubbiparts/uikit, when building HubbiParts/Hubbi frontend UI, when asked to "install the Hubbi UI kit", "update the uikit", "migrate local shadcn components to the kit", or when importing from '@hubbiparts/uikit'. Prefer it over the generic shadcn skill in those projects.
+user-invocable: true
+allowed-tools: Bash(npx hubbiparts-uikit *), Bash(npm view @hubbiparts/uikit *), Bash(npm outdated @hubbiparts/uikit)
+---
+
+# @hubbiparts/uikit
+
+HubbiParts' React UI kit: 61 shadcn/ui components (Radix base, `radix-nova` style), themed with HubbiParts tokens, **distributed as a compiled npm package** — not copied into the project.
+
+That single fact changes the shadcn workflow:
+
+| shadcn (source copy)                    | @hubbiparts/uikit (npm package)                                   |
+| --------------------------------------- | ----------------------------------------------------------------- |
+| `npx shadcn add button`                 | Already shipped — just `import { Button } from '@hubbiparts/uikit'` |
+| Component lives in `@/components/ui`    | Component lives in `node_modules`; never edit it there            |
+| Update = `shadcn add --diff`            | Update = bump the package version (see [maintenance.md](./rules/maintenance.md)) |
+| Customize by editing the file           | Compose, use variants, or contribute upstream to the kit          |
+
+## Current Project Context
+
+```json
+!`npx hubbiparts-uikit info --json`
+```
+
+If the block above is empty or failed, run `npx hubbiparts-uikit info --json` yourself (the CLI ships with the package; if it is missing, the kit is not installed — see [setup.md](./rules/setup.md)).
+
+Key fields:
+
+- **`installedVersion` / `latestVersion` / `updateAvailable`** → whether to propose an upgrade.
+- **`styleImportedIn`** → where `@hubbiparts/uikit/style.css` is imported. `null` means components render unstyled: fix that first.
+- **`tailwind.major`** → `4`, `3` or `null`. Decides how project utilities reach kit tokens ([theming.md](./rules/theming.md)).
+- **`isRSC`** → when `true` (Next.js App Router), any file that renders kit components with state/handlers needs `"use client"`. The bundle does not add it for you.
+- **`localDuplicates`** → local shadcn copies (e.g. `src/components/ui/button.tsx`) that duplicate kit components. Migration candidates, never silently delete them.
+- **`components`** → the exact catalog of the installed version. Never import a component that is not listed.
+- **`packageManager`** → use it for installs (`pnpm add`, `npm install`, ...).
+- **`isKitRepository`** → `true` inside the kit's own repo; then follow [contributing.md](./rules/contributing.md) instead.
+
+## Principles
+
+1. **Kit first.** Before writing any UI, check the catalog (`npx hubbiparts-uikit list`). A styled `div` that re-implements a kit component is a bug.
+2. **Compose, don't reinvent.** Settings page = `Tabs` + `Card` + `FieldGroup`. Dashboard = `Sidebar` + `Card` + `Chart` + `Table`.
+3. **Variants before classes.** `variant="outline"`, `size="sm"`. `className` is for layout (width, margin, grid placement), not for recoloring.
+4. **Semantic tokens only.** `bg-primary`, `text-muted-foreground`, `border-border`. Never `bg-blue-600` or `#1E3F9E` — the brand lives in the tokens.
+5. **One source of truth.** Missing variant or component? Add it to the kit ([contributing.md](./rules/contributing.md)) — do not fork a local copy.
+
+## Critical Rules
+
+Always enforced. Details and Incorrect/Correct pairs in the linked files.
+
+### Setup → [setup.md](./rules/setup.md)
+- Import `@hubbiparts/uikit/style.css` **once**, at the app entry, before project CSS.
+- Wrap the app with `TooltipProvider` once; wrap sidebar layouts with `SidebarProvider`.
+- Render `<Toaster />` once near the root; Toaster reads the theme via `next-themes` (`ThemeProvider attribute="class"`).
+- Dark mode is the `.dark` class on an ancestor (usually `<html>`). No `dark:` color overrides.
+
+### Imports → [usage.md](./rules/usage.md)
+- Always `import { X } from '@hubbiparts/uikit'`. Never deep-import `@hubbiparts/uikit/dist/...`.
+- `cn` is exported by the kit: `import { cn } from '@hubbiparts/uikit'`.
+- Icons are `lucide-react`, passed as components, with `data-icon="inline-start|inline-end"` inside buttons and no size classes.
+- `toast()` comes from `sonner` (the kit exports only `Toaster`).
+
+### Composition → [usage.md](./rules/usage.md)
+- Items inside their Group: `SelectItem` → `SelectGroup`/`SelectContent`, `CommandItem` → `CommandGroup`, `DropdownMenuItem` → `DropdownMenuContent`.
+- Custom triggers use `asChild` (Radix base). Exception: `Combobox` is Base UI — use its own props.
+- `Dialog`, `Sheet`, `Drawer`, `AlertDialog` always have a Title (`className="sr-only"` if hidden).
+- Full `Card` composition: `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`.
+- Forms: `FieldGroup` + `Field` + `FieldLabel`; validation = `data-invalid` on `Field` + `aria-invalid` on control.
+- Loading buttons: `Spinner` + `disabled`. There is no `isLoading` prop.
+- `Avatar` always has `AvatarFallback`. `TabsTrigger` always inside `TabsList`.
+- Callouts = `Alert`, empty states = `Empty`, placeholders = `Skeleton`, dividers = `Separator`, status = `Badge`.
+- Chat UIs: `MessageScroller` + `Message` + `Bubble` + `Attachment` + `Marker`.
+
+### Styling → [theming.md](./rules/theming.md)
+- `flex flex-col gap-*`, never `space-y-*`. `size-*` for squares. `truncate` shorthand.
+- No manual `z-index` on overlays.
+- Brand typography: `font-display` (Space Grotesk) for headings, `font-sans` (Inter) for UI, `font-mono` (Space Mono) for SKUs, plates, VINs, codes.
+- Brand changes (colors, radius, fonts) are made **in the kit's tokens**, never by overriding classes in a consumer.
+
+### Maintenance → [maintenance.md](./rules/maintenance.md)
+- Check `npx hubbiparts-uikit outdated` at the start of UI work; propose — don't silently perform — major/minor upgrades.
+- Upgrade via the package manager, then run typecheck + tests + build + a visual check.
+- Migrating local shadcn copies to the kit: one component at a time, diff behavior first, keep local customizations as composition.
+
+## Component Selection
+
+| Need                       | Use                                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------------------- |
+| Actions                    | `Button` (+ `ButtonGroup`), `Toggle`, `ToggleGroup` for 2–7 options                        |
+| Form inputs                | `Input`, `InputGroup`, `Textarea`, `Select`, `NativeSelect`, `Combobox`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `InputOTP`, `Calendar` |
+| Form layout                | `FieldGroup`, `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Label`             |
+| Data display               | `Table`, `Card`, `Item`, `Badge`, `Avatar`, `Kbd`, `ChartContainer` (Recharts)             |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Menubar`, `Breadcrumb`, `Tabs`, `Pagination`                 |
+| Overlays                   | `Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `Popover`, `HoverCard`, `Tooltip`              |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Command` (inside `Dialog` for palettes)                    |
+| Feedback                   | `Toaster` + `toast()` from sonner, `Alert`, `Progress`, `Skeleton`, `Spinner`, `Empty`     |
+| Layout                     | `Separator`, `ScrollArea`, `ResizablePanelGroup`, `Accordion`, `Collapsible`, `AspectRatio`, `Carousel` |
+| Chat / conversation        | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`                             |
+| Guided flows               | `Questionnaire`                                                                            |
+| Composition-only (no file) | Data Table = `Table` + state; Date Picker = `Popover` + `Calendar`; Typography = tokens    |
+
+## Getting a Component's API
+
+Never guess props. The installed version is the contract:
+
+```bash
+npx hubbiparts-uikit docs sidebar dialog     # exports + TypeScript signatures of the installed version
+npx hubbiparts-uikit list                    # every component and its exports
+```
+
+For usage examples and behavior, the shadcn page printed by `docs` (Radix variant) applies — HubbiParts only changes tokens. When the kit signature and the shadcn page disagree, **the kit signature wins**.
+
+## Workflow
+
+1. **Context** — read the injected info (or run `npx hubbiparts-uikit info --json`).
+2. **Setup check** — `styleImportedIn` set, providers present, Tailwind bridge configured ([setup.md](./rules/setup.md)). Fix before building features.
+3. **Freshness** — if `updateAvailable`, tell the user and propose the upgrade ([maintenance.md](./rules/maintenance.md)).
+4. **Pick components** — from the catalog; confirm the API with `docs`.
+5. **Build** — compose following the Critical Rules; semantic tokens only.
+6. **Verify** — project typecheck, lint, tests, build, and look at the rendered UI (light and dark).
+7. **Gaps** — if the kit lacks something, compose it locally in a feature folder (not `components/ui`) and report it as a kit contribution candidate.
+
+## Quick Reference
+
+```bash
+# Install (use the project's package manager)
+npm install @hubbiparts/uikit
+npx hubbiparts-uikit skill install                     # links this skill into .agents/skills
+npx hubbiparts-uikit skill install --dir .claude/skills
+
+# Context & catalog
+npx hubbiparts-uikit info --json
+npx hubbiparts-uikit list
+npx hubbiparts-uikit docs button field select
+
+# Updates
+npx hubbiparts-uikit outdated
+npm view @hubbiparts/uikit versions --json
+npm install @hubbiparts/uikit@latest
+```
+
+## Detailed References
+
+- [rules/setup.md](./rules/setup.md) — installation, CSS import, providers, dark mode, Tailwind v3/v4, Next.js/Vite
+- [rules/usage.md](./rules/usage.md) — imports, composition, forms, overlays, icons, toast, Incorrect/Correct pairs
+- [rules/theming.md](./rules/theming.md) — HubbiParts tokens, typography, spacing rules, using tokens in project utilities
+- [rules/maintenance.md](./rules/maintenance.md) — checking versions, upgrading, migrating local shadcn copies, regression checklist
+- [rules/contributing.md](./rules/contributing.md) — adding or updating components in the kit repository and releasing

package/skills/hubbiparts-uikit/rules/contributing.md

@@ -0,0 +1,49 @@
+# Contributing to the kit (inside the kit repository)
+
+Applies when `info` reports `isKitRepository: true` (package name `@hubbiparts/uikit`). Here the generic **shadcn skill applies** for source edits — components live in `src/components/ui` and are managed with the shadcn CLI.
+
+## Branching
+
+Never commit on protected branches (`main`, `dev`). Create `feat/<slug>` from the target branch before editing and preserve uncommitted work with `git switch -c`.
+
+## Adding a component
+
+```bash
+npx shadcn@latest add <component>          # writes src/components/ui/<component>.tsx
+```
+
+Then, in the same change:
+
+1. Export it from `src/components/ui/index.ts` (`export * from './<component>'`).
+2. Add the slug to `publicComponentSlugs` in the same file.
+3. Add an inventory entry with a dedicated preview in `playground/src/component-inventory.ts` and `playground/src/ComponentInventory.tsx` (the test fails if any entry uses the default preview).
+4. Add stories if the component belongs to a Storybook category.
+5. If it needs a new third-party package, add it to `dependencies` **and** to `build.rollupOptions.external` in `vite.config.ts`.
+
+## Updating a component from upstream shadcn
+
+Follow the shadcn skill's update flow: `npx shadcn@latest add <component> --dry-run`, then `--diff <file>`, merge preserving HubbiParts changes. Never `--overwrite` without explicit approval.
+
+## Changing tokens
+
+Edit `src/index.css` only. Keep semantic names stable — renaming a variable is a breaking change for consumers.
+
+## Validation before release
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run build:playground
+npm publish --dry-run --access public
+```
+
+Check the tarball contains `dist`, `bin/hubbiparts-uikit.mjs` and `skills/hubbiparts-uikit`, and that `npx hubbiparts-uikit list` reflects the new component.
+
+## Release
+
+1. Bump the version (`npm version patch|minor --no-git-tag-version`); on `0.x` use `minor` for breaking changes.
+2. Update this skill if rules, components or setup changed — it ships with the package and is what consumer agents read.
+3. Merge the MR into `main` on `gitlab.hubbi.app`. The push mirror sends `main` to `gitlab.com/hubbiparts1/uikit`, whose pipeline publishes via npm Trusted Publishing (OIDC, no token). Never publish from a local machine unless a human explicitly asks for it (it requires the npm account's 2FA/OTP).
+4. Confirm: `npm view @hubbiparts/uikit version`.

package/skills/hubbiparts-uikit/rules/maintenance.md

@@ -0,0 +1,74 @@
+# Maintenance: keeping the kit up to date
+
+In a consumer project, "updating components" means **updating the package version**. There is nothing to `shadcn add`.
+
+## Check
+
+```bash
+npx hubbiparts-uikit outdated              # installed vs latest
+npx hubbiparts-uikit info --json           # installedVersion, latestVersion, declaredRange
+npm view @hubbiparts/uikit versions --json # full release list
+```
+
+Do this at the start of any UI task in a consumer project. If `updateAvailable` is true, **tell the user** and propose the upgrade; do not upgrade silently inside an unrelated feature change.
+
+## Semver policy
+
+The kit follows semver. While on `0.x`, a **minor** bump (`0.1 → 0.2`) may contain breaking changes; a patch is safe.
+
+| Bump            | Action                                                                 |
+| --------------- | ---------------------------------------------------------------------- |
+| Patch           | Upgrade, run the checks below.                                          |
+| Minor on `0.x` / Major | Ask the user first; read the release notes/diff of `dist/components/ui/*.d.ts` between versions; upgrade in its own branch/commit. |
+
+Compare APIs between versions without installing:
+
+```bash
+npm pack @hubbiparts/uikit@<old> @hubbiparts/uikit@<new> --pack-destination "$TMPDIR"
+# extract both and diff package/dist/components/ui/*.d.ts
+```
+
+## Upgrade
+
+```bash
+npm install @hubbiparts/uikit@latest     # or a pinned version: @0.2.0
+```
+
+Use the project's package manager. Keep the lockfile change in the same commit.
+
+If the skill was installed with `--copy`, refresh it:
+
+```bash
+npx hubbiparts-uikit skill install --copy
+```
+
+Symlinked skills update automatically.
+
+## Regression checklist after upgrading
+
+1. `npx hubbiparts-uikit info --json` shows the new `installedVersion`.
+2. Project typecheck — signature changes surface here first.
+3. Project lint and tests.
+4. Project build.
+5. Visual check of the screens that use changed components, in light and dark mode.
+6. Report which components changed and what was verified. If something could not be verified (e.g. no browser available), say so.
+
+## Migrating local shadcn copies to the kit
+
+`localDuplicates` lists local files such as `src/components/ui/button.tsx` whose slug exists in the kit.
+
+1. Ask the user before starting; migration touches many imports.
+2. One component at a time. For each:
+   - Diff the local file against `npx hubbiparts-uikit docs <slug>` — note custom variants, props or behavior.
+   - Local additions that are pure styling → drop them (the kit tokens replace them).
+   - Local additions that are real features (new variant, prop) → keep them as composition in a feature component, and report them as kit contribution candidates.
+   - Replace imports `@/components/ui/<slug>` → `@hubbiparts/uikit`.
+   - Delete the local file only after no import references it (`grep -r "components/ui/<slug>"`).
+3. Run the regression checklist after each component or small batch.
+4. Never delete local copies in bulk, never use `--overwrite`-style shortcuts.
+
+## Keeping the dependency healthy
+
+- Pin with a caret range (`^0.1.0`) or an exact version according to the project's policy; do not use `*` or `latest` in `package.json`.
+- Do not add `resolutions`/`overrides` for kit internals (Radix, sonner) unless asked; report conflicts to the kit instead.
+- Duplicate React warnings mean the project resolves two React copies — check `npm ls react`; the kit only has React as a peer.

package/skills/hubbiparts-uikit/rules/setup.md

@@ -0,0 +1,90 @@
+# Setup
+
+## Install
+
+Use the project's package manager (`packageManager` from `info`):
+
+```bash
+npm install @hubbiparts/uikit        # or: pnpm add / yarn add / bun add
+```
+
+Peer dependencies: `react` and `react-dom` `>=18.2 <20`. Everything else (Radix, sonner, recharts, lucide-react, next-themes, ...) is a regular dependency of the kit.
+
+If the project also imports `lucide-react` or `sonner` directly, add them to its own `package.json` instead of relying on hoisting.
+
+Then install the agent skill so every agent in the repo sees it:
+
+```bash
+npx hubbiparts-uikit skill install                      # .agents/skills/hubbiparts-uikit (symlink)
+npx hubbiparts-uikit skill install --dir .claude/skills # Claude Code layout
+npx hubbiparts-uikit skill install --copy               # copy instead of symlink (e.g. to commit it)
+```
+
+The symlink points into `node_modules`, so the skill always matches the installed kit version. A copied skill must be refreshed after each upgrade.
+
+## Import the stylesheet once
+
+The CSS contains the tokens, fonts, base layer and every utility the components use. Without it components render unstyled.
+
+```tsx
+// src/main.tsx (Vite) — before the project's own CSS
+import '@hubbiparts/uikit/style.css'
+import './index.css'
+```
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+import '@hubbiparts/uikit/style.css'
+import './globals.css'
+```
+
+**Incorrect:** importing `style.css` in several components, or importing `@hubbiparts/uikit/dist/style.css`.
+
+## Providers
+
+```tsx
+import { ThemeProvider } from 'next-themes'
+import { Toaster, TooltipProvider } from '@hubbiparts/uikit'
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      <TooltipProvider>
+        {children}
+        <Toaster position="bottom-right" />
+      </TooltipProvider>
+    </ThemeProvider>
+  )
+}
+```
+
+- `TooltipProvider` once at the root (sidebar tooltips depend on it too).
+- `Toaster` once. It reads the theme through `next-themes`; without `ThemeProvider` it falls back to `system`.
+- `SidebarProvider` wraps only layouts that render a `Sidebar`.
+
+## Dark mode
+
+The kit switches on the `.dark` class on an ancestor. `ThemeProvider attribute="class"` sets it on `<html>`. Do not implement dark mode with `dark:` utilities on kit components.
+
+## Tailwind in the consumer project
+
+The kit CSS is precompiled; the project does **not** need Tailwind to use the components. It needs Tailwind configuration only so *its own* utilities (`bg-primary`, `font-display`, `rounded-lg`) resolve to kit tokens. See [theming.md](./theming.md#using-tokens-in-project-utilities) for the v4 and v3 snippets.
+
+The kit already ships Tailwind's preflight. With Tailwind v3 in the project this means preflight runs twice — harmless — but do not disable the kit's base layer.
+
+## Next.js App Router (`isRSC: true`)
+
+The bundle has no `"use client"` directive. Import kit components from client components:
+
+```tsx
+'use client'
+import { Button, Dialog, DialogContent, DialogTitle, DialogTrigger } from '@hubbiparts/uikit'
+```
+
+Server components may render purely presentational kit components (`Card`, `Badge`, `Separator`) only if they do not pass handlers; when in doubt, add `'use client'` to the file.
+
+## Setup verification
+
+1. `npx hubbiparts-uikit info --json` → `styleImportedIn` not null, `installedVersion` set.
+2. Render a `Button` and a `Dialog`: button is HubbiParts blue (`#1E3F9E` light), dialog overlays correctly.
+3. Toggle `.dark` on `<html>`: surfaces and text switch without any extra class.

package/skills/hubbiparts-uikit/rules/theming.md

@@ -0,0 +1,135 @@
+# Theming & Styling
+
+The brand is encoded in CSS variables shipped by `@hubbiparts/uikit/style.css`. Consumers **use** tokens; they never redefine the brand.
+
+## HubbiParts tokens
+
+| Role                    | Token (use this)                               | Value (reference only)          |
+| ----------------------- | ---------------------------------------------- | ------------------------------- |
+| Primary                 | `bg-primary` / `text-primary-foreground`       | `#1E3F9E` (light), lighter in dark |
+| Secondary brand blue    | `--blue-400`                                   | `#576DB5`                       |
+| Surfaces                | `bg-background`, `bg-card`, `bg-popover`, `bg-muted` | steel-blue neutrals        |
+| Text                    | `text-foreground`, `text-muted-foreground`     |                                 |
+| Borders / focus         | `border-border`, `border-input`, `ring-ring`   |                                 |
+| Danger                  | `destructive` variants, `text-destructive`     |                                 |
+| Charts                  | `var(--chart-1)` … `var(--chart-5)`            |                                 |
+| Sidebar                 | `bg-sidebar`, `text-sidebar-foreground`, …     |                                 |
+| Radius                  | `rounded-sm` … `rounded-2xl` (squircle-like brand radii) | `lg` = 16px           |
+| Fonts                   | `font-display`, `font-sans`, `font-mono`       | Space Grotesk / Inter / Space Mono |
+
+The hex values are for recognition only. **Never write them in code.**
+
+```tsx
+// Correct
+<span className="text-muted-foreground">Updated</span>
+<Badge variant="secondary">In stock</Badge>
+
+// Incorrect
+<span className="text-[#6B7A99]">Updated</span>
+<span className="bg-green-100 text-green-700">In stock</span>
+```
+
+## Typography
+
+- Headings, big numbers, hero text: `font-display`.
+- Interface copy, labels, tables: `font-sans` (default).
+- SKUs, plates, VINs, part numbers, codes: `font-mono`.
+
+## Styling rules
+
+- `className` on kit components is for **layout**: width, margin, grid/flex placement, `max-w-*`. Not for colors, font sizes or borders.
+- Stacks: `flex flex-col gap-4`, never `space-y-4`. Rows: `flex items-center gap-2`.
+- Squares: `size-10`, not `w-10 h-10`.
+- Ellipsis: `truncate`.
+- Conditional classes: `cn()` from the kit, not template-literal ternaries.
+- Dark mode: tokens handle it. No `dark:bg-*` / `dark:text-*` on kit components.
+- Overlays manage stacking. No `z-*` on `DialogContent`, `PopoverContent`, etc.
+
+## Using tokens in project utilities
+
+The kit CSS contains only utilities the kit itself uses. For the project's own markup to use `bg-primary`, `font-display`, etc., its Tailwind must map to the kit variables.
+
+### Tailwind v4 (`tailwind.major === 4`)
+
+```css
+/* src/index.css — after `@import "tailwindcss";` */
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --font-sans: var(--font-body-family);
+  --font-display: var(--font-display-family);
+  --font-mono: var(--font-mono-family);
+  --radius-sm: var(--radius-sm-brand);
+  --radius-md: var(--radius-md-brand);
+  --radius-lg: var(--radius-lg-brand);
+  --radius-xl: var(--radius-xl-brand);
+  --radius-2xl: var(--radius-2xl-brand);
+}
+```
+
+### Tailwind v3 (`tailwind.major === 3`)
+
+```js
+// tailwind.config.js
+export default {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: {
+        background: 'var(--background)',
+        foreground: 'var(--foreground)',
+        card: { DEFAULT: 'var(--card)', foreground: 'var(--card-foreground)' },
+        popover: { DEFAULT: 'var(--popover)', foreground: 'var(--popover-foreground)' },
+        primary: { DEFAULT: 'var(--primary)', foreground: 'var(--primary-foreground)' },
+        secondary: { DEFAULT: 'var(--secondary)', foreground: 'var(--secondary-foreground)' },
+        muted: { DEFAULT: 'var(--muted)', foreground: 'var(--muted-foreground)' },
+        accent: { DEFAULT: 'var(--accent)', foreground: 'var(--accent-foreground)' },
+        destructive: 'var(--destructive)',
+        border: 'var(--border)',
+        input: 'var(--input)',
+        ring: 'var(--ring)',
+      },
+      fontFamily: {
+        sans: 'var(--font-body-family)',
+        display: 'var(--font-display-family)',
+        mono: 'var(--font-mono-family)',
+      },
+      borderRadius: {
+        sm: 'var(--radius-sm-brand)',
+        md: 'var(--radius-md-brand)',
+        lg: 'var(--radius-lg-brand)',
+        xl: 'var(--radius-xl-brand)',
+        '2xl': 'var(--radius-2xl-brand)',
+      },
+    },
+  },
+}
+```
+
+Opacity modifiers (`bg-primary/50`) need `color-mix`-capable values in v3; prefer the kit's variants over opacity tricks.
+
+### No Tailwind (`tailwind.major === null`)
+
+Use the variables directly in CSS modules: `color: var(--muted-foreground)`.
+
+## Changing the brand
+
+Token or font changes belong in the kit's `src/index.css` and ship as a new kit version ([contributing.md](./contributing.md)). A consumer redefining `--primary` forks the design system — do it only when the user explicitly asks for a local theme, and scope it to a wrapper class, never `:root`.