spartan

spartan/ui

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

• Brain（@spartan-ng/brain） - 无障碍、无样式的原语（Angular 指令/组件）， 从 npm 安装。这一层负责行为和无障碍支持。
• Helm（@spartan-ng/helm） - 带样式的一层（Tailwind + class-variance-authority）。CLI 会将 Helm 代码 复制到用户的项目中，因此用户拥有这些代码并可自行定制。

你可以将 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>。

当前项目上下文

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

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 （该命令会安装依赖和主题）。添加第一个组件时会创建 components.json（参见 cli.md）。

原则

1. 优先使用现有组件。 检查 installedComponents，然后查看 availableComponents。通过 MCP 服务（spartan_components_list / spartan_components_get）或在线文档 https://www.spartan.ng/components/<name> 查阅文档。参见 mcp.md。
2. 组合使用，不要重新实现。 使用现有的 Helm + Brain 组件构建仪表板、表单和对话框，而不是编写自定义标记。
3. 先使用内置变体，再添加自定义样式。 按钮、徽章、警告提示等都提供 variant 和 size 输入项——请使用这些选项，而不要覆盖类。
4. 使用语义化颜色，切勿使用原始值。 使用 bg-primary text-primary-foreground，不要使用 bg-blue-500。参见 rules/styling.md。

关键规则

开始相关工作前，请先阅读规则文件：

• rules/styling.md - hlm() 工具函数、语义颜色令牌、仅用于布局的类、使用 gap-* 而非 space-*、size-*、深色模式，以及覆盖层中不得手动设置 z-index。
• rules/forms.md - 使用 hlmField（标签、控件、错误、说明）组合表单；在原生 <fieldset>/<legend> 上使用 hlmFieldSet / hlmFieldLegend；选项组（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-copy-in 分发模型、components.json，以及固定的组件目录（已发布的 CLI 不使用远程或自定义注册表）。
• customization.md - 通过 hlm-tailwind-preset.css、CSS 变量、ui-theme 生成器以及扩展复制的 Helm 组件进行主题定制。
• mcp.md - 使用 @spartan-ng/mcp 工具、资源和提示词进行发现。

关键模式

<button hlmBtn variant="destructive" size="lg">Delete</button>


<button hlmBtn size="icon" variant="ghost">
	<ng-icon name="lucideTrash" />
</button>


<button hlmBtn [disabled]="loading()">
	@if (loading()) {
	<hlm-spinner />
	} Save
</button>


<div class="flex items-center gap-2">
	<span hlmBadge variant="secondary">beta</span>
</div>

组件选择

需求	组件
操作 / 按钮	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
数据展示	chart、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

工作流

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

快速参考

# 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