coss

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

coss ui

coss ui is a component library built on Base UI with a shadcn-like developer experience plus a large particle catalog.

coss ui 是一个基于 Base UI 构建的组件库，提供类似 shadcn 的开发者体验，同时拥有一个大型 particle 目录。

What this skill is for

此 skill 的用途

Use this skill to:

pick the right coss primitive(s) for a UI task
write correct coss usage code (imports, composition, props)
avoid common migration mistakes from shadcn/Radix assumptions
reference particle examples to produce practical, production-like patterns

使用此 skill 可以：

为 UI 任务选择合适的 coss primitive
编写正确的 coss 用法代码（imports、composition、props）
避免沿用 shadcn/Radix 假设时常见的迁移错误
参考 particle 示例，生成实用且接近生产环境的模式

Source of truth

权威来源

coss components docs:

apps/ui/content/docs/components/*.mdx

https://github.com/cosscom/ui/tree/main/apps/ui/content/docs/components

coss particle examples:

apps/ui/registry/default/particles/p-*.tsx

https://github.com/cosscom/ui/tree/main/apps/ui/registry/default/particles

coss particles catalog:
```
https://coss.com/ui/particles
```
docs map for agents:
```
https://coss.com/ui/llms.txt
```

coss 组件文档：

apps/ui/content/docs/components/*.mdx

https://github.com/cosscom/ui/tree/main/apps/ui/content/docs/components

coss particle 示例：

apps/ui/registry/default/particles/p-*.tsx

https://github.com/cosscom/ui/tree/main/apps/ui/registry/default/particles

coss particles 目录：
```
https://coss.com/ui/particles
```
面向 Agent 的文档映射：
```
https://coss.com/ui/llms.txt
```

Out of scope

不在范围内

Maintaining coss monorepo internals/build pipelines.
Editing registry internals unless explicitly requested.

维护 coss monorepo 内部实现或构建流水线。
除非明确要求，否则编辑 registry 内部实现。

Principles for agent output

Agent 输出原则

Use existing primitives and particles first before inventing custom markup.
Prefer composition over custom behavior reimplementation.
Follow coss naming and APIs from docs exactly.
Keep examples accessible and production-realistic.
Prefer concise code that mirrors coss docs/particles conventions.
Assume Tailwind CSS v4 conventions in coss examples and setup guidance.

优先使用现有 primitives 和 particles，而不是自行创建自定义 markup。
优先采用 composition，而不是重新实现自定义行为。
严格遵循文档中的 coss 命名和 API。
确保示例具备无障碍能力且贴近生产环境。
优先使用简洁且符合 coss 文档/particles 约定的代码。
在 coss 示例和安装指南中，假定采用 Tailwind CSS v4 约定。

Critical usage rules

关键使用规则

Always apply before returning coss code:

Do not invent coss APIs. Verify against component docs first.
For trigger-based primitives (Dialog, Menu, Select, Popover, Tooltip), follow each primitive's documented trigger/content hierarchy and composition API; do not mix patterns across components.
Preserve accessibility labels and error semantics.
Consult primitive-specific guides for component invariants and edge cases.
For manual install guidance, include all required dependencies and local component files referenced by imports.
Prefer styled coss exports first; use
```
*Primitive
```
exports only when custom composition/styling requires it.

Rule references (read on demand when the task touches these areas):

```
./references/rules/styling.md
```
— Tailwind tokens, icon conventions, data-slot selectors
```
./references/rules/forms.md
```
— Field composition, validation, input patterns
```
./references/rules/composition.md
```
— Trigger/popup hierarchies, grouped controls
```
./references/rules/migration.md
```
— shadcn/Radix to coss/Base UI migration patterns
```
./references/segmented-control.md
```
— choose Radio Group, links, Toggle Group, or Tabs before applying segmented-control styling
```
./references/portal-props.md
```
— optional
```
portalProps
```
on composed popups and toast providers (
```
keepMounted
```
,
```
container
```
, which surfaces support it)

返回 coss 代码前始终应用以下规则：

不要臆造 coss API。先对照组件文档进行验证。
对于 trigger-based primitives（Dialog、Menu、Select、Popover、Tooltip），遵循各 primitive 文档中定义的 trigger/content 层级与 composition API；不要混用不同组件的模式。
保留无障碍标签和错误语义。
查阅 primitive 专属指南，了解组件不变量（invariants）和边缘情况。
对于手动安装指南，包含 imports 所引用的所有必需依赖项和本地组件文件。
优先使用带样式的 coss exports；仅当自定义 composition/styling 有需要时，才使用
```
*Primitive
```
exports。

规则引用（当任务涉及以下领域时按需阅读）：

```
./references/rules/styling.md
```
— Tailwind tokens、图标约定、data-slot 选择器
```
./references/rules/forms.md
```
— Field composition、验证、input 模式
```
./references/rules/composition.md
```
— Trigger/popup 层级、分组控件
```
./references/rules/migration.md
```
— shadcn/Radix 到 coss/Base UI 的迁移模式
```
./references/segmented-control.md
```
— 在应用 segmented-control 样式前，选择 Radio Group、链接、Toggle Group 或 Tabs
```
./references/portal-props.md
```
— 组合式 popup 和 toast provider 的可选
```
portalProps
```
（
```
keepMounted
```
、
```
container
```
，以及哪些 surfaces 支持它）

Component discovery

组件发现

All 54 primitives have dedicated reference guides at

./references/primitives/<name>.md

. To find the right one for a task, consult the component registry index:

```
./references/component-registry.md
```

所有 54 个 primitives 都有位于

./references/primitives/<name>.md

的专属参考指南。若要查找任务对应的正确文件，请查阅组件 registry 索引：

```
./references/component-registry.md
```

Usage workflow

使用工作流

Identify user intent (single primitive, composed flow, form flow, overlay flow, feedback flow).
Consult
```
references/component-registry.md
```
to identify candidate primitives.
Select primitives from coss docs first; avoid custom fallback unless needed.
Check at least one particle example for practical composition patterns. Particle files live at
```
apps/ui/registry/default/particles/p-<name>-<N>.tsx
```
(e.g.
```
p-dialog-1.tsx
```
).
Write minimal code using documented imports/props.
Self-check accessibility and composition invariants.

确定用户意图（单一 primitive、组合流程、表单流程、overlay 流程、反馈流程）。
查阅
```
references/component-registry.md
```
以确定候选 primitives。
优先从 coss 文档中选择 primitives；仅在必要时采用自定义 fallback。
至少检查一个 particle 示例，了解实用的 composition 模式。Particle 文件位于
```
apps/ui/registry/default/particles/p-<name>-<N>.tsx
```
（例如
```
p-dialog-1.tsx
```
）。
使用文档化的 imports/props 编写最精简代码。
自检无障碍能力和 composition 不变量。

Installation reference

安装参考

See

./references/cli.md

for full install/discovery workflow.

Quick CLI pattern:

bash

npx shadcn@latest add @coss/<component>

Quick manual pattern:

install dependencies listed in the component docs page
copy required component file(s)
update imports to match the target app alias setup

有关完整的安装和发现工作流，请参阅

./references/cli.md

。

快速 CLI 模式：

bash

npx shadcn@latest add @coss/<component>

快速手动模式：

安装组件文档页面中列出的依赖项
复制必需的组件文件
更新 imports，以匹配目标应用的 alias 设置

Primitive Guidance

Primitive 指南

Every primitive has a reference guide at

./references/primitives/<name>.md

with imports, minimal patterns, inline code examples, pitfalls, and particle references. Use the component registry to find the right file.

High-risk primitives (read these guides first -- they have the most composition gotchas):

```
./references/primitives/dialog.md
```
— modal overlays, form-in-dialog, responsive dialog/drawer
```
./references/primitives/menu.md
```
— dropdown actions, checkbox/radio items, submenus
```
./references/primitives/context-menu.md
```
— right-click/long-press menus at the pointer
```
./references/primitives/select.md
```
— items-first pattern, multiple, object values, groups
```
./references/primitives/form.md
```
— Field composition, validation, submission
```
./references/primitives/input-group.md
```
— addons, DOM order invariant, textarea layouts
```
./references/primitives/toast.md
```
— toastManager (not Sonner), anchored toasts, providers

每个 primitive 都有一份位于

./references/primitives/<name>.md

的参考指南，其中包含 imports、最小模式、内联代码示例、常见陷阱和 particle 引用。使用 component registry 找到正确的文件。

高风险 primitives（请先阅读以下指南，因为它们最容易出现 composition 问题）：

```
./references/primitives/dialog.md
```
— 模态 overlay、dialog 中的 form、响应式 dialog/drawer
```
./references/primitives/menu.md
```
— 下拉操作、checkbox/radio 项、子菜单
```
./references/primitives/context-menu.md
```
— 指针位置的右键或长按菜单
```
./references/primitives/select.md
```
— items-first 模式、多选、对象值、分组
```
./references/primitives/form.md
```
— Field composition、验证、提交
```
./references/primitives/input-group.md
```
— 附加项、DOM 顺序不变量、textarea 布局
```
./references/primitives/toast.md
```
— toastManager（不是 Sonner）、锚定 toast、provider

Output Checklist

输出检查清单

Before returning code:

imports and props match coss docs
composition structure is valid for selected primitive(s)
accessibility and explicit control types (
```
button
```
,
```
input
```
, etc.) are present
migration-sensitive flows are verified (type/lint, keyboard/a11y behavior, and SSR-sensitive primitives like Select/Command)

返回代码前：

imports 和 props 与 coss 文档一致
所选 primitive(s) 的 composition 结构有效
包含无障碍支持和显式控件类型（
```
button
```
、
```
input
```
等）
已验证对迁移敏感的流程（type/lint、键盘/a11y 行为，以及 Select/Command 等对 SSR 敏感的 primitives）