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:

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

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.

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.