Ux Polish

UX Polish

Workflow

1. Parse $ARGUMENTS → {subcommand} + {target} + options. Default subcommand = polish. Missing target → AskUserQuestion.

1. Resolve target — in order:

• Exact file path → use directly
• Directory path → Glob *.html in it
• Subject name → Glob dev/ux/wireframes/{target}/*.html
• Nothing found → AskUserQuestion

1. Load context:

• Glob dev/ux/design-system.yaml → read design tokens (required for colorize/polish)
• Glob biz/ux/empathy-map-{subject}.md → emotional tone hints (optional)
• Missing design system on polish/colorize → AskUserQuestion or create defaults

1. Read HTML — Read each target file. Assess current state.

1. Execute subcommand — Read references/design-rules.md first, then apply per subcommand:

Analysis subcommands (read-only)

| Subcommand | Action | Reference sections | |---|---|---| | audit | Report all design issues: contrast failures, spacing inconsistencies, anti-pattern violations (§3), heuristic violations (§10). Output structured markdown report grouped by severity. | §1-3, §10 | | critique | Opinionated design suggestions with priority ranking. Like audit but prescriptive — "increase CTA size by 20%", "add shadow to separate card from background". Include rationale from Gestalt/hierarchy principles. | §1-3, §10 |

Modification subcommands (write files)

| Subcommand | Focus | What to apply | Reference sections | |---|---|---|---| | polish | Full pass — the "do everything" command | Typography + color + spacing + motion + interaction + responsive. Apply all rules. | All sections | | colorize | Color only | Read design-system.yaml palette. Apply color harmony algorithm (§5): analogous secondary, complementary accent, tinted neutrals, semantic colors. Test WCAG AA contrast. Apply 60-30-10 rule. | §5, §3 color anti-patterns | | typeset | Typography only | Font pairing (serif+sans), modular scale, line-height per size, measure (45-75ch body, 20-35ch hero), tracking, OpenType features (tabular-nums, small-caps, hanging-punctuation), baseline grid. | §4, §3 typography anti-patterns | | space | Spacing only | Apply 4px scale system. Fix Gestalt Proximity violations (space within group Color > Weight > Position > Proximity > Typography > Texture. When elements compete for attention, the hierarchy has failed.

• Pre-attentive attributes (§1) — Color, size, position, motion process in <250ms. Use for critical information. Always encode meaning in 2+ channels (accessibility).
• Nielsen's 10 heuristics (§10) — Quality checklist for audit/critique: system status visibility, user control, consistency, error prevention, recognition over recall.
• Cognitive load laws (§10) — Hick's (fewer choices), Fitts's (big targets close to thumb), Miller's (chunk 5±2), Von Restorff (distinctive = memorable). Drive interaction decisions.
• Tufte's data-ink ratio (§2) — In data-heavy screens, maximize data, minimize decoration. Every pixel of ink should represent data.

Implementation Rules

• Never strip HTMX: all hx-* attributes are sacred
• Tinted neutrals: mix 5-10% of primary into grays — never use pure gray
• No pure black/white: #1E293B not #000, #FAFAFA not #FFF
• Spacing scale: 4px base unit (4/8/12/16/24/32/48/64/96)
• Motion: ease-out for entrances (0.2s), ease-in for exits (0.15s), prefers-reduced-motion always
• Touch targets: 44px minimum on mobile
• Contrast: WCAG AA minimum, AAA for body text

Testing

• Standalone: This skill is tested independently via manual smoke tests (audit/critique/colorize/polish on sample wireframes). Not managed through OpenSpec.

Maintenance

• Sync with /ux-wireframe: Both skills share design foundations (spacing scale, breakpoints, typography rules). When updating design rules here, check /ux-wireframe references for consistency. Both must agree on token values, spacing scale, and responsive breakpoints.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: digital-stoic-org
• Source: digital-stoic-org/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.