Skip to main content

UX/UI & Visual Design Guidelines (Research-Backed)

Apply these patterns when building or modifying any user-facing interface. They are defaults grounded in usability research, not laws — deviate when the product context clearly calls for it, but say why in a comment or the PR description.

Two organizing principles run through everything below:

  1. Function first. Beauty earns trust and tolerance but never substitutes for a usable workflow. A "pretty but pointless" interface fails.
  2. Beauty is functional. Users judge visual appeal in ~50ms, and that judgment shapes perceived usability, credibility, and how much friction they will forgive. Polish is a feature, not decoration — especially for software that must build trust.

PART 1 — CORE USABILITY (the functional backbone)​

Navigation & Information Architecture​

  • Keep primary navigation persistent and visible; highlight the active item.
  • Group related actions/content; avoid more than ~7 top-level nav items.
  • Provide breadcrumbs for hierarchies deeper than two levels.
  • Add search when content exceeds what a user can reasonably scan.
  • Avoid deep menu hierarchies and poor searchability — both measurably extend task time and raise cognitive load in complex/data-heavy apps.

Match Between System & the Real World​

  • Speak the user's language. Use words, concepts, and ordering familiar to the domain, not internal/system jargon or developer terms.
  • Follow real-world and domain conventions; don't break established metaphors (an icon or term that means one thing in the field should not mean something else in the UI).
  • Present information in a natural, logical order that mirrors how users think about the task — mismatches force users to re-translate the system's meaning every time.

System Status & Feedback​

  • Respond to every user action within ~100ms (even just a state change).
  • Use loading indicators or skeleton screens for anything over ~300ms.
  • For operations over ~10 seconds, show a step checklist with elapsed time, NOT a generic spinner or "please wait" — users need enough info to decide whether to wait or switch tasks.
  • Confirm success explicitly; never leave users guessing whether an action worked.
  • Implement all interactive states: default, hover, focus, active, disabled, loading, error, empty.
  • Prefer optimistic UI updates with rollback on failure.

Forms & Input (Baymard-backed)​

  • Use SINGLE-COLUMN layouts. Multi-column forms are consistently harder to complete.
  • Use visible labels above/beside fields — never placeholder text alone.
  • Mark BOTH required and optional fields explicitly. Don't rely on the asterisk convention.
  • Cut fields aggressively — combine duplicates, auto-detect where possible. Fewer fields measurably reduces abandonment.
  • Ask for one phone number, not separate landline/mobile fields, unless both are truly needed.
  • Validate inline (on blur or as the user types), not only on submit.
  • Show errors next to the field, in plain language, with how to fix it.
  • Preserve user input on error or navigation — never make them retype.
  • Use correct input types (email, tel, number, date) to trigger the right keyboard.
  • Disable submit while a request is in flight.

Affordances & Clickability​

  • Make interactive elements look interactive; static elements look static.
  • Establish clear visual distinction between primary, secondary, and destructive actions.
  • Touch targets >= 44x44px with adequate spacing.
  • Use cursor changes (pointer, not-allowed) to reinforce behavior.

Error Prevention & Recovery​

  • Require confirmation for destructive/irreversible actions; describe the consequence.
  • Prefer Undo and auto-saved version history over confirmation dialogs for high-investment work (documents, records, multi-step composition).
  • Show live previews while users configure or compose, so they see each change's effect.
  • Design helpful empty states: explain what goes here and offer the first action.
  • Error messages must name what went wrong and link to resolution/docs. Never write dead-ends like "Could not display data. Contact your administrator."

Recognition over Recall​

  • Make options, actions, and elements visible rather than memorized.
  • Show meaning on hover for domain codes/taxonomy (e.g., a code, role, or ID should reveal what it is). Don't make even trained users hold the taxonomy in their head.

Flexibility & Efficiency​

  • Provide keyboard shortcuts and accelerators for expert users, while keeping clearly labeled primary paths for novices.
  • Let users tailor frequent actions where it pays off.

Progressive Disclosure​

  • Show the common path first; reveal advanced/rare options on demand (e.g., after a related checkbox is checked).
  • Use sensible defaults so most users never touch advanced settings.

Help & Documentation​

  • Prefer in-context help (tooltips with a short description + shortcut, even a clip) over forced upfront tutorials. Users skip tours but use contextual help.

PART 2 — VISUAL DESIGN (what makes it attractive)​

Visual Hierarchy​

  • Communicate priority through size, contrast, placement, spacing, and typography working together.
  • Make ONE action obviously primary; keep secondary actions available but quieter.
  • Lay out for scan patterns: F-pattern for data/text-heavy screens, Z-pattern for simpler landing layouts. Put the most important element top or top-left.
  • Aim for disciplined prioritization, not minimalism for its own sake. "Clean" means the important thing is impossible to miss — not that the page is empty.

Typography​

  • Set the base (primary typeface, size, style) FIRST as a reference point.
  • Create hierarchy with contrast first, then spacing. Font weight is the most striking contrast lever.
  • Use a consistent type scale; limit sizes and weights ("as much variation as necessary, as little as possible").
  • Group related text via proximity; separate unrelated groups with space.
  • Keep body line length readable (~50–75 characters).

Color — the 60-30-10 rule​

  • 60% dominant/neutral (backgrounds, large surfaces, whitespace).
  • 30% secondary (containers, nav, structure).
  • 10% accent (CTAs, links, key interactive elements only).
  • Start in grayscale; confirm text/background contrast before adding color.
  • Use the accent SPARINGLY so the eye is drawn straight to key actions.
  • Reserve semantic colors (red/yellow/green) strictly for status — never for branding. This is critical in clinical/data contexts where those colors already carry meaning.
  • Never convey information by color alone — pair with icon, shape, or text (~8% of men and ~0.5% of women are colorblind).

Whitespace​

  • Use generous space to let the design breathe and create clear focal points.
  • Whitespace is what makes identical content read as premium vs. cramped.
  • Use spacing to group (proximity) and separate, reinforcing hierarchy.

Data Visualization & Tables​

  • Maximize the data-ink ratio: if a pixel isn't conveying information, remove it. Cut chartjunk — heavy gridlines, borders, drop shadows, 3D effects, decorative gradients.
  • Choose the chart that fits the data (line for trends, bar for comparisons); don't decorate. Label directly where possible instead of relying on dense legends.
  • Reserve semantic colors in charts for meaning (see Color); don't color bars by brand.
  • On small screens, don't shrink wide tables — convert each row into a stacked card (the "card stack" pattern) so content stays readable.

Micro-interactions & Motion​

  • Every micro-interaction = trigger -> rules -> feedback -> loop/mode. Design all four.
  • Use motion to: confirm actions, show cause and effect, indicate state changes, guide attention, and improve perceived speed (skeletons, smooth transitions).
  • Be restrained. Overused motion causes cognitive overload, distraction, and motion sickness. Animate only what aids comprehension or adds meaningful delight.
  • Match motion to brand: restrained fades and crisp transitions for enterprise/clinical tools; playful easing only for playful brands.
  • ALWAYS support prefers-reduced-motion.
  • Document motion tokens (durations, easing curves, density) in the design system so interactions feel cohesive.

Speed as an aesthetic​

  • Perceived performance is part of perceived quality. Small load-time improvements produce measurable gains in conversion and task completion.
  • Render layout/skeletons before data arrives; avoid layout shift after load (reserve space for images and async content).

PART 3 — CONSISTENCY, ACCESSIBILITY & TRUST​

Consistency​

  • Reuse shared components, a single spacing scale, and design tokens; don't reinvent UI per page.
  • Keep icon meanings, terminology, and interaction patterns consistent. One symbol = one meaning (e.g., "+" always means "add new," never also "expand").
  • Keep primary actions in consistent locations across screens.
  • Match platform conventions (web, iOS, Android) rather than inventing custom behavior.

Accessibility (required, not optional)​

  • Use semantic HTML; reach for ARIA only when semantics fall short.
  • Full keyboard navigation, logical tab order, visible focus indicators.
  • WCAG AA contrast: 4.5:1 normal text, 3:1 large text and UI components.
  • Alt text for meaningful images; mark decorative images as such.
  • Don't rely on color alone (see Color above).

Trust & credibility​

  • Nearly half of credibility judgment is visual — invest in a coherent, professional first impression (calm hero/landing, clear primary message, no above-the-fold clutter).
  • Show data provenance where relevant: where a value came from, when it was updated, whether it's verified. Rare in most software; directly builds trust.
  • Suppress duplicate and repetitive data entry: pre-fill known values, reuse data already captured, and flag (don't silently re-ask for) information the system has.
  • Apply consistent completeness rules so required data is captured without overwhelming users — signal what's missing rather than blocking the whole workflow.
  • Surface patterns, not raw data: highlight overdue items, deadlines, and rule violations rather than making users scan to find them.
  • Caution: because polish masks friction, validate usability by watching what users DO, not only what they say. Don't let a beautiful UI hide a broken workflow.