shadcn-ui

shadcn-ui 技能概览

shadcn-ui 的用途

shadcn-ui 技能可以帮助你在真实应用中规划、安装并调整 shadcn/ui 组件，而不是把它当成现成可直接接入的库来用。它最适合需要实用型 shadcn-ui 指南的开发者，尤其是在 Design Implementation 场景下：选择合适的组件、串联依赖关系，并把复制进来的代码改造成适配现有产品的实现。

这个技能为什么不一样

shadcn/ui 是直接复制到你的代码库里的，所以核心问题不是“我要 import 哪个包”，而是“我该如何安装合适的组件，并在之后掌握它的实现”。当你在意自定义能力、基于 Tailwind 的样式、Radix 或 Base UI primitives，以及避免黑盒式 UI 行为时，这个 shadcn-ui 技能尤其有用。

最适合的使用场景

当你需要 shadcn-ui 安装帮助、组件发现、模式选择，或者为表单、表格、登录流程、布局和可复用 UI 块寻找安全起点时，就适合用它。如果你只是想要一个纯视觉稿、没有代码库上下文，或者你的技术栈并不支持 React、Tailwind 和组件复制工作流，那么它就没那么适合。

如何使用 shadcn-ui 技能

正确安装并触发它

使用以下命令安装 shadcn-ui 技能：
npx skills add google-labs-code/stitch-skills --skill shadcn-ui --global

然后在任务中明确应用上下文、目标组件和期望行为来调用它。高质量提示词会清楚说明框架、路由模型、样式约束，以及你是只要安装、只要自定义，还是两者都要。

给它足够准确的输入

低质量提示词会说“加一个按钮”。更好的提示词会说：“在我的 Next.js 应用里，为注册页安装 shadcn-ui 的 button、card 和 form 组件，保持 Tailwind classes 与我们的中性色主题一致，并展示需要修改的文件。”这种细节能帮助技能选对组件，避免输出过于泛化。

先阅读这些文件

先从 SKILL.md 看工作流，然后再检查 README.md、resources/component-catalog.md、resources/setup-guide.md、resources/customization-guide.md 和 resources/migration-guide.md。再看 examples/form-pattern.tsx、examples/data-table.tsx 和 examples/auth-layout.tsx，了解 shadcn-ui 在真实应用模式中的用法。

采用以组件为中心的工作流

使用 shadcn-ui 时，先确认组件类别，再核对依赖，然后查看示例模式，最后才把代码适配到你的应用里。如果你是在做 Design Implementation，最好一开始就描述布局目标、状态和约束，因为这个技能最擅长把产品意图转成组件组合。

shadcn-ui 技能常见问题

如果我已经会 shadcn/ui，还需要 shadcn-ui 技能吗？

需要，尤其是在你想更快做出安装决策、减少实现错误的时候。shadcn-ui 技能不只是帮你复述文档；它会帮你从“有哪些组件”推进到“我应该在代码库里复制什么、配置什么、改什么”。

shadcn-ui 只适合 Next.js 吗？

不是。它的工作流以 React 为核心，但这个技能关注的是组件所有权和集成方式，而不是某一个单独框架。它在已经使用 Tailwind CSS、并且可以接受本地组件文件的项目里最强。

shadcn-ui 最大的边界是什么？

它不是托管式组件库。如果你的团队期待像 package 一样升级、尽量少的本地代码，或者不想使用 Tailwind 的视觉系统，那么 shadcn-ui 可能并不合适。只有当代码所有权和定制化 Design Implementation 比集中式库管理更重要时，它才最适合。

shadcn-ui 对新手友好吗？

算是中等友好。新手可以用它处理常见 UI 模式，但仍然需要理解文件放置、样式 token 和组件组合方式。最快的路径是先从一个简单组件开始，并在扩展到更大的表单或表格之前先验证安装是否成功。

如何改进 shadcn-ui 技能

指定设计目标，不要只说组件名

更好的输入会带来更好的 shadcn-ui 输出。不要只说“做一个 modal”，而要说“做一个用于删除团队的破坏性确认对话框，包含警告状态、取消按钮和提交中的 loading 状态”。这样技能才能知道实现时该优化什么。

尽早说明你的技术栈和约束

当你提到框架、是否使用 TypeScript、Tailwind 配置、app router 还是 pages router，以及是否使用 Radix UI 或 Base UI primitives 时，这个技能会表现得更好。这些细节会影响 shadcn-ui 的安装步骤、依赖选择，以及输出需要做多少适配。

直接说明你想要的实现路径

如果你想要快速落地，就要求最小化安装加第一页屏。如果你想走设计系统路线，就要求可复用变体、token 对齐，以及任何共享布局 primitives。这样可以避免技能给你太少代码，或者给出过度抽象的内容。

以可运行的基础版本为起点迭代

先用第一次结果确认组件结构，然后再细化间距、变体、可访问性标签，以及空状态/错误状态/loading 状态。最常见的失败模式是 UI 意图描述不够具体，所以最有效的改进通常是第二轮提示更精准，而不是更长。