Spartan Ng Developer

Spartan/ng Developer Guidelines

> Pairs with angular-developer - that skill provides Angular fundamentals (signals, DI, routing, forms, SSR, accessibility). This skill focuses on Spartan/ng specifics. Install both for the best experience.

Compatibility

• Tracks: @spartan-ng/brain v0.0.1-alpha.714 exactly. Spartan ships near-daily alpha patches, the skill is re-validated each time the tracked version is bumped.
• Angular: v18 or newer required. Standalone components, control flow (@if / @for), and signal-based APIs (input() / output()) are assumed. Will not generate NgModule-based or decorator-based code.
• Tailwind: v3 or v4. The skill detects the major version from package.json and adapts.
• Not supported: other Spartan alphas with API drift, Angular v17 or below, projects using @spartan-ng/ui-* packages (deprecated, replaced by @spartan-ng/helm).

If the project's installed version differs significantly from the tracked one, warn the user before generating code, the API surface may have shifted.

1. Always check the project's Spartan/ng version before providing guidance. Spartan is pre-1.0 and conventions evolve - package.json is the source of truth.

1. Detect the project layout up front:

• If nx.json exists → Nx workspace. Use npx nx g @spartan-ng/cli:ui commands.
• Otherwise → Angular CLI. Use ng g @spartan-ng/cli:ui commands.

The destination path for generated Helm source is configured in components.json (componentsPath) - don't hard-code path assumptions. Find the actual location in tsconfig.json paths after init. See [setup.md](references/setup.md).

1. Detect the Tailwind major version in package.json (tailwindcss dependency). Spartan supports both v3 and v4 but the config syntax differs significantly. See [setup.md](references/setup.md).

1. After generating code that uses Spartan components, run ng build to verify there are no compilation errors. If components render unstyled, the issue is almost always Tailwind config - see the troubleshooting section in [setup.md](references/setup.md).

Spartan architecture: Helm vs Brain (critical)

Spartan ships two packages with a unique relationship:

• @spartan-ng/helm - Styled components that live in the user's project, not in node_modules. The CLI (ng g @spartan-ng/cli:ui button) copies the component source into the path configured by components.json (componentsPath). The @spartan-ng/helm/ import is a tsconfig path alias to the generated source. To customize a Helm component, edit the file in the user's repo. Do not look for it in node_modules.

• @spartan-ng/brain - Headless, accessible primitives installed normally from npm. Helm components compose Brain primitives via Angular's hostDirectives.

Default to Helm. Reach for Brain only when: (1) Helm doesn't expose the primitive you need, (2) you're building a reusable composition that wraps multiple Helm components, or (3) you need to control accessibility attributes Helm hides.

Installation and theming

• Setup: Install the CLI, add Spartan, configure Tailwind (v3 and v4 both supported), CLI vs Nx detection. Read [setup.md](references/setup.md)
• Theming: CSS variables, dark mode, custom themes. Read [theming.md](references/theming.md)

Components

Spartan/ng provides 56 stable Helm components, grouped here by category. The shared conventions file applies to all of them; the category files cover specific component APIs and gotchas.

• Helm conventions: The hlm* directive pattern, signal inputs, composition via hostDirectives, the cn() helper, the HlmXImports barrel pattern, common pitfalls. Read [helm-conventions.md](references/helm-conventions.md)
• Form controls: Autocomplete, Button, Button Group, Checkbox, Combobox, Date Picker, Field, Input, Input Group, Input OTP, Label, Native Select, Radio Group, Select, Slider, Switch, Textarea, Toggle, Toggle Group. Read [form-controls.md](references/form-controls.md)
• Overlays: Alert Dialog, Command, Context Menu, Dialog, Dropdown Menu, Hover Card, Menubar, Navigation Menu, Popover, Sheet, Sonner (Toast), Tooltip. Read [overlays.md](references/overlays.md)
• Layout: Accordion, Aspect Ratio, Card, Collapsible, Resizable, Scroll Area, Separator, Sidebar, Tabs. Read [layout.md](references/layout.md)
• Display: Alert, Avatar, Badge, Empty, Icon, Item, Kbd, Progress, Skeleton, Spinner. Read [display.md](references/display.md)
• Data display: Breadcrumb, Calendar, Carousel, Data Table, Pagination, Table. Read [data-display.md](references/data-display.md)

Recipes

Cookbook patterns that compound multiple Helm components into a purpose-built surface. None of these are shipped Helm components, the recipe is the contribution. Start with the diff viewer (syntax highlighting, per-line gutter, file tree, inline line comments) if you're building a code-review tool. Read [recipes.md](references/recipes.md)

Brain primitives

• Brain: Headless primitives, when to drop down from Helm, building custom compositions. Read [brain.md](references/brain.md)

Forms integration

• Forms: Wiring Helm form components to ReactiveForms or Signal Forms, ControlValueAccessor patterns, validation display. Read [forms.md](references/forms.md)

Accessibility

• Accessibility: A11y conventions Helm and Brain provide for free, ARIA patterns to know, and gotchas. Read [accessibility.md](references/accessibility.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mofirojean
• Source: mofirojean/angular-ui-skills
• License: MIT
• Homepage: https://angular-ui-skills-docs.vercel.app/

Install and usage instructions live in the source repository linked above.