--- name: ui-ux-design description: UI/UX design — interaction states, accessibility contracts, information architecture, visual hierarchy, and design tokens. Use this skill whenever the user wants to design or critique an interface, asks to "design this screen", "what states does this button need", "what ARIA does this menu need", "make this accessible", "how should I structure the navigation", "is this UI any good", "set up design tokens", "review my UX", "mock up design options", or "make this convert better" — even if they never say design and only describe a cluttered screen, a flow users abandon, or a component that breaks on real data. Covers type and color as applied to a UI; send pure type-scale or palette-contrast questions to typography and color-system. Route signups, conversion, retention, and pricing-presentation asks here. Do NOT use for aesthetic direction and polish (see frontend-design), charts (see dataviz), React hooks (see ideal-react-component), A/B testing, or writing the copy itself (headlines, taglines, pricing text). license: MIT argument-hint: "[screen | flow | states | components | tokens | ethics | audit]" metadata: author: Antonin Januska version: "3.0.0" tags: [ux, ui, interaction-design, information-architecture, design-tokens, accessibility, usability, deceptive-patterns, aria] --- # UI/UX Design ## Overview An interface is judged on whether a person can accomplish their goal, not on whether it looks finished. Most defects an agent ships are not ugly — they are the states nobody drew, the flow that assumed the happy path, and the label that broke when the data got long. Two habits below prevent most of them: ship four states per surface, and name tokens for their role. ## Navigation **Read the project's or user's own pattern library first**, if one exists — a design-references folder, a component gallery, a saved set of screens they like. It encodes taste this file cannot, and it outranks the defaults below wherever the two disagree. With no project library to read, [antjanus.com/patterns](https://antjanus.com/patterns) holds 40 component patterns and [antjanus.com/page-designs](https://antjanus.com/page-designs) holds 46 whole-page designs, each with a prompt written to rebuild it without the source. | Load | When | |---|---| | **[references/INTERACTION.md](references/INTERACTION.md)** | Building a control or a route's states — the nine control states, latency, save feedback, undo, delete confirms, motion, forms | | **[references/COMPONENTS.md](references/COMPONENTS.md)** | Building a named component — the ARIA, keyboard, and focus contract for tabs, menus, tables, tooltips, cards, plus batch bars, parsed search, the command palette, and data-display surfaces | | **[references/EXPLORATION.md](references/EXPLORATION.md)** | Generating many design options to choose between — the builder brief, structured review verdicts, and narrowing rounds to one design | | **[references/LAYOUT.md](references/LAYOUT.md)** | Grids, responsive behavior, and the section recipes for landing, pricing, and portfolio pages | | **[references/SYSTEMS.md](references/SYSTEMS.md)** | Design tokens, design systems, and design-to-code handoff | | **[references/VISUAL.md](references/VISUAL.md)** | Applying type, color, and images to a UI, palette retunes, and the brand style guide | | Rarely: **[ETHICS.md](references/ETHICS.md)** · **[PROCESS.md](references/PROCESS.md)** | Conversion, signups, retention, or pricing presentation — the deceptive-pattern catalogue and where the persuasion line sits · planning research, wireframe fidelity, usability tests, launch checklists | ## Audit mode `audit` reviews an app that already exists rather than designing a surface that doesn't. Five phases, each gated on something outside this file. 1. **Scope from the repo, not from the brief.** Read the project's own agent doc, then enumerate every route and the components each one renders. A brief that describes the wrong app still yields the right audit when the surface list comes from the code. 2. **Build the state matrix before judging anything.** One row per surface, one column per state from the four below. A cell you can't fill by reading the code is itself a finding — that state doesn't exist. 3. **Audit inline up to about fifteen surfaces. Past that, split into three or four read-only lanes** by surface family (lists, forms, chrome, accessibility), each carrying the four-states table and the floor inline so a lane doesn't depend on loading this file. A lane starts with none of this context and re-reads the routes it covers, so on a small app it costs more than it saves. Always fewer lanes than surfaces; never one per route. Cap each lane's report so it arrives whole: every finding gets a one-line headline, its file and line, and why it matters; code excerpts only for that lane's top three. 4. **Publish one report, ranked by consequence, and stop.** Every visual change gets a **rendered before and after** — real markup at real sizes, side by side, with the difference named underneath. A description of a change is not a before and after. Size the report to the finding count; one longer than the fix list it produces goes unread. 5. **Get approval per finding before implementing.** Present the ranked list and let the user accept, cut, or reorder it — audits reliably surface items the user considers not worth the pixels, and shipping those spends the credibility the real findings earned. Record what was approved, and what was cut, where the project already tracks work. **A passing verdict is a legitimate outcome.** If the surfaces hold up, say so and name what was checked. An audit that always finds ten things isn't measuring. ## Presenting concept options Show each option as a **full screen in the app's own chrome** — its real nav, header, and a plausible amount of real data — not as thumbnails, isolated components, or fragments. A user cannot judge a layout they have to assemble in their head, and fragments get rejected on that ground alone. Within each screen, default to the fewest elements that answer the question being asked; add density only when the user asks for it, because a concept that reads as complex gets rejected before its idea is considered. Generating many options at once — dozens of directions, review rounds, narrowing to one — has its own method in [EXPLORATION.md](references/EXPLORATION.md). ## An approved mockup is the spec **On approval, write it into the project's tracked plan.** Add the approved design as its own task in `SESSION_PROGRESS.md` or `ROADMAP.md` — what was approved, and the artifact URL or file path where it lives. The session that implements it may never load this skill, and a plan it reads is the only way the approval reaches it; an approval that lives only in a chat transcript gets silently dropped while every listed task still reports done. For any implementation of a design the user signed off on, put the approved artifact and the running screen side by side before reporting done, and list every element that differs — the hero that isn't full-bleed, the strip that stopped short of the edge, the card layout that got simplified, the data that landed in a different section than agreed. Fix each one or say which differences you're keeping and why. Drift concentrates in whatever nobody re-opened: the sections further down the page, the second posture of a two-mode screen, the component specified last. ## The floor Non-negotiable, and cheap to get right at build time rather than in an audit later. - **4.5:1 contrast for normal text, 3:1 for large — in every state, in both color schemes.** Hover, pressed, and disabled fills are where this silently breaks; nobody rechecks them. A dark scheme built after the light one breaks all three at once, so it ships with the surface or the surface isn't done. - **44×44px minimum touch target.** Grow it with padding, not font size. - **Never let color alone carry meaning.** Pair every color shift with an icon, a border-weight change, or an underline, or the state is invisible to colorblind users. - **Visible focus, via `:focus-visible`.** Never `outline: none` without a replacement ring — that cuts off keyboard and assistive-tech users entirely. - **Native semantic HTML before ARIA.** ARIA layered onto generic markup adds errors rather than removing them. `
`, `