@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/frontend/application/.agents/skills/spartan/rules/composition.md

@@ -0,0 +1,105 @@
+# Component composition
+
+Most spartan components are made of several directives/components that must be nested correctly.
+Import the per-component `*Imports` const (e.g. `HlmDialogImports`, `HlmCardImports`) and add it to
+your standalone component's `imports`. Always confirm selectors via the docs or MCP before writing
+templates - the examples below are canonical but APIs evolve.
+
+## Items belong inside their group
+
+- `hlm-select-item` goes inside `hlm-select-content` (and optionally `hlm-select-group`).
+- `button[hlmToggleGroupItem]` goes inside `hlm-toggle-group`.
+- `button[hlmTabsTrigger]` goes inside `hlm-tabs-list`.
+- Accordion: `hlm-accordion-trigger` and `hlm-accordion-content` go inside `hlm-accordion-item`,
+  which goes inside `hlm-accordion`.
+
+## Overlays need a title
+
+Dialog, Sheet, and Alert Dialog must have a title for accessibility. If the design hides it, keep it
+present and apply `class="sr-only"`.
+
+```html
+<hlm-dialog>
+	<button hlmDialogTrigger hlmBtn>Edit profile</button>
+	<hlm-dialog-content *hlmDialogPortal class="sm:max-w-[425px]">
+		<hlm-dialog-header>
+			<h3 hlmDialogTitle>Edit profile</h3>
+			<p hlmDialogDescription>Make changes to your profile here.</p>
+		</hlm-dialog-header>
+		<div class="py-4">
+			<input hlmInput placeholder="Name" />
+		</div>
+		<hlm-dialog-footer>
+			<button hlmBtn hlmDialogClose>Save changes</button>
+		</hlm-dialog-footer>
+	</hlm-dialog-content>
+</hlm-dialog>
+```
+
+Sheet mirrors this (`hlmSheetTrigger`, `*hlmSheetPortal`, `hlm-sheet-content`, `hlm-sheet-header`,
+`hlmSheetTitle`). The `side` input (`top | bottom | left | right`) goes on the root `<hlm-sheet>`
+element, not on the content: `<hlm-sheet side="right">`.
+
+## Full Card composition
+
+Use the structural pieces rather than styling a bare `div`.
+
+```html
+<section hlmCard>
+	<div hlmCardHeader>
+		<h3 hlmCardTitle>Create project</h3>
+		<p hlmCardDescription>Deploy in one click.</p>
+	</div>
+	<div hlmCardContent>...</div>
+	<div hlmCardFooter class="justify-between">
+		<button hlmBtn variant="ghost">Cancel</button>
+		<button hlmBtn>Create</button>
+	</div>
+</section>
+```
+
+## Tabs
+
+```html
+<hlm-tabs tab="account">
+	<hlm-tabs-list>
+		<button hlmTabsTrigger="account">Account</button>
+		<button hlmTabsTrigger="password">Password</button>
+	</hlm-tabs-list>
+	<div hlmTabsContent="account">...</div>
+	<div hlmTabsContent="password">...</div>
+</hlm-tabs>
+```
+
+## Avatar always has a fallback
+
+```html
+<hlm-avatar>
+	<img hlmAvatarImage src="/avatar.jpg" alt="Jane Doe" />
+	<span hlmAvatarFallback>JD</span>
+</hlm-avatar>
+```
+
+## Buttons have no loading input
+
+There is no `isLoading`/`isPending` input on `hlmBtn`. Compose a `hlm-spinner` and disable the
+button:
+
+```html
+<button hlmBtn [disabled]="saving()">
+	@if (saving()) {
+	<hlm-spinner />
+	} Save
+</button>
+```
+
+## Use components, not custom markup
+
+- Callouts / inline messages -> `hlmAlert` (with `hlmAlertTitle` / `hlmAlertDescription`).
+- Empty states -> `hlm-empty` (`hlmEmptyMedia`, `hlmEmptyTitle`, `hlmEmptyDescription`).
+- Toasts -> the `sonner` component: place `<hlm-toaster />` once, then call `toast(...)` from
+  `@spartan-ng/brain/sonner` (`toast.success`, `toast.error`, etc.).
+- Dividers -> `hlm-separator`, not `<hr>`.
+- Loading placeholders -> `hlmSkeleton`, not custom pulsing divs.
+- Status pills -> `hlmBadge`, not custom styled spans.
+- Loading indicator -> `hlm-spinner`.

package/dist/templates/frontend/application/.agents/skills/spartan/rules/forms.md

@@ -0,0 +1,113 @@
+# Forms and inputs
+
+spartan/ui composes forms from the `field` component plus the relevant control. It works with
+template-driven forms, reactive forms, and Angular's Signal Forms.
+
+Import the pieces from `@spartan-ng/helm/field` (the `HlmFieldImports` const exports them together)
+and the control from its own entrypoint (e.g. `@spartan-ng/helm/input`).
+
+## Use `hlmField`, not raw `div`s
+
+Wrap each control in `hlmField`. It provides the label, control slot, description, and error
+display, and tracks validation state.
+
+```html
+<div hlmField>
+	<label hlmFieldLabel for="email">Email</label>
+	<input hlmInput id="email" [formControl]="email" />
+	<p hlmFieldDescription>We'll never share your email.</p>
+	@if (email.invalid && email.touched) {
+	<hlm-field-error>Enter a valid email address.</hlm-field-error>
+	}
+</div>
+```
+
+`hlmField` supports `orientation="vertical | horizontal | responsive"`.
+
+## Signal Forms
+
+The same `hlmField` and controls work with Angular's Signal Forms. Build the model with
+`form()` from `@angular/forms/signals`, bind the control with `[formField]`, and wrap the `<form>`
+with `[formRoot]`. Errors come from the field's `errors()` signal rather than the control's
+`invalid`/`touched` flags:
+
+```ts
+import { form, FormField, FormRoot, minLength, required } from '@angular/forms/signals';
+
+protected readonly model = signal({ email: '' });
+readonly emailForm = form(this.model, (path) => {
+	required(path.email, { message: 'Enter your email.' });
+	minLength(path.email, 5, { message: 'That email looks too short.' });
+});
+```
+
+```html
+<form [formRoot]="emailForm">
+	<div hlmField>
+		<label hlmFieldLabel for="email">Email</label>
+		<input hlmInput id="email" [formField]="emailForm.email" />
+		@for (error of emailForm.email().errors(); track error) {
+		<hlm-field-error [validator]="error.kind">{{ error.message }}</hlm-field-error>
+		}
+	</div>
+</form>
+```
+
+Import `FormRoot` and `FormField` alongside `HlmFieldImports`. Everything below (fieldsets, control
+choice, error display) applies regardless of which forms API you use.
+
+## Group related controls
+
+For sets of related checkboxes or radios, use the fieldset pieces so the group has a single legend
+and shared validation:
+
+`hlmFieldSet` and `hlmFieldLegend` are directives on the native `<fieldset>` and `<legend>`
+elements:
+
+```html
+<fieldset hlmFieldSet>
+	<legend hlmFieldLegend>Notifications</legend>
+	<div hlmFieldGroup>
+		<div hlmField orientation="horizontal">
+			<hlm-checkbox id="email-opt" />
+			<label hlmFieldLabel for="email-opt">Email</label>
+		</div>
+		<div hlmField orientation="horizontal">
+			<hlm-checkbox id="sms-opt" />
+			<label hlmFieldLabel for="sms-opt">SMS</label>
+		</div>
+	</div>
+</fieldset>
+```
+
+## Option sets (2-7 choices): `toggle-group`
+
+When the user picks from a small, fixed set of mutually exclusive options, prefer `hlm-toggle-group`
+over a row of buttons or a select.
+
+```html
+<hlm-toggle-group type="single" [(value)]="size">
+	<button hlmToggleGroupItem value="sm">Small</button>
+	<button hlmToggleGroupItem value="md">Medium</button>
+	<button hlmToggleGroupItem value="lg">Large</button>
+</hlm-toggle-group>
+```
+
+Use `type="multiple"` when more than one option can be active.
+
+## Choose the right control
+
+- Free text -> `input` / `textarea`
+- One-time codes -> `input-otp`
+- Input with leading/trailing affordances (icon, button, prefix) -> `input-group`
+- Single choice from many -> `select`, `combobox`, or `autocomplete`
+- Single choice from few -> `radio-group` or `toggle-group`
+- Boolean -> `switch` or `checkbox`
+- Numeric range -> `slider`
+- Native dropdown -> `native-select`
+
+## Validation display
+
+Show errors through the `<hlm-field-error>` component (not ad-hoc text), gated on the control being
+invalid and touched/dirty. The field reflects invalid state to its host so the label and control
+style consistently.

package/dist/templates/frontend/application/.agents/skills/spartan/rules/icons.md

@@ -0,0 +1,56 @@
+# Icons
+
+spartan/ui renders icons with [`@ng-icons`](https://ng-icons.github.io/ng-icons). The default set is
+Lucide (`@ng-icons/lucide`). The `icon` component (`@spartan-ng/helm/icon`) provides the `hlm`
+directive that sizes and styles icons consistently.
+
+## The element
+
+Icons are an `<ng-icon>` element with the `hlm` directive and a `name`:
+
+```html
+<ng-icon hlm name="lucideChevronRight" size="sm" />
+```
+
+## Register every icon
+
+Icon names are not global - each icon you reference must be provided to the component (or app) via
+`provideIcons`. Import the symbol from its set and register it:
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideChevronRight, lucideTrash } from '@ng-icons/lucide';
+import { HlmIcon } from '@spartan-ng/helm/icon';
+
+@Component({
+	selector: 'app-example',
+	imports: [NgIcon, HlmIcon],
+	providers: [provideIcons({ lucideChevronRight, lucideTrash })],
+	template: `
+		<ng-icon hlm name="lucideChevronRight" size="sm" />
+	`,
+})
+export class ExampleComponent {}
+```
+
+If an icon does not render, the usual cause is a missing `provideIcons` entry.
+
+## Sizing: use the `size` input
+
+Size icons with the `hlm` directive's `size` input (`xs | sm | base | lg | xl`), not Tailwind sizing
+classes, when the icon is inside a component. This keeps icons aligned with the component's metrics.
+
+```html
+<button hlmBtn size="icon" variant="ghost">
+	<ng-icon hlm name="lucideX" size="sm" />
+</button>
+```
+
+For free-standing decorative icons you may set color with a semantic class
+(`class="text-muted-foreground"`), but still prefer the `size` input over `w-*`/`h-*`.
+
+## Installing the icon component
+
+`npx nx g @spartan-ng/cli:ui --name=icon` (or `ng g ...`) installs `@ng-icons/core`,
+`@ng-icons/lucide`, and the Helm icon styles.

package/dist/templates/frontend/application/.agents/skills/spartan/rules/styling.md

@@ -0,0 +1,143 @@
+# Styling rules
+
+spartan/ui styles with Tailwind. The styled (Helm) layer is built with
+[class-variance-authority](https://cva.style) and merged with the `hlm()` utility.
+
+## Semantic colors only
+
+Never use raw Tailwind palette values (`bg-blue-500`, `text-gray-700`) on spartan components. Use the
+semantic tokens defined by the preset and CSS variables. Each has a paired `-foreground` for content
+placed on top of it:
+
+`background` / `foreground`, `card` / `card-foreground`, `popover` / `popover-foreground`,
+`primary` / `primary-foreground`, `secondary` / `secondary-foreground`,
+`muted` / `muted-foreground`, `accent` / `accent-foreground`,
+`destructive` / `destructive-foreground`, plus the standalone `border`, `input`, and `ring`, and the
+`sidebar*` family.
+
+```html
+<!-- Good -->
+<div class="bg-card text-card-foreground border-border border">...</div>
+<div class="bg-primary text-primary-foreground">...</div>
+
+<!-- Bad -->
+<div class="border-gray-200 bg-white text-black">...</div>
+<div class="bg-blue-600 text-white">...</div>
+```
+
+These tokens automatically flip in dark mode, so you never write dark-mode color overrides by hand.
+
+## Prefer built-in variants
+
+Components expose `variant` and `size` inputs. Use them instead of re-styling with classes.
+
+```html
+<button hlmBtn variant="outline" size="sm">Cancel</button>
+<span hlmBadge variant="secondary">beta</span>
+<div hlmAlert variant="destructive">...</div>
+```
+
+Button variants: `default | destructive | outline | secondary | ghost | link`.
+Button sizes: `default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg`.
+
+## `class` is for layout only
+
+Use the `class` attribute to position and space components (flex, grid, gap, margins, widths). Do
+not use it to override a component's own colors, typography, or internal padding - change the copied
+Helm file or a CSS variable instead.
+
+## Spacing: `gap-*`, not `space-*`
+
+Use `flex`/`grid` with `gap-*` for spacing between items. Avoid `space-x-*` / `space-y-*`.
+
+```html
+<!-- Good -->
+<div class="flex flex-col gap-4">...</div>
+<!-- Bad -->
+<div class="space-y-4">...</div>
+```
+
+## `size-*` for equal dimensions
+
+When width and height are equal, use `size-*` rather than `w-* h-*`.
+
+```html
+<div class="size-8 rounded-full">...</div>
+<!-- not w-8 h-8 -->
+```
+
+## Use `truncate`
+
+Use the `truncate` shorthand instead of manually combining `overflow-hidden text-ellipsis
+whitespace-nowrap`.
+
+## The `hlm()` utility
+
+When you compute classes in TypeScript, merge them with `hlm()` from `@spartan-ng/helm/utils` (it
+wraps `clsx` + `tailwind-merge`, so later classes win conflicts). Do not concatenate class strings
+by hand.
+
+```ts
+import { hlm } from '@spartan-ng/helm/utils';
+
+const cls = hlm('rounded-md border px-3 py-2', active() && 'bg-accent', userClass());
+```
+
+## Make your own component override-friendly
+
+When you build a component or directive in the "hlm-like" fashion, let callers pass classes that
+merge cleanly over your base styles. There are two patterns, both used across the hlm components.
+
+### Preferred: `classes()`
+
+Call `classes()` from `@spartan-ng/helm/utils` in the constructor. It applies your base classes to
+the host element and automatically merges (via `hlm()`) any `class` the consumer puts on the host,
+with the consumer's classes winning conflicts. No `class` input or binding needed, and it works
+the same on components and directives:
+
+```ts
+import { Component } from '@angular/core';
+import { classes } from '@spartan-ng/helm/utils';
+
+@Component({
+	selector: 'app-badge',
+	template: '<ng-content />',
+})
+export class AppBadge {
+	constructor() {
+		classes(() => 'inline-flex items-center rounded-md border px-2 py-0.5');
+	}
+}
+```
+
+A consumer writes `<app-badge class="bg-primary text-primary-foreground">` and it merges
+automatically. Because it manages the host `class` directly, it avoids clashing with other class
+bindings.
+
+### Explicit: a `class` input merged with `hlm()`
+
+When you need to fold the user's class into a `computed` alongside conditional classes, take a
+`class`-aliased input and bind the merged result yourself. Put the user's class last so it wins:
+
+```ts
+import { Component, computed, input } from '@angular/core';
+import { hlm } from '@spartan-ng/helm/utils';
+import type { ClassValue } from 'clsx';
+
+@Component({
+	selector: 'app-badge',
+	template: '<ng-content />',
+	host: { '[class]': '_computedClass()' },
+})
+export class AppBadge {
+	public readonly userClass = input<ClassValue>('', { alias: 'class' });
+	protected readonly _computedClass = computed(() =>
+		hlm('inline-flex items-center rounded-md border px-2 py-0.5', this.userClass()),
+	);
+}
+```
+
+## Overlays: no manual z-index
+
+Dialog, Sheet, Popover, Tooltip, Dropdown, and other overlay components manage stacking via the
+Angular CDK overlay. Do not set `z-index` on them manually.

package/dist/templates/frontend/application/.claude/skills/catalyst-component-catalog/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: catalyst-component-catalog
+description: >
+  Consume `@aurora/components` using `*.stories.ts` files as the canonical source of truth for
+  component APIs, variants, and composition patterns. Trigger: Whenever composing or generating ANY
+  screen, page, form, or dashboard that uses anything from `@aurora/components/`; when picking
+  between candidate components for the same requirement; when answering "how do I use X component?"
+  — EVEN IF the user doesn't mention "stories", "catalog", or "component docs" explicitly. If the
+  task consumes `@aurora/components`, this skill fires. For AUTHORING new stories (adding or
+  updating a component's story in `@aurora/components/`), use `catalyst-component-story-composer`
+  instead — this skill is read-only over the catalog.
+license: MIT
+metadata:
+  author: aurora
+  version: '2.1'
+---
+
+## When to Use
+
+- Composing or generating a screen that consumes anything from `@aurora/components`
+- Choosing between multiple `@aurora/components` that could satisfy the same user requirement
+- Answering "how does component X work?" or "what props does X take?"
+- Working in **Solution mode** (consuming the platform), not Framework mode
+
+**Skip this skill** when adding or modifying a component in `@aurora/components/` — that is authoring, covered by `catalyst-component-story-composer`.
+
+## Mandatory Discovery Protocol
+
+BEFORE writing any code that consumes an `@aurora/components` component, follow this protocol:
+
+1. **Glob for matching stories**
+   `Glob frontend/src/@aurora/components/**/*.stories.ts` — returns the full catalog.
+2. **Read the candidate story file(s)**
+   `Read` the `*.stories.ts` sibling of the component you plan to use. Lift from it:
+   - The `Meta.component` (canonical import)
+   - The `args` / `argTypes` (prop names, types, defaults, descriptions)
+   - Named `StoryObj` exports (representative variants — your composition should reuse these patterns, not invent new ones)
+   - The `parameters.aurora` metadata, if declared (see next section)
+3. **Consume, do NOT re-derive**
+   Write the usage by lifting prop names, slot shapes, and composition patterns from the story. Do not re-read the component source to "verify" prop names — the story is canonical.
+
+### Why `*.stories.ts` and not the component source?
+
+Story files encode **intended usage**: representative variants, argTypes with descriptions, prose in `parameters.docs.description.story`. Component `.ts` files document only what is syntactically possible. A component may accept 20 inputs; the story tells you which 3 are actually meaningful at the call site.
+
+## Two-Tier Component Selection (when multiple candidates fit)
+
+When you need to pick between two or more `@aurora/components` candidates:
+
+**Tier 1 — Read `parameters.aurora` metadata (preferred)**
+Each story MAY declare:
+
+```ts
+parameters: {
+  aurora: {
+    category: 'data-table' | 'navigation' | 'form' | ...,
+    when: 'one-sentence description of the primary use case',
+    whenNot: 'one-sentence description of when a different component is the better choice, naming that alternative',
+  },
+},
+```
+
+When present, `when` and `whenNot` disambiguate candidates explicitly. Prefer this signal over inference — it is authored by the component owner.
+
+**Tier 2 — Fall back to title / argTypes inference**
+If `parameters.aurora` is absent on the candidate(s), infer from:
+
+- `Meta.title` (e.g. `@aurora/components/data-table/table-search` hints at data-table scope)
+- `argTypes` descriptions
+- Story names (e.g. `FastDebounce`, `TranslatedPlaceholder`)
+
+Flag to the user that metadata was missing — this indicates the catalog entry is incomplete. Tier-2 inference is explicitly degraded.
+
+## Escalation: Undocumented Component
+
+If you need to use an `@aurora/components` export but `Glob frontend/src/@aurora/components/**/*.stories.ts` returns no matching story:
+
+1. **DO NOT** infer usage from the component source and ship code silently.
+2. **FLAG THE GAP** to the user: name the component and state that its story is missing.
+3. **DELEGATE the authoring**: hand off to `catalyst-component-story-composer` (or propose it to the user) BEFORE consuming the component. That skill owns the authoring convention and Generator Mode procedure.
+
+This rule exists because silently inferred usage is the primary source of drift between generated modules and the `@aurora/` platform layer.
+
+## Related Skills
+
+- **`catalyst-component-story-composer`** — sibling skill for **authoring** stories when a component has no documentation or needs an update. Fires in Framework mode; this one fires in Solution mode.
+- `layout-design-system` — spacing/density rules that apply when composing the screens that consume these components.
+- `transloco-i18n` — for stories that demonstrate translated content.
+- `catalyst-data-table-management` — specific patterns for the `data-table` family; this skill handles the broader catalog discovery loop.