shadcn/ui

shadcn/ui 表示项目采用官方 shadcn/ui 风格的 checked-in component layer：components.json、@/components/ui aliases、Radix primitives、Tailwind utilities、class-variance-authority、tailwind-merge、clsx 和 Lucide icons 共同构成组件约定。官方名称保留 slash，因此 Topic token 也写作 shadcn/ui。

这个 Topic 的重点是 open-code component ownership：组件源码在项目里，维护者需要审查 variants、tokens、accessibility state、dark/light theme、表单语义和复用边界。它不是 npm 组件库标签，也不是“看起来像 shadcn”的视觉判断；必须有 components.json 或项目快照中的 checked-in UI layer 证据（projects/proxy-broker.md、projects/kaisoumail.md）。

当 repo 里有 components.json 指向 ui.shadcn.com/schema.json，或项目 snapshot 明确引用 checked-in components/ui 组件层时使用。不要仅因视觉风格相似或使用 Radix/Tailwind 就套用。

如果改动触及按钮、表单、Dialog、Popover、Sidebar、Table、Toast、Theme、icon button 或 Tailwind/CVA 变体，应使用本 Topic。若项目只是使用 Radix primitive、Tailwind utilities 或 Lucide icons，但没有 shadcn/ui 组件层与 alias contract，应保留在 React app 或 TypeScript web 范畴（projects/flux-purr.md）。

• 把 shadcn/ui 当 open-code 组件层维护，组件源码归项目所有，不能当黑盒 npm 组件库。
• 组件系统 Topic 与 React app 正交；React 是 runtime，shadcn/ui 是组件组合约定。
• Storybook component QA/a11y 应覆盖重要组件状态，尤其是 Dialog、Popover、Table、Form、Sidebar。
• 保持官方大小写和 slash，不写成 Shadcn UI、shadcnui 或 repo/path 名。
• 新增组件默认遵守项目已有 open-code 习惯：少造新抽象，优先扩展现有 components/ui、tokens 和 variants；只有跨多个页面反复出现的复杂行为才提升为新组件（projects/proxy-broker.md）。
• 组件变更应同步 Storybook 或可控视觉证据，尤其是 owner-facing 管理台、设备控制台和操作型表单；只凭 DOM 快照或类型检查不足以证明交互状态正确（projects/kaisoumail.md、projects/flux-purr.md）。
• 默认先看 components.json 和别名约定，再谈视觉层。radix-nova、new-york、Tailwind CSS variables、icon 选择和 @/components/ui alias 都是维护契约，不是无关配置（projects/xp.md、projects/flux-purr.md）。
• 对 shadcn/ui 组件的修改，要把“这个组件是在表达设计 token，还是在表达业务语义”分开。业务型 Console 组件常常需要同时保留组件层可复用性和产品上下文，不能一把全推回通用 Button/Card。

• projects/proxy-broker.md：operator console 使用 shadcn/ui、Storybook a11y 和 Playwright。
• projects/kaisoumail.md：Cloudflare control plane 采用 React + shadcn/ui。
• projects/flux-purr.md：设备控制台用 web/components.json 固定 aliases 和 Lucide。
• projects/xp.md：cluster manager admin UI 使用 radix-nova style。
• skills/style-playbook/references/topics/storybook-component-qa/TOPIC.md：说明 shadcn/ui open-code 组件层为什么需要 Storybook 状态枚举和截图/interaction gate。
• skills/style-playbook/references/topics/storybook-accessibility/TOPIC.md：说明 Dialog、Popover、Form 等组件为什么需要 a11y addon 作为早期筛查。

• 把 shadcn/ui 命名随意大小写，会让 Topic 看起来草率。
• 只打 React app 不打 shadcn/ui，会丢失组件系统约定。
• 复制组件后不维护 Storybook/visual states，会让 open-code 组件层变成不可审查资产。
• 直接从别的项目复制组件但不调整 tokens、aliases、theme 和交互状态，会制造“看起来能用、维护时失控”的 UI 层。修正方式是回读 components.json、components/ui 和对应 Storybook 证据（projects/proxy-broker.md）。
• 把官方名称写成随意大小写或去掉 slash，会破坏 Topic 命名规范；本知识库保留官方 shadcn/ui 写法，并用 slug shadcn-ui 作为机器 ID（skills/style-playbook-write/SKILL.md）。
• 把 shadcn/ui 当“现成模板”而不是项目自有组件层，会让后续维护者回避必要的源码重构。这个 Topic 的前提就是 open-code ownership，不能只会复制、不会治理。

• projects/proxy-broker.md
• projects/kaisoumail.md
• projects/flux-purr.md
• projects/xp.md
• skills/style-playbook-write/SKILL.md