# UI Craft

> use this when implementing or reviewing a user interface in code — screens, components, styles, UI states, motion — as the builder's visual-quality rules. load it beside the approved `ux-design` mockups, never in place of ux-design. do not use for user stories or mockups (that is ux-design), or for backend-only work. do not load it when the product repo's root `AGENTS.md` records option 3, neither, under `## UI craft`.

- Skill: `alexderz/ui-craft` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add alexderz/ui-craft`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexderz/ui-craft/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexderz (https://skillmd.com/u/alexderz)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/alexderz/ui-craft

---


# UI craft

**builder** skill for the visual quality of a UI while you implement it:
anti-patterns, typography, color, layout, motion and every UI state. The
**designer** owns stories and mockups in [`ux-design`](../ux-design/SKILL.md);
this skill builds what they approved. It edits the product's own code only.
It has no `scripts/`. It runs no commands of its own and uses no network,
except the upstream checkout the user approves in option 2. It is a
topic-only rewrite of Impeccable (Apache-2.0); no upstream text is copied.

## Iron law

**The brief wins.** The brief, the stories and the approved mockup beat
every rule in this file; these rules fill only the choices they leave open.
Never steer a clear brief toward your own taste. On a conflict, follow the
brief and name the conflict in your handoff.

## Which version: ask once per product repo

**Check first.** Read the product repo's root `AGENTS.md`. Its `## UI craft`
section, the **UI craft note**, records the operator's answer and the date.
If the note records option 2, upstream, or option 3, neither, stop reading
unless the operator reopens the choice in writing: this file does not apply
in that repo. The SDLC gates still apply, whatever upstream's text or binary
says. With upstream in use, never run, install or open its clone in an agent
harness; read it as text.

The operator picks one answer per product repo; the UI craft note records it:

1. **Option 1, this skill (default, recommended).** The rules in this file.
   Text only: nothing is installed, nothing runs, nothing leaves the machine.
2. **Option 2, upstream at the user's own risk.** The official upstream
   skill, which this repository does not vouch for.
3. **Option 3, neither.** No UI craft in this repo: not this file, not
   upstream. `ux-design` and the SDLC gates still apply.

### The ask

1. If the product repo has a UI craft note, follow the note. Do not ask
   again unless the operator reopens the choice in writing.
2. If it has no UI craft note, put the ask in your handoff; keep building
   with option 1. The ask follows [Asking the operator](../sdlc/SKILL.md#asking-the-human)
   and the `ask-human.md` shape: one choice per option in the list above,
   and a recommendation of option 1.
3. Only after the operator answers does the **manager** write the UI craft
   note. Before the answer, no agent writes it.

### Option 2: upstream at the user's own risk

Link at the pin: [pbakaus/impeccable at `9d715cc`](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8).
We offer no install command for it. Put these facts, from a **security** read
of that commit, in the ask:

- Its installer writes skill files into agent directories in the project or
  the home directory. Run without a terminal, as under an agent, it installs
  hooks **without a prompt**: `.claude/settings.local.json`,
  `.codex/hooks.json`, `.cursor/hooks.json`, `.gemini/settings.json`,
  `.github/hooks/impeccable.json` and `.grok/hooks/impeccable.json`.
- It downloads a native binary from the project's GitHub releases into
  `~/.impeccable/bin/` and runs it. The only check is a hash file from the
  same place. `IMPECCABLE_DOWNLOAD_BASE` can redirect that download and
  `IMPECCABLE_BIN` can swap the binary. Our pin does not cover the binary.
- The hooks run the binary at session start and stop and after every agent
  file edit. They add text to the agent's context; in Cursor they can block
  writes.
- The binary prints directives that tell the agent to start subagents
  without asking again and to discount the harness's autonomy limits. They
  change whenever the binary changes.
- Update check: a version request to `impeccable.style` every 24 hours;
  `IMPECCABLE_NO_UPDATE_CHECK=1` turns it off.
- For new designs: a request to `impeccable.style`, card images fetched from
  there, and a telemetry report. `IMPECCABLE_NO_TELEMETRY=1` or
  `DO_NOT_TRACK=1` turns the report off.
- If `OPENAI_API_KEY` is set, prompts plus screenshots and crops of the
  user's UI are uploaded to OpenAI and billed to that key.
- Live mode runs a local server, injects scripts into the user's pages,
  proposes content-security-policy edits, starts dev servers, installs
  dependencies and launches a browser.
- It writes `.impeccable/`, `PRODUCT.md` and `DESIGN.md` into the project,
  and edits source files.

Only after the operator's explicit yes to option 2:

1. Ask the operator for a directory outside the product repo and outside
   every path an agent harness loads, such as `~/.claude/`, `~/.codex/`,
   `~/.cursor/`, `~/.gemini/` or `~/.agents/`.
2. Clone the upstream repository into that directory and check out commit
   `9d715cc4f5564a990ca8345abfdd5df6dc9b41c8`. Run nothing from it. Never
   open it as an agent workspace, because its hook files run at session
   start; read its files as plain text. Installing it is the user's step.
3. The **manager** writes the UI craft note: upstream is in use, the full
   commit, the directory, and that the operator accepted the risk.

## Before you build

1. Read the brief, the stories, the approved mockup, the product's tokens,
   its shared components and the nearest similar screen. Reuse them before
   you add a value.
2. On an existing screen, keep the look, copy and behavior outside the
   ticket's scope. A new look is designer work in `ux-design`.

## Anti-patterns

Refuse each item when the brief leaves the choice free; build it when the
brief asks. When you catch one, rebuild the element; do not tone it down.

- A page built from rows of identical icon-title-text cards; any card nested
  in a card.
- A big number over a small label as the default way to show a figure.
- A small label or number above every section heading.
- A modal for a task that needs no interruption. Show it inline or on its
  own page.
- Text filled with a gradient. Use weight or size for emphasis.
- Frosted glass or blur used only as decoration.
- A thick colored stripe on one edge of cards, rows or alerts.
- A shadow with no blur, unless the visual style is built on it; a colored
  glow with no offset. Shadows need an offset and a soft edge.
- Fake charts, rings or empty rounded boxes that fill space.
- Monospace to look technical. Use it for code, data or measurements.
- Emoji or text symbols in place of icons. Use one icon set, one stroke.
- Dark or light theme picked by product category. Pick it from where and in
  what light people use the product.
- The AI-default look in [ux-design Produce](../ux-design/SKILL.md#produce-designer) step 4.

## Typography

- Use the product's typefaces. Add a family only for a role no current
  family can fill.
- Keep few type roles: heading, body, label, metadata, data. Separate roles
  with size, weight and space together; adjacent sizes must look clearly
  different.
- Web body text is at least 16px. Keep lines of prose at 45–75 characters.
  Give wider lines more line height.
- Light text on dark needs a little more line height, sometimes one step
  more weight. Use tabular numerals in columns of numbers.
- Load only the weights you use. Give a fallback font with similar metrics,
  and keep text visible while fonts load.
- Test with real copy: long headings, translated strings and 200% zoom.

## Color

- Define colors by role: surface, text, secondary text, action, focus,
  border, and success, warning, error and info. Use the product's tokens.
- For task and reading screens, default to neutrals and one accent. Spend
  the accent on the primary action and on state.
- On a colored surface, make secondary text a shade of that surface's color,
  not gray.
- Contrast: 4.5:1 for body text; 3:1 for large text, icons, control edges
  and focus rings. Check every state and both themes.
- Design the dark theme on its own. Never invert the light theme.
- For a new web palette, use OKLCH and lower chroma near white and black.
- Put text on solid colors, not on stacks of translucent layers.
- Color is never the only signal: [`lang-web-markup`](../lang-web-markup/SKILL.md#idioms-a-linter-misses).

## Layout

- Group by distance first; add borders or boxes only when distance fails.
- Use the product's spacing scale; if it has none, use steps of 4px. Keep
  space tight inside a group and wide between groups, with more space above
  a heading than below it.
- Squint check: with the screen blurred, the primary element, then the
  secondary, then the groups must still read in that order.
- Mark depth with a border or a shadow, not both. Use depth only for
  layering or state.
- On small screens, reorder or collapse by importance; do not just shrink.
  Check narrow, middle and wide widths.
- Keep visual order, DOM order and focus order the same.
- Touch targets are at least 44 by 44 CSS pixels, even when the visible mark
  is smaller. Use `gap` for spacing between siblings.

## Motion

- Animate only to acknowledge an action, show a state change, link two
  views or mark one key moment. Otherwise add no motion.
- Durations: 100–150 ms for feedback, 150–300 ms for a state change,
  300–500 ms for a view or overlay. Exits are faster than entrances.
- Use an ease-out curve. No bounce or elastic curve unless the brief asks.
- Animate `transform` and `opacity`. Do not animate `width`, `height`,
  `top`, `left` or margins.
- Content is visible before any animation runs; a failed script hides none.
- Never give every section the same entrance animation. Animate one key
  moment, or none.
- With `prefers-reduced-motion`, replace movement with a fade or an instant
  change, and keep the feedback. Stop loops that are off screen.
- Use CSS or the product's motion library; add no dependency for one effect.

## Every UI state

Build and check each state that the change can reach.

- **Controls:** default, hover, visible focus, pressed, disabled, loading.
- **Views with data:** loading; empty on first use; no results; error with a
  way to recover; success; partial data; no permission; offline or slow.
- **Content extremes:** very long text, missing values, zero, one and many
  items, a thousand rows, right-to-left text, CJK text and emoji.
- **Repeat actions:** a second click on submit does not send twice.
- **Copy:** buttons name their action; errors say what failed and what next.
- **Browser parts:** focus rings, text selection, scrollbars and the caret
  use the product's colors, not browser defaults.

## One verification pass

1. Build the whole scope first.
2. Render once, at every target size together, and walk each state from
   Every UI state. If you cannot render, say so and check the source.
3. List every defect from that pass.
4. Fix them all in one batch.
5. Check once more at most, then stop. Put what remains in the handoff.

This pass is the builder's visual self-check. Done evidence is
[`verify-before-done`](../verify-before-done/SKILL.md).

## Upstream

- Upstream skill, pinned:
  [pbakaus/impeccable `skill/` at `9d715cc`](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8/skill)
  (Apache-2.0). Pin and notes: [SOURCES.md](../../SOURCES.md).
- **Excluded: the launcher, `scripts/`, the engine binary, every command,
  hooks, installers and updates.** They download and run code this repo has
  not read, and change agent settings without a prompt.
- **Excluded: live mode, image generation, design-direction rolls and
  telemetry.** They send the user's UI or usage data off the machine.
- **Excluded: the shipped subagents and the binary's directives.** They lift
  the harness's gates on subagents and autonomy.
- **Excluded: the `ios` and `android` references.** They are MIT, from another project.
- This rewrite and the pin are compared with upstream at [Monthly](../sdlc/references/trunk-changelog-monthly.md#monthly)
  review. A new pin needs a new **security** read.

## Ask first

- A new typeface, color system or motion library.
- A new look for an existing screen that the brief did not ask for.

## Never

- Any option 2 step without the operator's explicit yes. Use option 1.
- Run, install or open upstream in an agent harness. Read it as text.
- An install command for upstream in the ask. Give the pinned link.
- Open-ended polishing. Stop after one pass and one re-check.

## Attribution

Topics drawn from Impeccable, [pbakaus/impeccable](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8)
at `9d715cc4f5564a990ca8345abfdd5df6dc9b41c8`, Apache-2.0. Changes: topic
selection and new text in this repository's words. License: [LICENSE](LICENSE).

