Use whenever an agent designs, restructures, implements, or reviews an interface: information architecture, navigation, flows, forms, controls, content hierarchy, responsive behavior, accessibility, visual systems, interaction states, or usability.
Use it before aesthetic exploration to establish structure, and again after implementation as a rendered-interface quality gate. Do not use it for pure backend work or as a substitute for user research when the users, domain, or risks are unknown.
Contract
This skill produces interfaces that are understandable, operable, resilient, and visually coherent. It guarantees that:
the user, job, product truth, constraints, and success outcome are explicit before styling;
information architecture and task hierarchy precede component selection;
the complete flow includes loading, empty, partial, success, error, permission, offline, interruption, and recovery states where relevant;
UX laws are selected as diagnostic lenses, not treated as universal commandments;
accessibility, responsive behavior, content stress, and input modes are part of the design, not a cleanup pass;
recommendations are verified in the rendered interface when implementation access exists;
the output makes decisions and trade-offs explicit instead of producing generic advice.
Core principle
Design the shortest honest path from user intent to a recoverable outcome.
“Short” does not mean hiding important context. “Honest” means the interface accurately represents product state, consequences, price, availability, permissions, and uncertainty. “Recoverable” means mistakes, interruptions, and failures do not destroy work or trap the user.
Mandatory workflow
1. Define the real task and product truth
Before drawing or editing screens, state:
primary user and context;
job to be done;
entry point and prior knowledge;
successful outcome;
costly or dangerous mistakes;
product states and unavailable actions;
device, input, language, accessibility, privacy, and implementation constraints;
business goal only where it does not conflict with the user's goal.
Resolve contradictions between product behavior and interface promises first. Visual polish cannot rescue a dishonest or impossible flow.
2. Build the information architecture
Inventory the objects, attributes, actions, destinations, and lifecycle states the interface must represent. Then:
remove content or controls that do not support a real task;
use the user's language rather than internal system vocabulary;
group by meaning and decision sequence;
rank each item as primary, secondary, tertiary, or metadata;
keep critical context and consequences visible at the decision point;
progressively disclose advanced or rare complexity;
make navigation location, destination, and escape routes clear;
use search, filtering, grouping, or saved views when the information space is genuinely large.
Do not make the site map mirror the org chart or database schema unless users actually think that way.
Every consequential action must have visible availability, immediate acknowledgment, and a trustworthy final state.
4. Select UX laws by the observed problem
Do not decorate a design with law names after the fact. Start with a concrete failure (slow choice, missed target, forgotten context, weak grouping, abandoned flow) and select only the laws that explain it.
Decision and memory
Law or effect
Use when
Design move
Misuse to avoid
Cognitive Load
A screen requires excessive reading, remembering, switching, or decoding
“Simplifying” by hiding information needed for a safe decision
Miller's Law / working-memory limits
Users must remember items across screens or compare many unstructured facts
Chunk meaningfully, label groups, preserve context, and favor recognition over recall
Treating 7 ± 2 as a literal maximum for menu items or form fields; capacity varies and is often lower without rehearsal
Hick's Law
Decision time grows because choices are numerous or hard to distinguish
Remove irrelevant choices, group by meaningful attributes, recommend when evidence supports it, and add search/filtering for large sets
Hiding legitimate options, splitting one decision into unnecessary steps, or forcing a default that benefits the business over the user
Choice Overload
Users defer, abandon, or regret a decision because the option set feels unmanageable
Curate, compare on discriminating criteria, stage optional choices, and provide a reversible default
Confusing fewer choices with better choices or reducing user autonomy
Tesler's Law
A task contains irreducible domain complexity
Let the system absorb parsing, calculation, repetition, and safe defaults; expose complexity only where human judgment is required
Hiding consequences, uncertainty, compliance, or expert controls that the user genuinely needs
Targeting and conventions
Law or effect
Use when
Design move
Misuse to avoid
Fitts's Law
Important controls are slow or error-prone to acquire
Increase target and hit-area size, reduce pointer travel, place actions near the object they affect, and separate dangerous neighbors
Reducing the law to arbitrary list ordering; making a visually large element with a tiny actual hit area
Jakob's Law
Users hesitate because controls or navigation behave unexpectedly
Reuse platform and domain conventions; preserve keyboard and native-control expectations
Copying bad conventions or rejecting a clearly better pattern merely because it is new
Postel's Law, bounded
Benign human input arrives in varied formatting
Accept safe variation, normalize explicitly, preview the canonical result, and emit consistent data
Applying permissiveness to authentication, security boundaries, money, dates with ambiguous locale, or external protocols where strict validation is safer
Target-size floor: for web pointer inputs, WCAG 2.2 Level AA defines a 24×24 CSS-pixel minimum or sufficient spacing under its exceptions. Treat this as a floor, not an ergonomic goal. Prefer larger targets for primary actions, touch, motion impairment, destructive choices, and use under pressure.
Time, momentum, and interruption
Law or effect
Use when
Design move
Misuse to avoid
Doherty Threshold / response-time heuristics
Delay breaks the sense of direct manipulation or flow
Acknowledge input immediately, preserve input, show useful partial state, and provide honest progress/cancellation for longer work
Fake progress bars, decorative delays, blocking the whole screen, or using one fixed threshold for every context
Goal-Gradient Effect
A finite multi-step task is abandoned because progress is unclear
Show truthful progress, completed and remaining work, and a stable finish line
Moving the finish line, hiding surprise steps, or manufacturing pressure
Zeigarnik Effect
Users leave work unfinished or are interrupted
Auto-save when safe, label drafts, preserve position, and make resumption obvious
Guilt, nagging, anxiety loops, or retaining sensitive drafts without consent
Peak-End Rule
Completion, recovery, or a high-friction moment shapes the remembered experience
Make the hardest moment supported and the ending clear: what happened, what remains, and what to do next
Confetti or delight used to compensate for a broken core flow
Use the classic response-time bands as design heuristics, not service-level guarantees: around 0.1 s feels direct, around 1 s preserves thought flow, and beyond roughly 10 s users need meaningful progress, interruption, and return support. Measure the real product and users.
Order, emphasis, and grouping
Law or effect
Use when
Design move
Misuse to avoid
Serial Position Effect
Important items disappear in a long ordered sequence
Put high-priority or frequently needed items in strong positions and create meaningful sections
Ordering everything for memorability when task sequence, chronology, or alphabetical retrieval matters more
Von Restorff Effect
One action or status must stand out among similar elements
Create one controlled contrast in shape, weight, position, label, or color plus non-color meaning
Multiple “special” elements, novelty without meaning, or inaccessible color-only emphasis
Law of Proximity
Relationships are unclear because spacing is uniform
Use tighter spacing within groups and larger spacing between groups
Inferring semantic meaning from proximity alone without labels or structure
Law of Similarity
Repeated functions look inconsistent or different functions look identical
Make same-function controls consistent and distinct meanings visibly distinct
Making destructive and safe actions look the same; relying on appearance without accessible names
Law of Common Region
A boundary would clarify a real section or object
Use a container, fieldset, panel, or background only where it communicates membership
Card soup, nested boxes, and borders around every element
Aesthetic-Usability Effect
Trust and perceived ease suffer from incoherent craft
Use a deliberate type, spacing, color, motion, and component system; remove visual defects
Assuming attractive means usable or letting polish conceal accessibility and behavior failures
5. Define the interface system
Create a constrained system rather than styling each screen independently. Two defaults do most of the work: an 8px spatial grid and atomic composition. If the codebase already has an equivalent system, extend it; never run a second system beside it. Set direction before spending the grid:
5a. Aesthetic direction
Commit before styling: name the subject, audience, and the page's single job; derive palette, type, and layout from the subject's own world (frontend-design).
Kill the generic-AI looks: cream near #F4F1EA + serif + terracotta; near-black + lone acid-green/vermilion accent; broadsheet hairlines + zero radius. Use one only when the brief asks (frontend-design).
No purple-on-white default; no dark-mode bias unless requested; no flat single-color backgrounds, layer gradient/imagery/pattern for atmosphere (better-frontend).
Plan a token brief first: 4-6 named hex values, 2+ type roles (characterful display used with restraint, complementary body), one layout concept, one signature element. If any part matches what you would make for any similar prompt, revise it (frontend-design).
Spend boldness in one place: one signature element, everything around it quiet; remove one accessory before shipping (frontend-design).
Work in grayscale first. Color is the easiest way to fake hierarchy; removing it forces spacing, size, and contrast to carry the structure. Add the palette once the gray version already reads correctly (refactoring-ui).
Typography-led hierarchy
Two typefaces max; never default to Inter/Roboto/Arial/system-ui unless the design system requires them. Type carries the page's personality (better-frontend, frontend-design).
Build hierarchy from weight + size + leading as a set; emphasize with weight, it adds presence without space (apple-design).
Tracking is size-specific: about -0.02em on display, near 0 on body, slightly positive on small text; leading inversely with size (apple-design).
5b. Spacing and sizing: the 8px grid
Every padding, margin, gap, and fixed box dimension comes from one scale on an 8px base, with 4px as the half-step for tight pairs (icon-to-label, checkbox-to-text):
4 8 12 16 24 32 48 64 96
Define the scale as tokens (--space-1: 8px … --space-12: 96px, or the framework equivalent) and spend values from tokens, not literals.
Rules that survive real projects:
The grid governs boxes, not glyphs. Apply it to padding, margins, gaps, control heights, and icon sizes. Line-height obeys readability, not the grid: 25.6px or 28px line-height is correct where the grid would force 24px or 32px.
The spacing ladder must never invert. Spacing encodes grouping (Law of Proximity): label-to-control 4–8, siblings inside a group 8–16, between groups 24–32, between page sections 48+. A card whose internal padding (16) exceeds the gap to its neighbor (8) reads as one merged blob.
Size controls on the grid. Control heights 32/40/48; icons 16/20/24; pointer targets at least 24×24 (WCAG 2.2 floor), 44×44 for primary touch actions.
Start generous and subtract. Adding space until a layout stops looking bad lands on the minimum tolerable amount. Starting from too much and trimming lands on the right amount (refactoring-ui).
Steps must be far enough apart to choose between. Adjacent values differ by roughly 25% or more; that is what makes the pick unambiguous. A plain every-4px list gives no basis to decide between 120 and 124. Above 96, continue the ratio rather than the increment: 128, 192, 256, 384 (refactoring-ui).
Exceptions are declared, not leaked. A living system tolerates a few off-scale values (a 12px chip padding, an 80px hero offset) when they are named tokens with a stated reason. Silent literals like 9px, 13px, 17px are defects.
Audit mechanically. Run scripts/grid-audit.sh: it flags off-grid px per property (0/1/2 and line-height/letter-spacing exempt; font-size checked against the type set). In rendered review, off-grid values appear as almost-aligned edges: measure, do not eyeball.
5c. Composition: the atomic system
Build in strict layers; each layer consumes only the layer below:
Tokens in two tiers: primitive (--gray-700, --space-2) and semantic (--color-text, --btn-bg). Components reference semantic tokens only, so theming and dark mode become token swaps, not rewrites.
Build the ramps up front, in HSL. Two related HSL values look related; two related hex codes do not. Give each hue 8–10 steps (three runs out immediately), name them 100 lightest to 900 darkest, and fix 500 first as a color that works as a button fill, then the ends, then fill the gaps. Start the dark end at a very dark neutral rather than true black. Never derive shades at runtime, which yields dozens of near-identical blues (refactoring-ui).
Atoms: button, input, label, icon, badge, checkbox. An atom never sets its own external margin; the parent owns spacing via gap.
Molecules: form field (label + control + help + error), search bar, setting row, menu item.
Templates and screens compose organisms; a new screen that demands a new atom needs a stated reason.
Rules that survive real projects:
Tokens are step zero. Retrofitting tokens onto already-styled screens is the single largest time sink in system work; hardcoded colors and spacing metastasize. Cut tokens before styling the first screen.
Rule of three. Second appearance of a pattern: note it. Third: extract the component. Two "setting rows" with different backgrounds, radii, and padding are one molecule with a bug, not two designs.
Variants, not clones. Same function, one component, differentiated by modifier (primary/secondary/ghost/destructive, sm/md/lg), never by copy-pasted styles that drift apart.
One radius and one elevation per component level. Pick a small set (4/8/12/full) and map each component class to one value. Mixed radii inside one card stack is the fastest tell of an unsystematic UI.
Type scale is semantic and hand-picked. Roles (display, heading, subheading, body, caption) map to a fixed set: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72. Hand-picked beats ratio-derived: modular scales produce fractional pixels that round unevenly, and they run too sparse at interface density and too dense at display sizes (refactoring-ui). Size the scale in px or rem, never em, since nested em values compound off the scale. The type scale and the spacing scale are separate sets: 32 is a valid spacing step and not a type step (use 30 or 36), and 30 is a type step but not a spacing step. Line-height tightens as size grows; body lines stay within 40–80 characters. For typeface selection and pairing, use the google-fonts skill (https://www.skills.sh/sliday/google-fonts-skill/google-fonts) instead of picking fonts ad hoc.
Fix the remaining system rules explicitly: semantic color tokens for surface, text, action, status, and focus, with contrast floors of 4.5:1 for body text and 3:1 for large text and essential UI graphics (large means 24px regular or 18.66px bold, not 18px; the separate 3:1 non-text floor covers borders that identify a control, not decorative dividers); icon vocabulary; border, elevation, and motion rules; content and error-message voice; keyboard, pointer, touch, focus, hover, selected, disabled, loading, and destructive states.
One-off visual values require a reason. Consistency is not sameness: component variants should communicate different semantics while remaining part of one system.
5d. Craft details
Surfaces
Concentric radius: outerRadius = innerRadius + padding. Above 24px padding, treat layers as separate surfaces (make-interfaces-feel-better).
Shadows over borders for elevation. Light token: 0 0 0 1px rgba(0,0,0,.06), 0 1px 2px -1px rgba(0,0,0,.06), 0 2px 4px 0 rgba(0,0,0,.04); hover .08/.08/.06. Dark: single ring 0 0 0 1px rgba(255,255,255,.08), hover .13. Keep real borders for dividers and input outlines (make-interfaces-feel-better).
One box-shadow depth per section (better-frontend).
Image outlines: 1pxrgba(0,0,0,0.1) light / rgba(255,255,255,0.1) dark, outline-offset: -1px. Pure black/white only; tinted neutrals read as dirt (make-interfaces-feel-better).
Translucent chrome: backdrop-filter: blur(20px) saturate(180%) + semi-transparent bg; never stack two light translucent surfaces; scroll-edge fade instead of a 1px border under sticky headers (apple-design).
Dim scrim behind modal tasks; parallel non-blocking panels get no scrim (apple-design).
Optical alignment
Optical beats geometric. Icon-side button padding = text-side minus 2px; play triangles shift about 2px right; fix asymmetric icons in the SVG itself (make-interfaces-feel-better).
Align mixed type sizes on one line by baseline, not center; centering misaligns them in a way that reads as subtly broken (refactoring-ui).
Add roughly +0.05em tracking to all-caps text: caps are uniform blocks that crowd at default spacing (refactoring-ui).
Keep icons near their intended size. A 16–24px icon blown up to 48px reads chunky and detail-starved; nest it in a colored circle instead (refactoring-ui).
Choose elevation by the element's z-position, not by which shadow looks best; shrinking a shadow on press reads as depressed (refactoring-ui).
Constrain user-uploaded imagery: fixed containers, cover-fit, crop the overflow. When an upload's edges dissolve into the page, use a faint inset shadow rather than a border, which fights the image's own colors (refactoring-ui).
Text rendering
text-wrap: balance on headings (works only up to 6 lines Chromium / 10 Firefox); text-wrap: pretty on short-to-medium body; neither on 10+ lines (make-interfaces-feel-better).
font-variant-numeric: tabular-nums on any updating number (counters, timers, prices, table columns); not on phone numbers or version strings (make-interfaces-feel-better).
-webkit-font-smoothing: antialiased + -moz-osx-font-smoothing: grayscale once at the root (make-interfaces-feel-better).
Author the spacing scale in rem so it tracks user text size: 4px = 0.25rem, 8px = 0.5rem, 16px = 1rem. The px values in 5b name design-time grid steps, not literal units (apple-design).
Interaction feel
Feedback on pointer-down, not release; continuous during the interaction (apple-design).
Scale on press: :active { scale: 0.96 } with 150ms ease-out; never below 0.95; offer a static opt-out (make-interfaces-feel-better, emil-design-eng).
Gate hover behind @media (hover: hover) and (pointer: fine) (emil-design-eng).
Extend small controls to full hit size with a pseudo-element; never overlap two hit areas (make-interfaces-feel-better).
Tooltips: delay the first, open adjacent ones instantly with no animation while one is open (emil-design-eng).
Same action name through the flow: "Publish" button yields "Published" toast; errors say what happened and how to fix, no apology, never vague (frontend-design).
Self-check
Review with fresh eyes next day; play animations at 2-5x duration and frame-by-frame to catch overlap, wrong transform-origin, desynced properties (emil-design-eng).
Report polish diffs as a Before/After/Why table, one row per change (emil-design-eng).
5e. Motion
Decide first
Frequency gate: 100+ uses/day (keyboard shortcuts, command palette) never animate; tens/day reduce drastically; occasional (modals, drawers, toasts) standard; rare moments may delight. Never animate keyboard-initiated actions; context menus animate exit only (emil-design-eng, 12-principles-of-animation).
Every animation names a purpose: spatial consistency, state indication, feedback, explanation, or preventing a jarring change. "Looks cool" + frequent = cut (emil-design-eng).
Durations
Press feedback 100-160ms; tooltips/small popovers 125-200ms; dropdowns/selects 150-250ms; modals/drawers 200-300ms, large drawers up to 500ms only as a declared exception (the craft audit flags >=400ms for review); general UI ceiling 300ms (emil-design-eng).
Exits shorter and softer than enters (150ms vs 300ms); exit with small fixed translateY about -12px, not container height (make-interfaces-feel-better).
Identical timing for similar elements; slow only where the user decides (hold-to-delete 2s linear), fast where the system responds (release 200ms ease-out) (12-principles-of-animation, emil-design-eng).
Easing
Enter ease-out, exit ease-in, on-screen move ease-in-out, hover/color ease, linear only for constant motion. Never ease-in on entrances (emil-design-eng, 12-principles-of-animation).
Animate only transform, opacity, filter, clip-path; never transition: all, list exact properties (emil-design-eng, make-interfaces-feel-better).
Never enter from scale(0): use scale(0.95) + opacity: 0; enter recipe adds translateY(8-12px) + blur(4px) (emil-design-eng, make-interfaces-feel-better).
Popovers scale from their trigger's transform-origin; modals stay centered. Enter and exit along the same path (emil-design-eng, apple-design).
Stagger semantic chunks about 100ms apart, list items 30-80ms (50ms cap for dense lists); one focal point at a time; never block interaction (make-interfaces-feel-better, 12-principles-of-animation).
CSS transitions for interactive state (interruptible, retargets); keyframes only for one-shot sequences; @starting-style for entry; initial={false} so default-state elements skip mount animation (emil-design-eng, make-interfaces-feel-better).
Springs for gestures: bounce 0 default, 0.1-0.3 only after a flick; animate from the live on-screen value; hand off release velocity; rubber-band boundaries instead of hard stops (apple-design).
Reduced motion
prefers-reduced-motion: reduce means gentler, not zero: keep opacity/color changes, replace slides/springs/parallax with about 200ms cross-fades, drop overshoot; prefers-reduced-transparency raises bg opacity and drops blur (emil-design-eng, apple-design).
6. Compose hierarchy and layout
Use size, contrast, position, spacing, alignment, and containment to reflect actual importance.
When reviewing an interface you did not design, or when the only report is "it looks off", start from references/visual-diagnostics.md: a symptom-to-fix index covering hierarchy, spacing, borders, typography, imagery, polish, and accessibility.
Weight and color do more of this work than size. Leaning on size alone pushes the primary element to cartoon proportions and squeezes the secondary one below readability; keep sizes nearer the middle of the scale and separate levels with weight (600/700) and text color instead. Cap text colors at three (primary, secondary, tertiary), and hold all three to 4.5:1, which puts the lightest around the middle of the ramp rather than the pale end. When one element still refuses to lead, de-emphasize its neighbors instead of amplifying it (refactoring-ui).
Rank actions by importance, not by semantics: primary is one solid high-contrast action per surface, secondary is outline or low-contrast fill, tertiary reads as a link. A destructive action is not automatically a large red button; give Delete tertiary treatment where it sits, then make it the primary action inside its confirmation dialog (refactoring-ui).
When a component looks generic, the cause is usually an inherited mental picture of what that component is. Break the box: dropdowns can carry columns, icons, and per-item descriptions; a table column can hold two related fields; a radio group can become selectable cards that show the actual differences (refactoring-ui).
Marketing-surface composition rules:
Hero budget: brand, one headline, one supporting sentence, one CTA group, one dominant image. No stat strips, pill clusters, icon rows, promo chips (better-frontend).
Brand test: remove the nav; if the first viewport could belong to another brand, branding is too weak (better-frontend).
Full-bleed hero on landing pages; no inset/rounded media-card heroes, no floating badges on hero media (better-frontend).
Cards only when they contain interaction. Card test: strip border/shadow/background; if nothing is lost, it is not a card (better-frontend).
Structure encodes meaning: 01/02/03 markers only for real sequences; marketing narrative runs hero, supporting imagery, product detail, social proof, final CTA (frontend-design, better-frontend).
Required checks:
the primary task is obvious within a few seconds;
section boundaries survive a squint/blur test;
labels sit with the controls or values they describe;
primary, secondary, and destructive actions do not compete;
content remains readable at narrow widths and zoom;
long labels, translations, large numbers, missing images, and dense data do not collapse the layout;
visual centering is inspected, not assumed from equal CSS offsets.
Avoid centering long reading text, excessive line length, ornamental cards, ambiguous icons, and decorative whitespace that pushes the next action off-screen.
7. Design controls, forms, and content
Use familiar native semantics before custom widgets.
Keep visible labels on inputs; placeholders are examples, not labels.
In read-only data display, labels are a last resort: most values identify themselves by format or context. Fold the label into the value ("12 left in stock") or make it clearly secondary. Spec sheets, where people scan for the label itself, are the exception. This never licenses removing input labels (refactoring-ui).
Design the empty state as a real screen: one illustration or mark, one clear headline, one emphasized action. Hide tabs, filters, and search until content exists to act on (refactoring-ui).
Ask only for information required now.
Match controls to the decision: checkbox for independent choices, radio for a small exclusive set, select/combobox for larger known sets, search/filter for large spaces.
Preserve entered data after errors.
Validate at a useful moment without fighting normal typing.
Explain errors in plain language: what happened, where, and how to recover.
Make destructive consequences explicit and proportional; prefer undo when feasible.
Use action-specific button labels and destination-specific links.
Never rely on color, position, gesture, hover, or iconography as the only carrier of meaning.
8. Accessibility and resilience gate
At minimum verify:
semantic structure and accessible names;
logical reading and focus order;
keyboard operation and visible focus;
contrast and non-color status meaning;
target size and target spacing;
zoom, reflow, and text resizing;
screen-reader exposure of hidden/intermediate content;
error identification and recovery;
reduced motion and animation control;
touch, pointer, keyboard, and assistive-input paths;
loading, partial, offline, empty, and permission states.
Do not claim accessibility conformance from a visual review alone. Use automated checks as a floor and manually exercise keyboard, screen-reader, zoom, and state behavior relevant to the interface.
9. Verify the rendered product
Source code, a design file, or a component test is not enough. When implementation access exists:
open the real interface;
exercise the primary flow and at least one recovery flow;
capture representative wide and narrow viewports;
inspect actual pixels, content, alignment, focus, and state changes;
test realistic and extreme content;
verify console/network behavior when relevant;
compare before/after evidence;
distinguish verified behavior from assumptions and remaining risks.
Use agent-visual-verification when a deterministic screenshot evidence path is needed. Use full browser automation when the flow requires navigation, typing, state mutation, network inspection, or assertions.
Automated guards
The skill ships mechanical checks; run them instead of eyeballing:
scripts/grid-audit.sh <file-or-dir> flags every px value off the 8px grid, per CSS property: margins/padding/gap/radius must be 0/1/2 or divisible by 4; font-size must be in the 12/14/16/18/20/24/30/36/48/60/72 set; line-height and letter-spacing are exempt (readability beats grid). Exit 1 on violations, with file:line: property value output.
hooks/design-guard.sh is a PostToolUse hook: after any Edit/Write to a .css/.scss/.less/.html/.jsx/.tsx/.vue/.svelte file, it audits that file and feeds violations back to the agent as a fix prompt. Silent on clean files, non-style files, and malformed input; never blocks the edit itself; no retries.
Install: merge hooks/hooks.json into .claude/settings.json (project) or ~/.claude/settings.json (global); adjust the script path to where this skill is installed.
The guard catches literals, not judgment: it cannot see an inverted proximity ladder, a cloned component, or a missing state. Those still require the review workflow above.
Review severity
Classify findings by user impact:
Blocker: prevents completion, causes data loss, exposes unsafe action, or creates a critical accessibility barrier.
Major: likely confusion, abandonment, repeated error, inaccessible path, or material loss of trust.
Minor: local inconsistency or friction with a clear workaround.
Polish: aesthetic improvement without meaningful task impact.
Lead with blockers and majors. Do not bury a broken flow under spacing comments.
Output format
User, job, and interface promise
Product truth and constraints
IA hierarchy: primary, secondary, tertiary, metadata
Flow and state model
Relevant UX laws: problem → law → design move → trade-off
For implementation tasks, make the changes and cite concrete files/components. Do not stop at critique when the user asked for a fix.
Compact release checklist
Primary user, job, success, and failure are explicit.
Product state and action availability are truthful.
IA follows user meaning and decision sequence.
One clear primary action exists per decision surface.
Needed context is visible; rare complexity is progressively disclosed.
Relevant UX laws were selected by problem, with misuse checks.
Every padding, margin, and gap sits on the spacing scale; exceptions are named tokens with reasons.
Repeated patterns are extracted components with variants; no near-duplicate clones.
Components consume semantic tokens; no hardcoded color or spacing literals.
Loading, empty, partial, success, error, interruption, and recovery states are covered.
Controls have honest hierarchy, labels, target size, focus, and states.
Forms preserve work and explain recovery.
Color is not the only signal; contrast and focus are visible.
Narrow viewport, zoom, long content, and translation stress were tested.
Keyboard and relevant assistive-technology paths were exercised.
The actual rendered interface was inspected.
Verified facts and unverified assumptions are separated.
Anti-patterns
Starting with components, visual references, or a design trend before understanding the task.
Citing UX laws as proof without observing the actual user problem.
Applying arbitrary numeric limits such as “never show more than seven items.”
Hiding complexity that users need to understand consequences.
Using progressive disclosure to conceal price, risk, permissions, or destructive effects.
Adding cards, borders, icons, motion, gradients, or color without informational purpose.
Off-scale spacing literals (9px, 13px, 17px) instead of scale tokens.
Cloned near-identical components that drift in radius, padding, or background instead of one component with variants.
Forcing line-height and letter-spacing onto the 8px grid at the cost of readability.
Multiple competing primary actions.
Placeholder-only labels, icon-only meaning, or color-only status.
Custom controls that lose native keyboard and accessibility behavior.
Fake progress, manipulative urgency, guilt-driven incompletion, or surprise steps.
Treating responsive design as shrinking the desktop layout.
Declaring success from source inspection without exercising the rendered interface.
Reporting dozens of polish notes while a core flow is broken.
Do Not Use When
The task has no user interface or user-facing workflow.
The real blocker is an unresolved product, policy, legal, or business decision that design cannot safely invent.
The user needs empirical research with a specific population; run research rather than presenting heuristics as evidence.
A specialized domain standard (medical, aviation, automotive, financial trading, public safety) supersedes generic UX guidance.
Sources and provenance
This is an original synthesis. Version 1.2 additionally merges concrete craft rules mined from installed design skills (better-frontend, make-interfaces-feel-better, emil-design-eng, apple-design, frontend-design, 12-principles-of-animation, ui-ux-pro-max, landing-page-design, web-design-guidelines, google-fonts); the full deduped catalog with per-rule attribution lives in references/borrowed-craft.md. Version 1.3 adds a visual symptom-to-fix index in references/visual-diagnostics.md and inline hierarchy, palette, and type-scale rules distilled from Refactoring UI (Adam Wathan, Steve Schoger) by way of the refactoring-ui-skill notes, rewritten and reconciled with this skill's existing systems. A user-provided set of 18 UX-law notes was treated as source material, then rewritten, de-frameworked, corrected, and consolidated rather than republished as separate micro-skills.
The laws are heuristics. Validate consequential decisions with users, domain evidence, accessibility testing, and the real rendered product.
1---2name: ux-ui-ia3description: Use when designing or reviewing interfaces, setting up a spacing scale or design tokens, or restructuring UI into a component system.4license: MIT5---67# UX/UI/IA89## When to Use1011Use whenever an agent designs, restructures, implements, or reviews an interface: information architecture, navigation, flows, forms, controls, content hierarchy, responsive behavior, accessibility, visual systems, interaction states, or usability.1213Use it before aesthetic exploration to establish structure, and again after implementation as a rendered-interface quality gate. Do not use it for pure backend work or as a substitute for user research when the users, domain, or risks are unknown.1415## Contract1617This skill produces interfaces that are understandable, operable, resilient, and visually coherent. It guarantees that:1819- the user, job, product truth, constraints, and success outcome are explicit before styling;20- information architecture and task hierarchy precede component selection;21- the complete flow includes loading, empty, partial, success, error, permission, offline, interruption, and recovery states where relevant;22- UX laws are selected as diagnostic lenses, not treated as universal commandments;23- accessibility, responsive behavior, content stress, and input modes are part of the design, not a cleanup pass;24- recommendations are verified in the rendered interface when implementation access exists;25- the output makes decisions and trade-offs explicit instead of producing generic advice.2627## Core principle2829Design the shortest honest path from user intent to a recoverable outcome.3031“Short” does not mean hiding important context. “Honest” means the interface accurately represents product state, consequences, price, availability, permissions, and uncertainty. “Recoverable” means mistakes, interruptions, and failures do not destroy work or trap the user.3233## Mandatory workflow3435### 1. Define the real task and product truth3637Before drawing or editing screens, state:3839- primary user and context;40- job to be done;41- entry point and prior knowledge;42- successful outcome;43- costly or dangerous mistakes;44- product states and unavailable actions;45- device, input, language, accessibility, privacy, and implementation constraints;46- business goal only where it does not conflict with the user's goal.4748Resolve contradictions between product behavior and interface promises first. Visual polish cannot rescue a dishonest or impossible flow.4950### 2. Build the information architecture5152Inventory the objects, attributes, actions, destinations, and lifecycle states the interface must represent. Then:53541. remove content or controls that do not support a real task;552. use the user's language rather than internal system vocabulary;563. group by meaning and decision sequence;574. rank each item as **primary, secondary, tertiary, or metadata**;585. keep critical context and consequences visible at the decision point;596. progressively disclose advanced or rare complexity;607. make navigation location, destination, and escape routes clear;618. use search, filtering, grouping, or saved views when the information space is genuinely large.6263Do not make the site map mirror the org chart or database schema unless users actually think that way.6465### 3. Design the flow and state model6667Map the smallest complete journey:6869```text70entry → orientation → decision → action → feedback → outcome → next step71```7273Add relevant non-happy paths:7475- loading and slow response;76- zero, one, many, and extreme data;77- partial completion and drafts;78- validation and server errors;79- lost connection and retry;80- expired session or permission changes;81- destructive confirmation and undo/recovery;82- interruption and resumption;83- duplicate submission and idempotency;84- success closure and the next useful action.8586Every consequential action must have visible availability, immediate acknowledgment, and a trustworthy final state.8788### 4. Select UX laws by the observed problem8990Do not decorate a design with law names after the fact. Start with a concrete failure (slow choice, missed target, forgotten context, weak grouping, abandoned flow) and select only the laws that explain it.9192#### Decision and memory9394| Law or effect | Use when | Design move | Misuse to avoid |95|---|---|---|---|96| **Cognitive Load** | A screen requires excessive reading, remembering, switching, or decoding | Reduce extraneous work, externalize memory, sequence complexity, and keep needed context nearby | “Simplifying” by hiding information needed for a safe decision |97| **Miller's Law / working-memory limits** | Users must remember items across screens or compare many unstructured facts | Chunk meaningfully, label groups, preserve context, and favor recognition over recall | Treating `7 ± 2` as a literal maximum for menu items or form fields; capacity varies and is often lower without rehearsal |98| **Hick's Law** | Decision time grows because choices are numerous or hard to distinguish | Remove irrelevant choices, group by meaningful attributes, recommend when evidence supports it, and add search/filtering for large sets | Hiding legitimate options, splitting one decision into unnecessary steps, or forcing a default that benefits the business over the user |99| **Choice Overload** | Users defer, abandon, or regret a decision because the option set feels unmanageable | Curate, compare on discriminating criteria, stage optional choices, and provide a reversible default | Confusing fewer choices with better choices or reducing user autonomy |100| **Tesler's Law** | A task contains irreducible domain complexity | Let the system absorb parsing, calculation, repetition, and safe defaults; expose complexity only where human judgment is required | Hiding consequences, uncertainty, compliance, or expert controls that the user genuinely needs |101102#### Targeting and conventions103104| Law or effect | Use when | Design move | Misuse to avoid |105|---|---|---|---|106| **Fitts's Law** | Important controls are slow or error-prone to acquire | Increase target and hit-area size, reduce pointer travel, place actions near the object they affect, and separate dangerous neighbors | Reducing the law to arbitrary list ordering; making a visually large element with a tiny actual hit area |107| **Jakob's Law** | Users hesitate because controls or navigation behave unexpectedly | Reuse platform and domain conventions; preserve keyboard and native-control expectations | Copying bad conventions or rejecting a clearly better pattern merely because it is new |108| **Postel's Law, bounded** | Benign human input arrives in varied formatting | Accept safe variation, normalize explicitly, preview the canonical result, and emit consistent data | Applying permissiveness to authentication, security boundaries, money, dates with ambiguous locale, or external protocols where strict validation is safer |109110**Target-size floor:** for web pointer inputs, WCAG 2.2 Level AA defines a 24×24 CSS-pixel minimum or sufficient spacing under its exceptions. Treat this as a floor, not an ergonomic goal. Prefer larger targets for primary actions, touch, motion impairment, destructive choices, and use under pressure.111112#### Time, momentum, and interruption113114| Law or effect | Use when | Design move | Misuse to avoid |115|---|---|---|---|116| **Doherty Threshold / response-time heuristics** | Delay breaks the sense of direct manipulation or flow | Acknowledge input immediately, preserve input, show useful partial state, and provide honest progress/cancellation for longer work | Fake progress bars, decorative delays, blocking the whole screen, or using one fixed threshold for every context |117| **Goal-Gradient Effect** | A finite multi-step task is abandoned because progress is unclear | Show truthful progress, completed and remaining work, and a stable finish line | Moving the finish line, hiding surprise steps, or manufacturing pressure |118| **Zeigarnik Effect** | Users leave work unfinished or are interrupted | Auto-save when safe, label drafts, preserve position, and make resumption obvious | Guilt, nagging, anxiety loops, or retaining sensitive drafts without consent |119| **Peak-End Rule** | Completion, recovery, or a high-friction moment shapes the remembered experience | Make the hardest moment supported and the ending clear: what happened, what remains, and what to do next | Confetti or delight used to compensate for a broken core flow |120121Use the classic response-time bands as design heuristics, not service-level guarantees: around **0.1 s** feels direct, around **1 s** preserves thought flow, and beyond roughly **10 s** users need meaningful progress, interruption, and return support. Measure the real product and users.122123#### Order, emphasis, and grouping124125| Law or effect | Use when | Design move | Misuse to avoid |126|---|---|---|---|127| **Serial Position Effect** | Important items disappear in a long ordered sequence | Put high-priority or frequently needed items in strong positions and create meaningful sections | Ordering everything for memorability when task sequence, chronology, or alphabetical retrieval matters more |128| **Von Restorff Effect** | One action or status must stand out among similar elements | Create one controlled contrast in shape, weight, position, label, or color plus non-color meaning | Multiple “special” elements, novelty without meaning, or inaccessible color-only emphasis |129| **Law of Proximity** | Relationships are unclear because spacing is uniform | Use tighter spacing within groups and larger spacing between groups | Inferring semantic meaning from proximity alone without labels or structure |130| **Law of Similarity** | Repeated functions look inconsistent or different functions look identical | Make same-function controls consistent and distinct meanings visibly distinct | Making destructive and safe actions look the same; relying on appearance without accessible names |131| **Law of Common Region** | A boundary would clarify a real section or object | Use a container, fieldset, panel, or background only where it communicates membership | Card soup, nested boxes, and borders around every element |132| **Aesthetic-Usability Effect** | Trust and perceived ease suffer from incoherent craft | Use a deliberate type, spacing, color, motion, and component system; remove visual defects | Assuming attractive means usable or letting polish conceal accessibility and behavior failures |133134### 5. Define the interface system135136Create a constrained system rather than styling each screen independently. Two defaults do most of the work: an **8px spatial grid** and **atomic composition**. If the codebase already has an equivalent system, extend it; never run a second system beside it. Set direction before spending the grid:137138#### 5a. Aesthetic direction139140- Commit before styling: name the subject, audience, and the page's single job; derive palette, type, and layout from the subject's own world (frontend-design).141- Kill the generic-AI looks: cream near #F4F1EA + serif + terracotta; near-black + lone acid-green/vermilion accent; broadsheet hairlines + zero radius. Use one only when the brief asks (frontend-design).142- No purple-on-white default; no dark-mode bias unless requested; no flat single-color backgrounds, layer gradient/imagery/pattern for atmosphere (better-frontend).143- Plan a token brief first: 4-6 named hex values, 2+ type roles (characterful display used with restraint, complementary body), one layout concept, one signature element. If any part matches what you would make for any similar prompt, revise it (frontend-design).144- Spend boldness in one place: one signature element, everything around it quiet; remove one accessory before shipping (frontend-design).145- Work in grayscale first. Color is the easiest way to fake hierarchy; removing it forces spacing, size, and contrast to carry the structure. Add the palette once the gray version already reads correctly (refactoring-ui).146147**Typography-led hierarchy**148149- Two typefaces max; never default to Inter/Roboto/Arial/system-ui unless the design system requires them. Type carries the page's personality (better-frontend, frontend-design).150- Build hierarchy from weight + size + leading as a set; emphasize with weight, it adds presence without space (apple-design).151- Tracking is size-specific: about -0.02em on display, near 0 on body, slightly positive on small text; leading inversely with size (apple-design).152153#### 5b. Spacing and sizing: the 8px grid154155Every padding, margin, gap, and fixed box dimension comes from one scale on an 8px base, with 4px as the half-step for tight pairs (icon-to-label, checkbox-to-text):156157```text1584 8 12 16 24 32 48 64 96159```160161Define the scale as tokens (`--space-1: 8px` … `--space-12: 96px`, or the framework equivalent) and spend values from tokens, not literals.162163Rules that survive real projects:164165- **The grid governs boxes, not glyphs.** Apply it to padding, margins, gaps, control heights, and icon sizes. Line-height obeys readability, not the grid: 25.6px or 28px line-height is correct where the grid would force 24px or 32px.166- **The spacing ladder must never invert.** Spacing encodes grouping (Law of Proximity): label-to-control 4–8, siblings inside a group 8–16, between groups 24–32, between page sections 48+. A card whose internal padding (16) exceeds the gap to its neighbor (8) reads as one merged blob.167- **Size controls on the grid.** Control heights 32/40/48; icons 16/20/24; pointer targets at least 24×24 (WCAG 2.2 floor), 44×44 for primary touch actions.168- **Start generous and subtract.** Adding space until a layout stops looking bad lands on the minimum tolerable amount. Starting from too much and trimming lands on the right amount (refactoring-ui).169- **Steps must be far enough apart to choose between.** Adjacent values differ by roughly 25% or more; that is what makes the pick unambiguous. A plain every-4px list gives no basis to decide between 120 and 124. Above 96, continue the ratio rather than the increment: 128, 192, 256, 384 (refactoring-ui).170- **Exceptions are declared, not leaked.** A living system tolerates a few off-scale values (a 12px chip padding, an 80px hero offset) when they are named tokens with a stated reason. Silent literals like 9px, 13px, 17px are defects.171- **Audit mechanically.** Run `scripts/grid-audit.sh`: it flags off-grid px per property (0/1/2 and line-height/letter-spacing exempt; font-size checked against the type set). In rendered review, off-grid values appear as almost-aligned edges: measure, do not eyeball.172173#### 5c. Composition: the atomic system174175Build in strict layers; each layer consumes only the layer below:176177```text178tokens → atoms → molecules → organisms → templates → screens179```180181- **Tokens** in two tiers: primitive (`--gray-700`, `--space-2`) and semantic (`--color-text`, `--btn-bg`). Components reference semantic tokens only, so theming and dark mode become token swaps, not rewrites.182- **Build the ramps up front, in HSL.** Two related HSL values look related; two related hex codes do not. Give each hue 8–10 steps (three runs out immediately), name them 100 lightest to 900 darkest, and fix 500 first as a color that works as a button fill, then the ends, then fill the gaps. Start the dark end at a very dark neutral rather than true black. Never derive shades at runtime, which yields dozens of near-identical blues (refactoring-ui).183- **Atoms:** button, input, label, icon, badge, checkbox. An atom never sets its own external margin; the parent owns spacing via gap.184- **Molecules:** form field (label + control + help + error), search bar, setting row, menu item.185- **Organisms:** form, card list, header, settings section.186- **Templates and screens** compose organisms; a new screen that demands a new atom needs a stated reason.187188Rules that survive real projects:189190- **Tokens are step zero.** Retrofitting tokens onto already-styled screens is the single largest time sink in system work; hardcoded colors and spacing metastasize. Cut tokens before styling the first screen.191- **Rule of three.** Second appearance of a pattern: note it. Third: extract the component. Two "setting rows" with different backgrounds, radii, and padding are one molecule with a bug, not two designs.192- **Variants, not clones.** Same function, one component, differentiated by modifier (`primary/secondary/ghost/destructive`, `sm/md/lg`), never by copy-pasted styles that drift apart.193- **One radius and one elevation per component level.** Pick a small set (4/8/12/full) and map each component class to one value. Mixed radii inside one card stack is the fastest tell of an unsystematic UI.194- **Type scale is semantic and hand-picked.** Roles (display, heading, subheading, body, caption) map to a fixed set: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72. Hand-picked beats ratio-derived: modular scales produce fractional pixels that round unevenly, and they run too sparse at interface density and too dense at display sizes (refactoring-ui). Size the scale in px or rem, never em, since nested em values compound off the scale. The type scale and the spacing scale are separate sets: 32 is a valid spacing step and not a type step (use 30 or 36), and 30 is a type step but not a spacing step. Line-height tightens as size grows; body lines stay within 40–80 characters. For typeface selection and pairing, use the `google-fonts` skill (https://www.skills.sh/sliday/google-fonts-skill/google-fonts) instead of picking fonts ad hoc.195196Fix the remaining system rules explicitly: semantic color tokens for surface, text, action, status, and focus, with contrast floors of 4.5:1 for body text and 3:1 for large text and essential UI graphics (large means 24px regular or 18.66px bold, not 18px; the separate 3:1 non-text floor covers borders that identify a control, not decorative dividers); icon vocabulary; border, elevation, and motion rules; content and error-message voice; keyboard, pointer, touch, focus, hover, selected, disabled, loading, and destructive states.197198One-off visual values require a reason. Consistency is not sameness: component variants should communicate different semantics while remaining part of one system.199200#### 5d. Craft details201202##### Surfaces203204- Concentric radius: outerRadius = innerRadius + padding. Above 24px padding, treat layers as separate surfaces (make-interfaces-feel-better).205- Shadows over borders for elevation. Light token: `0 0 0 1px rgba(0,0,0,.06), 0 1px 2px -1px rgba(0,0,0,.06), 0 2px 4px 0 rgba(0,0,0,.04)`; hover .08/.08/.06. Dark: single ring `0 0 0 1px rgba(255,255,255,.08)`, hover .13. Keep real borders for dividers and input outlines (make-interfaces-feel-better).206- One box-shadow depth per section (better-frontend).207- Image outlines: `1px` `rgba(0,0,0,0.1)` light / `rgba(255,255,255,0.1)` dark, `outline-offset: -1px`. Pure black/white only; tinted neutrals read as dirt (make-interfaces-feel-better).208- Translucent chrome: `backdrop-filter: blur(20px) saturate(180%)` + semi-transparent bg; never stack two light translucent surfaces; scroll-edge fade instead of a 1px border under sticky headers (apple-design).209- Dim scrim behind modal tasks; parallel non-blocking panels get no scrim (apple-design).210211##### Optical alignment212213- Optical beats geometric. Icon-side button padding = text-side minus 2px; play triangles shift about 2px right; fix asymmetric icons in the SVG itself (make-interfaces-feel-better).214- Align mixed type sizes on one line by baseline, not center; centering misaligns them in a way that reads as subtly broken (refactoring-ui).215- Add roughly +0.05em tracking to all-caps text: caps are uniform blocks that crowd at default spacing (refactoring-ui).216- Keep icons near their intended size. A 16–24px icon blown up to 48px reads chunky and detail-starved; nest it in a colored circle instead (refactoring-ui).217- Choose elevation by the element's z-position, not by which shadow looks best; shrinking a shadow on press reads as depressed (refactoring-ui).218- Constrain user-uploaded imagery: fixed containers, cover-fit, crop the overflow. When an upload's edges dissolve into the page, use a faint inset shadow rather than a border, which fights the image's own colors (refactoring-ui).219220##### Text rendering221222- `text-wrap: balance` on headings (works only up to 6 lines Chromium / 10 Firefox); `text-wrap: pretty` on short-to-medium body; neither on 10+ lines (make-interfaces-feel-better).223- `font-variant-numeric: tabular-nums` on any updating number (counters, timers, prices, table columns); not on phone numbers or version strings (make-interfaces-feel-better).224- `-webkit-font-smoothing: antialiased` + `-moz-osx-font-smoothing: grayscale` once at the root (make-interfaces-feel-better).225- Author the spacing scale in rem so it tracks user text size: 4px = 0.25rem, 8px = 0.5rem, 16px = 1rem. The px values in 5b name design-time grid steps, not literal units (apple-design).226227##### Interaction feel228229- Feedback on pointer-down, not release; continuous during the interaction (apple-design).230- Scale on press: `:active { scale: 0.96 }` with 150ms ease-out; never below 0.95; offer a `static` opt-out (make-interfaces-feel-better, emil-design-eng).231- Gate hover behind `@media (hover: hover) and (pointer: fine)` (emil-design-eng).232- Extend small controls to full hit size with a pseudo-element; never overlap two hit areas (make-interfaces-feel-better).233- Tooltips: delay the first, open adjacent ones instantly with no animation while one is open (emil-design-eng).234- Same action name through the flow: "Publish" button yields "Published" toast; errors say what happened and how to fix, no apology, never vague (frontend-design).235236##### Self-check237238- Review with fresh eyes next day; play animations at 2-5x duration and frame-by-frame to catch overlap, wrong transform-origin, desynced properties (emil-design-eng).239- Report polish diffs as a Before/After/Why table, one row per change (emil-design-eng).240241#### 5e. Motion242243##### Decide first244245- Frequency gate: 100+ uses/day (keyboard shortcuts, command palette) never animate; tens/day reduce drastically; occasional (modals, drawers, toasts) standard; rare moments may delight. Never animate keyboard-initiated actions; context menus animate exit only (emil-design-eng, 12-principles-of-animation).246- Every animation names a purpose: spatial consistency, state indication, feedback, explanation, or preventing a jarring change. "Looks cool" + frequent = cut (emil-design-eng).247248##### Durations249250- Press feedback 100-160ms; tooltips/small popovers 125-200ms; dropdowns/selects 150-250ms; modals/drawers 200-300ms, large drawers up to 500ms only as a declared exception (the craft audit flags >=400ms for review); general UI ceiling 300ms (emil-design-eng).251- Exits shorter and softer than enters (150ms vs 300ms); exit with small fixed translateY about -12px, not container height (make-interfaces-feel-better).252- Identical timing for similar elements; slow only where the user decides (hold-to-delete 2s linear), fast where the system responds (release 200ms ease-out) (12-principles-of-animation, emil-design-eng).253254##### Easing255256- Enter ease-out, exit ease-in, on-screen move ease-in-out, hover/color ease, linear only for constant motion. Never ease-in on entrances (emil-design-eng, 12-principles-of-animation).257- Built-ins are weak; tokens: `--ease-out: cubic-bezier(0.23,1,0.32,1)`, `--ease-in-out: cubic-bezier(0.77,0,0.175,1)`, drawer `cubic-bezier(0.32,0.72,0,1)` (emil-design-eng).258259##### What and how260261- Animate only transform, opacity, filter, clip-path; never `transition: all`, list exact properties (emil-design-eng, make-interfaces-feel-better).262- Never enter from `scale(0)`: use `scale(0.95)` + `opacity: 0`; enter recipe adds `translateY(8-12px)` + `blur(4px)` (emil-design-eng, make-interfaces-feel-better).263- Popovers scale from their trigger's transform-origin; modals stay centered. Enter and exit along the same path (emil-design-eng, apple-design).264- Stagger semantic chunks about 100ms apart, list items 30-80ms (50ms cap for dense lists); one focal point at a time; never block interaction (make-interfaces-feel-better, 12-principles-of-animation).265- CSS transitions for interactive state (interruptible, retargets); keyframes only for one-shot sequences; `@starting-style` for entry; `initial={false}` so default-state elements skip mount animation (emil-design-eng, make-interfaces-feel-better).266- Springs for gestures: bounce 0 default, 0.1-0.3 only after a flick; animate from the live on-screen value; hand off release velocity; rubber-band boundaries instead of hard stops (apple-design).267268##### Reduced motion269270- `prefers-reduced-motion: reduce` means gentler, not zero: keep opacity/color changes, replace slides/springs/parallax with about 200ms cross-fades, drop overshoot; `prefers-reduced-transparency` raises bg opacity and drops blur (emil-design-eng, apple-design).271272### 6. Compose hierarchy and layout273274Use size, contrast, position, spacing, alignment, and containment to reflect actual importance.275276When reviewing an interface you did not design, or when the only report is "it looks off", start from `references/visual-diagnostics.md`: a symptom-to-fix index covering hierarchy, spacing, borders, typography, imagery, polish, and accessibility.277278Weight and color do more of this work than size. Leaning on size alone pushes the primary element to cartoon proportions and squeezes the secondary one below readability; keep sizes nearer the middle of the scale and separate levels with weight (600/700) and text color instead. Cap text colors at three (primary, secondary, tertiary), and hold all three to 4.5:1, which puts the lightest around the middle of the ramp rather than the pale end. When one element still refuses to lead, de-emphasize its neighbors instead of amplifying it (refactoring-ui).279280Rank actions by importance, not by semantics: primary is one solid high-contrast action per surface, secondary is outline or low-contrast fill, tertiary reads as a link. A destructive action is not automatically a large red button; give Delete tertiary treatment where it sits, then make it the primary action inside its confirmation dialog (refactoring-ui).281282When a component looks generic, the cause is usually an inherited mental picture of what that component is. Break the box: dropdowns can carry columns, icons, and per-item descriptions; a table column can hold two related fields; a radio group can become selectable cards that show the actual differences (refactoring-ui).283284Marketing-surface composition rules:285286- Hero budget: brand, one headline, one supporting sentence, one CTA group, one dominant image. No stat strips, pill clusters, icon rows, promo chips (better-frontend).287- Brand test: remove the nav; if the first viewport could belong to another brand, branding is too weak (better-frontend).288- Full-bleed hero on landing pages; no inset/rounded media-card heroes, no floating badges on hero media (better-frontend).289- Cards only when they contain interaction. Card test: strip border/shadow/background; if nothing is lost, it is not a card (better-frontend).290- Structure encodes meaning: 01/02/03 markers only for real sequences; marketing narrative runs hero, supporting imagery, product detail, social proof, final CTA (frontend-design, better-frontend).291292Required checks:293294- the primary task is obvious within a few seconds;295- section boundaries survive a squint/blur test;296- labels sit with the controls or values they describe;297- primary, secondary, and destructive actions do not compete;298- content remains readable at narrow widths and zoom;299- long labels, translations, large numbers, missing images, and dense data do not collapse the layout;300- visual centering is inspected, not assumed from equal CSS offsets.301302Avoid centering long reading text, excessive line length, ornamental cards, ambiguous icons, and decorative whitespace that pushes the next action off-screen.303304### 7. Design controls, forms, and content305306- Use familiar native semantics before custom widgets.307- Keep visible labels on inputs; placeholders are examples, not labels.308- In read-only data display, labels are a last resort: most values identify themselves by format or context. Fold the label into the value ("12 left in stock") or make it clearly secondary. Spec sheets, where people scan for the label itself, are the exception. This never licenses removing input labels (refactoring-ui).309- Design the empty state as a real screen: one illustration or mark, one clear headline, one emphasized action. Hide tabs, filters, and search until content exists to act on (refactoring-ui).310- Ask only for information required now.311- Match controls to the decision: checkbox for independent choices, radio for a small exclusive set, select/combobox for larger known sets, search/filter for large spaces.312- Preserve entered data after errors.313- Validate at a useful moment without fighting normal typing.314- Explain errors in plain language: what happened, where, and how to recover.315- Make destructive consequences explicit and proportional; prefer undo when feasible.316- Use action-specific button labels and destination-specific links.317- Never rely on color, position, gesture, hover, or iconography as the only carrier of meaning.318319### 8. Accessibility and resilience gate320321At minimum verify:322323- semantic structure and accessible names;324- logical reading and focus order;325- keyboard operation and visible focus;326- contrast and non-color status meaning;327- target size and target spacing;328- zoom, reflow, and text resizing;329- screen-reader exposure of hidden/intermediate content;330- error identification and recovery;331- reduced motion and animation control;332- touch, pointer, keyboard, and assistive-input paths;333- loading, partial, offline, empty, and permission states.334335Do not claim accessibility conformance from a visual review alone. Use automated checks as a floor and manually exercise keyboard, screen-reader, zoom, and state behavior relevant to the interface.336337### 9. Verify the rendered product338339Source code, a design file, or a component test is not enough. When implementation access exists:3403411. open the real interface;3422. exercise the primary flow and at least one recovery flow;3433. capture representative wide and narrow viewports;3444. inspect actual pixels, content, alignment, focus, and state changes;3455. test realistic and extreme content;3466. verify console/network behavior when relevant;3477. compare before/after evidence;3488. distinguish verified behavior from assumptions and remaining risks.349350Use `agent-visual-verification` when a deterministic screenshot evidence path is needed. Use full browser automation when the flow requires navigation, typing, state mutation, network inspection, or assertions.351352## Automated guards353354The skill ships mechanical checks; run them instead of eyeballing:355356- **`scripts/grid-audit.sh <file-or-dir>`** flags every px value off the 8px grid, per CSS property: margins/padding/gap/radius must be 0/1/2 or divisible by 4; `font-size` must be in the 12/14/16/18/20/24/30/36/48/60/72 set; `line-height` and `letter-spacing` are exempt (readability beats grid). Exit 1 on violations, with `file:line: property value` output.357- **`hooks/design-guard.sh`** is a PostToolUse hook: after any Edit/Write to a `.css/.scss/.less/.html/.jsx/.tsx/.vue/.svelte` file, it audits that file and feeds violations back to the agent as a fix prompt. Silent on clean files, non-style files, and malformed input; never blocks the edit itself; no retries.358- Install: merge `hooks/hooks.json` into `.claude/settings.json` (project) or `~/.claude/settings.json` (global); adjust the script path to where this skill is installed.359360The guard catches literals, not judgment: it cannot see an inverted proximity ladder, a cloned component, or a missing state. Those still require the review workflow above.361362## Review severity363364Classify findings by user impact:365366- **Blocker:** prevents completion, causes data loss, exposes unsafe action, or creates a critical accessibility barrier.367- **Major:** likely confusion, abandonment, repeated error, inaccessible path, or material loss of trust.368- **Minor:** local inconsistency or friction with a clear workaround.369- **Polish:** aesthetic improvement without meaningful task impact.370371Lead with blockers and majors. Do not bury a broken flow under spacing comments.372373## Output format3743751. **User, job, and interface promise**3762. **Product truth and constraints**3773. **IA hierarchy**: primary, secondary, tertiary, metadata3784. **Flow and state model**3795. **Relevant UX laws**: problem → law → design move → trade-off3806. **System rules**: spacing grid, tokens, atomic component inventory, type, color, motion, copy3817. **Screen/component decisions**3828. **Accessibility and resilience requirements**3839. **Rendered verification evidence**38410. **Findings by severity and remaining risks**385386For implementation tasks, make the changes and cite concrete files/components. Do not stop at critique when the user asked for a fix.387388## Compact release checklist389390- [ ] Primary user, job, success, and failure are explicit.391- [ ] Product state and action availability are truthful.392- [ ] IA follows user meaning and decision sequence.393- [ ] One clear primary action exists per decision surface.394- [ ] Needed context is visible; rare complexity is progressively disclosed.395- [ ] Relevant UX laws were selected by problem, with misuse checks.396- [ ] Every padding, margin, and gap sits on the spacing scale; exceptions are named tokens with reasons.397- [ ] Repeated patterns are extracted components with variants; no near-duplicate clones.398- [ ] Components consume semantic tokens; no hardcoded color or spacing literals.399- [ ] Loading, empty, partial, success, error, interruption, and recovery states are covered.400- [ ] Controls have honest hierarchy, labels, target size, focus, and states.401- [ ] Forms preserve work and explain recovery.402- [ ] Color is not the only signal; contrast and focus are visible.403- [ ] Narrow viewport, zoom, long content, and translation stress were tested.404- [ ] Keyboard and relevant assistive-technology paths were exercised.405- [ ] The actual rendered interface was inspected.406- [ ] Verified facts and unverified assumptions are separated.407408## Anti-patterns409410- Starting with components, visual references, or a design trend before understanding the task.411- Citing UX laws as proof without observing the actual user problem.412- Applying arbitrary numeric limits such as “never show more than seven items.”413- Hiding complexity that users need to understand consequences.414- Using progressive disclosure to conceal price, risk, permissions, or destructive effects.415- Adding cards, borders, icons, motion, gradients, or color without informational purpose.416- Off-scale spacing literals (9px, 13px, 17px) instead of scale tokens.417- Cloned near-identical components that drift in radius, padding, or background instead of one component with variants.418- Forcing line-height and letter-spacing onto the 8px grid at the cost of readability.419- Multiple competing primary actions.420- Placeholder-only labels, icon-only meaning, or color-only status.421- Custom controls that lose native keyboard and accessibility behavior.422- Fake progress, manipulative urgency, guilt-driven incompletion, or surprise steps.423- Treating responsive design as shrinking the desktop layout.424- Declaring success from source inspection without exercising the rendered interface.425- Reporting dozens of polish notes while a core flow is broken.426427## Do Not Use When428429- The task has no user interface or user-facing workflow.430- The real blocker is an unresolved product, policy, legal, or business decision that design cannot safely invent.431- The user needs empirical research with a specific population; run research rather than presenting heuristics as evidence.432- A specialized domain standard (medical, aviation, automotive, financial trading, public safety) supersedes generic UX guidance.433434## Sources and provenance435436This is an original synthesis. Version 1.2 additionally merges concrete craft rules mined from installed design skills (better-frontend, make-interfaces-feel-better, emil-design-eng, apple-design, frontend-design, 12-principles-of-animation, ui-ux-pro-max, landing-page-design, web-design-guidelines, google-fonts); the full deduped catalog with per-rule attribution lives in `references/borrowed-craft.md`. Version 1.3 adds a visual symptom-to-fix index in `references/visual-diagnostics.md` and inline hierarchy, palette, and type-scale rules distilled from Refactoring UI (Adam Wathan, Steve Schoger) by way of the refactoring-ui-skill notes, rewritten and reconciled with this skill's existing systems. A user-provided set of 18 UX-law notes was treated as source material, then rewritten, de-frameworked, corrected, and consolidated rather than republished as separate micro-skills.437438Useful public references:439440- Laws of UX, a practitioner index of UX laws: https://lawsofux.com/441- Nielsen Norman Group, 10 usability heuristics: https://www.nngroup.com/articles/ten-usability-heuristics/442- Nielsen Norman Group, response-time limits: https://www.nngroup.com/articles/response-times-3-important-limits/443- W3C, WCAG 2.2 target size minimum: https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html444- W3C, WCAG 2.2 focus appearance: https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html445446The laws are heuristics. Validate consequential decisions with users, domain evidence, accessibility testing, and the real rendered product.
Run npx skillmds@latest add sliday/ux-ui-ia in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when designing or reviewing interfaces, setting up a spacing scale or design tokens, or restructuring UI into a component system. It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
sliday (@sliday) published this skill. Their other Agent Skills are listed on their SkillMD profile.
sliday