agentleFS
L-X-TL-X-T/ng-agentic-skills/.agents/skills/spartan/SKILL.md

spartan

Skill13 starsChanged 44 days agoMITView on GitHub

Manages spartan/ui, the Angular UI library - adding, composing, fixing, debugging, and styling UI with the Brain (headless primitives) and Helm (styled) layers. Provides project context, component APIs, and usage examples. Applies when working with spartan/ui, @spartan-ng/brain, @spartan-ng/helm, the @spartan-ng/cli generators, or any Angular project with a components.json file. Also triggers for "spartan init", "add a spartan component", or "set up spartan/ui".

2 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All CLI commands run through the workspace's runner.

    line 31
  2. Distinctive:

    Before generating any code, gather the project context:

    line 38
  3. Very specific:

    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).

    line 57
  4. Very specific:

    Use existing components first: Check installedComponents, then availableComponents.

    line 63
  5. Distinctive:

    Read the rule file before doing the related work:

    line 75
  6. Very specific:

    references/cli.md: - every generator (init, ui, ui-theme, healthcheck, info, migrate-*), with Nx and Angular CLI invocations.

    line 89
  7. Very specific:

    Get context: Run @spartan-ng/cli:info --json.

    line 143
  8. Very specific:

    Check what is installed: Do not re-add anything in installedComponents.

    line 145
  9. Very specific:

    Find the component: Use the MCP tools or https://www.spartan.ng/components/<name> for the API and examples (references/mcp.md).

    line 146
  10. Very specific:

    Compose correctly: Import the *Imports const (e.g.

    line 151
  11. Very specific:

    Verify: After bigger changes or upgrades, run @spartan-ng/cli:healthcheck to catch deprecated patterns and fix imports.

    line 156

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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): pnpm exec 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:

pnpm exec 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 references/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 references/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 references/styling.md.

Critical rules

Read the rule file before doing the related work:

  • references/styling.md - the hlm() util, semantic color tokens, layout-only classes, gap-* over space-*, size-*, dark mode, no manual z-index on overlays.
  • references/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.
  • references/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.
  • references/icons.md - icons are <ng-icon name="lucide...">; register with provideIcons; no manual sizing classes inside components - use the size input.
  • references/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.
  • references/cli.md - every generator (init, ui, ui-theme, healthcheck, info, migrate-*), with Nx and Angular CLI invocations.
  • references/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).
  • references/customization.md - theming via the hlm-tailwind-preset.css, CSS variables, the ui-theme generator, and extending copied Helm components.
  • references/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

NeedComponent(s)
Action / buttonbutton (hlmBtn), button-group
Text/number inputinput, textarea, input-otp, input-group, native-select
Choice inputselect, combobox, autocomplete, radio-group, checkbox, switch, slider
Toggle 2-7 optionstoggle-group
Form layout/validationfield, label
Data displaychart, table, card, badge, avatar, kbd, item
Navigationsidebar, navigation-menu, breadcrumb, tabs, pagination
Overlaysdialog, sheet, alert-dialog, popover, hover-card, tooltip
Menusdropdown-menu, context-menu, menubar, command
Feedbacksonner (toasts), alert, progress, skeleton, spinner
Layout/containerscard, separator, resizable, scroll-area, accordion, collapsible, aspect-ratio
Empty statesempty
Datescalendar, date-picker
Iconsicon (@ng-icons)
Typographytypography

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 (references/mcp.md). Never guess selectors - confirm them.
  4. Add it. pnpm exec 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 references/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)
pnpm exec nx g @spartan-ng/cli:init
ng g @spartan-ng/cli:init

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

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

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

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.