UI UX Design

UI/UX Design Master Guide

Overview

This guide gives you the principles, decision frameworks, and battle-tested patterns to design interfaces people can actually use. It is opinionated — when there is a clear better answer, it says so. When the answer is "it depends," it names what it depends on.

The guide is organized into a quick-start checklist, ten core principles, decision frameworks, and four reference deep-dives. Read SKILL.md first; load the reference and example files only when this guide tells you to.

Quick Start: Six Questions Before You Touch a Pixel

Before designing anything, answer these. If you cannot, your design will drift.

1. Who is the user? A specific user, not "users." Their context, expertise, time pressure.
2. What are they trying to accomplish? The job-to-be-done, not the feature name.
3. What is the single most important action on this screen? That is the visual focus.
4. What is the riskiest moment? Where the user could lose data, money, or trust. That moment gets extra care.
5. What is the smallest viable interface? Strip everything. Add back only what earns its place.
6. What does failure look like? Empty states, errors, slow networks, screen readers. Designed, not punted.

The Ten Core Principles

1. Hierarchy is a contract

Every element on the screen claims a level of importance. If three things scream, nothing screams. Use one dominant element per zone. Techniques: size, weight, color, and space — in that order. See reference/foundations.md for the full toolkit.

2. Reduce, then refine

Default to less. Fewer type sizes, fewer colors, fewer spacing values, fewer components. Constraint produces consistency. Adding is easy; the discipline is subtraction.

3. Whitespace is structure, not decoration

Padding, margin, and gaps communicate grouping faster than borders or backgrounds. Tight = related; loose = separate. Whitespace is what your eye reads first, even though you do not notice it.

4. Type does the heavy lifting

Most "design" problems are typography problems. Get the type scale, line-height, and contrast right and 60% of the work is done. See reference/foundations.md for the type scale, pairing, and hierarchy rules.

5. Color carries meaning

Pick a palette of 1 brand color, 2–3 neutrals, and 3–4 semantic colors (success, warning, error, info). Anything more is decoration. WCAG contrast is non-negotiable; see reference/accessibility.md.

6. Every state must be designed

Default, hover, focus, active, disabled, loading, empty, error, success. Skipping any of these is a bug, not a polish item. See reference/interaction.md.

7. Motion is feedback

Use motion to confirm an action, indicate continuity, or direct attention. Never use it for delight alone. Default: 150–300ms with an ease-out curve. See reference/interaction.md.

8. Words are UI

Microcopy is a primary design element, not an afterthought. Every label, button, error, and empty state is an opportunity to be clear, short, and human. See reference/interaction.md.

9. Accessibility is the floor, not the ceiling

WCAG 2.2 AA is the minimum. Keyboard, screen reader, color blindness, low vision, motor impairment — all real users. See reference/accessibility.md.

10. Patterns over invention

Use established patterns unless you have a strong reason not to. Inventing a new dropdown costs your user comprehension; the win is rarely worth it. See reference/patterns.md.

Decision Frameworks

When choosing between options

• Default to the most boring option that works. Boring = familiar = fast to learn.
• Cost of being wrong matters. Reversible changes can be bold. Irreversible ones (delete, send, pay) need friction.
• Fewer steps is not always better. A 3-step flow with clear progress beats a 1-step flow with 12 fields.

When the screen feels "off"

Check in this order — fix the first thing that fails:

1. Hierarchy — does the eye know where to land first?
2. Spacing — is grouping clear? Are gaps consistent?
3. Type — too many sizes? Weights doing the wrong job?
4. Color — is anything competing for attention with the primary action?
5. Alignment — is everything on the grid? Are optical adjustments right?
6. Density — too cramped or too sparse for the content type?

When you cannot decide between two designs

• Show both to a real user with a real task.
• If you cannot test, pick the one that is easier to change later.
• Never resolve disagreements with "I prefer X." Resolve them with "X serves the user goal better because Y."

When stakeholders ask for "more emphasis"

The instinct is to make the thing bigger or redder. The fix is usually to make everything else quieter. Hierarchy is comparative.

How to Use This Skill

The references are self-contained deep-dives. Read the one that matches the current task:

The examples show concrete good-vs-bad pairs:

Related skills

This skill teaches universal UI/UX principles. It does not carry brand-specific visual decisions — palettes, signature shadows, custom cursors, named primitives. When the work is for a project with a defined visual system, also load that system's skill alongside this one.

The two skills compose: ui-ux-design answers "is this design good?", the brand skill answers "does this design read as our brand?". Apply both.

Voice and Tone of UI Reviews

When using this skill to critique a design, be:

• Specific. "The CTA loses against the secondary button" beats "hierarchy is off."
• Prioritized. Lead with what costs the user the most. Polish notes go last.
• Constructive. Every problem gets a suggested fix or a question that surfaces the trade-off.
• Honest. If it is wrong, say so. Designers learn from clear feedback, not hedged feedback.

Anti-Patterns to Recognize

These appear constantly. When you see one, the correct alternative is in the reference noted.

• Decorative animations on every interaction → reference/interaction.md
• More than ~6 type sizes in a single product → reference/foundations.md
• Disabled buttons with no explanation of why → reference/interaction.md
• Empty states that show nothing instead of teaching what to do → examples/error-states.md
• Forms that validate on first keystroke and shame the user mid-typing → examples/forms.md
• Modals stacked on modals → reference/patterns.md
• "Are you sure?" on reversible actions; no confirmation on irreversible ones → reference/patterns.md
• Tooltips carrying essential information (not keyboard- or touch-accessible by default) → reference/accessibility.md
• Color as the only signal (red/green with no icon or text) → reference/accessibility.md
• Placeholder text used as the only label → examples/forms.md
• "Click here" or "Submit" as the only button label → examples/buttons.md

When This Skill Does Not Apply

• Pure brand or marketing visual design (poster, illustration, identity system) — different discipline. This skill is for product UI.
• Hardware or industrial design.
• Information architecture at the org level — covered partially in reference/patterns.md but not the focus.

For those, recognize the boundary and say so explicitly rather than misapplying these principles.