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;
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:
- Option 1, this skill (default, recommended). The rules in this file.
Text only: nothing is installed, nothing runs, nothing leaves the machine.
- Option 2, upstream at the user's own risk. The official upstream
skill, which this repository does not vouch for.
- Option 3, neither. No UI craft in this repo: not this file, not
upstream.
ux-design and the SDLC gates still apply.
The ask
- If the product repo has a UI craft note, follow the note. Do not ask
again unless the operator reopens the choice in writing.
- If it has no UI craft note, put the ask in your handoff; keep building
with option 1. The ask follows Asking the operator
and the
ask-human.md shape: one choice per option in the list above,
and a recommendation of option 1.
- 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.
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:
- 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/.
- 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.
- 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
- 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.
- 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 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.
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
- Build the whole scope first.
- 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.
- List every defect from that pass.
- Fix them all in one batch.
- 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.
Upstream
- Upstream skill, pinned:
pbakaus/impeccable
skill/ at 9d715cc
(Apache-2.0). Pin and notes: 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
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
at 9d715cc4f5564a990ca8345abfdd5df6dc9b41c8, Apache-2.0. Changes: topic
selection and new text in this repository's words. License: LICENSE.
1---2name: ui-craft3description: 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`.4metadata:5 source: https://skillmd.com/skills/alexderz/ui-craft6---78# UI craft910**builder** skill for the visual quality of a UI while you implement it:11anti-patterns, typography, color, layout, motion and every UI state. The12**designer** owns stories and mockups in [`ux-design`](../ux-design/SKILL.md);13this skill builds what they approved. It edits the product's own code only.14It has no `scripts/`. It runs no commands of its own and uses no network,15except the upstream checkout the user approves in option 2. It is a16topic-only rewrite of Impeccable (Apache-2.0); no upstream text is copied.1718## Iron law1920**The brief wins.** The brief, the stories and the approved mockup beat21every rule in this file; these rules fill only the choices they leave open.22Never steer a clear brief toward your own taste. On a conflict, follow the23brief and name the conflict in your handoff.2425## Which version: ask once per product repo2627**Check first.** Read the product repo's root `AGENTS.md`. Its `## UI craft`28section, the **UI craft note**, records the operator's answer and the date.29If the note records option 2, upstream, or option 3, neither, stop reading30unless the operator reopens the choice in writing: this file does not apply31in that repo. The SDLC gates still apply, whatever upstream's text or binary32says. With upstream in use, never run, install or open its clone in an agent33harness; read it as text.3435The operator picks one answer per product repo; the UI craft note records it:36371. **Option 1, this skill (default, recommended).** The rules in this file.38 Text only: nothing is installed, nothing runs, nothing leaves the machine.392. **Option 2, upstream at the user's own risk.** The official upstream40 skill, which this repository does not vouch for.413. **Option 3, neither.** No UI craft in this repo: not this file, not42 upstream. `ux-design` and the SDLC gates still apply.4344### The ask45461. If the product repo has a UI craft note, follow the note. Do not ask47 again unless the operator reopens the choice in writing.482. If it has no UI craft note, put the ask in your handoff; keep building49 with option 1. The ask follows [Asking the operator](../sdlc/SKILL.md#asking-the-human)50 and the `ask-human.md` shape: one choice per option in the list above,51 and a recommendation of option 1.523. Only after the operator answers does the **manager** write the UI craft53 note. Before the answer, no agent writes it.5455### Option 2: upstream at the user's own risk5657Link at the pin: [pbakaus/impeccable at `9d715cc`](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8).58We offer no install command for it. Put these facts, from a **security** read59of that commit, in the ask:6061- Its installer writes skill files into agent directories in the project or62 the home directory. Run without a terminal, as under an agent, it installs63 hooks **without a prompt**: `.claude/settings.local.json`,64 `.codex/hooks.json`, `.cursor/hooks.json`, `.gemini/settings.json`,65 `.github/hooks/impeccable.json` and `.grok/hooks/impeccable.json`.66- It downloads a native binary from the project's GitHub releases into67 `~/.impeccable/bin/` and runs it. The only check is a hash file from the68 same place. `IMPECCABLE_DOWNLOAD_BASE` can redirect that download and69 `IMPECCABLE_BIN` can swap the binary. Our pin does not cover the binary.70- The hooks run the binary at session start and stop and after every agent71 file edit. They add text to the agent's context; in Cursor they can block72 writes.73- The binary prints directives that tell the agent to start subagents74 without asking again and to discount the harness's autonomy limits. They75 change whenever the binary changes.76- Update check: a version request to `impeccable.style` every 24 hours;77 `IMPECCABLE_NO_UPDATE_CHECK=1` turns it off.78- For new designs: a request to `impeccable.style`, card images fetched from79 there, and a telemetry report. `IMPECCABLE_NO_TELEMETRY=1` or80 `DO_NOT_TRACK=1` turns the report off.81- If `OPENAI_API_KEY` is set, prompts plus screenshots and crops of the82 user's UI are uploaded to OpenAI and billed to that key.83- Live mode runs a local server, injects scripts into the user's pages,84 proposes content-security-policy edits, starts dev servers, installs85 dependencies and launches a browser.86- It writes `.impeccable/`, `PRODUCT.md` and `DESIGN.md` into the project,87 and edits source files.8889Only after the operator's explicit yes to option 2:90911. Ask the operator for a directory outside the product repo and outside92 every path an agent harness loads, such as `~/.claude/`, `~/.codex/`,93 `~/.cursor/`, `~/.gemini/` or `~/.agents/`.942. Clone the upstream repository into that directory and check out commit95 `9d715cc4f5564a990ca8345abfdd5df6dc9b41c8`. Run nothing from it. Never96 open it as an agent workspace, because its hook files run at session97 start; read its files as plain text. Installing it is the user's step.983. The **manager** writes the UI craft note: upstream is in use, the full99 commit, the directory, and that the operator accepted the risk.100101## Before you build1021031. Read the brief, the stories, the approved mockup, the product's tokens,104 its shared components and the nearest similar screen. Reuse them before105 you add a value.1062. On an existing screen, keep the look, copy and behavior outside the107 ticket's scope. A new look is designer work in `ux-design`.108109## Anti-patterns110111Refuse each item when the brief leaves the choice free; build it when the112brief asks. When you catch one, rebuild the element; do not tone it down.113114- A page built from rows of identical icon-title-text cards; any card nested115 in a card.116- A big number over a small label as the default way to show a figure.117- A small label or number above every section heading.118- A modal for a task that needs no interruption. Show it inline or on its119 own page.120- Text filled with a gradient. Use weight or size for emphasis.121- Frosted glass or blur used only as decoration.122- A thick colored stripe on one edge of cards, rows or alerts.123- A shadow with no blur, unless the visual style is built on it; a colored124 glow with no offset. Shadows need an offset and a soft edge.125- Fake charts, rings or empty rounded boxes that fill space.126- Monospace to look technical. Use it for code, data or measurements.127- Emoji or text symbols in place of icons. Use one icon set, one stroke.128- Dark or light theme picked by product category. Pick it from where and in129 what light people use the product.130- The AI-default look in [ux-design Produce](../ux-design/SKILL.md#produce-designer) step 4.131132## Typography133134- Use the product's typefaces. Add a family only for a role no current135 family can fill.136- Keep few type roles: heading, body, label, metadata, data. Separate roles137 with size, weight and space together; adjacent sizes must look clearly138 different.139- Web body text is at least 16px. Keep lines of prose at 45–75 characters.140 Give wider lines more line height.141- Light text on dark needs a little more line height, sometimes one step142 more weight. Use tabular numerals in columns of numbers.143- Load only the weights you use. Give a fallback font with similar metrics,144 and keep text visible while fonts load.145- Test with real copy: long headings, translated strings and 200% zoom.146147## Color148149- Define colors by role: surface, text, secondary text, action, focus,150 border, and success, warning, error and info. Use the product's tokens.151- For task and reading screens, default to neutrals and one accent. Spend152 the accent on the primary action and on state.153- On a colored surface, make secondary text a shade of that surface's color,154 not gray.155- Contrast: 4.5:1 for body text; 3:1 for large text, icons, control edges156 and focus rings. Check every state and both themes.157- Design the dark theme on its own. Never invert the light theme.158- For a new web palette, use OKLCH and lower chroma near white and black.159- Put text on solid colors, not on stacks of translucent layers.160- Color is never the only signal: [`lang-web-markup`](../lang-web-markup/SKILL.md#idioms-a-linter-misses).161162## Layout163164- Group by distance first; add borders or boxes only when distance fails.165- Use the product's spacing scale; if it has none, use steps of 4px. Keep166 space tight inside a group and wide between groups, with more space above167 a heading than below it.168- Squint check: with the screen blurred, the primary element, then the169 secondary, then the groups must still read in that order.170- Mark depth with a border or a shadow, not both. Use depth only for171 layering or state.172- On small screens, reorder or collapse by importance; do not just shrink.173 Check narrow, middle and wide widths.174- Keep visual order, DOM order and focus order the same.175- Touch targets are at least 44 by 44 CSS pixels, even when the visible mark176 is smaller. Use `gap` for spacing between siblings.177178## Motion179180- Animate only to acknowledge an action, show a state change, link two181 views or mark one key moment. Otherwise add no motion.182- Durations: 100–150 ms for feedback, 150–300 ms for a state change,183 300–500 ms for a view or overlay. Exits are faster than entrances.184- Use an ease-out curve. No bounce or elastic curve unless the brief asks.185- Animate `transform` and `opacity`. Do not animate `width`, `height`,186 `top`, `left` or margins.187- Content is visible before any animation runs; a failed script hides none.188- Never give every section the same entrance animation. Animate one key189 moment, or none.190- With `prefers-reduced-motion`, replace movement with a fade or an instant191 change, and keep the feedback. Stop loops that are off screen.192- Use CSS or the product's motion library; add no dependency for one effect.193194## Every UI state195196Build and check each state that the change can reach.197198- **Controls:** default, hover, visible focus, pressed, disabled, loading.199- **Views with data:** loading; empty on first use; no results; error with a200 way to recover; success; partial data; no permission; offline or slow.201- **Content extremes:** very long text, missing values, zero, one and many202 items, a thousand rows, right-to-left text, CJK text and emoji.203- **Repeat actions:** a second click on submit does not send twice.204- **Copy:** buttons name their action; errors say what failed and what next.205- **Browser parts:** focus rings, text selection, scrollbars and the caret206 use the product's colors, not browser defaults.207208## One verification pass2092101. Build the whole scope first.2112. Render once, at every target size together, and walk each state from212 Every UI state. If you cannot render, say so and check the source.2133. List every defect from that pass.2144. Fix them all in one batch.2155. Check once more at most, then stop. Put what remains in the handoff.216217This pass is the builder's visual self-check. Done evidence is218[`verify-before-done`](../verify-before-done/SKILL.md).219220## Upstream221222- Upstream skill, pinned:223 [pbakaus/impeccable `skill/` at `9d715cc`](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8/skill)224 (Apache-2.0). Pin and notes: [SOURCES.md](../../SOURCES.md).225- **Excluded: the launcher, `scripts/`, the engine binary, every command,226 hooks, installers and updates.** They download and run code this repo has227 not read, and change agent settings without a prompt.228- **Excluded: live mode, image generation, design-direction rolls and229 telemetry.** They send the user's UI or usage data off the machine.230- **Excluded: the shipped subagents and the binary's directives.** They lift231 the harness's gates on subagents and autonomy.232- **Excluded: the `ios` and `android` references.** They are MIT, from another project.233- This rewrite and the pin are compared with upstream at [Monthly](../sdlc/references/trunk-changelog-monthly.md#monthly)234 review. A new pin needs a new **security** read.235236## Ask first237238- A new typeface, color system or motion library.239- A new look for an existing screen that the brief did not ask for.240241## Never242243- Any option 2 step without the operator's explicit yes. Use option 1.244- Run, install or open upstream in an agent harness. Read it as text.245- An install command for upstream in the ask. Give the pinned link.246- Open-ended polishing. Stop after one pass and one re-check.247248## Attribution249250Topics drawn from Impeccable, [pbakaus/impeccable](https://github.com/pbakaus/impeccable/tree/9d715cc4f5564a990ca8345abfdd5df6dc9b41c8)251at `9d715cc4f5564a990ca8345abfdd5df6dc9b41c8`, Apache-2.0. Changes: topic252selection and new text in this repository's words. License: [LICENSE](LICENSE).