메뉴
Globally customize Nuxt UI 4 components via the @nuxt/ui vite plugin's ui option (appConfig equivalent). Use when adding Tailwind classes (cursor-pointer, rounded-full, etc.) to all instances of a component, changing default variants, or setting compound variants — without touching each instance.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
| name | nuxt-ui-global-config |
| description | Globally customize Nuxt UI 4 components via the @nuxt/ui vite plugin's ui option (appConfig equivalent). Use when adding Tailwind classes (cursor-pointer, rounded-full, etc.) to all instances of a component, changing default variants, or setting compound variants — without touching each instance. |
Nuxt UI 4 的每个组件（125+ 全部）都支持全局 Tailwind 装饰。组件用法、语义色体系、theme 结构详解归 nuxt-ui skill 及其 references/theming.md（"Component theme customization" 节）；本件只管全局覆盖怎么写 + 本项目实测钉死的合并行为踩坑（合并红线的单一真身在此，别处只留指针）。
每个组件内部用 tailwind-variants 合成样式：tv({ extend: tv(theme), ...appConfig.ui?.<component> })——构建时生成的默认 theme 作 parent，用户覆盖作 child。合并是拼接不是替换：内置默认 class 会残留在最终 DOM 里，只靠 tailwind-merge 去重直接同属性冲突（rounded-md + rounded-full → rounded-full）+ CSS 优先级决胜。
本项目不用 Nuxt，全局覆盖写在 ui/vite.config.js 的 ui({ ui: {...} }) 插件选项里（appConfig 的 Vite 等价物）。该文件现有配置连同注释就是案例库——button/toaster/dropdownMenu/select/input/textarea 各块注释记录了每处覆盖的落点选择与原因，动手前先读同类先例。
覆盖片段与组件 theme 同构，四部分都可给：
ui: {
button: {
slots: { base: 'cursor-pointer' }, // 追加 slot class（最常用）
variants: { size: { md: { leadingIcon: 'size-4' } } }, // 覆盖 variant 样式
compoundVariants: [{ color: 'neutral', variant: 'outline', class: { base: 'ring-2' } }],
defaultVariants: { variant: 'outline' }, // 修改默认 prop
},
}
覆盖前必须先看目标组件的生成 theme：ui/node_modules/.nuxt-ui/ui/<component>.ts（Vite 构建时生成）。每个组件 slot 名不同；内置 class 落在 slots 还是 variants，决定你的覆盖该落哪（见下方红线第 3 条）。内置主题的打包产物在 @nuxt/ui/dist/shared/ui.<hash>.mjs——文件名带哈希，别在测试里 import 它。
ui prop / class prop > 全局配置 > theme 默认值。全局配置会被实例级 :ui / class 覆盖。
p-4、sm:p-6）不会被你的 pb-5 删掉。凡内置在某断点用了简写，同断点要显式盖对应方向（如 pb-5 sm:pb-5——少写 sm: 那份，桌面端就被残留的 sm:p-6 顶回）。variants.xxx.yyy 里写了 content 就把内置 content 整个顶掉（modal 全屏曾因此画错）。只写要改的键。slots.base 会被变体类去重吃掉（tv 实测；如 input 各 size 的字号/文字色）——覆盖须落在同名 variant 的 base 上（variants.size.<每档>.base，每档都写）。与末条的分工：改静态逐档样式落这里；要盖内置响应式断点规则（带 md: 等前缀的）走 compoundVariants（见末条）。text-default 压不掉内置 text-highlighted，两者并存只能 text-default! important 决胜。input 覆盖不传导到 textarea：theme 由 input 工厂派生，但配置按组件名取——两者要分别写。md:text-base 盖回内置 md:text-sm；写进 base 无效，compound 在 base 之后应用会反盖）。背景：input 内置的响应式字号（手机 16px、md+ 缩 14/12px）是 iOS 防聚焦缩放方案，但它按宽度 ≥768 当"桌面"，漏掉横屏 iPhone/iPad——仍是 iOS Safari，<16px 照样触发聚焦缩放，故本项目全档盖回 16px。另：defaultVariants 翻到 theme 里没定义的分支值是空操作（如 input 的 fixed 只定义了 false 分支，翻成 true 看着改了实际没动）。ui/vitest.config.js 不挂 @nuxt/ui/vite 插件，全局主题在单测里惰性（弹窗测试普遍 stub UModal）。全局主题只做"配置对象形态"级单测（见 ui/src/constants/modal-theme.js 及其测试），合并后的真实渲染靠 dev + devtools/截图验证。已评估过补真实渲染测试（复刻合并/改测试基建/E2E），不划算、不补。
| 需求 | 配置 |
|---|---|
所有按钮手指光标（Tailwind v4 preflight 不再给 <button> 设 cursor，Nuxt UI 也不内置） | button.slots.base: 'cursor-pointer' |
| 所有按钮点击反馈 | button.slots.base: 'active:scale-[0.98] active:opacity-80' |
| 所有卡片圆角加大 | card.slots.root: 'rounded-2xl' |
| 所有 Badge 改药丸形 | badge.slots.base: 'rounded-full' |
版本发布流程，三种模式：完整发布（bump + push + 视情发 npm）、只 bump push（不发 npm）、紧急 npm（不 push）。Use when 用户要求"发布"、"release"、"bump 版本"、"push 版本"。
E2E 测试执行规范与踩坑约束。Use when 执行、编写、调试 E2E 测试，或涉及 Playwright、e2e 目录下文件的改动。
只读探针——枚举并驱动上游 OpenClaw provider 的登录逻辑，捕获真实返回（验证 URL/码、note 格式、交互需求、返回结构）而不完成授权、不落凭据、不动现有代码。手动调研工具，仅显式 /oauth-device-code-probe 调用，不自动触发。
Maintain CoClaw deploy Nginx rules for domain routing, HTTPS redirects, certbot certificate issuance, and SPA/release-artifact cache headers. Use when changing deploy/nginx/ config (modes/*.conf.template, includes/, templates/), or diagnosing browser stale-cache issues after frontend release (especially WeChat Android WebView).
移动端子页面适配规范（MobilePageHeader + 路由 meta）。Use when 新建非底部导航直达的子页面，或调整移动端页面 header/导航栏显隐。
Build UIs with @nuxt/ui v4 — 125+ accessible Vue components with Tailwind CSS theming. Use when creating interfaces, customizing themes to match a brand, building forms, or composing layouts like dashboards, docs sites, and chat interfaces.