admin-ui-starter-kit 0.4.5 → 0.6.1

package/.agents/skills/component-library-rules/references/components/docs__design-system-consistency.md

@@ -0,0 +1,413 @@
+---
+id: docs/design-system-consistency
+title: "Design system consistency guide"
+description: "The operating manual for keeping the package cohesive: goals, ownership, token rules, drift detection, and browser-quality review."
+layer: docs
+family: "Start here"
+sourcePath: src/components + src/css + src/preview
+examples:
+imports:
+tags:
+  - docs
+  - start
+  - here
+  - preview
+  - design
+  - system
+  - consistency
+  - guide
+---
+
+# Design system consistency guide
+
+The operating manual for keeping the package cohesive: goals, ownership, token rules, drift detection, and browser-quality review.
+
+**Layer:** `docs`
+**Source:** `src/components + src/css + src/preview`
+
+## Purpose
+
+This package is a publishable React admin component library. The showcase is not
+marketing chrome. It is the working inspection surface for the package: every
+public component should have a route, realistic examples, exact import
+documentation, generated props, and a visual state that proves the component can
+ship.
+
+The goal of a polish pass is not to make one screenshot acceptable. The goal is
+to make the underlying component system harder to drift. If an example looks
+wrong, first assume the package component, token, API, or docs source is wrong.
+Only patch the preview when the preview is genuinely misusing the public API.
+
+## Product Goals
+
+The package has five non-negotiable goals:
+
+- Centralize shadcn primitives behind package-owned wrappers so consumers import
+  stable public subpaths.
+- Stay framework-neutral: no routing, i18n SDKs, query libraries, backend
+  clients, or app ambient types inside library components.
+- Make complex surfaces composable through callbacks, slots, render props,
+  accessors, exported partials, and headless hooks.
+- Let consumers tune the whole visual system through CSS variables and the
+  single `UIProvider`, not repeated one-off class strings.
+- Keep the admin voice calm, dense, readable, and professional: rich enough to
+  use all day, never decorative for its own sake.
+
+Success means a downstream app can upgrade the package and receive better
+spacing, state handling, docs, and behavior without rewriting its own UI glue.
+
+## Layer Ownership
+
+Every visual or API change starts by identifying the owner:
+
+- `src/components/ui`: shadcn primitives. Do not edit for package styling.
+- `src/components/typography`: text primitives. They are peer to `base`, not
+  children of it.
+- `src/components/base`: package wrappers and focused primitives, such as
+  buttons, cards, item rows, forms, combobox, table, badge, metadata, and
+  display utilities.
+- `src/components/layout`: app shell primitives built from base and typography.
+  They do not import composed or feature components.
+- `src/components/composed`: reusable domain surfaces built from base:
+  commerce rows, AI cards, admin rows, timelines, dense information blocks.
+- `src/components/features`: app-level workflows. They can compose base and
+  composed surfaces, but behavior is callback-driven and strings are
+  overrideable.
+- `src/preview`: documentation and examples only. Examples demonstrate real
+  components; they do not hide package defects behind private JSX.
+
+The preferred fix order is: component API, component token, component
+composition, preview usage. Reversing that order creates visual demos that look
+fine while the package remains inconsistent.
+
+## Design Voice
+
+The library is an admin/SaaS system. It should feel quiet, utilitarian, and
+precise:
+
+- Primary body, row, and card text defaults to `sm`.
+- Secondary labels, descriptions, metadata, and helper text use `xs`.
+- Eyebrows, counts, and dense metadata can use `xxs`.
+- `text-base` is reserved for true page or hero values, not row/card titles.
+- Titles inside cards and rows are normally semibold, not oversized.
+- Labels should be medium or semibold when they name a value, never accidental
+  plain body text.
+- Rows need enough internal padding to be readable. Dense does not mean
+  vertically starved.
+- Row primitives keep their own balanced padding. Do not strip `Item` rows with
+  local `px-0` / `py-*` classes to make a card align; adjust the parent section
+  or card spacing.
+- Similar surfaces should share heights, x padding, y padding, icon size,
+  radius, border treatment, and focus state unless their API deliberately
+  differentiates them.
+- Active states should read as selected state, not as a raised card unless the
+  component is actually a card.
+
+When reviewing visuals, compare siblings side by side. A combobox option, menu
+item, select trigger, table row, metadata row, and item row do not need identical
+markup, but their density should feel like one system.
+
+## Token System
+
+The design system is controlled from CSS variables, then consumed through
+Tailwind aliases and base components.
+
+Core token families:
+
+- Theme palette and shadcn-compatible color tokens live in
+  `src/css/themes/shadcn.default.css`.
+- Structural typography scale, spacing, density, control sizes, row rhythm,
+  surface padding, media sizing, shell dimensions, state extensions, and the
+  Tailwind utility aliases generated from them live in `src/css/tokens/*`.
+- Tailwind utility aliases are mapped through `@theme inline`.
+- Runtime defaults that are not pure CSS live in `UIProvider`, such as default
+  badge size, button defaults, card padding, locale-ish display defaults, and
+  table density.
+
+Use a variable when a value needs to stay consistent across a family or be
+theme-tunable by consumers. Do not add variables to avoid making a design
+decision. A new variable should have a comment, a clear owner, and at least one
+real component usage.
+
+Controls should converge around shared structural tokens:
+
+- Buttons, inputs, select triggers, combobox triggers, popover triggers, menu
+  triggers, and tag inputs should share `--control-height*` and
+  `--control-x*`.
+- Rich option rows, command rows, global-search rows, filter rows, table rows,
+  and combobox options should use the shared `--row-*` rhythm.
+- Cards, empty states, form sections, and feature panels should use
+  `--surface-*` plus the `--space-*` scale for internal regions.
+- Icons and avatars should use `--icon*` and `--avatar*`; raw fixed sizes are
+  reserved for illustrations, maps, charts, and intentionally fixed artwork.
+- Do not reintroduce component-family aliases for action controls, cards,
+  tables, headers, app shells, or component-specific text roles.
+- Compact modes are explicit. The normal mode should be readable without
+  looking inflated.
+
+## Component API Rules
+
+Public APIs must make good usage easy and bad usage obvious:
+
+- Prefer defaults from the component and `UIProvider`; avoid exposing many size
+  choices just because the primitive can.
+- Keep size APIs narrow. For most action controls, default and small are enough.
+  Repeated `xs`, `sm`, `md`, `lg`, `compact`, and `dense` variants are a drift
+  smell unless they map to a real component contract.
+- Components with user-facing strings export `*Strings`,
+  `default*Strings`, and accept `strings` merged by `useStrings`.
+- Async features expose `fetcher`, `onError`, and lifecycle callbacks rather
+  than importing a query library.
+- Workflows expose `onSubmit`, `onSelect`, `onAfterMutate`, `onOpenChange`, and
+  similar callback seams.
+- Consumer-owned data shapes are handled through accessors, render props, or
+  generics.
+- Complex features expose slots and partials when consumers need to replace a
+  region without forking.
+- Public roots include stable BEM hooks like `combobox--component`, plus
+  meaningful subregion hooks when tests or consumers need them.
+
+If a preview needs a 100-line local mock to demonstrate a component, the
+component probably needs a better public seam.
+
+## Drift Detection
+
+Run static checks before and after visual work. They catch classes of drift that
+screenshots miss.
+
+Required broad checks:
+
+```bash
+npm run lint:architecture
+npm run quality:smells
+npm run test:exports
+npm run docs:check-feature-parity
+npm run docs:check-props
+npm run docs:sync-skill -- --check
+npm run docs:check-scripts
+npm run typecheck
+npm run lint
+```
+
+Release-grade checks:
+
+```bash
+npm run verify
+npm run build:lib
+npm run test:dist-assets
+npm run build:showcase
+npm run test:package-smoke:check
+npm run test:browser:features
+npm run test:a11y:features
+npm run test:visual:features
+git diff --check
+```
+
+Targeted code searches for touched areas:
+
+```bash
+rg "text-\\[|text-foreground/|focus:|bg-primary/" src/components src/preview
+rg "text-(orange|red|green|blue|yellow|amber)-|bg-(orange|red|green|blue|yellow|amber)-" src/components src/preview
+rg "@/components/ui/" src/components src/preview
+rg "console\\.(warn|error|log)" src/components src/services src/lib
+rg "react-router|next/|@inertiajs|@tanstack/react-query|ziggy-js|navigator.language" src/components
+```
+
+Treat script output as triage, not proof. A route can pass every static check
+and still look wrong because the rhythm, hierarchy, or state treatment drifted.
+
+## Code Review Loop
+
+Use this loop for every component pass:
+
+1. Read the owning component, types, strings, hooks, partials, index export,
+   tests, MDX page, examples file, and neighboring components in the same
+   family.
+2. Identify whether the problem belongs to tokens, base wrappers, composed
+   surfaces, features, layout, or preview docs.
+3. Patch the smallest responsible layer.
+4. Add or update tests when behavior, controlled state, callbacks, async
+   flows, errors, slots, or provider resolution are involved.
+5. Regenerate docs only when API surfaces changed.
+6. Recheck the exact route and the sibling routes that share the same
+   component family.
+7. Run focused checks first, then broad checks.
+
+Do not declare a component family clean after checking one example at the top of
+one route. Scroll top, middle, and bottom. Open interactive states. Compare
+equivalent examples.
+
+## Playwright Visual QA
+
+Playwright is the repeatable gate. It should run against registered routes, not
+hand-written memory lists.
+
+Route discovery starts here:
+
+```bash
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs --section Base
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs --scope base/combobox
+```
+
+The showcase browser spec uses `readyRoutes()` from `tests/showcase/registry.ts`
+so the runtime/layout gate covers every registered `ready` route. Scope route
+health assertions to `main.preview-shell--content`; layout examples can contain
+their own nested semantic `<main>` landmarks.
+
+For each selected route, Playwright checks should:
+
+- Open the route on desktop `1440x900`.
+- Open the route on mobile `390x844`.
+- Wait for fonts, lazy imports, and async demo data to settle.
+- Fail on console errors and Vite/runtime overlays.
+- Fail on blank renders.
+- Fail on horizontal overflow.
+- Check main content is visible.
+- Scroll top, middle, and bottom.
+- Exercise interactive examples: open comboboxes, popovers, menus, dialogs,
+  drawers, tabs, selection states, submit paths, empty states, loading states,
+  and error states where the route exposes them.
+- Capture screenshots for changed or suspicious pages.
+
+Useful Playwright assertions include computed style checks for height, padding,
+font size, overflow, active state color, visible option count, row alignment,
+and whether a scroll viewport exists where long content needs one.
+
+Visual baselines should be updated only when the change is intentional and the
+reviewer has inspected the before/after.
+
+## Browser Plugin QA
+
+The in-app Browser skill is the human-grade visual check. Use it when a change
+is visual, interactive, or documentation-facing.
+
+Browser pass checklist:
+
+- Open the running showcase route in the in-app Browser.
+- Inspect desktop first, then mobile or narrow viewport.
+- Use the actual UI: click, type, open, select, close, submit, cancel, and
+  trigger the visible states.
+- Read the visible page state after every interaction. Use DOM snapshots for
+  structure and screenshots for spacing, color, balance, and hierarchy.
+- Check console errors and runtime overlays.
+- Scroll through the full page. Problems often appear below the first demo.
+- Capture screenshots for changed routes and defect reports.
+
+Use Browser for qualitative questions:
+
+- Does the page feel balanced?
+- Are labels aligned with values?
+- Does the icon column displace the title?
+- Does the option padding feel equal vertically and horizontally?
+- Are sidebars stable while scrolling?
+- Does the component look like the rest of the library?
+
+If the Browser plugin is unavailable, say so explicitly and run the equivalent
+local Playwright pass. Do not call visual work complete without some browser
+surface proving the rendered result.
+
+## Manual Visual Rubric
+
+Before calling a visual pass done, answer these questions with the page open:
+
+1. Spacing breathes: nothing is cramped, smashed, or separated by ornamental
+   gaps.
+2. Typography reads in a clear hierarchy: title, label, body, helper, metadata,
+   and count each have the right weight and size.
+3. Equivalent controls match: button, input, select, combobox trigger, menu
+   trigger, tag input, and form controls share predictable height and padding.
+4. Equivalent rows match: item rows, command rows, combobox options, table rows,
+   metadata rows, and global-search rows feel related.
+5. States are intentional: hover, active, focus-visible, disabled, loading,
+   error, selected, and destructive states are visible and calm.
+6. Colors are semantic, not random raw hues.
+7. Cards have enough padding, but not nested-card clutter.
+8. Tables have readable cell padding, stable row height, no accidental
+   truncation, and compact mode is intentionally smaller.
+9. Sidebars and page shells own their scroll contract. Consumers should not
+   patch layout with ad hoc height calculations and overflow classes.
+10. A designer cannot point to an obvious defect in three seconds.
+
+Any "no" means the pass is not done.
+
+## Docs And Showcase Parity
+
+Every public surface needs:
+
+- Exact package export.
+- Registered preview route.
+- MDX page with a clear purpose.
+- Examples using real library components.
+- Generated props table when the component has public props.
+- Source path and public import guidance.
+- Skill metadata synced by `npm run docs:sync-skill`.
+
+Docs pages are part of the product. Their tables, examples, search controls,
+sidebars, and "on this page" rail need the same typography and spacing review as
+components. A bad docs page is usually one of two problems: docs chrome is
+under-designed, or the example is exposing a real component defect.
+
+## Fix Ownership Examples
+
+Use these ownership decisions during review:
+
+- Combobox option padding is a `base/combobox` and token problem, not a single
+  example problem.
+- Card title weight is a `SmartCard` usage or composed-card title path problem,
+  not a docs route problem.
+- Global search row density belongs in `features/global-search` partials and
+  shared row tokens.
+- Sidebar scroll and active styling belong in `layout/sidebar` and its base
+  sidebar primitives.
+- Table cell padding and compact mode belong in `base/table`.
+- Preview route labels and sidebar grouping belong in `src/preview/registry.tsx`
+  and preview navigation, not component code.
+- API tables and props formatting belong in `src/preview/_docs`.
+
+If a defect appears in multiple routes, stop patching individual examples and
+move the fix down to the shared component or token.
+
+## Reporting Template
+
+Final reports should be concrete:
+
+- Components and files changed.
+- Routes visually inspected.
+- Viewports checked.
+- Interactive states exercised.
+- Tests added or updated.
+- Exact commands run and whether they passed.
+- Browser plugin result or Playwright fallback.
+- Remaining risks or routes not covered.
+
+Good report shape:
+
+```text
+Changed:
+- Base combobox option rhythm now uses the shared menu row spacing tokens.
+- AI cards route titles through SmartCard title/icon and medium labels.
+- Item rows no longer use local zero-padding overrides in composed, feature, or
+  layout surfaces.
+
+Visual QA:
+- Routes: all registered ready preview routes.
+- Viewports: 1440x900 and 390x844.
+- Interactions: opened single/multiple/grouped comboboxes; checked option
+  padding, scroll viewport, active row, AI card hierarchy, and row padding
+  metrics.
+
+Validation:
+- npm run verify: passed.
+- npm run build:lib: passed.
+- npm run build:showcase: passed.
+- git diff --check: passed.
+
+Residual risk:
+- Full feature visual baseline was not updated because this was a focused
+  component patch.
+```
+
+Do not say "perfect" unless the route list, visual states, static checks, and
+functional tests back it up.
+

package/.agents/skills/component-library-rules/references/components/docs__installation.md

@@ -0,0 +1,221 @@
+---
+id: docs/installation
+title: "Installation"
+description: "Install the package, import the stylesheet, and consume exact public subpaths."
+layer: docs
+family: "Start here"
+sourcePath: README.md
+examples:
+  - InstallCommand
+  - RequiredSteps
+  - ImportRecipe
+  - OptionalPeers
+  - MaintainerChecks
+  - NextLinks
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/base/display
+  - @/components/typography
+tags:
+  - docs
+  - start
+  - here
+  - readme.md
+  - installation
+  - install
+  - package
+  - import
+---
+
+# Installation
+
+Install the package, import the stylesheet, and consume exact public subpaths.
+
+**Layer:** `docs`
+**Source:** `README.md`
+
+## Install
+
+<Example name="InstallCommand" source={examplesSource} layout="flush">
+	<Examples.InstallCommand />
+</Example>
+
+<Example name="RequiredSteps" source={examplesSource} layout="flush">
+	<Examples.RequiredSteps />
+</Example>
+
+## Imports
+
+<Example name="ImportRecipe" source={examplesSource} layout="flush">
+	<Examples.ImportRecipe />
+</Example>
+
+Exact subpaths are part of the public contract. The root entrypoint intentionally
+stays small; component families are imported from `base/*`, `composed/*`,
+`features/*`, or `layout/*` public paths.
+
+## Optional Peers
+
+<Example name="OptionalPeers" source={examplesSource} layout="flush">
+	<Examples.OptionalPeers />
+</Example>
+
+Only install optional peers for surfaces your app renders. The library remains
+framework-neutral; routing, mutations, query clients, and i18n systems stay in
+the consuming app.
+
+## Verification
+
+<Example name="MaintainerChecks" source={examplesSource} layout="flush">
+	<Examples.MaintainerChecks />
+</Example>
+
+<Example name="NextLinks" source={examplesSource} layout="center">
+	<Examples.NextLinks />
+</Example>
+
+## Examples
+
+```tsx
+import {
+	ClipboardCheck,
+	PackageOpen,
+	Plug,
+	TerminalSquare,
+	Wrench } from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { IconBadge,
+} from '@/components/base/display';
+import { Text } from '@/components/typography';
+
+const REQUIRED_STEPS = [
+	['Package', 'Install the library plus React, Tailwind, and icon peers used by the base layer.'],
+	['Stylesheet', 'Import the package stylesheet once in the application entry.'],
+	['Provider', 'Wrap the app in UIProvider when you want centralized display defaults.'],
+	['Imports', 'Use exact package subpaths for every component family.'],
+] as const;
+
+export function InstallCommand() {
+	return (
+		<SmartCard
+			title="Install the package"
+			description="Use the package as a library dependency, not copied source."
+			icon={<IconBadge icon={PackageOpen} tone="primary" shape="square" size="default" />}
+		>
+			<div className="rounded-md bg-muted px-3 py-2 font-mono text-xs text-foreground">
+				npm install admin-ui-starter-kit react react-dom tailwindcss lucide-react
+			</div>
+		</SmartCard>
+	);
+}
+
+export function RequiredSteps() {
+	return (
+		<div className="grid gap-3 md:grid-cols-2">
+			{REQUIRED_STEPS.map(([title, description], index) => (
+				<SmartCard key={title} surface="framed" padding="default">
+					<div className="flex items-start gap-3">
+						<span className="inline-flex size-7 shrink-0 items-center justify-center rounded-md bg-muted text-xs font-semibold text-foreground">{index + 1}</span>
+						<div>
+							<Text weight="semibold">{title}</Text>
+							<Text size="xs" type="secondary" className="mt-1">
+								{description}
+							</Text>
+						</div>
+					</div>
+				</SmartCard>
+			))}
+		</div>
+	);
+}
+
+export function ImportRecipe() {
+	return (
+		<SmartCard
+			title="Exact public imports"
+			description="Do not import raw shadcn primitives or preview files from consuming apps."
+			icon={<IconBadge icon={Plug} tone="info" shape="square" size="default" />}
+		>
+			<div className="grid gap-2 font-mono text-xs text-foreground">
+				<div className="rounded-md bg-muted px-3 py-2">import 'admin-ui-starter-kit/style.css';</div>
+				<div className="rounded-md bg-muted px-3 py-2">import {'{ UIProvider }'} from 'admin-ui-starter-kit/ui-provider';</div>
+				<div className="rounded-md bg-muted px-3 py-2">import {'{ Button }'} from 'admin-ui-starter-kit/base/buttons';</div>
+				<div className="rounded-md bg-muted px-3 py-2">import {'{ GlobalSearch }'} from 'admin-ui-starter-kit/features/global-search';</div>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function OptionalPeers() {
+	return (
+		<SmartCard surface="framed" padding="default">
+			<div className="flex items-start gap-3">
+				<IconBadge icon={Wrench} tone="warning" shape="square" />
+				<div className="min-w-0 space-y-2">
+					<div>
+						<Text weight="semibold">Feature peers stay opt-in</Text>
+						<Text size="xs" type="secondary" className="mt-1">
+							Rich text, charts, maps, drag and drop, and command palettes are installed only when the consuming app uses those surfaces.
+						</Text>
+					</div>
+					<div className="flex flex-wrap gap-2">
+						<Badge variant="secondary">@tiptap/react</Badge>
+						<Badge variant="secondary">recharts</Badge>
+						<Badge variant="secondary">embla-carousel-react</Badge>
+						<Badge variant="secondary">cmdk</Badge>
+					</div>
+				</div>
+			</div>
+		</SmartCard>
+	);
+}
+
+export function MaintainerChecks() {
+	return (
+		<div className="grid gap-3 md:grid-cols-2">
+			<SmartCard
+				title="Consumer install skill"
+				description="Installs the migration guidance into a downstream app."
+				icon={<IconBadge icon={ClipboardCheck} tone="success" shape="square" size="default" />}
+			>
+				<div className="rounded-md bg-muted px-3 py-2 font-mono text-xs text-foreground">npx admin-ui-starter-kit-install-skill</div>
+			</SmartCard>
+			<SmartCard
+				title="Release verification"
+				description="Run package checks before publishing a release."
+				icon={<IconBadge icon={TerminalSquare} tone="warning" shape="square" size="default" />}
+			>
+				<div className="rounded-md bg-muted px-3 py-2 font-mono text-xs text-foreground">npm run verify:release</div>
+			</SmartCard>
+		</div>
+	);
+}
+
+export function NextLinks() {
+	return (
+		<div className="flex flex-wrap gap-2">
+			<Button href="#/base/css-variables" size="default">
+				View CSS variables
+			</Button>
+			<Button href="#/docs/showcase" size="default" buttonStyle="outline">
+				Use the showcase
+			</Button>
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `InstallCommand`
+- `RequiredSteps`
+- `ImportRecipe`
+- `OptionalPeers`
+- `MaintainerChecks`
+- `NextLinks`
+