UI/UX Agent Skill — UI/UX Guide (Modern Minimal)

A skill for AI coding assistants that turns abstract design feedback into code you can ship.

Two modes:

• guide — compact principles and concrete do/don't rules for building modern, clean interfaces.

• review — structured audit of existing UI (screenshot / mock / HTML / PR) with prioritized, implementable fixes.

Keep outputs concise. Bullets over paragraphs. Specific over generic.

Workflow

1. Guide workflow

• Identify the surface: marketing page / dashboard / settings / creation flow / list-detail / form / mobile screen.

• Identify the primary user task and primary CTA.

• Apply system-level guiding principles first — these are the mental model and interaction logic layer (references/system-principles.md ).

• Apply core principles below — start from UX, then refine with CRAP visual hierarchy.

• Apply domain-specific guidance as needed:

• Icons: references/icons.md

• Accessibility: references/accessibility.md

• Responsive: references/responsive-design.md

• Typography: references/typography.md

• Color: references/color-systems.md

• Navigation: references/navigation.md

• Data visualization: references/data-visualization.md

2. Review workflow

• State assumptions (platform, target user, primary task).

• List findings as P0 / P1 / P2 (blocker / important / polish) with short evidence.

• For each major issue, label the diagnosis: execution vs evaluation gulf; slip vs mistake (see references/design-psych.md ).

• Propose fixes that are implementable (layout, hierarchy, components, copy, states).

• Check accessibility compliance against references/accessibility.md .

• End with a short checklist to verify changes.

Use references/review-template.md for a stable output format.

Non-Negotiables (hard rules)

These are binary. No exceptions.

• No emoji as icons — no emoji as UI decoration, status indicators, section markers, or button labels. Replace with a proper icon from a consistent set.

• One icon family — use a single consistent icon set across the product. No mixing outlined/filled/3D/emoji styles.

• Minimize copy by default — add explanatory text only when it prevents errors, reduces ambiguity, or builds trust. Text is the last resort, not the default.

• Accessible by default — WCAG 2.1 AA is the floor, not an aspiration. Color contrast, keyboard navigation, screen reader support, and focus management are non-negotiable.

• No decoration without purpose — every visual effect (gradient, shadow, blur, glow, animation) must answer: "what does this help the user understand?" No answer = remove it.

System-Level Guiding Principles

Apply these as first-order constraints before choosing components or page patterns. Full definitions and review questions: references/system-principles.md .

Key principles: concept constancy / primary task focus / UI copy source discipline / state perceptibility / help text layering (L0-L3) / feedback loop closure / prevention + recoverability / progressive complexity / action perceptibility / cognitive load budget / evolution with semantic continuity.

Core Principles

A) Task-First UX

The thing about any interface is that it exists to serve a task. Not to look good. Not to impress stakeholders. To help someone do something.

• Make the primary task obvious in <3 seconds.

• Allow exactly one primary CTA per screen/section.

• Optimize the happy path; hide advanced controls behind progressive disclosure.

• Remove anything that doesn't serve the user's current goal.

Review question: If someone lands here cold, can they figure out what to do in 3 seconds?

B) Information Architecture (grouping + findability)

• Group by user mental model (goal / object / time / status), not by backend data structure.

• Use clear section titles; keep navigation patterns stable across similar screens.

• When item count grows: add search/filter/sort early, not late.

• Card sort your IA against real user language, not your internal nomenclature.

Review question: Does the grouping match how users think about this, or how the database stores it?

C) Feedback and System Status

• Cover all states: loading, empty, error, success, permission. Full checklist in references/checklists.md .

• After any action, answer three questions: "Did it work?" + "What changed?" + "What can I do next?"

• Prefer inline, contextual feedback over global toasts (except for cross-page actions).

• Loading states must prevent layout jumps — use skeletons, not spinners that collapse content.

Review question: At any moment, can the user tell what the system is doing and what they should do next?

D) Consistency and Predictability

• Same interaction = same component + same wording + same placement.

• Use a small, stable set of component variants; avoid one-off styles.

• Consistency across screens matters more than pixel-perfection on any single screen.

Review question: If someone learns this pattern on page A, will it transfer to page B without relearning?

E) Affordance + Signifiers (make actions obvious)

• Clickable things must look clickable: button/link styling + hover/focus + cursor change. On web, custom clickable elements need cursor: pointer and visible focus styles.

• Primary actions need a label; icon-only is reserved for universally-known actions (search, close, settings).

• Show constraints before submit (format, units, required), not only after errors.

• For deeper theory: references/design-psych.md .

Review question: Without any help text or tooltips, can users predict what is actionable and what will happen?

F) Error Prevention and Recovery

• Prevent errors with constraints, defaults, and inline validation.

• Make destructive actions reversible when possible; otherwise require deliberate confirmation.

• Error messages must be actionable: what happened + how to fix it. Never just "Something went wrong."

• Frame destructive confirmations around what will be lost, not the action itself.

Review question: Is the path designed to be easy to do right and safe to recover when wrong?

G) Cognitive Load Control

• Reduce choices: sensible defaults, presets, and progressive disclosure.

• Break long tasks into steps only when it genuinely reduces thinking (not just to look "enterprise").

• Keep visual noise low: fewer borders, fewer colors, fewer competing highlights.

• Don't force users to remember information across screens — carry context forward.

Review question: As information grows, does comprehension cost stay stable?

H) CRAP (visual hierarchy + layout)

• Contrast — emphasize the few things that matter (CTA, current state, key numbers). If everything is bold, nothing is.

• Repetition — tokens, components, and spacing follow a scale. Avoid "almost the same" styles — they create cognitive noise.

• Alignment — align to a clear grid. Fix 2px drift. Align baselines where text matters.

• Proximity — tight within a group, loose between groups. Spacing is the primary grouping tool, not borders.

Review question: Close your eyes, open them — is the first thing you see the most important thing on the page?

I) Accessibility

Accessibility is not a feature. It's a quality standard. Like structural integrity in a building — you don't "add" it later.

• WCAG 2.1 AA is the minimum. Test against it.

• Color must never be the only way to convey information.

• All interactive elements must be keyboard accessible with visible focus indicators.

• Screen reader users must get equivalent information and functionality.

• Full guidance: references/accessibility.md .

Review question: Can a user who can't see color, can't use a mouse, or can't see at all still complete the primary task?

J) Responsive Design

• Design for the smallest screen first, then enhance for larger ones.

• Content hierarchy should be preserved across breakpoints, not just reflowed.

• Touch targets: minimum 44x44 CSS px (web) / 48x48 dp (mobile).

• Full guidance: references/responsive-design.md .

Review question: Does the interface work on a phone held in one hand, a tablet in landscape, and a wide desktop monitor?

K) Typography

Typography is the backbone of visual hierarchy. Get it right and everything else falls into place.

• Use a type scale — not arbitrary font sizes.

• Limit to 2 typefaces maximum (one for headings, one for body — or one for everything).

• Line length: 45-75 characters for body text. Wider than that and reading comprehension drops.

• Full guidance: references/typography.md .

Review question: Can you identify the hierarchy (title > subtitle > body > caption) just from the typography?

L) Color Systems

• Keep the palette small and intentional. One accent color for primary actions and key states.

• Use semantic color tokens, not raw hex values — this makes theming and dark mode possible.

• Test all color combinations for WCAG AA contrast (4.5:1 for text, 3:1 for large text and UI components).

• Full guidance: references/color-systems.md .

Review question: If you printed this screen in grayscale, would the hierarchy still be clear?

Spacing and Layout Discipline

Use this when implementing or reviewing layouts. Short set of rules, strictly enforced.

Rule 1 — One spacing scale:

• Base unit: 4px.

• Allowed set: 4 / 8 / 12 / 16 / 24 / 32 / 40 / 48 / 64 / 80.

• Off-scale values need a clear, documented reason.

Rule 2 — Repetition first:

• Same component type keeps the same internal spacing (cards, list rows, form groups, section blocks).

• Components with the same visual role must not have different spacing patterns.

Rule 3 — Alignment + grouping:

• Align to one grid and fix 1-2px drift.

• Tight spacing within a group, looser spacing between groups.

• Spacing is the primary grouping tool. If you need a border to show grouping, your spacing is wrong.

Rule 4 — No decorative nesting:

• Extra wrappers must add real function (grouping, state, scroll, affordance).

• If a wrapper only adds border/background, remove it and group with spacing instead.

Quick review pass:

• Any off-scale spacing values?

• Any baseline/edge misalignment?

• Any wrapper layer removable without losing meaning?

Modern Minimal Style Guidance

This is about taste, not trends. Modern minimal is not "flat and boring." It's using restraint as a design tool.

• Use whitespace + typography to create hierarchy. Avoid decoration-first design.

• Prefer subtle surfaces (light elevation, low-contrast borders). Avoid heavy shadows.

• Keep color palette small; use one accent color for primary actions and key states.

• Copy: short, direct labels. Add helper text only when it reduces mistakes or increases trust.

• Let content breathe. Dense information is not the same as useful information.

Motion and Animation Guidance

• Motion explains hierarchy (what is a layer/panel) and state change (what just happened). Not decoration.

• Default motion vocabulary: fade > small translate+fade > tiny scale+fade for overlays. Avoid bouncy, elastic, or "showy" motion.

• Keep the canvas/content area stable. Panels and overlays can move; the work surface must not float.

• Same component type uses the same motion pattern. Consistency over creativity.

• Avoid layout jumps. Use placeholders/skeletons to keep layout stable while loading.

• Interaction feedback (hover/pressed) must feel immediate. Never make users wait for an animation to complete before they can proceed.

Red flags:

• Continuous decorative motion (breathing backgrounds, floating cards)

• Large bouncy/elastic overshoot that steals attention

• Big page-level transitions for routine navigation

• Multiple simultaneous animations competing for attention

Anti-AI Self-Check (run after generating any UI)

Before finalizing generated UI, verify these items. Violating any one is a mandatory fix.

• Gradient restraint — gradients must convey meaning (progress, depth, state distinction). Purely decorative gradients: at most one per page. If background, buttons, and borders all use gradients simultaneously, that is overuse. Pick one and flatten the rest.

• No emoji as UI — re-check: no emoji slipped in as section icons, status indicators, or button labels. This is already a non-negotiable. Double-check.

• Copy necessity — for every piece of text, ask: if I remove this, can the user still understand through layout, icons, and position alone? If yes, remove it.

• Decoration justification — every purely visual effect (blur, glow, animated entrance, layered shadows) must answer: "what does this help the user understand?" No answer = remove.

• Contrast check — run a quick contrast check on all text/background combinations. WCAG AA minimum.

• Touch target check — all interactive elements meet minimum 44x44 CSS px.

• Keyboard test — tab through the entire interface. Can you reach and activate every interactive element? Is focus visible?

References

• System-level guiding principles: references/system-principles.md

• Interaction psychology (Fitts/Hick/Miller, cognitive biases, flow, attention): references/interaction-psychology.md

• Design psychology (affordances, signifiers, mapping, constraints, gulfs, slips vs mistakes): references/design-psych.md

• Accessibility (WCAG, keyboard, screen readers, color, forms, media): references/accessibility.md

• Responsive design (breakpoints, mobile-first, touch, fluid layouts): references/responsive-design.md

• Typography (type scale, pairing, line height, measure, hierarchy): references/typography.md

• Color systems (palettes, semantic tokens, contrast, dark mode): references/color-systems.md

• Navigation patterns (nav structures, wayfinding, mobile nav): references/navigation.md

• Data visualization (chart selection, data-ink ratio, dashboard design): references/data-visualization.md

• Icon rules and "intuitive refined" guidance: references/icons.md

• Review output template and scoring: references/review-template.md

• Expanded checklists (states, affordance, lists, forms, settings, motion, dashboards, copy): references/checklists.md