Parsons/.claude/skills/polish/SKILL.md

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
polish	Final production readiness pass — visual alignment, spacing consistency, interaction states, copy, edge cases. Use before marking a component done.	true	[component or area to polish]

Perform a meticulous final pass on a component or area, fixing every detail that separates good work from great work. Unlike audit/critique which only assess, polish finds AND fixes issues.

Target: $ARGUMENTS

Preparation

1. Read docs/design-system.md for FA design conventions
2. Read docs/memory/decisions-log.md for design rationale and prior decisions
3. Read the target component/area source files and stories
4. Reference docs/reference/impeccable/polish-skill.md for the full checklist
5. Reference docs/conventions/component-conventions.md for structural rules

FA context: Funeral Arranger serves families in grief or distress. The design must feel warm, trustworthy, and calm. Touch targets >= 44px. Transitions 150ms ease-in-out. No aggressive colours for errors (copper, not red — see D024). Accessibility is critical — users may be elderly, emotional, or on mobile.

CRITICAL: Polish is the last step, not the first. Do not polish work that is not functionally complete. If the component has open TODOs or missing features, flag them and skip those areas.

Pre-Polish Assessment

Before fixing anything, assess the current state:

1. Review completeness — Is the component functionally complete? Are there known issues to preserve (mark with TODOs)?
2. Identify polish areas — Scan for visual inconsistencies, spacing issues, interaction state gaps, copy problems, edge cases, and transition roughness.
3. Set scope — List the specific fixes to make. Do not attempt structural changes — polish is micro-detail work.

Polish Systematically

Work through each dimension. Fix issues as you find them — do not just document.

1. Visual Alignment & Spacing

• Grid alignment: All elements line up to the spacing scale (no arbitrary gaps)
• Consistent spacing: Every gap uses theme.spacing() or var(--fa-spacing-*) — no magic numbers
• Optical alignment: Adjust for visual weight where needed (icons often need offset for optical centering)
• Responsive consistency: Spacing works at all breakpoints (mobile, tablet, desktop)

How to check: Inspect computed styles. Look for values that are not multiples of 4px or 8px. Squint at the layout — anything that feels off probably is.

2. Typography Refinement

• Hierarchy consistency: Same element types use the same typography variant throughout
• Line length: Body text stays within 45-75 characters
• Line height: Appropriate for font size and reading context
• Token compliance: All font sizes, weights, and families come from theme.typography.*

3. Colour & Contrast

• Contrast ratios: All text meets WCAG AA (4.5:1 for normal text, 3:1 for large text and UI)
• Token usage: No hardcoded hex values — all via theme palette or CSS variables
• Tinted neutrals: No pure gray or pure black — add subtle colour tint per FA palette
• Gray on colour: Never put gray text on coloured backgrounds — use a shade of that colour

4. Interaction States

Every interactive element must have ALL of these states:

State	Treatment	FA note
Default	Base styling	Warm, inviting
Hover	Subtle lift, colour shift	150ms ease-in-out
Focus	Visible ring via :focus-visible	2px, offset 2px, high contrast
Active	Pressed/darker	Immediate feedback
Disabled	Reduced opacity, aria-disabled	Clearly non-interactive
Loading	Spinner or skeleton	Reduce perceived wait
Error	Copper border/text, not red	Gentle, per D024
Success	Confirmation feedback	Reassuring, not flashy

The common miss: Designing hover without focus. Keyboard users never see hover states.

5. Micro-interactions & Transitions

• Timing: All transitions 150ms ease-in-out (FA convention)
• Properties: Only animate transform, opacity, background-color, border-color, box-shadow — never animate width, height, or top/left
• Reduced motion: Must respect prefers-reduced-motion
• Easing: Ease-in-out or ease-out. Never bounce or elastic — they feel dated.

6. Copy & Content

• Consistent terminology: Same things called the same names throughout
• Capitalisation: Sentence case for body, consistent for labels
• Tone: Warm, professional, clear — no jargon, no condescension
• Labels: Unambiguous — a user should never wonder "what does this mean?"
• Punctuation: Consistent (periods on sentences, not on labels)

7. Edge Cases

• Long content: Handles very long names, descriptions, prices
• Empty states: Helpful guidance, not blank space
• Missing data: Graceful degradation with sensible defaults
• Loading states: Clear async feedback, skeleton over spinner where possible
• Error states: Helpful, non-blaming messages with recovery paths (copper, not red)

8. Code Cleanliness

• Remove console.log statements
• Remove commented-out code
• Remove unused imports
• Verify displayName is set on the component
• Verify barrel export in index.ts
• Ensure all props have JSDoc descriptions
• No TypeScript any types

Polish Checklist

Verify each item after completing fixes:

• Visual alignment correct at all breakpoints
• Spacing uses design tokens consistently (no magic numbers)
• Typography hierarchy consistent
• All interactive states implemented (hover, focus, active, disabled, loading, error)
• All transitions 150ms ease-in-out
• Focus indicators visible via :focus-visible
• Copy is consistent, warm, and unambiguous
• Touch targets >= 44px on all interactive elements
• Contrast ratios meet WCAG AA
• Keyboard navigation works correctly
• No console errors or warnings
• No layout shift on load
• Respects prefers-reduced-motion
• Code is clean (no TODOs, console.logs, commented code, unused imports)
• Component has displayName and barrel export
• All props have JSDoc descriptions

Final Verification

After all fixes:

1. Check Storybook — Verify all stories render correctly
2. Check TypeScript — Ensure no type errors introduced
3. Compare states — Walk through every interactive state visually
4. Test keyboard — Tab through the component, verify focus order and indicators

NEVER:

• Polish before the component is functionally complete
• Introduce bugs while polishing (test thoroughly after each fix)
• Ignore systematic issues (if spacing is off everywhere, fix the system not individual instances)
• Perfect one area while leaving others rough (maintain consistent quality level)
• Make structural or architectural changes — that is not polish work

Report a summary of what was fixed when done.