Agent Skills › MapleTechLabs/maple › coss

coss

GitHub

辅助正确使用coss UI组件库，涵盖组件选择、代码编写、shadcn迁移及故障排除。基于Base UI，强调组合优于自定义，遵循文档规范与无障碍标准，提供样式、表单及触发器规则参考。

.agents/skills/coss/SKILL.md MapleTechLabs/maple

Trigger Scenarios

使用 coss 原语构建 UI 从 shadcn/Radix 迁移到 coss 解决 coss 组件行为问题配置触发式叠加层

Install

npx skills add MapleTechLabs/maple --skill coss -g -y

More Options

Non-standard path

npx skills add https://github.com/MapleTechLabs/maple/tree/main/.agents/skills/coss -g -y

Use without installing

npx skills use MapleTechLabs/maple@coss

指定 Agent (Claude Code)

npx skills add MapleTechLabs/maple --skill coss -a claude-code -g -y

安装 repo 全部 skill

npx skills add MapleTechLabs/maple --all -g -y

预览 repo 内 skill

npx skills add MapleTechLabs/maple --list

SKILL.md

Frontmatter

{
    "name": "coss",
    "license": "MIT",
    "metadata": {
        "author": "cosscom"
    },
    "description": "Helps implement coss UI components correctly. Use when building UIs with coss primitives (buttons, dialogs, selects, forms, menus, tabs, inputs, toasts, etc.), migrating from shadcn\/Radix to coss\/Base UI, composing trigger-based overlays, or troubleshooting coss component behavior. Covers imports, accessibility, Tailwind styling, and common pitfalls.",
    "compatibility": "Requires Tailwind CSS v4 and @base-ui\/react. Designed for React projects using the coss component registry."
}

coss ui

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

What this skill is for

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

Source of truth

coss components docs: apps/ui/content/docs/components/*.mdx
- https://github.com/cosscom/coss/tree/main/apps/ui/content/docs/components
coss particle examples: apps/ui/registry/default/particles/p-*.tsx
- https://github.com/cosscom/coss/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

Out of scope

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

Principles for agent output

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.

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/portal-props.md — optional portalProps on composed popups (keepMounted, container, which wrappers support it)

Component discovery

All 53 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

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.

Installation reference

See ./references/cli.md for full install/discovery workflow.

Quick CLI pattern:

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

Primitive Guidance

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

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)