@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/frontend/application/.claude/skills/layout-design-system/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: layout-design-system
+description: >
+  Design system for evaluating and composing dashboard layouts, data tables, forms, and page
+  structure. Provides spacing rules, visual hierarchy principles, and density guidelines to achieve
+  clean, breathable interfaces that maximize data consumption without visual stress. Trigger: When
+  reviewing UI layout, adjusting spacing, designing new pages, evaluating visual balance, or
+  composing dashboard/form layouts.
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+---
+
+## When to Use
+
+- Reviewing or adjusting spacing in a page layout
+- Creating a new list/table view, form, or dashboard page
+- Evaluating visual balance and breathing room
+- User asks about spacing, padding, margins, or visual density
+- Composing page sections (header, toolbar, content, pagination)
+- Comparing layout against reference designs (e.g., Spartan dashboard)
+
+---
+
+## Core Philosophy
+
+> Clean dashboards that let you consume maximum information in a single glance, without feeling
+> visual stress.
+
+Every spacing decision serves two goals simultaneously:
+
+1. **Breathing room** -- elements need air to be scannable
+2. **Data density** -- wasted space means more scrolling and less information per viewport
+
+The sweet spot is **structured density**: tight where repetition creates rhythm (table rows),
+generous where the eye needs anchoring (section transitions).
+
+---
+
+## Spacing Scale
+
+Use Tailwind's spacing scale consistently. These are the approved values for layout composition:
+
+| Token | px  | Use case                                          |
+| ----- | --- | ------------------------------------------------- |
+| `0`   | 0   | Collapsed gaps, flush alignment                   |
+| `0.5` | 2   | Micro adjustments (icon padding)                  |
+| `1`   | 4   | Tight inner padding (compact buttons, cells)      |
+| `2`   | 8   | Default cell padding, inline element spacing      |
+| `3`   | 12  | Section-to-section within a group                 |
+| `4`   | 16  | Content padding, layout container gaps            |
+| `6`   | 24  | Major section separation (title block to content) |
+| `8`   | 32  | Page-level padding, hero spacing                  |
+
+**CRITICAL**: Avoid arbitrary values (`mt-[13px]`). Stay on the scale. If a spacing feels wrong,
+move one step up or down -- don't invent intermediate values.
+
+---
+
+## Page Anatomy
+
+Every data page follows this vertical structure:
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Site Header (breadcrumbs + sidebar trigger)          │  Fixed
+├─────────────────────────────────────────────────────┤
+│ gap-3 (12px)                                        │  Layout gap
+├─────────────────────────────────────────────────────┤
+│ Page Header (title + subtitle + primary action)     │  mb-3 to content
+├─────────────────────────────────────────────────────┤
+│ Toolbar (search + filters + column toggles)         │  space-y-3 group
+├─────────────────────────────────────────────────────┤
+│ Data Table                                          │  Core content
+│   ├─ Sticky header (bg-muted, z-10)                │
+│   ├─ Rows (49px height each)                       │
+│   └─ Scrollable container (max-h-[700px])          │
+├─────────────────────────────────────────────────────┤
+│ Pagination footer                                   │  mt-1 from table
+└─────────────────────────────────────────────────────┘
+```
+
+### Reference spacing values (current implementation)
+
+| Zone                             | Class       | px  |
+| -------------------------------- | ----------- | --- |
+| Layout → content gap             | `gap-3`     | 12  |
+| Content container padding        | `px-6 pb-6` | 24  |
+| Section spacing (within content) | `space-y-3` | 12  |
+| Page header → toolbar separation | `mb-3`      | 12  |
+| Pagination → table separation    | `mt-1`      | 4   |
+
+---
+
+## Data Table Rules
+
+### Row density
+
+| Element       | Height | How achieved                                |
+| ------------- | ------ | ------------------------------------------- |
+| Header row    | 40px   | Default `hlmTh` padding                     |
+| Data row      | 49px   | Cell padding `py-2 pr-0 pl-2` + content     |
+| Action button | 24px   | `class="h-6 w-6 p-0.5"` (not `size="icon"`) |
+
+### Header
+
+- Always sticky: `class="bg-muted sticky top-0 z-10"` on `<thead>`
+- Scrollable container: `max-h-[700px] overflow-auto` on wrapper div
+
+### Cell padding
+
+```
+Data cells:    py-2 pr-0 pl-2   (8px top/bottom, 0 right, 8px left)
+Header cells:  Default hlmTh     (0px top/bottom, 8px left)
+```
+
+This matches the Spartan dashboard reference: `padding: 8px 0px 8px 8px`.
+
+### Column order convention
+
+```
+1. Actions (ellipsis menu)  -- size: 50, enableHiding: false
+2. Select (checkbox)        -- size: 40, enableHiding: false
+3. Primary identifier       -- (name, title, etc.)
+4. Secondary fields         -- (status, type, date, etc.)
+```
+
+Actions go first (leftmost) for quick access. Select follows. Data columns fill the rest.
+
+---
+
+## Pagination Bar
+
+The pagination bar sits below the table and contains three zones:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ [X of Y row(s) selected]   [Rows per page: 10 v]        │
+│                             [Page X of Y]  [« ‹ › »]    │
+└──────────────────────────────────────────────────────────┘
+```
+
+- Left: selection count (`text-muted-foreground text-sm`)
+- Right: page size selector + page indicator + navigation buttons
+- Page sizes: `[5, 10, 20, 10000]` (10000 renders as "All")
+- Navigation: 4 buttons (first, prev, next, last) with `size="icon-sm"` and `variant="outline"`
+
+---
+
+## Toolbar Rules
+
+The toolbar row contains search/filter inputs and action buttons:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ [Filter by name...]                [Customize Columns v] │
+└──────────────────────────────────────────────────────────┘
+```
+
+- Layout: `flex items-center justify-between gap-2`
+- Input: `w-full md:w-80` (responsive, caps at 320px)
+- Customize Columns button: `variant="outline" size="sm"` with `lucideColumns2` +
+  `lucideChevronDown`
+- No vertical padding on the toolbar div itself -- let `space-y-3` handle it
+
+---
+
+## Button Sizing Guide
+
+| Context                | Size      | Notes                                  |
+| ---------------------- | --------- | -------------------------------------- |
+| Primary page action    | default   | "New Tag", "Save"                      |
+| Toolbar actions        | `sm`      | "Customize Columns", "Export"          |
+| Pagination navigation  | `icon-sm` | Chevron buttons                        |
+| Row actions (ellipsis) | custom    | `h-6 w-6 p-0.5` with `variant="ghost"` |
+| Dialog actions         | default   | "Cancel", "Delete"                     |
+
+---
+
+## Visual Hierarchy Checklist
+
+When evaluating a page layout, check these in order:
+
+### 1. Vertical rhythm
+
+- [ ] Is there a consistent spacing scale? (no jumps from 4px to 32px)
+- [ ] Does each section boundary use the same gap?
+- [ ] Is the title block clearly separated from the toolbar?
+
+### 2. Breathing room
+
+- [ ] Does the page header have enough air above it? (min 12px from site header)
+- [ ] Is there space between the toolbar and the table? (12px)
+- [ ] Does the pagination have a slight separation from the table? (4px extra via mt-1)
+
+### 3. Data density
+
+- [ ] Are table rows compact enough? (49px target)
+- [ ] Is the action button small enough to not dominate? (24px, not 36px)
+- [ ] Can you see 10+ rows without scrolling on a standard viewport?
+
+### 4. Horizontal balance
+
+- [ ] Left-aligned content (titles, names) vs right-aligned actions (buttons)?
+- [ ] Does the toolbar stretch edge to edge with content at both ends?
+- [ ] Are column widths proportional to their content?
+
+### 5. Visual weight
+
+- [ ] Is the primary action (New Tag) the heaviest element? (filled button)
+- [ ] Are secondary actions lighter? (outline/ghost variants)
+- [ ] Does the header row (`bg-muted`) create a subtle but clear boundary?
+
+### 6. Stress test
+
+- [ ] With 20+ rows, does the page still feel scannable?
+- [ ] With long text in cells, does truncation or wrapping behave correctly?
+- [ ] With all columns visible, is horizontal scroll manageable?
+
+---
+
+## Form Layout Rules
+
+### Spacing
+
+| Zone                       | Class       | px  |
+| -------------------------- | ----------- | --- |
+| Form section gap           | `space-y-6` | 24  |
+| Field-to-field gap         | `space-y-4` | 16  |
+| Label to input             | `space-y-2` | 8   |
+| Form actions (Save/Cancel) | `mt-6`      | 24  |
+
+### Structure
+
+```
+┌─────────────────────────────────────────────────┐
+│ Section Title                                    │
+│ Section description (muted)                      │
+│                                                  │
+│ [Label]                                          │
+│ [Input field                                   ] │
+│                                                  │
+│ [Label]                                          │
+│ [Input field                                   ] │
+│                                                  │
+│                          [Cancel]  [Save]        │
+└─────────────────────────────────────────────────┘
+```
+
+- Labels: always above inputs (not inline)
+- Full-width inputs by default, use `max-w-md` for short fields (emails, numbers)
+- Action buttons right-aligned in a `flex justify-end gap-2` container
+
+---
+
+## Anti-Patterns
+
+| Problem                            | Why it fails                                          | Fix                              |
+| ---------------------------------- | ----------------------------------------------------- | -------------------------------- |
+| `space-y-6` everywhere             | Uniform large gaps waste viewport                     | Use `space-y-3` for tight groups |
+| `p-6` on content container         | Creates dead space at top when layout already has gap | Use `px-6 pb-6` (no top padding) |
+| `size="icon"` for row actions      | 36px button inflates row height to 53px               | Use `h-6 w-6 p-0.5` (24px)       |
+| Inconsistent section gaps          | 24px here, 8px there -- breaks visual rhythm          | Pick one scale step per zone     |
+| `rounded-full` on toolbar buttons  | Pill shape clashes with standard rounded UI           | Use default border-radius        |
+| Padding on both layout AND content | Double padding creates excessive margins              | One level owns padding, not both |
+
+---
+
+## Theme Variables (CRITICAL)
+
+The Spartan Helm components use CSS custom properties for border-radius. If your theme scopes
+`--radius` inside a class (e.g., `.theme-neutral`), you MUST also define the derived variables in
+the same scope:
+
+```css
+:root .theme-neutral {
+  --radius: 0.625rem;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+```
+
+Without these, Helm components render with `border-radius: 0` because the preset defines the derived
+variables at `:root` level where `--radius` doesn't exist in scoped themes.
+
+---
+
+## Reference Implementation
+
+The tag list (`iam/tag/features/tag-list.component.ts`) is the reference implementation for data
+table pages. When creating new list views, use it as the template for:
+
+- Page structure and spacing
+- Table configuration (columns, sorting, filtering, pagination)
+- Selection column setup
+- Action cell pattern
+- Customize Columns dropdown
+- Delete confirmation dialog
+
+The layout wrapper (`domains/admin/layout/layout.component.ts`) defines the outer spacing:
+
+```html
+<div class="flex flex-1 flex-col gap-3 px-4 pb-4">
+  <router-outlet />
+</div>
+```
+
+Content components should use `px-6 pb-6` (no top padding) to avoid double-padding with the layout.

package/dist/templates/frontend/application/.claude/skills/spartan/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: spartan-ng
+description: "Manages Spartan Angular UI components — adding, searching, composing, styling, and debugging. Provides project context, component docs (Brain/Helm APIs), and usage examples. Applies when working with @spartan-ng packages, Brain/Helm components, or any Angular project with Spartan UI installed. Also triggers for 'nx generate @spartan-ng/cli:ui' or Spartan component imports."
+user-invocable: false
+allowed-tools: Bash(npx nx generate @spartan-ng/cli:ui *), Bash(npx nx generate @spartan-ng/cli:init *), Bash(npm install @spartan-ng/*), Bash(pnpm add @spartan-ng/*), Bash(yarn add @spartan-ng/*)
+---
+
+# Spartan Angular UI
+
+A headless (Brain) + styled (Helm) component library for Angular. Components are installed as npm packages and composed using Angular directives and hostDirectives.
+
+> **IMPORTANT:** Run Nx generators using the project's package runner. Examples use `npx` but substitute the correct runner for the project.
+
+## Principles
+
+1. **Use existing components first.** Use `spartan_search` MCP tool before writing custom UI.
+2. **Choose the right layer.** Use Helm for styled components, Brain for headless/custom styling.
+3. **Compose with hostDirectives.** Don't wrap Brain directives manually; use Angular's hostDirectives.
+4. **Use CVA variants and `hlm()`/`classes()`.** Never override component styles with raw Tailwind classes.
+5. **Use semantic color tokens.** `bg-primary`, `text-muted-foreground` — never `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Brain vs Helm → [brain-helm.md](./rules/brain-helm.md)
+
+- **Use Helm when you want styling.** Brain is for custom-styled or headless use cases.
+- **Never mix Brain selectors and Helm selectors** on the same element.
+- **Helm wraps Brain (or CDK) via hostDirectives.** Don't manually apply Brain directives when using Helm.
+- **Both layers use mixed selector patterns.** Brain: mostly `[brnX]` but some `brn-x`. Helm: `[hlmBtn]`, `hlm-dialog-content`, or both `[hlmCard],hlm-card`.
+- **Some Helm components use CDK directly** (DropdownMenu, ContextMenu, Menubar use `@angular/cdk/menu`).
+
+### Component Composition → [composition.md](./rules/composition.md)
+
+- **Dialog, Sheet, and AlertDialog always need a Title.** For accessibility. Use `class="sr-only"` if visually hidden.
+- **Use full Card composition.** `hlmCardHeader` / `hlmCardTitle` / `hlmCardDescription` / `hlmCardContent` / `hlmCardFooter`.
+- **TabsTrigger inside TabsList.** Never render triggers directly in Tabs.
+- **Avatar needs AvatarFallback.** For when image fails to load.
+- **Use existing components, not custom markup.** Alert for callouts, Separator instead of `<hr>`, Skeleton for loading, Badge instead of styled spans.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **Use `hlm()` for inline class merging, `classes()` for host class management.**
+- **No `space-x-*`/`space-y-*`.** Use `flex` with `gap-*`.
+- **Use `size-*` when width and height are equal.**
+- **No manual `dark:` color overrides.** Use semantic tokens.
+- **No manual `z-index` on overlays.** Components handle stacking.
+- **Use CVA variants before className.** `variant="outline"` not custom classes.
+
+### Forms → [forms.md](./rules/forms.md)
+
+- **Use Angular Reactive Forms.** `FormGroup` + `FormControl`, not template-driven.
+- **Use the HlmField system for form layout.** `HlmField` + `HlmFieldLabel` + `HlmFieldError`.
+- **Use `hlm-field-error` for validation.** Auto-detects state. Not manual `@if` with `text-destructive`.
+- **Use `HlmFieldGroup` for grouping fields**, `HlmFieldSet` + `HlmFieldLegend` for fieldsets.
+- **Use BrnSelect for complex dropdowns, HlmNativeSelect for simple ones.**
+- **Use `hlmTextarea` for textareas** (separate directive, not `hlmInput`).
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Use `ng-icon` with `hlm` directive.** Not raw SVGs or icon fonts.
+- **No manual sizing on icons inside Spartan components.** Components handle sizing via CSS.
+- **Import from `@ng-icons/*`.** Check which icon set the project uses.
+
+### Angular Directives → [directives.md](./rules/directives.md)
+
+- **Use signals for reactive state.** `input()`, `signal()`, `computed()`, `linkedSignal()`.
+- **Standalone is the default.** Angular 19+ — no need to write `standalone: true`.
+- **Use new control flow syntax.** `@if`, `@for`, `@switch` — not `*ngIf`, `*ngFor`.
+- **Use `inject()` for DI.** Not constructor injection.
+- **OnPush change detection.** All Spartan components use OnPush.
+- **Import patterns:** Brain from `@spartan-ng/brain/{name}`, Helm from `@spartan-ng/helm/{name}`, utils from `@spartan-ng/helm/utils`.
+
+## Component Selection
+
+| Need | Component |
+|------|-----------|
+| Button/action | `hlmBtn` directive on `<button>` |
+| Text input | `hlmInput` directive on `<input>` |
+| Textarea | `hlmTextarea` directive on `<textarea>` |
+| Select dropdown | `BrnSelect` + `HlmSelect*` directives |
+| Native select | `HlmNativeSelect` on `<select>` |
+| Combobox/autocomplete | `BrnCombobox` / `BrnAutocomplete` |
+| Checkbox | `BrnCheckbox` / `HlmCheckbox` |
+| Radio group | `BrnRadioGroup` / `HlmRadioGroup` |
+| Switch/toggle | `BrnSwitch` / `HlmSwitch` |
+| Slider | `BrnSlider` / `HlmSlider` |
+| Form field layout | `HlmField` + `HlmFieldLabel` + `HlmFieldError` |
+| Data display | `HlmTable*`, `HlmBadge`, `HlmAvatar*`, `HlmCarousel*` |
+| Navigation | `HlmSidebar*`, `HlmTabs*`, `HlmBreadcrumb*`, `HlmPagination*` |
+| Dialog (modal) | `BrnDialog` + `HlmDialog*` |
+| Sheet (side panel) | `BrnSheet` + `HlmSheet*` |
+| Alert dialog | `BrnAlertDialog` + `HlmAlertDialog*` |
+| Dropdown menu | `HlmDropdownMenu*` (wraps CDK, no Brain) |
+| Context menu | `HlmContextMenu*` (wraps CDK, no Brain) |
+| Feedback | `HlmAlert*`, `HlmProgress`, `HlmSkeleton`, `HlmSpinner`, `HlmToaster` |
+| Command palette | `BrnCommand` inside `BrnDialog` |
+| Layout | `hlmCard*`, `HlmSeparator`, `BrnAccordion*`, `BrnCollapsible*`, `HlmScrollArea` |
+| Tooltip/info | `BrnTooltip` / `BrnHoverCard` / `BrnPopover` |
+| Empty states | `HlmEmpty*` |
+| Typography | `HlmH1`, `HlmP`, `HlmKbd`, `ng-icon[hlm]` |
+
+## Workflow
+
+1. **Get project context** — use `spartan_project_info` MCP tool
+2. **Check installed components** — use `spartan_project_components` MCP tool
+3. **Find components** — use `spartan_search` MCP tool
+4. **Get docs and examples** — use `spartan_view` MCP tool
+5. **Check dependencies** — use `spartan_dependencies` MCP tool
+6. **Get source code if needed** — use `spartan_source` MCP tool
+7. **Install** — use `spartan_install_command` MCP tool, then run the command
+8. **Verify installation** — use `spartan_audit` MCP tool
+9. **Review code against rules** — check Brain/Helm usage, composition, styling
+
+## Detailed References
+
+- [rules/brain-helm.md](./rules/brain-helm.md) — Brain vs Helm layer selection, CDK-based components
+- [rules/composition.md](./rules/composition.md) — Component structure, Dialog/Card/Tabs patterns
+- [rules/styling.md](./rules/styling.md) — Tailwind, CVA, `hlm()`, `classes()`, semantic tokens
+- [rules/forms.md](./rules/forms.md) — HlmField system, Angular Reactive Forms, form controls
+- [rules/icons.md](./rules/icons.md) — ng-icon patterns, icon sizing
+- [rules/directives.md](./rules/directives.md) — Signals, standalone, OnPush, control flow, `inject()`
+- [cli.md](./cli.md) — Nx generators, migration tools
+- [customization.md](./customization.md) — Theming, CSS variables, Spartan Tailwind preset
+- [mcp.md](./mcp.md) — MCP server tools documentation

package/dist/templates/frontend/application/.claude/skills/spartan/cli.md

@@ -0,0 +1,82 @@
+# Spartan CLI / Nx Generators Reference
+
+## Component Installation
+
+### Via Nx Generator (recommended)
+
+```bash
+npx nx generate @spartan-ng/cli:ui --name=dialog
+npx nx generate @spartan-ng/cli:ui --name=button,card,dialog
+npx nx generate @spartan-ng/cli:ui  # interactive picker
+```
+
+### Via npm (manual)
+
+```bash
+# Install both Brain and Helm
+npm install @spartan-ng/brain/dialog @spartan-ng/helm/dialog
+
+# Brain only (headless)
+npm install @spartan-ng/brain/dialog
+
+# Helm only (requires Brain as peer dependency)
+npm install @spartan-ng/helm/dialog
+```
+
+## Project Setup
+
+### Initialize Spartan in a project
+
+```bash
+npx nx generate @spartan-ng/cli:init
+```
+
+### Health check
+
+```bash
+npx nx generate @spartan-ng/cli:healthcheck
+```
+
+### Add theme
+
+```bash
+npx nx generate @spartan-ng/cli:ui-theme
+```
+
+## Migration Generators
+
+Run these when upgrading Spartan versions:
+
+| Generator | Purpose |
+|-----------|---------|
+| `migrate-brain-imports` | Update Brain imports to secondary entrypoints |
+| `migrate-helm-imports` | Update Helm imports structure |
+| `migrate-module-imports` | Convert NgModule imports to standalone |
+| `migrate-icon` | Migrate `hlm-icon` to `ng-icon` |
+| `migrate-naming-conventions` | Update to latest naming standards |
+| `migrate-helm-libraries` | Update library versions |
+
+### Running migrations
+
+```bash
+npx nx generate @spartan-ng/cli:migrate-brain-imports
+npx nx generate @spartan-ng/cli:migrate-helm-imports
+npx nx generate @spartan-ng/cli:migrate-module-imports
+npx nx generate @spartan-ng/cli:migrate-icon
+npx nx generate @spartan-ng/cli:migrate-naming-conventions
+```
+
+## Package Naming
+
+| Scope | Pattern | Example |
+|-------|---------|---------|
+| Brain | `@spartan-ng/brain/{name}` | `@spartan-ng/brain/dialog` |
+| Helm | `@spartan-ng/helm/{name}` | `@spartan-ng/helm/dialog` |
+| Utils | `@spartan-ng/helm/utils` | `hlm()`, `classes()` |
+| CLI | `@spartan-ng/cli` | Nx generators |
+
+## Important Notes
+
+- The Nx generator handles both Brain and Helm layers, peer dependencies, and Tailwind preset configuration automatically.
+- When installing manually, ensure `@angular/cdk` is installed and the Spartan Tailwind preset is configured.
+- Use `spartan_install_command` MCP tool to generate the correct command for your project's package manager.

package/dist/templates/frontend/application/.claude/skills/spartan/customization.md

@@ -0,0 +1,99 @@
+# Theming & Customization
+
+## How It Works
+
+1. CSS variables defined in `:root` (light) and `.dark` (dark mode)
+2. Spartan's Tailwind preset maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
+3. Helm components use these utilities — changing a variable changes all components
+
+## Tailwind Preset Setup
+
+### Tailwind v4
+
+```css
+@import "tailwindcss";
+@plugin "@spartan-ng/brain/hlm-tailwind-preset";
+```
+
+### Tailwind v3
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require('@spartan-ng/brain/hlm-tailwind-preset')],
+}
+```
+
+## Color Variables (OKLCH)
+
+| Variable | Purpose |
+|----------|---------|
+| `--background` / `--foreground` | Page background and default text |
+| `--card` / `--card-foreground` | Card surfaces |
+| `--primary` / `--primary-foreground` | Primary buttons and actions |
+| `--secondary` / `--secondary-foreground` | Secondary actions |
+| `--muted` / `--muted-foreground` | Muted/disabled states |
+| `--accent` / `--accent-foreground` | Hover and accent states |
+| `--destructive` / `--destructive-foreground` | Error and destructive actions |
+| `--border` | Default border color |
+| `--input` | Form input borders |
+| `--ring` | Focus ring color |
+| `--sidebar-*` | Sidebar-specific colors |
+
+Colors use OKLCH format: `oklch(lightness chroma hue)`.
+
+## Adding Custom Colors
+
+Always add to the project's global CSS file. Never create new CSS files.
+
+```css
+:root {
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
+}
+```
+
+For Tailwind v4, register with `@theme inline`:
+
+```css
+@theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+```
+
+For Tailwind v3, register in `tailwind.config.js`:
+
+```js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        warning: "oklch(var(--warning) / <alpha-value>)",
+        "warning-foreground": "oklch(var(--warning-foreground) / <alpha-value>)",
+      },
+    },
+  },
+}
+```
+
+## Customizing Components
+
+Priority order:
+
+1. **CVA variants** — `variant="outline"`, `size="sm"`
+2. **`hlm()` / `classes()`** — layout classes only, not colors
+3. **CSS variables** — define custom tokens in global CSS
+4. **Wrapper components** — compose Spartan primitives into higher-level components
+
+## Dark Mode
+
+Class-based toggle via `.dark` on the root element. Semantic tokens handle light/dark automatically — never write manual `dark:` overrides.
+
+## Border Radius
+
+`--radius` controls border radius globally. Components derive from it. Change in global CSS to affect all components.