用途：为 Shade（Ghost 项目）中通过 ShadCN CLI 新增组件提供操作护栏。Shade 新组件多从 ShadCN 安装起步，而该 CLI 默认具有破坏性，因此需按此流程执行。
必要命令：pnpm dlx shadcn@latest add <component-name>。必须使用 pnpm，不要用 npx、yarn 或 bunx。
执行前：先切到新分支，否则 CLI 生成的 diff 会与分支改动混在一起。检查组件是否已存在于 apps/shade/src/components/ui/；若已存在，不要对仓库运行 CLI，而应生成到临时仓库再手动移植，因为 CLI 会提示覆盖并可能丢失 Shade 定制。
提示交互中：若询问是否覆盖已有文件，一律选择 No；若询问路径别名，保留 @/。
文件生成后的必要清理：把原始颜色替换为语义 token（如 bg-white、border-gray-200、text-zinc-500 换成 bg-surface-elevated、border-border-default、text-muted-foreground 等）；移除所有 dark: 颜色变体，语义 token 会自动切换；内部导入使用 @/ 别名而非相对路径；确保 default、hover、focus-visible、disabled 四种状态可用，只使用 focus-visible:，不要用 focus:；删除暗示特定界面的 props（如 isMembersPage、layoutMode），这类应抽成 Pattern；表单控件的边框、背景与焦点通过 inputSurface recipe 驱动；若尚无 <name>.stories.tsx 则补上，可从 https://ui.shadcn.com/docs/components/<name> 复制示例；必须使用 forwardRef 并通过 cn() 合并 className。
典型修正：bg-background dark:bg-background 改为 bg-background；bg-white text-zinc-950 dark:bg-zinc-950 dark:text-zinc-50 改为 bg-surface-elevated text-foreground；border-input 改为 border-control-border（表单控件）或 border-border-default（其他）；相对导入改为 @/ 别名。
不适用 CLI 的情况：组件已存在于 Shade（改为从临时仓库移植）；构建的是 Pattern（如 KpiCard、PageHeader，ShadCN 不提供）；构建的是 Recipe（纯 class 字符串函数，ShadCN 不提供）。事实来源为 Storybook 的 Overview / Contributing。