# UX Polish

> Define UI tokens, accessibility rules, and consistent component behavior for the Astro frontend, plus empty/loading/error states and light hover/focus transitions. Use when adding or refining frontend UX polish and documentation under frontend/ in this repo.

- Skill: `majiayu000/ux-polish` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/ux-polish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/ux-polish/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/ux-polish

---


# UX Polish

## Overview

Make the Astro frontend coherent and production-grade without architectural rewrites. Focus on tokens, a11y, state handling, and minimal-interaction polish with low JS impact.

## Workflow

1. Inspect existing global styles/components under `frontend/` to avoid style drift.
2. Define UI tokens using CSS variables or Tailwind theme strategy (typography, spacing, radii, shadows, color roles).
3. Apply accessibility guardrails (focus visibility, semantic headings, keyboard nav, contrast).
4. Add empty/loading/error states to blog list and post detail.
5. Add only hover/focus transitions (no animation libraries).
6. Document decisions in `frontend/docs/ux.md`.

## Scope

- Define tokens: typography scale, spacing scale, radii and shadows, color roles (bg/fg/muted/accent).
- Ensure accessibility: visible focus states, semantic headings, keyboard navigation, reasonable contrast.
- Add empty, loading skeleton, and error fallback states.
- Add micro-interactions via hover/focus transitions only.

## Outputs

- Add `frontend/docs/ux.md` describing tokens, component rules, and an a11y checklist.
- Apply minimal changes to global styles and components to match the rules.

## Acceptance Checklist

- Focus is visible on all interactive elements.
- Empty/loading/error states exist for blog list and post detail.
- Typography and spacing are consistent across pages.