open-slide 中的 shadcn/ui 组件管理实战：Agent 驱动的 UI 添加、搜索、修复与组合规范

【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载本文以 open-slide 仓库内置的 shadcn Skill 文档 为核心系统讲解如何在项目中通过shadcnCLI 管理 UI 组件——从info注入项目上下文、search检索注册表、add安装与智能合并到样式、表单、组合、图标、聊天 UI 六大类强制规则。读完你既能掌握完整的 shadcn CLI 工作流也能理解 open-slide 自身在 components.json 与packages/core/src/app/components/ui/中是如何落地这套规范的。一、Skill 定位面向 Agent 的 shadcn/ui 操作规范在 open-slide 的.agents/skills/目录中shadcn是一个**用户不可手动调用user-invocable: false**的 Agent Skill其职责明确写在元信息中管理 shadcn 组件与项目——添加、搜索、修复、调试、样式化与组合 UI含聊天界面。触发场景包括处理 shadcn/ui、组件注册表、preset 代码或任何带有components.json的项目以及 shadcn init、用 --preset 创建应用、切换到 --preset 等操作。它向 Agent 开放的工具只有三类见.agents/skills/shadcn/SKILL.md的allowed-toolsBash(npx shadcnlatest *)Bash(pnpm dlx shadcnlatest *)Bash(bunx --bun shadcnlatest *)运行器选择是贯穿全文的第一原则所有 CLI 命令必须使用项目packageManager对应的运行器——npx shadcnlatest、pnpm dlx shadcnlatest或bunx --bun shadcnlatest。文档示例统一用npx shadcnlatest实际使用时应按项目替换。同时文档明确警告只使用文档列出的 flags不要凭空猜测参数——例如 CLI 会从锁文件自动检测包管理器因此不存在--package-manager这个 flag。二、项目上下文注入一切判断的起点Skill 在激活时会注入当前项目的 JSON 上下文对应npx shadcnlatest info --json的输出其中包含项目配置与已安装组件列表。在任何创建、修复、调试、使用组件的操作前都应先运行npx shadcnlatest docs component获取文档与示例 URL 并抓取内容而不是靠猜。info输出中的关键字段决定了代码怎么写详见.agents/skills/shadcn/SKILL.md的 Key Fields 一节字段含义与影响aliases导入别名前缀如/、~/永远不要硬编码别名isRSC为true时使用useState、useEffect、事件处理器或浏览器 API 的组件需在文件顶部加use clienttailwindVersionv4用theme inline块v3用tailwind.config.jstailwindCssFile全局 CSS 文件自定义 CSS 变量必须写在这里不得新建 CSS 文件style组件视觉风格如nova、vegabase底层原语库radix或base决定组件 API 与可用 propsiconLibrary图标库决定图标导入来源lucide→lucide-react、tabler→tabler/icons-react等不要假定是 lucide-reactresolvedPaths组件、工具、hooks 等落盘的确切文件系统路径framework路由与文件约定Next.js App Router vs Vite SPApackageManager所有非 shadcn 依赖安装都用它pnpm add date-fnsvsnpm install date-fnspreset当前项目已解析的 preset 代码与值只需要 preset 信息时用preset resolve --jsoninfo的完整字段参考见 cli.md —info命令其中还细化了framework、frameworkVersion、isSrcDir、isTsx、aliasPrefix等项目信息字段以及components.json中的base、style、tailwind.config、tailwind.css、iconLibrary、aliases.*、resolvedPaths、registries等配置字段。仓库实证open-slide 自身的 packages/core/components.json 展示了典型配置——style: new-york、tsx: true、rsc: false、全局 CSS 位于src/app/styles.css、别名映射为/components、/lib/utils、/components/ui、/lib、/hooks图标库为lucide。与之呼应packages/core/package.json 的依赖里可以看到shadcn ^4.12.0、lucide-react、sonner、base-ui/react、tailwindcss ^4.3.3等实际落地的库。三、四条设计原则先查、先组、先用、语义化Skill 的 Principles 一节定义了四条总纲优先使用已有组件写自定义 UI 前先用npx shadcnlatest search检查注册表含社区注册表避免重复造轮子。组合而非重造设置页 TabsCard 表单控件Dashboard SidebarCardChartTable。优先内置 variantsvariantoutline、sizesm等而不是手写样式。使用语义化颜色bg-primary、text-muted-foreground绝不用bg-blue-500这类裸值。四、六大类 Critical Rules始终强制执行的规范以下规则总是生效每条都对应一个带 Incorrect/Correct 代码对的规则文件。4.1 样式与 Tailwindrules/styling.mdclassName只用于布局如max-w-md、mx-auto绝不覆盖组件颜色或排版改颜色优先走 variants → 语义 token → CSS 变量三级路径。禁用space-x-*/space-y-*用flexgap-*纵向堆叠用flex flex-col gap-*。宽高相等时用size-*size-10而非w-10 h-10适用于图标、头像、骨架屏等。文本截断用truncate简写而非overflow-hidden text-ellipsis whitespace-nowrap。不手写dark:颜色覆盖语义 token 通过 CSS 变量天然处理明暗主题用bg-background text-foreground而非bg-white dark:bg-gray-950。条件类名用cn()工具函数不在 className 字符串里手写模板三元表达式。不给覆盖层组件手加z-indexDialog、Sheet、Popover 等自带层级管理无需z-50或z-[999]。加载态文字用shimmer工具类滚动容器边缘淡出用scroll-fade含scroll-fade-x/scroll-fade-b不手写keyframes或 mask 渐变——聊天组件内部已自动应用。4.2 表单与输入rules/forms.md表单布局必须用FieldGroupField绝不用裸divspace-y-*或grid gap-*。InputGroup内部必须用InputGroupInput/InputGroupTextarea不能直接放裸Input/Textarea。输入框内的按钮用InputGroupInputGroupAddon组合。2–7 个选项的选择集用ToggleGroup不要用循环Button加手动 active 状态。关联的复选框/单选/开关分组用FieldSetFieldLegend不用div加标题。校验状态双管齐下data-invalid加在Field上、aria-invalid加在控件上禁用态同理data-disabled加在Field、disabled加在控件上。这套规则适用于Input、Textarea、Select、Checkbox、RadioGroupItem、Switch、Slider、NativeSelect、InputOTP全部控件。控件选型速查表来自 rules/forms.md需求用简单文本输入Input预定义下拉Select可搜索下拉Combobox无 JS 的原生 selectnative-select布尔开关Switch设置页/Checkbox表单少量单选RadioGroup2–5 个选项切换ToggleGroupToggleGroupItemOTP/验证码InputOTP多行文本Textarea4.3 组件结构rules/composition.md条目永远放在对应的 Group 里SelectItem→SelectGroup、DropdownMenuItem→DropdownMenuGroup、CommandItem→CommandGroup聊天组件还有MessageScrollerItem→MessageScrollerContent、Message→MessageGroup、Bubble→BubbleGroup、Attachment→AttachmentGroup等对应关系。自定义触发器用asChildradix或renderbase具体用哪个看info输出的base字段详见 base-vs-radix.md。Dialog、Sheet、Drawer 必须有 TitleDialogTitle/SheetTitle/DrawerTitle是无障碍必需项视觉隐藏时加classNamesr-only。使用完整的 Card 组合CardHeader/CardTitle/CardDescription/CardContent/CardFooter别把内容全塞进CardContent。Button没有isPending/isLoadingprop用Spinnerdata-icondisabled组合出加载态。TabsTrigger必须包在TabsList里不能直接渲染在Tabs下。Avatar永远需要AvatarFallback用于图片加载失败时的兜底。提示条用Alert、空状态用Empty、Toast 用sonner的toast()、分割线用Separator、加载占位用Skeleton、徽标用Badge——一句话能用现有组件就别手写 styled div。4.4 图标rules/icons.md按钮里的图标加data-iconinline-start前缀或data-iconinline-end后缀且不加尺寸类size-4、w-4 h-4——组件通过 CSS 处理图标尺寸。图标以组件对象传递icon{CheckIcon}不要用字符串 key 查映射表。图标导入来源永远以iconLibrary字段为准。4.5 聊天与消息rules/chat.md聊天 UI 必须组合聊天原语会话用MessageScroller行用Message气泡表面用Bubble禁止手写气泡 div 或裸滚动容器。安装命令npx shadcnlatest add message-scroller message bubble attachment marker。滚动行为归MessageScroller所有流式跟随、锚定、跳至最新MessageScrollerButton都内置了不要自写useStickToBottom/ResizeObserverhook。附件用Attachmentstate支持idle/uploading/processing/error/done上传/处理中会自动给标题加shimmer动画系统消息与分隔线用Markervariant支持default/separator/border。结构固定嵌套顺序MessageScrollerProvider→MessageScroller→MessageScrollerViewport→MessageScrollerContent→MessageScrollerItem。兜底逃生舱useMessageScroller、useMessageScrollerVisibility、useMessageScrollerScrollable三个 hooks 来自自动安装的shadcn/react依赖只有在组合无法表达时才用。4.6 CLI 规则绝不手动解码 preset 代码或手工拼接 preset URL用preset decode code、preset url code、preset open code需要项目感知的 preset 检测时用preset resolve。preset 代码直接交给 CLI已有项目用npx shadcnlatest apply code初始化时用npx shadcnlatest init --preset code。五、Key Patterns正确与错误代码对照SKILL.md 汇总了最常见的正反写法关键模式// 表单布局FieldGroup Field而不是 div Label。 FieldGroup Field FieldLabel htmlForemailEmail/FieldLabel Input idemail / /Field /FieldGroup // 校验data-invalid 在 Field 上aria-invalid 在控件上。 Field># 创建新项目。 npx shadcnlatest init --name my-app --preset base-nova npx shadcnlatest init --name my-app --preset a2r6bw --template vite # 创建 monorepo 项目。 npx shadcnlatest init --name my-app --preset base-nova --monorepo npx shadcnlatest init --name my-app --preset base-nova --template next --monorepo # 初始化已有项目。 npx shadcnlatest init --preset base-nova npx shadcnlatest init --defaults # 快捷方式--templatenext --presetnova隐含 base 风格 # 给已有项目应用 preset。 npx shadcnlatest apply a2r6bw npx shadcnlatest apply a2r6bw --only theme npx shadcnlatest apply a2r6bw --only font npx shadcnlatest apply a2r6bw --only theme,font # 检查 preset 代码与项目 preset 状态。 npx shadcnlatest preset decode a2r6bw npx shadcnlatest preset url a2r6bw npx shadcnlatest preset open a2r6bw npx shadcnlatest preset resolve npx shadcnlatest preset resolve --json # 添加组件。 npx shadcnlatest add button card dialog npx shadcnlatest add magicui/shimmer-button npx shadcnlatest add owner/repo/item npx shadcnlatest add --all # 添加/更新前预览。 npx shadcnlatest add button --dry-run npx shadcnlatest add button --diff button.tsx npx shadcnlatest add acme/form --view button.tsx npx shadcnlatest add owner/repo/item --dry-run # 搜索注册表。 npx shadcnlatest search shadcn -q sidebar npx shadcnlatest search tailark -q stats npx shadcnlatest search owner/repo -q login npx shadcnlatest search # 所有已配置注册表 npx shadcnlatest search shadcn -q menu -t ui # 按条目类型过滤 # 获取组件文档与示例 URL。 npx shadcnlatest docs button dialog select # 查看注册表条目详情未安装的条目。 npx shadcnlatest view shadcn/button npx shadcnlatest view owner/repo/item命名 presetnova、vega、maia、lyra、mira、luma。模板next、vite、start、react-router、astro均支持--monorepo与laravel不支持 monorepo。Preset 代码带版本前缀的 base62 字符串如a2r6bw或b0。9.1 关键命令与 flags 细节init初始化或创建项目的常用 flags 包括--template/-tnext、start、vite、next-monorepo、react-router、--preset/-p命名、代码或 URL、--yes/-y、--defaults/-d、--force/-f、--cwd/-c、--name/-n、--silent/-s、--rtl、--reinstall、--monorepo/--no-monorepo。create是init的别名。apply把 preset 应用到已有项目覆盖 preset 驱动的配置、字体、CSS 变量与检测到的 UI 组件支持--preset、--yes、--cwd、--silent位置参数[preset]是--preset的简写两者同时给出时必须一致不带 preset 时 CLI 会提议打开ui.shadcn.com/create的自定义 preset 构建器。add接受组件名、注册表前缀名magicui/shimmer-button、GitHub 条目地址owner/repo/item、URL 或本地路径flags 包括--yes、--overwrite/-o、--cwd、--all/-a、--path/-p、--silent、--dry-run、--diff [path]、--view [path]。search支持--query/-q、--type/-t如ui、block、hook可逗号分隔、--limit/-l默认 100、--offset/-o、--json、--cwd同时是list的别名支持命名空间acme、公开 GitHub 注册表源owner/repo与注册表目录 URL不传注册表时搜索components.json中配置的全部注册表。docs components...输出组件文档、示例与 API 引用的已解析 URL例如docs input button会分别给出 base/radix 的文档与示例链接某些组件还带api链接指向底层库如 command 组件的cmdk。diff命令被废弃——用add --diff代替。info命令支持--cwdbuild命令把registry.json构建为分发用的独立 JSON 文件默认输入./registry.json默认输出./public/r--output/-o与--cwd/-c可调用于作者分发自定义注册表配套规则见 registry.md。十、base 与 radix 的关键差异base字段来自info决定组件 API。两者核心差异详见 base-vs-radix.md组合方式radix 用asChild替换默认元素base 用render不要在触发器外加多余包装元素。当render把元素变成非 buttona、span时base 需要加nativeButton{false}。Selectbase 在根组件上要求itemspropplaceholder 用items数组中的{ value: null }项内容定位用alignItemWithTrigger并支持multiple多选、SelectValue渲染函数子节点与itemToStringValue对象值radix 只用内联 JSXplaceholder 用SelectValue placeholder...定位用positionpopper仅支持单选取字符串值。ToggleGroupbase 用multiple布尔 prop 且defaultValue恒为数组单选时defaultValue{[daily]}radix 用typesingle/typemultiple单选defaultValue是字符串。受控单值时 base 需要数组包装/解包。Sliderbase 单滑块接受普通数字defaultValue{50}radix 恒为数组defaultValue{[50]}范围滑块两者都用数组。Accordionradix 需要typesingle/typemultiple且支持collapsibledefaultValue是字符串base 无typeprop用multiple布尔defaultValue恒为数组。十一、主题定制从 CSS 变量到组件customization.md主题机制是三层链路CSS 变量:root亮色 /.dark暗色→ Tailwind 工具类bg-primary等→ 组件消费。改一个变量所有引用它的组件同步变化。颜色遵循name/name-foreground约定基色用于背景-foreground用于该背景上的文本/图标核心变量包括--background/--foreground、--card/--card-foreground、--primary/--primary-foreground、--secondary/--secondary-foreground、--muted/--muted-foreground、--accent/--accent-foreground、--destructive/--destructive-foreground、--border、--input、--ring、--chart-1~--chart-5、--sidebar-*、--surface/--surface-foreground。颜色采用 OKLCH 格式--primary: oklch(0.205 0 0)亮度 0–1、色度 0 为灰、色相 0–360。暗色模式基于根元素的.dark类切换Next.js 中用next-themes的ThemeProvider attributeclass defaultThemesystem enableSystem。新增自定义颜色三步走① 在info给出的tailwindCssFile通常为globals.css中定义:root与.dark变量绝不新建 CSS 文件② Tailwind v4 用theme inline注册--color-warning: var(--warning)v3 则在tailwind.config.js的theme.extend.colors中注册③ 组件里直接classNamebg-warning text-warning-foreground使用。自定义组件外观的优先级内置 variants →className布局类 → 用cva新增 variant → 用 shadcn 原语组合出更高层的包装组件如文档中的ConfirmDialog封装AlertDialog。十二、在 open-slide 仓库中的落地印证这套 Skill 并非空谈——open-slide 的open-slide/core包见 packages/core/package.json本身就是 shadcn/ui 的实际消费者packages/core/components.json 以new-york风格、lucide图标库配置了整个 UI 体系别名与 Skill 文档中的/components/ui约定完全一致。依赖清单中shadcn ^4.12.0、lucide-react、sonner对应规则中的 toast 方案、base-ui/react对应base原语库、tailwindcss ^4.3.3与class-variance-authoritycva的源头一应俱全。packages/core/src/app/components/ui/目录下可以看到button.tsx、dialog.tsx、badge.tsx、skeleton.tsx、separator.tsx、tooltip.tsx、tabs.tsx、toggle-group.tsx、select.tsx、slider.tsx等组件文件正是文档所述以源码形式落入项目的产物而packages/core/src/app/components/下的业务组件如面板、检查器、样式面板等则体现了用现有组件组合而非手写 div的原则。Skill 同时提供了 cli.md命令、flags、presets、templates、registry.md编写源码注册表、include、条目定义、依赖、GitHub 注册表规则与 customization.md 三份详细参考构成完整的 Agent 可检索知识库。十三、常见误区与检查清单最后把全文最容易被违反的规则收敛成一份自查清单是不是先search/ 检查已装组件再决定写自定义 UI表单是否用了FieldGroup/Field/InputGroup/ToggleGroup/FieldSet校验是否成对出现data-invalidaria-invalid条目是否都进了对应 GroupDialog/Sheet/Drawer 是否都有 Title间距是否用了gap-*、等宽高是否用了size-*、条件类是否走了cn()图标是否带data-icon且未加尺寸类导入是否来自项目iconLibrary是否用语义 token 而不是裸 Tailwind 色值是否手写了dark:覆盖是否给覆盖层组件加了z-index是否手写了 loading 动画而不是shimmer更新组件是否先--dry-run/--diff且未经确认不用--overwritepreset 是否直接交给 CLI 解析而非手动解码或拼 URL第三方注册表组件添加后是否通读文件、修复硬编码导入与图标库差异遵循这份清单配合info注入的项目上下文Agent 就能在 shadcn/ui 项目中稳定地产出风格统一、可访问、可维护的 UI 代码——这正是 open-slide 将这套 Skill 内置于.agents/skills/shadcn/的初衷。赞分享【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载相关推荐new-api 前端 UI 组合规范shadcn/ui 组件正确组合模式实践指南new api 前端 UI 组合规范shadcn/ui 组件正确组合模式实践指南 本文以 new api 仓库中 vendored 的 shadcn/ui 组后端API网关LLM 网关大模型shadcn/ui Vite Monorepo 模板实战在 packages/ui 中集中管理组件并用 Turborepo 驱动开发shadcn/ui Vite Monorepo 模板实战在 packages/ui 中集中管理组件并用 Turborepo 驱动开发 本文基于 shadcn/前端UI组件设计系统new-api 前端 shadcn/ui 组件组合规范从 composition.md 读懂 13 条组件组装规则new api 前端 shadcn/ui 组件组合规范从 composition.md 读懂 13 条组件组装规则 new api 的 Web 控制台 we后端API网关LLM 网关大模型认证鉴权桌面应用上一篇Zotero PDF Translate插件性能优化架构设计突破翻译效率瓶颈的技术实践下一篇res-downloader 配置完全指南从证书信任到代理调通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考