shadcn/ui 并非依赖包而是分发机制：运行 npx shadcn@latest add 会把组件源码写入你的仓库，此后由你拥有。这带来三点影响：定制即直接编辑文件，而非从外部覆写；升级是需审阅的 diff，而非版本号变更；组件已由底层原语库与工具类 CSS 组合而成。
用途：把组件加入项目并保持更新；编辑已拥有的组件源码以新增变体、属性或行为；维护主题约定（背景/前景成对、OKLCH 值、@theme inline、暗色模式）；组合注册表提供的复合组件并选择重叠组件。
主要能力与用法：CLI 是访问注册表的接口，常用命令包括 npx shadcn@latest init、npx shadcn@latest add button card dialog、--diff 查看你的副本与注册表的偏离、npx shadcn@latest info 查看解析后的项目上下文。新增组件应使用 npx shadcn@latest add <name>，由 CLI 解析依赖、安装原语包、按 components.json 写入文件并重写导入别名。所有类名应经 cn() 处理且传入的 className 放最后，因为它按“后者胜出”解决 Tailwind 冲突。每个新背景色需搭配对应前景色，在 :root 与 .dark 中声明并通过 @theme inline 映射为工具类。表单布局使用 Field 系列（FieldLabel、FieldDescription、FieldError、FieldGroup、FieldSet、FieldLegend），它们是纯布局与无障碍接线，不持有值；旧式 Form/FormField 仍可用但绑定单一表单库。组件样式以变体映射声明，新增变体通过编辑自身源码中的映射完成。
限制：Field 不处理表单状态、校验与提交；工具类编写与 CSS 流水线、底层原语库属性与无障碍契约、通用变体映射技巧均不属本技能范围。缺少 components.json 时 CLI 命令会失败；背景色未配前景色、只加 :root 未加 .dark 或未做 @theme inline 映射、将 hsl() 套在 oklch() 外、按钮内嵌链接而非用 asChild、Select 未给 value 或 defaultValue 均会导致问题。