# Ux Polish

> Visual design quality skill — elevates HTML wireframes from structural prototypes to polished UI. Applies typography, color, spacing, motion, interaction polish. Works on /ux-wireframe output or any HTML. Use when "ux polish", "polish wireframe", "colorize", "design audit", "design critique", "visual polish", "add color", "improve design".

- **Type:** Skill
- **Install:** `agentstack add skill-digital-stoic-org-agent-skills-ux-polish`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [digital-stoic-org](https://agentstack.voostack.com/s/digital-stoic-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [digital-stoic-org](https://github.com/digital-stoic-org)
- **Source:** https://github.com/digital-stoic-org/agent-skills/tree/main/biz/skills/ux-polish

## Install

```sh
agentstack add skill-digital-stoic-org-agent-skills-ux-polish
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# UX Polish

## Workflow

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

2. **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

3. **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

4. **Read HTML** — Read each target file. Assess current state.

5. **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](https://github.com/digital-stoic-org)
- **Source:** [digital-stoic-org/agent-skills](https://github.com/digital-stoic-org/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-digital-stoic-org-agent-skills-ux-polish
- Seller: https://agentstack.voostack.com/s/digital-stoic-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.