Polish

Polish — Frontend Improvements

The website is built and works. Now it gets polished.

Triangle:

/design-system         /audit Phase 09          /polish
    RULES        →       CHECK           →       ACTION
  "How it should be"  "How it is"          "How it gets better"
   (Reference)       (Findings list)      (Analysis + Implementation)

7 Modes

6 Analysis Dimensions

Each dimension is rated with a score of 1-10. Details in dimensions/*.md.

Overall Score = Average of all 6 dimensions (weighted: VIS/EMO x1.2, PERF x0.8).

Process per Mode

scan

1. Load prior context: Read existing audit states for severity-based prioritization:
   • .audit-state.json → Findings from ALL phases (not just Phase 09)
   • .project-audit-state.json → Code quality findings
   • .astro-audit-state.json → Astro-specific findings
   • .micro-check-results.json → Results from micro skills (if available)
   • Benefit: Address CRITICAL/HIGH findings first, use findings as context for dimension rating
2. Identify project: Read package.json, config files, site.ts
3. Detect stack: Astro? Tailwind? → load matching stack supplement (stacks/)
4. Detect industry: From site.ts or scan file → reference /design-system industry palette
5. Run auto-detection:
   • CSS/Tailwind: Extract colors (custom properties, theme config)
   • Fonts: Font files in public/fonts/, @font-face declarations
   • Spacing: Count most frequent padding/margin values
   • Animations: Find transition/animation declarations
   • Icons: Lucide/Heroicons? SVG inline or sprite?
6. Rate 6 dimensions: Go through each dimension file, assign score
7. Output report: Use template templates/scan-report.md
8. Write state: .polish-state.json
9. Recommendation: AskUserQuestion — recommend quick wins or targeted focus

quick

1. Read state (if available) or run a brief scan
2. Build impact matrix:

3. Select 3-5 quick wins from strategies/quick-wins.md
4. Implement — brief verification after each change
5. Update state

focus [dim]

1. Dimension code: visual, ux, content, emotion, conversion, perf
2. Load matching dimension file
3. Go through all checks of the dimension
4. Identify weaknesses, prioritize fixes
5. Implement max 5 improvements per focus session
6. Score update in state

wow

1. Read state — which dimensions are weak?
2. Suggest wow effects from strategies/wow-effects.md
3. AskUserQuestion — which effects to implement?
   • Mark recommendation (best impact for this website)
   • Max 3 to choose from
4. Checkpoint before each change (automatically via hook)
5. Implement with performance check after each effect
6. Verification: npm run build must succeed

compete [url]

1. Analyze competitor URL: Playbook from strategies/compete-playbook.md
2. Build comparison matrix:
   • Design quality, features, performance, mobile, content
3. Identify differentiation opportunities
4. AskUserQuestion: Which improvements to implement?
5. Implement — specifically target areas where competitor is better
6. Document before/after

showcase

1. Playwright screenshots: Desktop (1440px) + Mobile (375px)
2. If previous screenshots exist (from state): Side-by-side
3. Use template templates/showcase.md
4. Delete screenshots after documentation (cleanup rule)

auto

1. Run scan
2. Analyze results, prioritize
3. quick — implement 3-5 quick wins
4. AskUserQuestion: Add wow effects?
   • Yes (recommendation): Run wow
   • No: Go directly to showcase
5. showcase — before/after

Rules

Performance Budget (CRITICAL)

No effect may exceed these limits:

• LCP: Max +100ms degradation
• CLS: Max +0.01 degradation
• JS: Max +5KB additional JavaScript
• CSS-only preferred: Always try animations as CSS-only first

Context Protection

• Max 8 improvements per session
• If more: AskUserQuestion whether to continue or start a new session

Quality Checks after Each Change

1. npm run build — must succeed
2. Check contrast (WCAG AA: 4.5:1 text, 3:1 large)
3. Mentally walk through mobile view
4. Do not introduce new a11y problems

Integration with Other Skills

• Before polish: Read .audit-state.json — use findings from ALL phases as input (not just Phase 09)
• Design reference: Follow /design-system industry palette + spacing scale
• After polish: Recommend /lighthouse-quick for performance verification
• After polish: Recommend /capture-pdf quick for before/after documentation

Smart Next Steps

After completing polish, suggest appropriate follow-up skills to the user:

State Management

.polish-state.json in project root:

{
  "version": "1.0",
  "project": "slug-from-directory-name",
  "stack": "astro",
  "industry": "industry-from-site-ts",
  "lastScan": {
    "date": "2026-02-21",
    "overallScore": 68,
    "dimensions": {
      "visual": { "score": 7, "findings": 3 },
      "ux": { "score": 8, "findings": 1 },
      "content": { "score": 6, "findings": 4 },
      "emotion": { "score": 5, "findings": 3 },
      "conversion": { "score": 7, "findings": 2 },
      "perf": { "score": 9, "findings": 0 }
    }
  },
  "improvements": [
    {
      "id": "VIS-01",
      "description": "Unified section spacing",
      "status": "fixed",
      "fixedIn": "2026-02-21"
    }
  ]
}

Industry Context

Industry is automatically detected from:

1. src/config/site.ts → industry field
2. Scan file in scans/ (if available)
3. Directory name (e.g., hair-salon-downtown → Hair Salon)

Load industry palette from /design-system and use as reference. Do not apply blindly — respect the website's existing color scheme.