shark-ui

Shark UI

Shark UI 是一个基于 Ark UI 构建的组件注册表，提供类似 shadcn 的开发体验（npx shadcn@latest add @shark/<component>）。

请使用项目的包运行器运行 CLI 示例（npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx shadcn@latest）——与 packageManager / 团队约定保持一致。

此技能的用途

使用此技能来：

• 为 UI 任务选择合适的 Shark 原语
• 编写正确的用法代码（导入、组合、属性），并遵循 Shark 封装的 Ark UI 模式
• 避免未经查证 Shark 文档和示例，就假设 API 与 Radix/shadcn 相同
• 将注册表示例作为了解组件组合方式的首要参考

原则

1. 优先使用现有组件。 优先选择 Shark 原语和 registry/react/examples/，而不是自定义 UI。请使用 references/component-registry.md。
2. 组合使用，而非重新发明。 设置类流程组合文档中介绍的部分（例如 Tabs + Card + Field）；仪表板使用 Sidebar、Table、图表——遵循仓库内的示例。
3. 先用内置变体，再用自定义类。 优先使用 variant、size 和语义令牌，再重设原语样式（参见 references/rules/styling.md）。
4. 使用语义颜色。 使用 bg-primary、text-muted-foreground、border-input，而非在产品 UI 中使用原始调色板工具类。

事实来源

• 组件文档：content/docs/components/*.mdx
• 注册表示例：registry/react/examples/<component>/example-*.tsx
• 实现：registry/react/components/<component>.tsx
• 已发布的注册表项：public/r/<name>.json（由 registry/manifest/<name>.ts 构建）
• 面向 LLM 的路由：app/(llms)/ 和 lib/llms.ts
• 仓库约定：AGENTS.md

不在范围内

• Next.js 应用路由、营销页面，以及非注册表应用代码，除非用户明确提出要求。
• 手动编辑生成的 public/r/*.json，除非用户明确提出要求。

关键规则

Shark 输出始终必须遵循以下规则。各节链接到更详细的指南，其中包含适用的错误/正确模式。

样式与 Tailwind → references/rules/styling.md

• className 用于布局，而非临时重设样式——优先为原语使用变体和语义令牌。
• 不要使用 space-x-* / space-y-*。 使用 flex / grid + gap-*。
• 宽度与高度相同时使用 size-*——图标和正方形控件优先使用它，而不是成对使用 w-* / h-*。
• 使用 truncate 简写——不要使用 overflow-hidden text-ellipsis whitespace-nowrap。
• 语义令牌已能满足需求时，不要手动配对设置 dark: 调色板类。
• 条件类或合并类使用来自 @/lib/utils 的 cn()。
• 不要在覆盖层上手动设置 z-index——Dialog、Sheet、Drawer、AlertDialog、Menu、ContextMenu、Popover、Tooltip、HoverCard 等会自行处理堆叠顺序。

表单与输入 → references/rules/forms.md

• 表单布局使用 FieldGroup + Field——不要使用原始 div + space-y-*。
• 使用 InputGroup + InputGroupInput / InputGroupTextarea——不要在分组内直接使用原始 Input / Textarea。
• 附加项——输入框旁的操作使用文档中的 InputGroup + InputGroupAddon 模式。
• 小型选项集（2–7 个）——优先使用 ToggleGroup + ToggleGroupItem，而不是循环渲染 Button 并手动设置激活样式。
• 分组复选框/单选框使用 FieldSet + FieldLegend——参见 Field 文档。
• 验证——在 Field 上设置 invalid，它会自动传递给控件；禁用模式请遵循表单指南。

表单与验证 → references/rules/forms.md

组件结构与组合 → references/rules/composition.md

• 将项目放在正确的父级中 — 遵循每个基元的结构（例如，按文档所述将列表行放在集合／列表部件中）。
• 触发器 — 按照 Shark 模式，为每个触发器使用 asChild，并且只包含一个子元素（Button、a）；不要在触发器上使用 render={...}（参见 references/rules/migration.md）。
• 叠加层需要标题 — 为满足无障碍要求，使用 DialogTitle、SheetTitle 等；若标题在视觉上隐藏，请使用 className="sr-only"。
• 复合组件 — 像 MDX 中那样使用导出的部件（CardHeader、TabsList + TabsTrigger 等）；除非该基元本就刻意设计得很精简，否则不要把所有内容塞进单个插槽。
• TabsList 中的 TabsTrigger — 绝不要将未包裹的触发器直接放在 Tabs 根节点下。
• Avatar + AvatarFallback — 始终提供备用内容，以应对图片加载失败。

使用组件，而非一次性标记

• 当用例符合文档说明时，优先使用 Alert、Separator、Skeleton、Badge（以及其他基元），而不是自定义样式的 div。
• Toast — 遵循 Shark toast／文档中的模式；除非确有需要，否则不要手动编写通知 DOM。

图标

• 装饰性图标请遵循 AGENTS.md 和 references/rules/styling.md 中的说明（aria-hidden、示例中的尺寸）。
• 在产品 UI 中，采用该组件注册表示例和 MDX 中使用的图标方案。

Shark 专属要求（始终遵守）

• 不要臆造 Shark 或 Ark API —— 请从 MDX 和 registry/react/components/<name>.tsx 中确认。
• Combobox（及类似组件）：使用 useFilter + useListCollection、collection 属性、从 onInputValueChange 调用 filter(inputValue)，并在列表中使用 collection.items.map(...)（AGENTS.md）。
• Select／listbox 配合集合使用时：按示例使用 createListCollection／useListCollection。
• 图表：使用 ChartTooltip，并设置 content={(props) => <ChartTooltipContent {...props} />}；不要为 tooltip 属性提供桩实现；静态预览可选用 accessibilityLayer={false}（AGENTS.md）。
• Sidebar 文档预览：使用 absolute inset-0 overflow-hidden，为 Sidebar 设置 className="absolute"，为 SidebarProvider 设置 h-full；当 ScrollArea 破坏布局时，使用原生 overflow-y-auto（AGENTS.md）。

组件发现

请参阅 references/component-registry.md，查看完整列表及指向 ./references/primitives/<name>.md 的链接。

使用工作流

1. 确定意图（叠加层、表单、集合控件、图表等）。
2. 打开 references/component-registry.md；若存在目标文件，再打开 ./references/primitives/<name>.md。
3. 阅读 content/docs/components/<name>.mdx，了解安装、结构、API 和 Ark 文档链接。
4. 至少打开一个 registry/react/examples/<component>/example-*.tsx。
5. 如果行为不明确，请阅读 registry/react/components/<component>.tsx，了解 Ark 导入项和属性透传方式。
6. 在使用组件的应用中，避免重复添加 resolvedPaths 下已有的组件。
7. 自行检查无障碍支持、受控与非受控状态、SSR／延迟挂载默认值，以及上方的 关键规则。

更新／比较安装内容

将上游 CLI 输出与本地修改合并时，请先对每个文件使用 npx shadcn@latest add @shark/<component> --dry-run 和 --diff；未经用户明确批准，绝不要使用 --overwrite 覆盖文件。请参阅 references/cli.md。

安装参考

请参阅 references/cli.md。

npx shadcn@latest add @shark/<component>

高组合度基元

处理叠加层、集合或应用界面框架时，请先阅读以下指南：

• ./references/primitives/dialog.md
• ./references/primitives/sheet.md
• ./references/primitives/menu.md
• ./references/primitives/context-menu.md
• ./references/primitives/popover.md
• ./references/primitives/select.md
• ./references/primitives/combobox.md
• ./references/primitives/field.md
• ./references/primitives/sidebar.md

详细参考资料

• references/rules/styling.md — 语义颜色、变体、className、间距、size-*、truncate、深色模式、cn()、z-index
• references/rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、验证
• references/rules/composition.md — 触发器/内容层级、asChild、复合部件
• references/rules/migration.md — Radix/shadcn 习惯与 Shark/Ark（render → asChild 等）的差异
• references/cli.md — CLI 命令、@shark/*、dry-run / diff
• 主题设置 / CSS 变量 — content/docs/(root)/styling.mdx 和 content/docs/(root)/ 中的安装文档

输出检查清单

返回代码前：

• 导入和属性与 Shark 文档和/或源代码一致
• 组合方式符合 Shark 中使用的 Ark 模式（触发器、集合对象）
• 表单中的按钮显式设置 type；控件已关联标签
• 适用时，combobox/select 示例使用集合 + 过滤模式
• 关键规则（样式、表单、组合、CLI）均已满足