spartan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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>

spartan/ui是一款Angular UI库，采用双层架构：

Brain (
@spartan-ng/brain
)——可访问、无样式的原语（Angular指令/组件），从npm安装。这是负责行为与可访问性的层。
Helm (
@spartan-ng/helm
)——样式化层（基于Tailwind + class-variance-authority）。Helm代码会通过CLI复制到用户项目中，以便用户拥有并自定义它。

你可以将Helm指令/组件组合到宿主元素上；Helm会在底层关联匹配的Brain原语。优先使用现有组件而非手写标记。

所有CLI命令通过工作区的运行器执行，可从项目中检测运行器类型：

Nx工作区（包含

nx.json

）：

npx nx g @spartan-ng/cli:<generator>

（或

pnpm nx g ...

）。

Angular CLI工作区（包含

angular.json

，无

nx.json

）：

ng g @spartan-ng/cli:<generator>

。

Current project context

当前项目上下文

Before generating any code, gather the project context:

bash

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.

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

在生成任何代码之前，先收集项目上下文：

bash

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

这是只读操作，会输出包含以下内容的JSON：

```
workspaceType
```
——
```
nx
```
|
```
angular-cli
```
（决定使用上述哪种运行器）。
```
config.componentsPath
```
——Helm组件的复制路径（例如
```
libs/ui
```
）。
```
config.importAlias
```
——Helm的导入前缀，默认为
```
@spartan-ng/helm
```
。
```
config.generateAs
```
——
```
library
```
|
```
entrypoint
```
（Nx布局选项）。
```
versions
```
——Angular、Angular CDK、Tailwind、
```
@spartan-ng/brain
```
、
```
@spartan-ng/cli
```
的版本。
```
iconLibrary
```
——当存在时为
```
@ng-icons
```
。
```
tailwindCssFile
```
——导入预设的全局样式表。
```
installedComponents
```
——已存在的组件（请勿重复添加）。
```
availableComponents
```
——CLI可生成的所有组件。

如果

components.json

不存在，说明项目尚未设置——先运行

@spartan-ng/cli:init

（它会安装依赖项和主题）。当你首次使用

ui

添加组件时，会创建

components.json

（详见

cli.md

）。

Principles

原则

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

Compose, do not reinvent. Build dashboards, forms, and dialogs from existing Helm + Brain pieces rather than custom markup.
Use built-in variants before custom styles. Buttons, badges, alerts, etc. ship
```
variant
```
and
```
size
```
inputs - use them instead of overriding classes.

Use semantic colors, never raw values.

bg-primary text-primary-foreground

, not

bg-blue-500

. See

rules/styling.md

优先使用现有组件。先检查

installedComponents

，再查看

availableComponents

。可通过MCP服务器（

spartan_components_list

spartan_components_get

）或在线文档

https://www.spartan.ng/components/<name>

查找文档。详见

mcp.md

。

组合而非重造。使用现有Helm + Brain组件构建仪表板、表单和对话框，而非自定义标记。
优先使用内置变体而非自定义样式。按钮、徽章、警告等组件提供
```
variant
```
和
```
size
```
输入——优先使用这些，而非覆盖类。
使用语义化颜色，绝不使用原始值。例如使用
```
bg-primary text-primary-foreground
```
，而非
```
bg-blue-500
```
。详见
```
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.

在进行相关工作前，请阅读规则文件：

rules/styling.md
——
```
hlm()
```
工具、语义化颜色令牌、仅布局类、优先使用
```
gap-*
```
而非
```
space-*
```
、
```
size-*
```
、深色模式、不在覆盖层上手动设置z-index。
rules/forms.md
——使用
```
hlmField
```
（标签、控件、错误信息、描述）和
```
hlmFieldSet
```
/
```
hlmFieldLegend
```
组合表单，原生
```
<fieldset>
```
/
```
<legend>
```
需搭配使用；选项集（2-7个选项）使用
```
hlm-toggle-group
```
。
rules/composition.md
——元素需放在对应组内；对话框/侧边栏需要标题；完整的Card组合；标签触发器需放在
```
hlm-tabs-list
```
内；头像必须有回退方案；使用
```
Alert
```
/
```
Empty
```
/
```
Skeleton
```
/
```
Badge
```
/
```
Separator
```
/
```
Spinner
```
而非自定义标记。
rules/icons.md
——图标使用
```
<ng-icon name="lucide...">
```
；通过
```
provideIcons
```
注册；组件内不使用手动尺寸类——使用
```
size
```
输入。
rules/brain-vs-helm.md
——双层模型（一个无头库Brain，加上样式化的Helm层）；何时直接使用Brain而非Helm，以及通过指令实现组合的方式。
cli.md
——所有生成器（
```
init
```
、
```
ui
```
、
```
ui-theme
```
、
```
healthcheck
```
、
```
info
```
、
```
migrate-*
```
），包含Nx和Angular CLI的调用方式。
registry.md
——Brain（npm安装）+ Helm（复制到项目）的分发模型、
```
components.json
```
，以及固定的组件目录（发布的CLI不使用远程或自定义注册表）。
customization.md
——通过
```
hlm-tailwind-preset.css
```
、CSS变量、
```
ui-theme
```
生成器进行主题定制，以及扩展复制的Helm组件。
mcp.md
——使用
```
@spartan-ng/mcp
```
工具、资源和提示进行组件探索。

Key patterns

核心模式

html

<!-- 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>

html

<!-- 按钮：使用variant/size输入，而非自定义类 -->
<button hlmBtn variant="destructive" size="lg">删除</button>

<!-- 按钮内的图标：使用ng-icon -->
<button hlmBtn size="icon" variant="ghost">
	<ng-icon name="lucideTrash" />
</button>

<!-- 加载状态：组合spinner，没有isLoading输入 -->
<button hlmBtn [disabled]="loading()">
	@if (loading()) {
	<hlm-spinner />
	} 保存
</button>

<!-- 布局：使用gap，而非space-* ; 宽高相等时使用size-* -->
<div class="flex items-center gap-2">
	<span hlmBadge variant="secondary">测试版</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`

需求	组件
操作 / 按钮	`button` ( `hlmBtn` ), `button-group`
文本/数字输入	`input` , `textarea` , `input-otp` , `input-group` , `native-select`
选择输入	`select` , `combobox` , `autocomplete` , `radio-group` , `checkbox` , `switch` , `slider`
切换2-7个选项	`toggle-group`
表单布局/验证	`field` , `label`
数据展示	`table` , `card` , `badge` , `avatar` , `kbd` , `item`
导航	`sidebar` , `navigation-menu` , `breadcrumb` , `tabs` , `pagination`
覆盖层	`dialog` , `sheet` , `alert-dialog` , `popover` , `hover-card` , `tooltip`
菜单	`dropdown-menu` , `context-menu` , `menubar` , `command`
反馈	`sonner` （提示框）, `alert` , `progress` , `skeleton` , `spinner`
布局/容器	`card` , `separator` , `resizable` , `scroll-area` , `accordion` , `collapsible` , `aspect-ratio`
空状态	`empty`
日期相关	`calendar` , `date-picker`
图标	`icon` ( `@ng-icons` )
排版	`typography`

Workflow

工作流程

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
```
).
Check what is installed. Do not re-add anything in
```
installedComponents
```
.
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.
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.
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.
Register icons. Any
```
<ng-icon>
```
you use must be passed to
```
provideIcons(...)
```
(see
```
rules/icons.md
```
).
Verify. After bigger changes or upgrades, run
```
@spartan-ng/cli:healthcheck
```
to catch deprecated patterns and fix imports.
Theme/customize. Edit the copied Helm files and the CSS variables; do not fork Brain.

获取上下文。运行
```
@spartan-ng/cli:info --json
```
。如果项目未设置，运行
```
:init
```
，然后使用
```
:ui
```
添加组件（首次运行
```
:ui
```
会创建
```
components.json
```
）。
检查已安装组件。请勿重复添加
```
installedComponents
```
中的任何组件。
查找组件。使用MCP工具或
```
https://www.spartan.ng/components/<name>
```
查看API和示例（详见
```
mcp.md
```
）。切勿猜测选择器——务必确认。
添加组件。Nx项目使用
```
npx nx g @spartan-ng/cli:ui --name=<component>
```
，Angular CLI项目使用
```
ng g @spartan-ng/cli:ui --name=<component>
```
。这会安装Brain依赖并复制Helm代码。省略
```
--name
```
可进入交互式多选模式。
正确组合。导入
```
*Imports
```
常量（例如
```
HlmDialogImports
```
）或从导入别名导入单个类，将其添加到独立组件的
```
imports
```
中，并遵循组合规则。
注册图标。所有使用的
```
<ng-icon>
```
必须传入
```
provideIcons(...)
```
（详见
```
rules/icons.md
```
）。
验证。在较大改动或升级后，运行
```
@spartan-ng/cli:healthcheck
```
以检测已弃用的模式并修复导入。
主题/自定义。编辑复制的Helm文件和CSS变量；请勿fork Brain。

Quick reference

快速参考

bash

undefined

bash

undefined

Initialize (creates components.json, wires Tailwind + preset)

初始化（创建components.json，配置Tailwind + 预设）

npx nx g @spartan-ng/cli:init ng g @spartan-ng/cli:init

Project context as JSON

以JSON格式获取项目上下文

npx nx g @spartan-ng/cli:info --json

Add components (interactive, or pass --name)

添加组件（交互式，或传入--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

升级后扫描并自动修复已弃用的API/导入

npx nx g @spartan-ng/cli:healthcheck --autoFix

undefined

npx nx g @spartan-ng/cli:healthcheck --autoFix

undefined