zard

zard/ui

一个 Angular 组件库。组件由 CLI 以源代码形式安装到用户的项目中——没有可供导入的运行时包，也无需 npm install 任何组件。

IMPORTANT： 每条 CLI 命令都要使用项目自己的包运行器：npx zard-cli、pnpm dlx zard-cli、yarn zard-cli 或 bunx zard-cli——根据 components.json 中的 packageManager 选择。以下示例使用 npx zard-cli；请替换为正确的运行器。

当前项目上下文

在进行任何操作之前，先阅读项目根目录下的 components.json。 该文件由 zard-cli init 写入，包含全部配置——没有可供调用的 zard-cli info 命令。

{
  "$schema": "https://zardui.com/schema.json",
  "style": "css",
  "icons": "lucide",
  "rtl": false,
  "projectType": "angular",
  "appConfigFile": "src/app/app.config.ts",
  "packageManager": "npm",
  "tailwind": { "css": "src/styles.css", "baseColor": "neutral" },
  "baseUrl": "src/app",
  "aliases": {
    "components": "@/shared/components",
    "utils": "@/shared/utils",
    "core": "@/shared/core",
    "services": "@/shared/services",
    "blocks": "@/shared/blocks"
  }
}

没有 components.json 说明项目尚未初始化——请运行 init，不要手动编写组件文件。

如果 components.json 存在，但已安装的组件源代码使用了重命名后的选择器或旧文件布局（例如 core/css/tailwind.css 而不是 core/css/zard.css、全局 CSS 中单独的 ::-webkit-scrollbar 代码块、按钮组使用 “divider” 而不是 “separator”，或使用 toast 文件夹而不是 sonner），则说明该项目早于当前 registry。此时应使用迁移技能，其中会准确列出所有重命名的选择器——不要猜测当前版本的结构。

对于该文件未说明的内容——有哪些组件、组件的 API 是什么、组件依赖什么——请阅读 registry 或使用 MCP 服务。切勿凭记忆还原组件 API。

关键字段

• aliases.components → 每个组件的导入前缀。请使用实际值；切勿硬编码 @/shared/components。前缀可以是任意值（如 @app/...、~/...）——它映射在 tsconfig.json 中，Nx 工作区则映射在 tsconfig.base.json 中。
• aliases.blocks → 区块（add dashboard-01、add login-01）所使用的导入前缀。在区块可安装之前写入的 components.json 中不存在此字段；重新运行 init 会添加该字段。
• baseUrl → 别名所对应的源代码根目录。组件会写入该目录。
• projectType → angular、angular-library、nx、nx-library 或 analog。此字段决定别名存放在哪个 tsconfig 中、Tailwind 在哪里配置，以及是否存在 app.config.ts。请参阅 cli.md。
• appConfigFile → 注册 provideZard() 的位置。在库中为空——由使用该库的应用注册。
• tailwind.css → 保存主题令牌的全局 CSS 文件。始终编辑此文件；切勿另建一个文件。
• tailwind.baseColor → 主题预设：neutral、stone、zinc、gray 或 slate。
• icons → 编写组件时使用的图标系列（当前为 lucide）。此字段决定 @ng-icons/* 包和符号名称。请参阅 rules/icons.md。
• rtl → 声明布局方向意图。此字段不会改变安装内容。
• packageManager → 所有依赖安装命令都使用该包管理器（例如 pnpm add date-fns，而不是 npm install date-fns），并据此选择 CLI 运行器。
• registryUrl → 可选。当项目从 https://zardui.com/r 以外的 registry 安装时，此字段会存在。请参阅 registry.md。

原则

1. 先安装，再导入。 只有在 zard-cli add 写入组件后，该组件才存在。先检查组件目录；不要导入不存在的组件。
2. 组合已有组件。 设置页面由 Card + Field + Input + Button 组成。仪表板由 Sidebar + Card + Chart + Table 组成。只有在没有合适组件时才使用自定义标记。
3. 优先使用变体，而不是类。 使用 zType="outline"、zSize="sm"，不要用 class 将组件重新设置为相同样式。
4. 只使用语义化令牌。 使用 bg-primary、text-muted-foreground。绝不使用 bg-blue-500，也绝不使用 dark: 颜色覆盖。
5. 你编写的代码也必须遵循库自身的约定。 使用独立组件、OnPush、input()、带 z 前缀的输入。参见 rules/angular.md。

关键规则

始终必须遵守。每项规则都链接到包含错误/正确示例的文件。

Angular API → rules/angular.md

• 使用独立组件，并配置 imports、ChangeDetectionStrategy.OnPush、ViewEncapsulation.None。 不使用 NgModules，也不使用 Default 变更检测。
• 信号输入：input()、model()、output()。 新代码中不使用 @Input() / @Output() 装饰器。
• 选择器为 z-<name> 和/或 [z-<name>]。 有些组件只能用作元素，有些则作为原生标签上的属性（input[z-input]、button[z-button]）。使用组件声明的选择器。
• 组合组件应导入其 Zard<Name>Imports 数组，而不是逐个导入各个类。
• 绝不编辑生成的输出。 apps/web/src/generated/** 和 public/r/*.json 是构建产物。

样式 → rules/styling.md

• 使用语义化令牌，绝不使用原始颜色。 使用 bg-primary，而不是 bg-blue-600。
• class 用于布局，不用于重新设置样式。 它会最后合并并覆盖其他类——这正是它不应用于覆盖组件自身颜色的原因。
• 使用 mergeClasses()，不要拼接字符串。 它使用 twMerge(clsx(...))；简单插值会丢失冲突解决逻辑。
• 不使用 space-x-* / space-y-*。 使用带 gap-* 的 flex。
• 宽度和高度相同时使用 size-*。 使用 size-4，而不是 w-4 h-4。
• 不使用 dark: 颜色覆盖。 令牌会自动切换。
• 仅使用 Tailwind v4。 没有 tailwind.config.js；主题定义在 CSS 中。
• scroll-fade 需要溢出容器；shimmer 仅用于文本。 两者都是 core 项目提供的纯 CSS 工具类。

组合 → rules/composition.md

• 使用完整的组合结构。 z-card 应包含 z-card-header / z-card-title / z-card-content / z-card-footer，不要把所有内容都塞进 content。
• 子项应放在所属分组中。 将 z-select-item 放在 z-select-group 内。
• 对话框、工作表、警告对话框和抽屉各有两种用法。 可以在模板中组合 z-dialog / z-sheet / z-alert-dialog / z-drawer，并使用 [(zVisible)] 以及标题、标题文本、描述和页脚子项；也可以通过 ZardDialogService / ZardSheetService / ZardAlertDialogService / ZardDrawerService 从代码中打开相同面板。绝不要通过手写 open 标志或 @if 来切换它们。
• Toast 应通过 ZardSonnerService 显示——使用 show、success、error、promise。
• 使用组件，而不是带样式的标记。 使用 z-separator，而不是 <hr>；使用 z-skeleton，而不是带 animate-pulse 的 div；使用 z-badge，而不是带样式的 span；使用 z-empty，而不是手动构建空状态。

表单 → rules/forms.md

• 支持 Angular 的全部三种表单 API：Signal Forms、Reactive Forms、Template-driven。遵循项目现有的用法。
• 表单布局使用 z-field-group + z-field，绝不使用带 space-y-* 的 div。
• 验证状态应通过字段上的 data-invalid 和控件上的 aria-invalid 表示。
• 错误应渲染在 z-field-error 中，不要使用单独的段落。

排版 → rules/typeset.md

• 渲染后的 Markdown 会使用 typeset 容器，不会为每个标签单独添加类。 zard-cli add typeset 会安装样式表。
• 它由 6 个变量控制，其中 3 个控制节奏：--typeset-size、--typeset-leading、--typeset-flow。
• 嵌入正文的组件都要添加 not-typeset。 该组件会使用自己的尺寸设置。
• 宽表格外层使用 typeset-scroll，而不是手动编写溢出包装器。
• 工具类可以覆盖它，无需使用 !important——每个元素选择器都位于 :where() 中。

图标 → rules/icons.md

• 图标来自 @ng-icons/<family>，并通过 viewProviders 中的 provideIcons 注册。 未注册的名称不会渲染任何内容，也不会提示。
• 图标系列由 components.json 中的 icons 指定。 不要假定它是 lucide。
• 组件内的图标不要设置尺寸类。 组件会为图标设置尺寸。

关键模式

// Host classes: computed + mergeClasses. Never assembled in the template.
protected readonly classes = computed(() => mergeClasses(cardVariants(), this.class()));

// Variants, not classes.
<button z-button zType="outline" zSize="sm">Save</button>   // correct
<button z-button class="border bg-transparent px-2.5">Save</button>  // wrong

// Spacing: gap-*, not space-y-*.
<div class="flex flex-col gap-4">   // correct
<div class="space-y-4">             // wrong

// Field: data-invalid on the field, aria-invalid on the control.
<div z-field [attr.data-invalid]="invalid || null">
  <label z-field-label for="email">Email</label>
  <input z-input id="email" [attr.aria-invalid]="invalid || null" />
  <z-field-error>Enter a valid email.</z-field-error>
</div>

// Loading button: the zLoading input, not a hand-rolled spinner.
<button z-button [zLoading]="saving()" [zDisabled]="saving()">Save</button>

组件选择

需求	使用
操作	z-button（zType：default、destructive、outline、secondary、ghost、link）
分组操作	z-button-group、z-toggle、z-toggle-group
文本输入	input[z-input]、textarea[z-textarea]、z-input-group、z-input-otp
选择	z-select、z-combobox、z-radio-group、z-checkbox、z-switch、z-slider
日期	z-calendar、z-date-picker
表单结构	z-field-group、z-field、z-field-label、z-field-description、z-field-error
数据展示	z-table、z-card、z-item、z-badge、z-avatar、z-chart
导航	z-navigation-menu、z-breadcrumb、z-tab-group、z-pagination
嵌套／树形列表	z-collapsible，嵌套使用——文件夹树应由一个 z-collapsible 放在另一个 z-collapsible-content 内组成，而非使用专用的树形组件。请参阅组合规则。
布局	z-sidebar（配合 z-sidebar-provider 和 z-sidebar-inset 使用）、z-separator、z-resizable、z-accordion、z-carousel
覆层	z-dialog（模态框）、z-drawer（底部／侧边抽屉）、z-sheet（侧边面板）、z-alert-dialog（确认框）——每种也可通过其服务从代码中使用——、z-popover、z-tooltip、z-dropdown
命令面板	z-command
反馈	ZardSonnerService（Toast）、z-alert、z-progress、z-skeleton、z-spinner
空状态	z-empty
聊天／消息	z-bubble、z-bubble-group、z-bubble-content、z-bubble-reactions
键盘提示	z-kbd
已渲染的散文	typeset + 一个预设类（样式表，而非组件）——请参阅 rules/typeset.md

名称均为注册表中的名称——也是 zard-cli add 接受的相同字符串。旧版注册表中的两个名称 tree 和 layout 已不再存在：layout 的页眉／内容／侧边栏结构已由上面的 sidebar 组件取代；tree 没有对应的替代组件——请按照上面的说明改为嵌套使用 z-collapsible。在移除这些名称之前安装的项目可能仍包含它们；请参阅迁移指南。

非组件条目

注册表中的名称并非都对应可用于满足 UI 需求的组件——有五项用于安装基础设施：

条目	说明	安装方式
core	共享指令、覆盖层堆栈、provideZard() 和主题 CSS	自动安装——init 会安装它；没有组件将其声明为依赖项
utils	mergeClasses()（twMerge(clsx(...))）	自动安装——与 core 相同
utilities	scroll-fade / shimmer CSS 工具类——参见 rules/styling.md	使用 zard-cli add utilities 安装，或随使用它们的组件一同安装
dark-mode	深色模式服务以及注入 index.html 的切换脚本	可选安装——zard-cli add dark-mode（交互式；需要 index.html 路径）
typeset	用于渲染 Markdown 的正文样式表	可选安装——zard-cli add typeset——参见 rules/typeset.md

工作流

1. 读取 components.json。 若文件不存在，运行 init。记下 aliases、baseUrl、icons、packageManager、projectType。
2. 检查已安装内容。 列出由 aliases.components 解析出的组件目录。不要重复添加已有内容，也不要导入不存在的内容。
3. 查找可用内容。 <registryUrl>/registry.json 中的注册表索引列出了所有条目；MCP 服务也通过 list-components 和 search-components 提供相同内容。
4. 编写代码前，先阅读实际 API。 使用 get-component-docs（MCP）或访问 https://zardui.com/docs/components/<name>.md。每个组件页面都以 Markdown 发布。臆测输入参数是最常见的失败原因。
5. 安装。 运行 npx zard-cli add <name>——组件的依赖项，包括 npm 包和其他注册表条目，都会一并解析并安装。
6. 检查写入的内容。 阅读新增文件。确认导入路径符合项目实际使用的别名，并确认图标系列与 icons 相匹配。
7. 切勿从 GitHub 手动获取组件源代码。 请使用 CLI 或注册表；项目实际安装来源就是注册表。

快速参考

# Initialise a project (full-screen wizard).
npx zard-cli init
npx zard-cli init --type nx --project web        # answer the wizard up front
npx zard-cli init --yes                          # accept the defaults; required without a TTY

# Add components.
npx zard-cli add button card dialog
npx zard-cli add                                 # pick from the list
npx zard-cli add --all
npx zard-cli add button --overwrite              # replace local changes — ask first
npx zard-cli add button --path src/app/ui        # a directory other than the configured one

# Diagnose.
npx zard-cli add button --debug
npx zard-cli --version

没有 search、view、diff、info 或 build 命令——这些是 shadcn 的命令。完整的标志参考请参见 cli.md。

详细参考

• cli.md — init 和 add、所有标志、五种项目类型、无头模式行为
• registry.md — 索引、条目和图标目录格式、JSON Schema、指定自己的注册表
• mcp.md — 九个 MCP 工具、连接方式、ZARD_REGISTRY_URL / ZARD_DOCS_URL
• customization.md — 主题令牌、CVA 变体、mergeClasses、扩展组件
• rules/angular.md — 独立组件、input()、OnPush、ViewEncapsulation.None、选择器
• rules/styling.md — Tailwind v4、语义令牌、mergeClasses、变体优先于原始类、scroll-fade / shimmer 工具
• rules/composition.md — 优先使用现有内容进行组合，而非自行编写标记
• rules/forms.md — Signal Forms、Reactive Forms、模板驱动表单
• rules/icons.md — ng-icons、provideIcons、目录、可配置系列
• rules/typeset.md — 使用一个容器类为渲染后的 Markdown 设置样式，而不是为每个标签单独设置
• ../zard-migration/SKILL.md — 为已安装组件源码早于当前注册表的项目提供的独立技能（重命名选择器、--overwrite、core/utils/utilities 拆分）