digital-stoic-org UX Polish
Workflow
Parse
$ARGUMENTS→{subcommand}+{target}+ options. Default subcommand =polish. Missing target → AskUserQuestion.Resolve target — in order:
- Exact file path → use directly
- Directory path → Glob
*.htmlin it - Subject name → Glob
dev/ux/wireframes/{target}/*.html - Nothing found → AskUserQuestion
Load context:
- Glob
dev/ux/design-system.yaml→ read design tokens (required forcolorize/polish) - Glob
biz/ux/empathy-map-{subject}.md→ emotional tone hints (optional) - Missing design system on
polish/colorize→ AskUserQuestion or create defaults
- Glob
Read HTML — Read each target file. Assess current state.
Execute subcommand — Read
references/design-rules.mdfirst, 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 < space between groups). Vertical rhythm. White space hierarchy (micro/meso/macro). Section breathing room. | §6, §1 Gestalt, §2 White Space |
animate |
Motion only | Add CSS transitions: hover states (100-150ms ease-out), focus-visible, enter/exit animations (ease-out/ease-in), stagger siblings (+50ms), skeleton loading. Include prefers-reduced-motion. |
§7, §8 interaction states |
adapt |
Responsive only | Mobile-first breakpoints (375/768/1024/1440). Container queries. Touch targets 44px. Thumb zone. Stack columns on mobile. Fluid typography with clamp(). Max content width 1200px. | §9 |
bolder |
Increase assertiveness | Increase type scale ratio, strengthen contrast, enlarge CTAs, add bolder shadows, increase font-weight on headings, more saturated primary color. Push Von Restorff effect. | §2 hierarchy, §4, §5 |
quieter |
Reduce visual noise | Desaturate palette toward monochromatic, increase whitespace, reduce border-radius variation, soften shadows, lighter font-weights on non-critical elements, remove decorative elements. | §2 hierarchy, §5 monochromatic, §6 macro whitespace |
delight |
Add micro-delights | Subtle hover animations beyond defaults, success state celebrations (checkmark animation), empty state illustrations/messages, loading skeleton with brand-tinted pulse, stagger entrance on list items. | §7 motion, §8 affordance, §11 UX writing |
extract |
Reverse-engineer design system | Parse all CSS values from HTML. Identify color palette, font families, spacing values, border-radius values. Detect inconsistencies (ad-hoc values). Generate dev/ux/design-system.yaml with detected tokens. Report deviations. |
§12 |
Subcommand dispatch rules
- Unknown subcommand → tell user available subcommands, suggest closest match
extractis unique: outputs YAML, not modified HTML. Does NOT require existing design-system.yaml.audit/critiquenever modify files — output to console only- All modification subcommands respect
--scope,--tone,--preserve-structure,--diffoptions - Stacking: User can run
typesetthencolorizethenanimatefor incremental polish instead of fullpolish
Apply options:
--scope {area}→ only modify matching section (header/hero/cta/forms/cards/nav/footer/all)--tone {tone}→ override emotional direction (professional/friendly/urgent/celebratory)--preserve-structure→ CSS-only changes, never modify HTML tags/attributes--diff→ show before/after diff, don't overwrite
Write output — Write modified HTML in-place. Preserve all
hx-*attributes,data-*attributes, and HTML structure (unless structure changes are needed and--preserve-structurenot set).Open —
xdg-open/openthe modified file(s).
Design Foundations
Every decision in this skill traces back to these frameworks (full rules in references/design-rules.md):
- Gestalt principles (§1) — Proximity, Similarity, Closure, Continuity, Figure-Ground, Prägnanz. These are the physics of visual perception. Spacing is semantic (grouping), not decorative. Alignment creates continuity. One focal point per viewport.
- Visual hierarchy stack (§2) — Size > 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:
#1E293Bnot#000,#FAFAFAnot#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-motionalways - 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-wireframereferences for consistency. Both must agree on token values, spacing scale, and responsive breakpoints.