| name | ask-shadcn-mechanic |
| description | Expert maintenance skill for shadcn/ui. Handles component customization, responsive layout debugging, and Form/Zod wiring while strictly enforcing UI/UX design integrity. |
name: ask-shadcn-mechanic
description: shadcn/ui maintenance, customization, layout debugging, Form/Zod wiring, and design integrity.
triggers: ["fix layout", "add variant", "debug tailwind", "update shadcn", "dark mode bug", "fix form validation", "responsive shadcn issue"]
<critical_constraints>
❌ NO arbitrary inline styles (style={{...}}) → Always use Tailwind utilities and cn().
❌ NO breaking a11y → Preserve Radix UI accessibility primitives (aria-attributes, focus management) when modifying components.
✅ MUST use class-variance-authority (cva) when expanding standard components with new visual variants.
✅ MUST verify responsive breakpoints (sm:, md:, lg:) and target dark mode (dark:) when resolving layout/color bugs.
✅ MUST utilize tailwind-merge (via cn()) gracefully when overriding styles from parent components.
</critical_constraints>
<design_integrity>
shadcn has distinct UI/UX aesthetics (e.g., standard rounded corners, muted backgrounds, clear visual hierarchy).
- Keep padding and gaps consistent with shadcn's default
p-6, p-4, and gap-4.
- Enforce visual hierarchy utilizing
text-muted-foreground for secondary text and font-medium for emphasis.
- Forbid hardcoding exact colors (like
bg-zinc-900) and mandate CSS variables (bg-background, border-border, ring-ring) so that light/dark mode transitions remain flawless.
- Reference the structures used in the official shadcn blocks library (e.g., Dashboards, Authentication pages) when scaffolding or fixing complete layouts.
</design_integrity>
<variant_expansion>
To add new visual states to a component (e.g., a "ghost-success" button):
- Locate the
cva() definition in the component (e.g., components/ui/button.tsx).
- Add the new styles into the
variants object.
- Update the corresponding Props interface to allow the new variant.
- DO NOT tack on conditional classes at the implementation level if a variant is more appropriate.
</variant_expansion>
<layout_mechanics>
- Flex/Grid Issues: Navigate standard Tailwind layout issues when composing shadcn Cards, Grids, and Dialogs.
- Responsive Layouts: Fix collapsed menus and mobile overlays by checking standard breakpoints.
- Z-Index Overlaps: Resolve overlapping elements (e.g., Select dropdowns getting hidden behind sticky headers) by carefully applying
z-40, z-50 to the specific Popover/Dropdown wrapper using className={cn(..., "z-50")}.
</layout_mechanics>
<form_wiring>
Forms use react-hook-form and zod.
- Debug the connection between the
zodResolver, the <Form> context, <FormField>, <FormControl>, and <FormMessage>.
- Ensure
name bindings in FormField perfectly match the Zod schema keys.
</form_wiring>
<component_upgrades>
When shadcn/ui releases an update to a custom-modified component:
- Re-run
npx shadcn@latest add [component] in a temp directory or backup the old component.
- Diff the changes and carefully overwrite.
- Re-apply any custom
cva variants to the new file.
</component_upgrades>
