Component Polish

Polish components to production quality. Run a full pass or target a specific area.

Usage

/component-polish              — full pass (states + interactions + polish)
/component-polish states       — interactive states only (hover, focus, active, disabled, loading)
/component-polish interactions — micro-interactions only (animations, transitions, entrance effects)

Instructions

Parse the argument and run the specified area. If no argument, run all three in order.

Area: states

Add complete interactive states to components: hover, focus, active, disabled, loading.

Goals:

• Every interactive element has all essential states defined
• States are visually distinct and accessible (focus visible to keyboard users)
• Transitions between states are smooth (150ms ease-out for micro, 200ms for larger elements)

Hover states — subtle, purposeful changes:

css
1.button:hover { background: var(--color-primary-dark); transform: translateY(-1px); box-shadow: 0 2px 4px rgba(0,0,0,.1); }
2.card:hover { border-color: var(--color-border-hover); box-shadow: 0 4px 12px rgba(0,0,0,.08); }
3.link:hover { color: var(--color-primary-dark); text-decoration-color: currentColor; }

Focus states — keyboard-accessible, always visible:

css
1.button:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }
2.input:focus { border-color: var(--color-primary); box-shadow: 0 0 0 3px rgba(37,99,235,.15); outline: none; }

Active/pressed states:

css
1.button:active { transform: translateY(0); box-shadow: none; background: var(--color-primary-darker); }
2.card:active { transform: scale(0.99); }

Disabled states:

css
1.button:disabled { opacity: 0.5; cursor: not-allowed; pointer-events: none; }
2.input:disabled { background: var(--color-gray-100); color: var(--color-gray-400); cursor: not-allowed; }

Loading states:

css
1.buttonLoading { position: relative; color: transparent; pointer-events: none; }
2.buttonLoading::after {
3  content: ''; position: absolute; width: 16px; height: 16px;
4  border: 2px solid currentColor; border-right-color: transparent;
5  border-radius: 50%; animation: spin 0.6s linear infinite;
6  top: 50%; left: 50%; transform: translate(-50%, -50%);
7}
8@keyframes spin { to { transform: translate(-50%, -50%) rotate(360deg); } }

Component-specific state guide:

Base transition:

css
1.button { transition: all 0.15s ease-out; }
2.card { transition: transform 0.2s ease-out, box-shadow 0.2s ease-out, border-color 0.15s ease-out; }

Area: interactions

Add micro-interactions — animations and transitions that make interfaces feel responsive and alive.

Goals:

• Hover/press feedback on all interactive elements
• Entrance animations for content that appears dynamically
• Loading states that feel smooth (no jarring spinners)
• All animations respect prefers-reduced-motion
• Only animate transform and opacity for 60fps performance

Hover effects:

css
1/* Lift */
2.card { transition: transform 0.2s ease-out, box-shadow 0.2s ease-out; }
3.card:hover { transform: translateY(-4px); box-shadow: 0 12px 24px rgba(0,0,0,.15); }
4
5/* Underline slide */
6.link::after { content: ''; position: absolute; bottom: 0; left: 0; width: 0; height: 2px; background: currentColor; transition: width 0.2s ease-out; }
7.link:hover::after { width: 100%; }

Press feedback:

css
1.button:active { transform: scale(0.98); transition: transform 0.1s ease; }

Entrance animations:

css
1@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
2@keyframes slideUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } }
3
4.fadeIn { animation: fadeIn 0.3s ease-out; }
5.slideUp { animation: slideUp 0.4s ease-out; }
6
7/* Stagger for lists */
8.staggerItem { opacity: 0; animation: slideUp 0.4s ease-out forwards; }
9.staggerItem:nth-child(1) { animation-delay: 0ms; }
10.staggerItem:nth-child(2) { animation-delay: 50ms; }
11.staggerItem:nth-child(3) { animation-delay: 100ms; }

Loading animations:

css
1/* Skeleton pulse */
2.skeleton { background: var(--color-gray-200); animation: pulse 1.5s ease-in-out infinite; }
3@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }

Common patterns:

css
1/* Tooltip */
2.tooltip { opacity: 0; transform: translateY(4px); transition: all 0.15s ease-out; pointer-events: none; }
3.trigger:hover .tooltip { opacity: 1; transform: translateY(0); }
4
5/* Modal */
6.modal { opacity: 0; transform: scale(0.95); transition: all 0.3s ease-out; }
7.modalOpen { opacity: 1; transform: scale(1); }

Timing guide:

Always include reduced-motion override:

css
1@media (prefers-reduced-motion: reduce) {
2  *, *::before, *::after {
3    animation-duration: 0.01ms !important;
4    transition-duration: 0.01ms !important;
5  }
6}

Full Polish Pass (default)

When no argument is provided, run all three areas in order, then apply final refinements:

1. States — Apply the states area above
2. Interactions — Apply the interactions area above
3. Design system consistency — Verify all colors, spacing, typography from tokens
4. Subtle details — Layered shadows, inner glows, gradient accents where appropriate
5. Spacing and alignment — Optical alignment for icons, consistent rhythm
6. Accessibility final check — aria-busy on loaders, aria-invalid on errors, all focus states visible

Design system consistency check:

tsx
1// ❌ Inconsistent
2<div className="p-3 rounded-md bg-gray-100">
3<div className="p-4 rounded-lg bg-slate-50">
4
5// ✅ Consistent
6<div className="p-4 rounded-lg bg-surface">

Refined shadows:

css
1.card { box-shadow: 0 1px 2px rgba(0,0,0,.04), 0 4px 8px rgba(0,0,0,.04); }
2.cardElevated { box-shadow: 0 2px 4px rgba(0,0,0,.04), 0 8px 16px rgba(0,0,0,.08); }

Polish checklist:

• All design tokens used (no hardcoded values)
• All interactive states present (hover, focus, active, disabled, loading)
• Entrance animations on dynamic content
• Skeleton loading states instead of spinners for content loads
• Error states styled with accessible messaging
• Touch targets ≥ 44px on mobile
• Focus indicators visible and styled
• prefers-reduced-motion respected
• No layout shift on state change
• Responsive at all breakpoints