SmoothUI Component Craft

Orchestrate multiple quality skills through a strict phased workflow to produce polished, accessible, performant SmoothUI components.

Strict Workflow

Every component task follows these phases in order. Do not skip phases.

Phase 1: Brainstorm & Research

Invoke superpowers:brainstorming first to explore intent, requirements, and design before any code.

During brainstorming:

• Clarify what the component does and its interaction patterns
• Identify animation requirements (enter, exit, hover, state transitions)
• Decide Motion vs GSAP (prefer Motion unless complex morphing/timelines needed)
• Identify controlled/uncontrolled state needs
• List variants and props

After brainstorming, research existing components in packages/smoothui/components/ for similar patterns to follow.

Phase 2: Design with Interface Craft

Invoke interface-craft to design the animation and interaction layer:

• Define animation stages and sequencing
• Plan spring configurations (duration: 0.25, bounce: ≤0.1 for UI)
• Design hover/focus/active states
• Plan layout animations if needed

Output: animation spec with concrete Motion/GSAP values.

Phase 3: Implement

Read scaffolding templates from references/scaffolding.md for file templates.

Create all required files:

1. Component — packages/smoothui/components/[name]/index.tsx

   • "use client" directive if interactive
   • Export types as [ComponentName]Props
   • Use cn() from @repo/shadcn-ui/lib/utils
   • Import useReducedMotion from motion/react

2. package.json — packages/smoothui/components/[name]/package.json

   • Use workspace:* for internal deps

3. tsconfig.json — packages/smoothui/components/[name]/tsconfig.json

4. Export — Add to packages/smoothui/components/index.ts

5. Example — apps/docs/examples/[name].tsx

   • Default export named [ComponentName]Demo
   • Show all variants

6. Docs — apps/docs/content/docs/components/[name].mdx

   • Frontmatter: title, description, icon, dependencies, installer
   • Use <AutoTypeTable> for props

7. Navigation — Add to apps/docs/content/docs/components/meta.json alphabetically in correct section

Animation Requirements (non-negotiable)

• Import and use useReducedMotion from motion/react
• When shouldReduceMotion is true: instant transitions (duration: 0) or static state
• Only animate transform and opacity
• Spring: { type: "spring", duration: 0.25, bounce: 0.1 }
• Enter easing: cubic-bezier(.23, 1, .32, 1)
• Move easing: cubic-bezier(0.645, 0.045, 0.355, 1)
• Never use string easing like "easeInOut"
• Hover animations: detect hover-capable devices with matchMedia("(hover: hover) and (pointer: fine)")

Accessibility Requirements (non-negotiable)

• Semantic HTML (<button>, <nav>, not <div> with roles)
• ARIA attributes (aria-label, aria-expanded, role, etc.)
• Keyboard navigation (arrow keys, Enter, Escape as appropriate)
• Proper tabIndex management (never positive values)
• Alt text for images
• Color contrast compliance

Phase 4: Quality Review

Run all three review skills in sequence:

1. Invoke vercel-react-best-practices — Check React/Next.js performance patterns
2. Invoke web-design-guidelines — Check Web Interface Guidelines compliance
3. Invoke rams — Run accessibility and visual design review

Fix all issues found before considering the component complete.

Phase 5: Verify

• Run pnpm check from project root to verify linting
• Run pnpm build to verify the build passes
• Start dev server and visually verify in browser if possible

Improving Existing Components

For improvement tasks, skip Phase 1 brainstorming if the change is small (e.g., "add a variant"). Otherwise follow full workflow.

Always:

1. Read the existing component first
2. Identify what's missing (reduced motion? keyboard nav? hover detection?)
3. Apply changes
4. Run Phase 4 review skills
5. Run Phase 5 verification

Quick Reference: File Paths