spartan

spartan/ui

spartan/ui is an Angular UI library. It uses a two-layer architecture:

• Brain (@spartan-ng/brain) - accessible, unstyled primitives (Angular directives/components),
  installed from npm. This is the behavior and accessibility layer.
• Helm (@spartan-ng/helm) - the styled layer (Tailwind + class-variance-authority). Helm code
  is copied into the user's project by the CLI so they own and can customize it.

You compose Helm directives/components onto host elements; Helm wires up the matching Brain
primitive under the hood. Always prefer existing components over hand-written markup.

All CLI commands run through the workspace's runner. Detect it from the project:

• Nx workspace (has nx.json): npx nx g @spartan-ng/cli:<generator> (or pnpm nx g ...).
• Angular CLI workspace (has angular.json, no nx.json): ng g @spartan-ng/cli:<generator>.

Current project context

Before generating any code, gather the project context:

npx nx g @spartan-ng/cli:info --json     # Nx
ng g @spartan-ng/cli:info --json         # Angular CLI

This is read-only and prints JSON with:

• workspaceType - nx | angular-cli (decides which runner to use above).
• config.componentsPath - where Helm components are copied (e.g. libs/ui).
• config.importAlias - the import prefix for Helm, default @spartan-ng/helm.
• config.generateAs - library | entrypoint (Nx layout choice).
• versions - Angular, Angular CDK, Tailwind, @spartan-ng/brain, @spartan-ng/cli.
• iconLibrary - @ng-icons when present.
• tailwindCssFile - the global stylesheet that imports the preset.
• installedComponents - components already present (do not re-add these).
• availableComponents - everything the CLI can generate.

If components.json does not exist, the project is not set up yet - run @spartan-ng/cli:init
first (it installs dependencies and the theme). components.json itself is created when you add the
first component with ui (see cli.md).

Principles

1. Use existing components first. Check installedComponents, then availableComponents. Find
   docs via the MCP server (spartan_components_list / spartan_components_get) or the live docs at
   https://www.spartan.ng/components/<name>. See mcp.md.
2. Compose, do not reinvent. Build dashboards, forms, and dialogs from existing Helm + Brain
   pieces rather than custom markup.
3. Use built-in variants before custom styles. Buttons, badges, alerts, etc. ship variant and
   size inputs - use them instead of overriding classes.
4. Use semantic colors, never raw values. bg-primary text-primary-foreground, not
   bg-blue-500. See rules/styling.md.

Critical rules

Read the rule file before doing the related work:

• rules/styling.md - the hlm() util, semantic color tokens, layout-only classes,
  gap-* over space-*, size-*, dark mode, no manual z-index on overlays.
• rules/forms.md - compose forms with hlmField (label, control, error, description) and
  hlmFieldSet / hlmFieldLegend on native <fieldset>/<legend>; option sets (2-7 choices) use
  hlm-toggle-group.
• rules/composition.md - items belong inside their group; dialogs/sheets need a title;
  full Card composition; tabs triggers inside hlm-tabs-list; avatar always has a fallback;
  use Alert/Empty/Skeleton/Badge/Separator/Spinner instead of custom markup.
• rules/icons.md - icons are <ng-icon name="lucide...">; register with provideIcons;
  no manual sizing classes inside components - use the size input.
• rules/brain-vs-helm.md - the two-layer model (one headless library, Brain, plus the styled
  Helm layer); when to reach for Brain directly vs Helm, and how composition works via directives.
• cli.md - every generator (init, ui, ui-theme, healthcheck, info, migrate-*),
  with Nx and Angular CLI invocations.
• registry.md - the Brain-npm + Helm-copy-in distribution model, components.json, and the
  fixed component catalog (the shipped CLI uses no remote or custom registry).
• customization.md - theming via the hlm-tailwind-preset.css, CSS variables, the ui-theme
  generator, and extending copied Helm components.
• mcp.md - using the @spartan-ng/mcp tools, resources, and prompts for discovery.

Key patterns

<!-- Buttons: use variant/size inputs, not custom classes -->
<button hlmBtn variant="destructive" size="lg">Delete</button>

<!-- Icon in a button: ng-icon -->
<button hlmBtn size="icon" variant="ghost">
	<ng-icon name="lucideTrash" />
</button>

<!-- Loading state: compose a spinner, there is no isLoading input -->
<button hlmBtn [disabled]="loading()">
	@if (loading()) {
	<hlm-spinner />
	} Save
</button>

<!-- Layout: gap, not space-* ; size-* when width == height -->
<div class="flex items-center gap-2">
	<span hlmBadge variant="secondary">beta</span>
</div>

Component selection

Need	Component(s)
Action / button	button (hlmBtn), button-group
Text/number input	input, textarea, input-otp, input-group, native-select
Choice input	select, combobox, autocomplete, radio-group, checkbox, switch, slider
Toggle 2-7 options	toggle-group
Form layout/validation	field, label
Data display	table, card, badge, avatar, kbd, item
Navigation	sidebar, navigation-menu, breadcrumb, tabs, pagination
Overlays	dialog, sheet, alert-dialog, popover, hover-card, tooltip
Menus	dropdown-menu, context-menu, menubar, command
Feedback	sonner (toasts), alert, progress, skeleton, spinner
Layout/containers	card, separator, resizable, scroll-area, accordion, collapsible, aspect-ratio
Empty states	empty
Dates	calendar, date-picker
Icons	icon (@ng-icons)
Typography	typography

Workflow

1. Get context. Run @spartan-ng/cli:info --json. If the project is not set up, run :init,
   then add components with :ui (the first :ui run creates components.json).
2. Check what is installed. Do not re-add anything in installedComponents.
3. Find the component. Use the MCP tools or https://www.spartan.ng/components/<name> for the
   API and examples (mcp.md). Never guess selectors - confirm them.
4. Add it. npx nx g @spartan-ng/cli:ui --name=<component> (Nx) or
   ng g @spartan-ng/cli:ui --name=<component> (Angular CLI). This installs the Brain dependency and
   copies the Helm code. Omit --name to get an interactive multiselect.
5. Compose correctly. Import the *Imports const (e.g. HlmDialogImports) or the individual
   classes from the import alias, add them to the standalone component's imports, and follow the
   composition rules.
6. Register icons. Any <ng-icon> you use must be passed to provideIcons(...) (see
   rules/icons.md).
7. Verify. After bigger changes or upgrades, run @spartan-ng/cli:healthcheck to catch
   deprecated patterns and fix imports.
8. Theme/customize. Edit the copied Helm files and the CSS variables; do not fork Brain.

Quick reference

# Initialize (creates components.json, wires Tailwind + preset)
npx nx g @spartan-ng/cli:init
ng g @spartan-ng/cli:init

# Project context as JSON
npx nx g @spartan-ng/cli:info --json

# Add components (interactive, or pass --name)
npx nx g @spartan-ng/cli:ui
npx nx g @spartan-ng/cli:ui --name=dialog

# Generate theme variables
npx nx g @spartan-ng/cli:ui-theme

# Scan + auto-fix deprecated APIs/imports after an upgrade
npx nx g @spartan-ng/cli:healthcheck --autoFix