ttstd-infinite-canvas/web/src/components/ui/README.md

Celadon UI 组件层

web/src/components/ui/ 下的自研组件层。规范全文见仓库 docs/plans/ui-design-system.mdx（组件编写规范）与 docs/plans/ui-kit-rollout-plan.mdx（实施计划）、决策记录 docs/adr/0008-ui-component-layer-antd-replacement.md。本文是目录内速查版。

分层

层	目录	内容
base	ui/base/	原语 + 基础件：buttons/、badges/、kbd/、segmented-control/ 等
product	ui/product/	跨页面模式件：empty-state/、callout/、loading-state/、section-card/、property-row/
fx	ui/fx/	特效件（原 aceternity/* 归位至此命名空间，引用随用随迁，不重写）
application	ui/application/	产品块（P3 起）：agent-chat、notification-center、app-shell 等

视觉数值唯一权威源：composio-brand-package（仓库根同级兄弟目录），消费规则见实施计划 §2.4。

目录与导出

• 每"族"一目录（base/badges/），族内按文件拆变体；族级 index.ts 汇总导出（组件 + XxxVariants 类型）；无全局 barrel。
• 导入一律深路径 @/components/ui/<layer>/<family>；组件 PascalCase、文件 kebab-case.tsx、目录 kebab-case/。
• 变体用 cva（class-variance-authority）定义并从 index.ts 导出类型；className 经 cn 合并；ref 转发；根元素 data-slot。

硬性纪律

1. 样式只消费三层 token（var(--*) 或经 @theme 映射的工具类，如 bg-surface、text-caption、text-status-success）；禁止裸 text-[Npx]/rounded-[Npx]/十六进制色值。字号/行高用注册排版工具类或 token 引用。
2. 明暗自适应由 CSS 变量完成，不读皮肤 ID；持久切换 aria-pressed + data-active，保留 :focus-visible，尊重 prefers-reduced-motion。
3. 图标以 lucide 组件引用传入（icon={Move}），尺寸/颜色由宿主组件决定，禁止调用方传 icon className 改尺寸。
4. 组件头注释注明：用途、消费 token 组、对标/接管对象（AntD 组件或参考系统组件）、明暗差异要点。

进库门槛

新组件必须满足其一：① ≥2 处真实重复（PR 附 grep 证据）；② 隔离明确协议/交互契约。纯透传壳不进库。

当前族目录

• base/kbd/ — Kbd（快捷键提示键帽）
• base/badges/ — StatusBadge（状态点徽章；NodeTypeBadge 规划中）
• base/buttons/ — IconButton / ToolButton（IconButton 含 ghost/default/outline/solid/danger 变体；ButtonGroup 规划中）
• base/segmented-control/ — SegmentedControl（分段单选，thumb 滑动，泛型 + block/size）
• base/checkbox/ — Checkbox + CheckboxGroup（原生 input + 自绘 glyph，checked/indeterminate/bare）
• base/select/ — Select（RAC 单选壳，value/options/allowClear；多选/搜索 ComboBox 待建）
• base/tooltip/ — Tooltip（RAC 浮层，AntD 8 向 placement 映射，title 空不渲染）
• base/switch/ — Switch（button role=switch + data-state，checkedChildren 文本轨、loading、Form.Item 注入）
• product/empty-state/ — EmptyState（空态占位）
• product/callout/ — Callout（规划中，P0）
• base/badges/ — StatusBadge（状态点徽章；NodeTypeBadge 规划中）
• product/empty-state/ — EmptyState（空态占位）
• product/callout/ — Callout（规划中，P0）
• base/buttons/ — IconButton / ToolButton / ButtonGroup（规划中，P0）