shadcn 组件视觉适配器

🎯 目标

重构位于 ${component_file_path} 的现有 ${component_name} 组件，使其匹配以下位置提供的参考组件的视觉设计、结构和行为：

${install_command:bunx --bun shadcn@latest add accordion} ${reference_url:} ← 可选；如果不存在文档页面则留空

不要替换业务逻辑、现有 props 接口或数据获取模式。保留它们。 仅适配视觉层：标记结构、类名、动画和无障碍属性。

---

📋 步骤 1 — 分析现有组件

在编写任何代码之前：

1. 阅读 ${component_file_path} 的完整源码。
2. 梳理出：
   • 所有 props 及其类型（TypeScript 接口或 PropTypes）。
   • 内部状态变量（useState、useReducer、Zustand slices 等）。
   • 所消费的上下文提供者或自定义 hooks。
   • 所渲染的子组件及其所在位置。
   • 暴露给父组件的事件处理器和回调。
3. 列出每一个 import —— 标记出任何会与 shadcn 原语冲突或可被其替换的项。

在改动任何代码之前，先输出一份简要的审计表：

项目	当前值	操作
Props	...	保留 / 重命名 / 移除
State	...	保留 / 迁移
Context/Hooks	...	保留 / 替换
子组件	...	保留 / 替换
依赖	...	保留 / 安装 / 移除

---

📦 步骤 2 — 依赖解析

直接运行安装命令：

${install_command}

命令完成后，生成的文件将出现在 ${components_dir:components/ui}/ 中。使用这些文件继续执行步骤 3。

---

🔬 步骤 3 — 审查参考组件

如果提供了 ${reference_url} → 获取它并像之前一样提取视觉规范。

如果 ${reference_url} 为空 → 阅读步骤 2 中 CLI 命令下载的文件， 并直接从源代码中提取相同的信息： - cva variant schema - data-state / data-disabled 属性 - 动画/过渡类 - ARIA 角色和属性 - cn() 使用模式

🛠 第 4 步 — 重构组件

将第 3 步的视觉结构应用到第 1 步的现有组件上。

规则：

• ✅ 保留所有现有的 prop 名称和类型，除非存在直接对应的 shadcn 等价物。
• ✅ 保留所有数据获取、业务逻辑和回调。
• ✅ 使用 forwardRef 包装 Radix 原语，并展开 ...props 以保持灵活性。
• ✅ 所有 className 合并都使用 cn() —— 绝不用字符串拼接。
• ✅ 如果参考组件使用了具名复合子组件，则导出它们（例如 Accordion、AccordionItem、AccordionTrigger、AccordionContent）。
• ❌ 不要导入生成的 shadcn 文件并重新导出它 —— 在重构后的文件中内联构建原语，以保持逻辑就近。
• ❌ 未经明确指示，不要添加参考组件中不存在的 Tailwind 类。

响应式行为（${responsive_breakpoints:sm md lg}）：

应用移动优先的响应式类。确认 tailwind.config.ts 中的当前断点与项目约定一致。如果参考组件使用容器查询，请安装 @tailwindcss/container-queries。

---

🧩 第 5 步 — 上下文提供者与 Hook

如果参考组件需要上下文提供者（例如 ToastProvider、TooltipProvider）：

1. 检查它是否已挂载在 ${provider_file:app/layout.tsx} 或 ${provider_file:app/providers.tsx} 中。
2. 如果没有，将其添加到相应的布局文件中。提供确切的 diff。
3. 如果需要自定义 hook（例如 useToast、useDialog），将其放在 ${hooks_dir:hooks/} 中并从那里导入。

---

❓ 第 6 步 — 澄清问题（如果未知，在生成前询问）

如果以下任何一项无法从现有代码中确定，请在编写前询问：

1. 数据/props：将传入什么形状的数据？（如果有帮助，提供一个示例对象。）
2. 状态管理：组件状态是局部的，还是外部管理的（Zustand、Redux、React Query）？
3. 资源：是否有 lucide-react 未覆盖的必需图片、徽标或自定义图标？
4. 响应式：在 ${responsive_breakpoints:sm md lg} 断点处的预期布局是什么？
5. 放置位置：该组件将位于应用路由/布局树的什么位置？（对于上下文提供者的放置很重要。）

---

📐 第 7 步 — 输出格式

按以下形式提供结果：

1. ${component_file_path} — 完整的重构后组件文件。
2. ${components_dir:components/ui}/${shadcn_component_slug}.tsx — shadcn 原语（仅在需要且未由 CLI 生成时）。
3. lib/utils.ts — 仅在需要创建或更新时。
4. 布局/provider 差异 — 仅在需要添加 provider 时。
5. 一个简短的 迁移说明 部分，列出：
   • 已移除的依赖
   • 已重命名的 props（如有）
   • 任何需要手动执行的步骤（例如，向 globals.css 添加 CSS 变量）

---

🎨 Tailwind CSS 变量（shadcn 设计令牌）

确认 globals.css 包含所需的 CSS 自定义属性。如果参考组件使用了诸如 --radius、--background、--foreground、--primary、--ring 之类的令牌，请追加缺失的变量。除非项目已定义自定义主题，否则对 ${color_theme:zinc} 使用 shadcn 默认令牌集。

---

🚫 约束

• 框架：${framework:Next.js 14+ App Router}
• 样式：仅限 Tailwind CSS ${tailwind_version:3} — 不使用内联样式，不使用 CSS modules，不使用 styled-components。
• TypeScript：严格模式。所有新代码必须完全类型化。
• 除非存在直接的 peer 冲突，否则不要升级或降级任何现有依赖版本。

shadcn Component Visual Adapter

🎯 Objective

Refactor the existing ${component_name} component located at ${component_file_path} to match the visual design, structure, and behavior of the reference component available at:

${install_command:bunx --bun shadcn@latest add accordion} ${reference_url:} ← optional; leave blank if no docs page exists

Do NOT replace business logic, existing props interface, or data-fetching patterns. Preserve them. Adapt only the visual layer: markup structure, class names, animations, and accessibility attributes.

---

📋 Step 1 — Analyze the Existing Component

Before writing any code:

1. Read the full source of ${component_file_path}.
2. Map out:
   • All props and their types (TypeScript interfaces or PropTypes).
   • Internal state variables (useState, useReducer, Zustand slices, etc.).
   • Context providers or custom hooks consumed.
   • Child components rendered and where they live.
   • Event handlers and callbacks exposed to the parent.
3. List every import — flag any that will conflict with or can be replaced by the shadcn primitive.

Output a brief audit table before touching any code:

Item	Current value	Action
Props	...	keep / rename / remove
State	...	keep / migrate
Context/Hooks	...	keep / replace
Sub-components	...	keep / replace
Dependencies	...	keep / install / remove

---

📦 Step 2 — Dependency Resolution

Run the install command directly:

${install_command}

After the command completes, the generated files will appear in ${components_dir:components/ui}/. Proceed to Step 3 using those files.

---

🔬 Step 3 — Review Reference Component

IF ${reference_url} is provided → fetch it and extract the visual spec as before.

IF ${reference_url} is blank → read the files downloaded by the CLI command in Step 2 and extract the same information from the source code directly:

• cva variant schema
• data-state / data-disabled attributes
• animation/transition classes
• ARIA roles and props
• cn() usage patterns

---

🛠 Step 4 — Refactor the Component

Apply the visual structure from Step 3 to the existing component from Step 1.

Rules:

• ✅ Keep all existing prop names and types unless a direct shadcn equivalent exists.
• ✅ Keep all data-fetching, business logic, and callbacks.
• ✅ Wrap Radix primitives using forwardRef and spread ...props to preserve flexibility.
• ✅ Use cn() for all className merging — never string concatenation.
• ✅ Export named compound sub-components if the reference component uses them (e.g., Accordion, AccordionItem, AccordionTrigger, AccordionContent).
• ❌ Do NOT import the generated shadcn file and re-export it — build the primitive inline in the refactored file to keep the logic co-located.
• ❌ Do NOT add Tailwind classes not present in the reference component without explicit instruction.

Responsive behavior (${responsive_breakpoints:sm md lg}):

Apply mobile-first responsive classes. Confirm current breakpoints in tailwind.config.ts match the project's convention. If the reference uses container queries, install @tailwindcss/container-queries.

---

🧩 Step 5 — Context Providers and Hooks

If the reference component requires a context provider (e.g., ToastProvider, TooltipProvider):

1. Check if it is already mounted in ${provider_file:app/layout.tsx} or ${provider_file:app/providers.tsx}.
2. If not, add it to the appropriate layout file. Provide the exact diff.
3. If a custom hook is required (e.g., useToast, useDialog), place it in ${hooks_dir:hooks/} and import it from there.

---

❓ Step 6 — Clarifying Questions (ask before generating if unknown)

If any of the following are not determinable from the existing code, ask before writing:

1. Data/props: What shape of data will be passed? (Provide a sample object if helpful.)
2. State management: Is component state local, or managed externally (Zustand, Redux, React Query)?
3. Assets: Are there required images, logos, or custom icons not covered by lucide-react?
4. Responsive: What is the expected layout at ${responsive_breakpoints:sm md lg} breakpoints?
5. Placement: Where in the app routing/layout tree will this component live? (Important for context provider placement.)

---

📐 Step 7 — Output Format

Provide the result as:

1. ${component_file_path} — full refactored component file.
2. ${components_dir:components/ui}/${shadcn_component_slug}.tsx — shadcn primitive (only if needed and not generated by CLI).
3. lib/utils.ts — only if it needs to be created or updated.
4. Layout/provider diff — only if a provider needs to be added.
5. A short migration notes section listing:
   • Removed dependencies
   • Renamed props (if any)
   • Any manual steps required (e.g., adding CSS variables to globals.css)

---

🎨 Tailwind CSS Variables (shadcn design tokens)

Confirm that globals.css contains the required CSS custom properties. If the reference component uses tokens like --radius, --background, --foreground, --primary, --ring, append the missing variables. Use the shadcn default token set for ${color_theme:zinc} unless the project already defines a custom theme.

---

🚫 Constraints

• Framework: ${framework:Next.js 14+ App Router}
• Styling: Tailwind CSS ${tailwind_version:3} only — no inline styles, no CSS modules, no styled-components.
• TypeScript: strict mode. All new code must be fully typed.
• Do not upgrade or downgrade any existing dependency version unless there is a direct peer conflict.