Skip to content

phuryn/product-engineering / app-stack/skills/ui-design

ui-design

Verified

Mandatory for any product's screens, a builder's too, and any mock, prototype or artifact that shows them: its design system, colour, type, components; judging the look.

UI design

Load this skill for the whole of a product's look. It holds the rules, which outside skill leads when, and how to judge the result. Reading only part of the method leaves already documented mistakes open to repetition.

What binds, in order

  1. Keep taste and changes to written rules with the owner. Apply the agent-instructions skill to record choices and their precedence. Put each visual question to them as specimens built in the product's real tokens, side by side, never described in words. references/review.md says how to sort a fix from an owner's call.
  2. Apply the method to every kit and every screen. Read references/method.md. A mock, prototype or artifact of a screen is high fidelity too: read the method; where the product has a kit, load its CSS and compose it rather than imitate it (a new product's artifact keeps its values in tokens, and the design stage builds the kit); and check a screenshot against the method before the owner sees it. A product departs from a rule only by the owner's decision, recorded in its kit README with the reason.
  3. Keep the product's kit in three files and compose every screen from it. Put them wherever the product keeps design, often a design/ folder: tokens.css, every raw value (colour, type, space, radius, duration); kit.css, the primitives, built from tokens only; and the kit README, the product's own design document: its direction, palette, type, layout and button roles, each with its reason, and every departure from the method. With no provided design system, start the kit at the design stage, before the first app screen (an artifact before it keeps its values in tokens); maintain it and extend its primitives for each later need so buttons, fields and dialogs remain one set. Screens compose the kit; a screen never invents a style.
  4. Take collection suggestions only through the kit's tokens or primitives. Record them in the kit README; read references/collections.md. Where a collection disagrees with the method, the method wins.

Every screen builder loads this skill from the installed app-stack pack. Keep no product copy. A copy freezes the method at its copied version, and Claude Code loads it twice beside the pack. Builders need to be able to load the rule to read it.

A builder that isn't Claude Code has the pack installed in it too. Codex reads the same marketplace (codex plugin add app-stack@product-engineering), and a brief names the skill there as $app-stack:ui-design: headless codex exec loads it with the pack installed (observed 2026-11-03, codex-cli 0.166.0). An agent with no plugin installer takes the folder through npx skills add, into its own skills folder only. Whatever a collection taught that the next screen needs goes into the kit README, not just the session that used it.

Before any screen: the jobs map

Map the user's jobs before drawing any screen, a builder's included. Work out what people come to do, with one row per job: the job in the user's words → its screen → the screen's one question → its primary action. Put the map in the proposal artifact and every stage brief adding screens. A screen with no job is cut; a job with no screen is a gap.

  • The product's data rules stay out of the copy. The brief lists them (how records are split, sampled, versioned or locked), and a screen shows each only as an outcome in plain words: "12 traces wait for your review", never the table or the method's own vocabulary.
  • Default to the familiar tool's structure when replacing one the owner knows. Generalize that structure and justify every departure in the kit README.
  • The example data fills every screen. Fill every tab too. Show empty states on purpose beside it, so a click-through never meets an empty screen.

Complete phase visual checks before its review series and owner preview

The coordinator checks running screens briefly at the end of each stage. Look at phone and desktop widths and both themes when two exist. The builder never substitutes for this exploratory look.

Finish phase visual checks before its independent review series and owner preview. The coordinator explores the journeys and screens the phase added or changed. Complete the newcomer walkthrough below, the rendered-screen pass against references/screens.md § What to verify visually, and the app-screen screenshot critique. Critique at 1440, 768 and 390, with three rounds at most.

Run the scored Impeccable-style audit at phase end for first screens and kit changes. Fix its P0 and P1 findings. Rerun it before a release changing a screen or kit, and whenever the owner asks. Both critique and audit run from references/collections.md checklists without installing the collections. The owner judges the look at the phase preview, which does not hold the next phase (references/review.md).

The newcomer walkthrough

Give a fresh session only the ordered screenshots and the user's job. Never give the brief or code; alternatively, ask a person new to the domain. Ask the same questions for every screen: what is it for, what would you press next, and what is unclear? Fix any screen it cannot explain or next step it cannot find. Capture every route and dialog with a Playwright crawl at 1280 and 390. Crop pages taller than about 3,000px into ordered parts for reading without downscaling. For Clerk's test-user sign-in recipe, apply the clerk-production skill (references/authenticated-mile.md); other providers use their development test sessions.

Which collection leads, stage by stage

StageLeadsTakeKeep out
The jobs. Before any screenthis skill, § Before any screenthe jobs map; the data rules kept out of the copya screen per table
Direction. No look yet; the look is the problem; a public page whose job is to persuadefrontend-design (always on)a direction grounded in the product's subject; a plan (palette, type, layout, principles) checked against the generic defaults before anything is built; keeping brand colours still runs the kit stagea new direction per screen. Once one is picked, it stops leading
A choice between options. A palette, a font pairing, a chart type, a stack's conventionUI/UX Pro Maxcandidates to choose from. The pick goes into the kit by handits persisted design-system files and its installer: a second design system beside the kit
The kitthe method, with frontend-design's plantokens and primitives that satisfy every rule in method.md, each held by a test where one can be writtenanything a collection proposes that the method forbids
Screens people work in. Dashboards, admin, tables, settingsthe app-screen checklist in references/collections.md § Taste, distilled from its last upstream app chapterthe screen's one question and face; every block's empty, zero, loading and error state; colour only on data, status and the one primary action; its screenshot critique, three rounds at mostTaste's current company-page system, and its palette and type when a kit exists
Chartsdataviz (built in)form first, colour last; its palette validator; one axis; hover by defaultstate colours reused as series colours
What a screen saysreferences/screens.md § What a screen may claim, and frontend-design's section on writingsentences only as true as what the renderer is handed; one function for every summary of a state—
Before it shipsreferences/screens.md § What to verify visually, then Impeccableevery width, state, theme and role; Pro Max's web checks (quick-reference.md §1–3, §8, §9, inside the UI/UX Pro Max skill; without it, its distilled list in collections.md) as a quick pass; Impeccable's audit, hardening and polishPro Max's native/mobile pre-delivery checklist for web work; Impeccable's commands that write their own design documents, and any redesign through it; ellipsis for text a person typed
The owner judges the lookreferences/review.mdmeasured claims, before/after specimens in the real tokens, fixes split from the owner's callsopinions without numbers
A page published as a claude.ai artifactartifact-design (built in)its page contract and both themes—

Read collections.md for each collection's purpose, what to take, what to keep out, installation and a checklist usable without installing it. Without third-party collections, design from the method, frontend-design and those checklists.

The owner's standing preferences

Record your preferences in the kit README or user-level agent instructions. For one product, use the kit README with a pointer from the product's entry file. For every product, use your user-level agent instructions. Use your own words and the date of each choice; edits to the installed pack vanish at its next update. The entries below are the author's worked examples: a taste call with its receipt and scope. Until you write your own, treat them as one owner's taste, not rules.

  • Weight doesn't mark state. "Colors already say this. Two things saying the same it unnecessary in my opinion." (author preference, 2026-10-22, rejecting "bold only on problems".)
    • Don't propose bold, size or weight as a second signal for what colour, shape and word already carry.
    • This is separate from the method's state is form as well as text. That rule exists so colour is never the only signal: it's accessibility, not emphasis, and it stays.
    • It covers bold that's already there, not only new proposals. "Same weight for every state" (author preference, 2026-10-22, asked whether a down badge's word and a failed value should lose their bold): a problem's badge, value, row and name wear the weight of their healthy counterparts. A title stays bold because every title is, whatever state it describes.
  • Use 8 px corners on an app's buttons. "8 px corners in the app" (author preference, 2026-10-22, a monitoring product, shown its pill buttons beside 8 px ones).
    • Inside the app, buttons and segmented controls take a corner between an input's and a panel's, so a control reads as part of the form around it.
    • Tags stay pills everywhere, so inside the app a pill means a label, not something to press. The marketing site and public pages may keep pill buttons.
    • Start the next product's app this way. If its brand points elsewhere, show the owner both before choosing.
  • Calm and reassuring is the target for monitoring and status products. Supabase is the reference the owner named. A healthy screen says so in its own colour, and nothing on it says press or beware louder than that.

Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.

How you can tell it worked

Every screen answers a mapped job and passed the walkthrough, rendered pass and screenshot critique; the last scored audit has no open P0 or P1. The owner approved its look at phone and desktop width, and every raw style value comes from the tokens.

When something is learned

  • Send lessons true for any product to this collection. Make a change for this collection, drafted in the product's feedback file or as an issue on the collection's repository (/agent-harness:retro says how), naming the file it belongs in:

    • a rule for the kit or for building screens goes in method.md;
    • a rule about what screens claim, or how they're checked, goes in screens.md;
    • a change to the review procedure goes in review.md.

    Give each its receipt: the date, and what happened, in a product named by kind, not by name. Hold it with a test where one can be written: a rule only in a report is gone by the next product.

  • Keep lessons true only for this product in its kit README.

  • Record owner preferences in their own words. Use the kit README or their user-level agent instructions (§ The owner's standing preferences).

Where the method lives

  • Replace design with ui-design in product agent instructions. Change any "apply design" instruction there.

  • Install app-stack in every agent that builds screens. Use Claude Code for the user, or with --scope project so every checkout of the product asks for it; Codex from the same marketplace; any other agent through npx skills. Each keeps it current with its own update command (the collection's README, § Install).

  • Delete a product's skill copy once the pack is installed. This includes .claude/skills/design/ or ui-design/, and .agents/skills/ equivalents. Before that, diff -r against the pack's installed folder shows what the copy says that the pack doesn't: this product's lessons go to the kit README, the owner's preferences as above, and a lesson for any product to this collection (§ When something is learned).

  • Nobody edits the installed pack and hopes it travels. A product's lesson goes into its own docs the day it is learned, and the general one goes to this collection as above.

Files

FileHoldsRead when
references/method.mdthe rules every kit and screen satisfieswriting or changing a kit; building any screen
references/collections.mdeach design skill collection: what to take, what to keep out, how to install it, its checklist distilledchoosing or running a collection, or working without one
references/screens.mdwhat a screen may claim; what to verify visuallychanging what a screen says; before a release
references/review.mdreviewing a built product's look with its ownerthe owner judges the look; a release's visual pass
scripts/color.pyOKLCH lightness, chroma and hue, and WCAG contrast (standard library only)any question about a colour: measure it, don't describe it
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall