From 3ab66666e032d92ae61ea06758c75b4e6370c6a5 Mon Sep 17 00:00:00 2001 From: Thomas Wunner Date: Mon, 20 Apr 2026 11:31:01 +0200 Subject: [PATCH] feat(ux-design): add gestalt-ui, laws-of-ux, and ui-patterns skills Three new skills for evidence-based UI/UX design: - gestalt-ui: 13 Gestalt principles applied to interface design (proximity, similarity, figure-ground, closure, continuity, etc.) - laws-of-ux: ~30 behavioural UX laws from lawsofux.com (Fitts, Hick, Miller, Jakob, Doherty, Von Restorff, Peak-End, etc.) - ui-patterns: scanning patterns, component patterns, and decision reference for navigation, forms, buttons, cards, modals, tables, loading states, and notifications Each skill includes SKILL.md + 3 reference files. Skills complement existing ux-heuristics (Nielsen), refactoring-ui (visual systems), web-typography, and design-everyday-things without duplicating content. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 9 +- CLAUDE.md | 6 +- README.md | 73 ++++ gestalt-ui/SKILL.md | 310 ++++++++++++++++ .../references/figure-ground-closure.md | 124 +++++++ gestalt-ui/references/proximity-similarity.md | 116 ++++++ gestalt-ui/references/region-connectedness.md | 139 ++++++++ laws-of-ux/SKILL.md | 333 ++++++++++++++++++ laws-of-ux/references/decision-laws.md | 114 ++++++ laws-of-ux/references/memory-laws.md | 156 ++++++++ laws-of-ux/references/motor-laws.md | 125 +++++++ ui-patterns/SKILL.md | 319 +++++++++++++++++ ui-patterns/references/navigation-forms.md | 190 ++++++++++ ui-patterns/references/scanning-patterns.md | 139 ++++++++ .../references/tables-search-loading.md | 258 ++++++++++++++ 15 files changed, 2405 insertions(+), 6 deletions(-) create mode 100644 gestalt-ui/SKILL.md create mode 100644 gestalt-ui/references/figure-ground-closure.md create mode 100644 gestalt-ui/references/proximity-similarity.md create mode 100644 gestalt-ui/references/region-connectedness.md create mode 100644 laws-of-ux/SKILL.md create mode 100644 laws-of-ux/references/decision-laws.md create mode 100644 laws-of-ux/references/memory-laws.md create mode 100644 laws-of-ux/references/motor-laws.md create mode 100644 ui-patterns/SKILL.md create mode 100644 ui-patterns/references/navigation-forms.md create mode 100644 ui-patterns/references/scanning-patterns.md create mode 100644 ui-patterns/references/tables-search-loading.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f1bf194..d9c0f18 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,13 +1,13 @@ { "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "wondelai-skills", - "description": "42 agent skills for product strategy, UX design, marketing, sales, motivation, conversion optimization, code quality, and systems architecture — based on bestselling books", + "description": "45 agent skills for product strategy, UX design, marketing, sales, motivation, conversion optimization, code quality, and systems architecture — based on bestselling books and research", "owner": { "name": "Wondel.ai", "email": "hello@wondel.ai" }, "metadata": { - "description": "42 agent skills for product strategy, UX design, marketing, sales, motivation, conversion optimization, code quality, and systems architecture — based on bestselling books", + "description": "45 agent skills for product strategy, UX design, marketing, sales, motivation, conversion optimization, code quality, and systems architecture — based on bestselling books and research", "version": "1.3.0" }, "plugins": [ @@ -57,7 +57,10 @@ "./top-design", "./design-everyday-things", "./lean-ux", - "./microinteractions" + "./microinteractions", + "./gestalt-ui", + "./laws-of-ux", + "./ui-patterns" ] }, { diff --git a/CLAUDE.md b/CLAUDE.md index ff36d35..559b116 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository Purpose -This is a collection of 42 agent skills for Claude Code and agentskills.io-compatible agents. Skills provide specialized domain knowledge and frameworks for specific use cases (UX design, marketing, product strategy, sales, operations, positioning, virality, code quality, systems architecture, etc.). +This is a collection of 45 agent skills for Claude Code and agentskills.io-compatible agents. Skills provide specialized domain knowledge and frameworks for specific use cases (UX design, marketing, product strategy, sales, operations, positioning, virality, code quality, systems architecture, etc.). ## Repository Structure @@ -21,11 +21,11 @@ skills/ └── README.md # Skill catalog with descriptions and installation instructions ``` -## Current Skills (42) +## Current Skills (45) | Category | Skills | |----------|--------| -| **UX/Design** | refactoring-ui, ios-hig-design, ux-heuristics, hooked-ux, improve-retention, web-typography, top-design, design-everyday-things, lean-ux, microinteractions | +| **UX/Design** | refactoring-ui, ios-hig-design, ux-heuristics, hooked-ux, improve-retention, web-typography, top-design, design-everyday-things, lean-ux, microinteractions, gestalt-ui, laws-of-ux, ui-patterns | | **Marketing/CRO** | cro-methodology, storybrand-messaging, scorecard-marketing, contagious, one-page-marketing | | **Sales/Influence** | influence-psychology, predictable-revenue, made-to-stick, hundred-million-offers | | **Product/Innovation** | jobs-to-be-done, lean-startup, design-sprint, inspired-product, continuous-discovery, 37signals-way | diff --git a/README.md b/README.md index 48a9194..a36f253 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,9 @@ npx skills add wondelai/skills/clean-architecture npx skills add wondelai/skills/release-it npx skills add wondelai/skills/high-perf-browser npx skills add wondelai/skills/37signals-way +npx skills add wondelai/skills/gestalt-ui +npx skills add wondelai/skills/laws-of-ux +npx skills add wondelai/skills/ui-patterns ``` ## Available Skills @@ -121,6 +124,9 @@ npx skills add wondelai/skills/37signals-way | [release-it](https://skills.wondel.ai/skills/release-it/) | Production-ready systems: circuit breakers, bulkheads, timeouts, retry logic | [Michael Nygard](https://x.com/mtnygard)'s [*"Release It!"*](https://www.amazon.com/Release-Design-Deploy-Production-Ready-Software/dp/1680502395?tag=wondelai00-20) | | [high-perf-browser](https://skills.wondel.ai/skills/high-perf-browser/) | Web performance: network protocols, resource loading, browser rendering | [Ilya Grigorik](https://x.com/igrigorik)'s [*"High Performance Browser Networking"*](https://www.amazon.com/High-Performance-Browser-Networking-performance/dp/1449344763?tag=wondelai00-20) | | [37signals-way](https://skills.wondel.ai/skills/37signals-way/) | Build less, shape work, ship in six-week cycles with small autonomous teams | [Jason Fried](https://x.com/jasonfried) & [DHH](https://x.com/dhh)'s [*"Getting Real"*](https://www.amazon.com/Getting-Real-Smarter-Successful-Application/dp/0578012812?tag=wondelai00-20), [*"Rework"*](https://www.amazon.com/Rework-Jason-Fried/dp/0307463745?tag=wondelai00-20) & [Ryan Singer](https://x.com/rjs)'s [*"Shape Up"*](https://www.amazon.com/Shape-Up-Circles-Ship-Work/dp/B09ZSY1MWP?tag=wondelai00-20) | +| [gestalt-ui](https://skills.wondel.ai/skills/gestalt-ui/) | Apply Gestalt principles of visual perception to UI design | Gestalt psychology research (Wertheimer, Koffka, Köhler) applied to digital interfaces | +| [laws-of-ux](https://skills.wondel.ai/skills/laws-of-ux/) | Apply evidence-based UX laws to interaction design decisions | [Jon Yablonski](https://x.com/jonyablonski)'s [*"Laws of UX"*](https://www.amazon.com/Laws-UX-Using-Psychology-Products/dp/149205531X?tag=wondelai00-20) | +| [ui-patterns](https://skills.wondel.ai/skills/ui-patterns/) | Apply proven UI component patterns and scanning behaviour to build effective interfaces | Nielsen Norman Group research, Smashing Magazine best practices | > **Looking for real-world scenarios?** See [EXAMPLES.md](EXAMPLES.md) for 49 copy-pasteable prompts organized by persona (founders, PMs, marketers, designers, sales, copywriters, solopreneurs). @@ -1059,6 +1065,70 @@ Build lean, opinionated products using the 37signals philosophy: build less, sha --- +### [gestalt-ui](https://skills.wondel.ai/skills/gestalt-ui/) + +Apply Gestalt principles of visual perception to UI design. Understand how users automatically group, separate, and interpret visual elements -- and use these principles intentionally to make interfaces self-explanatory. + +**Based on:** Gestalt psychology research (Max Wertheimer, Kurt Koffka, Wolfgang Köhler) applied to digital interface design, synthesised from [Smashing Magazine](https://www.smashingmagazine.com/2014/03/design-principles-visual-perception-and-the-principles-of-gestalt/) and [Interaction Design Foundation](https://www.interaction-design.org/literature/topics/gestalt-principles). + +**Use when you need to:** +- Group and organize UI elements effectively using spacing, borders, and visual connections +- Create intuitive visual relationships between components +- Audit layouts for perceptual clarity and unintended grouping +- Design navigation, cards, forms, or dashboards that users understand instantly +- Resolve conflicting visual signals between proximity, similarity, and containers + +**Example prompts:** +- *"Audit this dashboard layout for Gestalt violations. Use gestalt-ui skill."* +- *"These form fields feel disconnected. Fix the visual grouping. Use gestalt-ui skill."* +- *"How should I use proximity and common region to group these settings? Use gestalt-ui skill."* +- *"Score this card layout on Gestalt principle adherence. Use gestalt-ui skill."* + +--- + +### [laws-of-ux](https://skills.wondel.ai/skills/laws-of-ux/) + +Apply evidence-based UX laws to interaction design decisions. These behavioural psychology principles describe how humans perceive, decide, and act -- use them to design interfaces that work with human cognition, not against it. + +**About the author:** [Jon Yablonski](https://x.com/jonyablonski) is a designer and author of [*"Laws of UX"*](https://www.amazon.com/Laws-UX-Using-Psychology-Products/dp/149205531X?tag=wondelai00-20), synthesising decades of research from Fitts, Hick, Miller, Nielsen, and others into actionable design principles at [lawsofux.com](https://lawsofux.com/). + +**Use when you need to:** +- Size and position interactive targets effectively (Fitts's Law) +- Reduce cognitive load and decision complexity (Hick's Law, Miller's Law) +- Design progress indicators and memory-friendly interfaces (Goal-Gradient, Serial Position) +- Resolve design trade-offs with psychological evidence +- Optimise response times and perceived performance (Doherty Threshold) +- Follow platform conventions or decide when to break them (Jakob's Law) + +**Example prompts:** +- *"Our mobile buttons feel too small and hard to tap. Audit using Fitts's Law. Use laws-of-ux skill."* +- *"Users abandon our settings page. Too many choices? Diagnose with Hick's Law. Use laws-of-ux skill."* +- *"Design a progress indicator for our 6-step onboarding. Use laws-of-ux skill."* +- *"Score this checkout flow against UX laws. Use laws-of-ux skill."* + +--- + +### [ui-patterns](https://skills.wondel.ai/skills/ui-patterns/) + +Apply proven UI component patterns and scanning behaviour to build effective interfaces. Concrete guidance for navigation, forms, buttons, cards, modals, tables, loading states, and notifications -- plus a decision reference for choosing between competing patterns. + +**Based on:** Nielsen Norman Group eye-tracking research, [Smashing Magazine](https://www.smashingmagazine.com/) best practices (navigation, forms, buttons), and industry-standard component design patterns. + +**Use when you need to:** +- Design navigation that answers "Where am I? Where can I go? Where have I been?" +- Build forms with optimal label placement, validation, and friction reduction +- Choose between competing UI patterns (dropdown vs radio, modal vs inline, carousel vs static) +- Apply F-pattern and Z-pattern scanning knowledge to content placement +- Design appropriate loading states and notification patterns + +**Example prompts:** +- *"Should I use a hamburger menu or visible nav for this site? Use ui-patterns skill."* +- *"Improve this form's completion rate. Use ui-patterns skill."* +- *"Where should I place the CTA on this landing page for maximum visibility? Use ui-patterns skill."* +- *"Design loading states for our dashboard. Use ui-patterns skill."* + +--- + ## Learn More: The Skills Ecosystem Want to go deeper with skills — how they work, how to create your own, and what's available across the community? @@ -1123,6 +1193,9 @@ The methodologies and frameworks referenced in these skills are the intellectual - **Getting Real**: Jason Fried, David Heinemeier Hansson - **Rework**: Jason Fried, David Heinemeier Hansson - **Shape Up**: Ryan Singer +- **Laws of UX**: Jon Yablonski +- **Gestalt psychology**: Max Wertheimer, Kurt Koffka, Wolfgang Köhler (public domain research) +- **UI Patterns**: Nielsen Norman Group (Jakob Nielsen, Don Norman), Smashing Magazine These skills were created without directly copying or reproducing content from the original books or materials. They are based on: - Publicly available information about the methodologies diff --git a/gestalt-ui/SKILL.md b/gestalt-ui/SKILL.md new file mode 100644 index 0000000..13564cf --- /dev/null +++ b/gestalt-ui/SKILL.md @@ -0,0 +1,310 @@ +--- +name: gestalt-ui +description: 'Apply Gestalt principles of visual perception to UI design. Use when you need to: (1) group and organize UI elements effectively, (2) create intuitive visual relationships between components, (3) audit layouts for perceptual clarity, (4) design navigation, cards, forms, or dashboards that users understand instantly. Based on Gestalt psychology research applied to digital interfaces.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Gestalt Principles for UI Design + +A framework for applying Gestalt psychology to interface design. Gestalt principles describe how humans automatically group, separate, and interpret visual elements -- use them intentionally to make interfaces self-explanatory. + +## Core Principle + +**Users don't see individual elements -- they see patterns and relationships.** Every spacing decision, border, colour choice, and alignment communicates grouping, hierarchy, and meaning whether you intend it to or not. Gestalt principles are always active. The question is whether you're using them deliberately or accidentally. + +## Scoring + +**Goal: 10/10.** When reviewing or designing interfaces, rate 0-10 based on deliberate application of Gestalt principles. + +- **9-10:** Every grouping is intentional. Proximity, similarity, and common region work together. Visual relationships match semantic relationships perfectly. +- **7-8:** Most groupings are clear. Minor spacing inconsistencies or ambiguous element relationships in secondary areas. +- **5-6:** Groupings partially work but some elements feel disconnected or wrongly associated. Spacing is inconsistent. +- **3-4:** Significant grouping problems. Users must read labels to understand relationships because visual structure doesn't communicate them. +- **1-2:** No discernible visual grouping. Elements scattered without spatial logic. Users are lost. + +## The Gestalt Framework + +### 1. Proximity -- The Primary Grouping Mechanism + +**Core concept:** Elements positioned close together are perceived as related. Spacing is the most fundamental tool for communicating structure. + +**Why it works:** The brain groups nearby elements automatically, before conscious thought. This is faster than reading labels or borders. + +**Key insights:** +- Related elements need less space between them than unrelated elements +- A label must be closer to its input field than to the previous field +- Section gaps should be noticeably larger than intra-section spacing +- Equal spacing everywhere makes everything look equally related -- destroying hierarchy + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Forms | Tighter spacing within field groups, larger gaps between groups | Shipping address fields grouped tightly, separated from billing by 2x gap | +| Navigation | Clustered items in header menus | Primary nav items grouped, utility links (login, search) spatially separated | +| Dashboards | Related metrics grouped by proximity | Revenue metrics clustered together, user metrics in a separate spatial zone | +| Cards | Content within cards tightly spaced | Title-description-meta as a tight unit, action buttons slightly separated | + +**Common mistake:** Equal margins on all elements. If your form has identical gaps between every field, you've removed all visual grouping. + +See: [references/proximity-similarity.md](references/proximity-similarity.md) + +### 2. Similarity -- Visual Consistency Signals Function + +**Core concept:** Elements sharing visual characteristics (colour, shape, size, weight, texture) are perceived as related and functionally equivalent. + +**Why it works:** Once the brain identifies one element's meaning, it transfers that meaning to all visually similar elements. A blue underlined word learned as "clickable" makes all blue underlined words clickable. + +**Key insights:** +- All interactive elements of the same type must look identical (links, buttons, inputs) +- Breaking similarity creates emphasis -- the Von Restorff Effect (see `laws-of-ux` skill) +- Icon families must use uniform stroke weight, dimensions, and style +- Typography hierarchy: same size and weight = same level of importance + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Navigation | Consistent link styling signals clickability | All nav links same colour, weight, and hover behaviour | +| Buttons | Same-level buttons share visual style | All secondary actions use outlined style, all primary use filled | +| Data tables | Consistent cell styling signals data type | All currency values right-aligned, same font, same colour | +| Status indicators | Consistent badge/tag styling | All "active" badges green, same size and shape | + +**Critical rule:** Breaking similarity must be intentional. A red item in a list of blue items demands attention -- use this for CTAs, errors, or critical actions, never accidentally. + +See: [references/proximity-similarity.md](references/proximity-similarity.md) + +### 3. Common Region -- Boundaries Create Groups + +**Core concept:** Elements enclosed within the same boundary are perceived as grouped and related, even if they're otherwise dissimilar. + +**Why it works:** Borders, backgrounds, and cards create explicit containers. Common region can override proximity -- items far apart but within the same card appear more related than close items in different cards. + +**Key insights:** +- Cards, panels, and bordered sections are common region in action +- Background colour changes signal section boundaries +- Common region is stronger than proximity -- use it to override spatial grouping when needed +- Too many containers create visual noise; use sparingly and with purpose + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Forms | Fieldsets with visible borders group related inputs | Address fields in a bordered fieldset, payment in another | +| Dashboards | Cards containing related metrics | "Revenue" card with total, growth, and chart -- visually one unit | +| Settings | Panels separating configuration areas | Account settings panel, notification preferences panel, privacy panel | +| Pricing | Plan cards enclosing features, price, and CTA | Each plan visually distinct as a complete unit | + +See: [references/region-connectedness.md](references/region-connectedness.md) + +### 4. Figure-Ground -- Focus vs Context + +**Core concept:** Elements separate into figure (focal element) and ground (background/context). The brain must decide what's foreground and what's behind -- make this decision obvious. + +**Why it works:** Stable figure-ground relationships direct attention. Unstable ones create confusion about what to focus on. + +**Key insights:** +- High-contrast elements become figure; low-contrast becomes ground +- Smaller overlapping objects tend to be figure; larger ones ground +- Shadows and elevation create clear figure-ground separation +- Modal overlays use dimmed backgrounds to force figure-ground clarity + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| CTAs | High-contrast button against neutral background | Bright "Sign Up" button on a muted hero section | +| Modals | Dimmed/blurred backdrop establishes overlay as figure | Dark scrim behind a confirmation dialog | +| Cards | Subtle shadows lift content off the page | Card with `box-shadow` on flat background | +| Navigation | Sidebar visually distinct from main content | Darker sidebar, lighter content area | + +**Ethical boundary:** Never use ambiguous figure-ground to hide important information (dark patterns). Pricing, terms, and opt-outs must be clear figure elements. + +See: [references/figure-ground-closure.md](references/figure-ground-closure.md) + +### 5. Closure -- The Brain Completes Patterns + +**Core concept:** We fill in missing visual information to perceive complete shapes. Partial information is enough when the pattern is recognisable. + +**Why it works:** The brain wants coherence. Showing "enough" lets users infer the rest without overwhelming them with visual detail. + +**Key insights:** +- Partially visible carousel items signal "more content available" +- Progress bars use closure -- an incomplete fill implies a complete target +- Truncated text with "..." signals expandable content +- Dotted or dashed lines suggest boundaries without solid visual weight + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Carousels | Partially visible cards at edges | Next card peeking 20% into view signals scrollability | +| Progress | Incomplete fills show remaining work | "3 of 5 steps completed" with partial bar | +| Lists | Truncated items signal more content | "Showing 5 of 23 results" with fade-out | +| Icons | Simplified shapes the brain completes | An incomplete circle still reads as "loading" | + +See: [references/figure-ground-closure.md](references/figure-ground-closure.md) + +### 6. Continuity -- Follow the Line + +**Core concept:** Elements arranged on a line or curve appear related and sequential. The eye follows the path naturally. + +**Why it works:** We continue perceiving shapes and paths beyond their visible endpoints. This creates flow and sequence. + +**Key insights:** +- Aligned elements along invisible grid lines create order and cohesion +- Progress steppers guide users through sequences +- Breadcrumbs follow a linear path showing hierarchy +- Diagonal or curved layouts guide eye movement through content + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Wizards | Step indicators connected by a line | Steps 1-2-3-4 connected, showing progression | +| Timelines | Chronological events along a vertical line | Activity feed with connecting timeline | +| Breadcrumbs | Linear path showing navigation hierarchy | Home > Category > Product | +| Grid alignment | Elements aligned to invisible columns | Dashboard widgets snapped to a 12-column grid | + +### 7. Uniform Connectedness -- The Strongest Grouping + +**Core concept:** Visually connected elements are perceived as most strongly related. This is the most powerful Gestalt grouping principle. + +**Why it works:** Explicit visual connections (lines, arrows, shared containers) create unambiguous relationships that override all other grouping cues. + +**Key insights:** +- Connecting lines don't need direct contact with elements -- visual alignment is sufficient +- Stronger than proximity, similarity, and common region +- Use for explicit relationships that must be unambiguous +- Process flows, org charts, and data relationships benefit most + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Process flows | Lines connecting sequential steps | Checkout: Cart → Shipping → Payment → Confirm | +| Org charts | Lines showing reporting relationships | Tree structure with connecting branches | +| Data viz | Lines connecting related data points | Line charts, node graphs, dependency trees | +| Forms | Visual connectors between conditional fields | "If yes" → reveal connected sub-fields | + +See: [references/region-connectedness.md](references/region-connectedness.md) + +### 8. Common Fate -- Movement Creates Grouping + +**Core concept:** Elements moving together or in the same direction are perceived as related, regardless of visual similarity or distance. + +**Why it works:** Shared motion is a powerful grouping signal -- the brain assumes co-moving elements are part of the same system. + +**Key insights:** +- Animated hover states affecting multiple elements simultaneously group them +- Parallax layers moving at the same speed appear related +- Swiping a card group as a unit signals they belong together +- Scroll-linked animations on multiple elements create perceived unity + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Hover effects | Related elements react together on hover | Hovering a card highlights its image, title, and CTA simultaneously | +| Loading | Grouped skeleton placeholders shimmer together | Three related cards pulsing in sync | +| Scroll effects | Co-moving elements during scroll | Header and subheader sliding up together | +| Drag and drop | Selected items moving as a group | Multi-select files dragging together | + +### 9. Focal Points -- What Stands Out Gets Attention + +**Core concept:** Elements with contrast, emphasis, or visual distinction capture attention. The eye is drawn to what differs from its surroundings. + +**Why it works:** Focal points require a baseline of similarity -- without uniform surrounding elements, nothing can stand out. Contrast is relative. + +**Key insights:** +- A highlighted CTA only works if surrounding elements are visually quieter +- Larger text draws attention to key information +- Colour contrast makes specific elements stand out +- Unique shapes among uniform elements attract the eye +- If everything is emphasised, nothing is emphasised + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| CTAs | Contrasting colour on primary action | Blue "Submit" button among grey secondary buttons | +| Pricing | Recommended plan visually distinct | "Popular" plan larger, different colour, highlighted border | +| Alerts | Prominent styling for important messages | Red banner for errors among neutral content | +| Data | Key metric highlighted | Dashboard KPI in large, bold font; supporting data in standard size | + +### 10. Pragnanz (Simplicity) -- Simple Wins + +**Core concept:** People perceive complex arrangements in the simplest possible form. We prefer clear, ordered, symmetrical structures because they require less cognitive effort. + +**Why it works:** Simpler interpretations are processed faster and feel safer. This is the meta-principle underlying all other Gestalt principles. + +**Key insights:** +- Clean, uncluttered interfaces are processed faster +- Break complex information into simple, scannable components +- Favour straightforward iconography over detailed illustrations +- When in doubt, simplify -- if users must think about the structure, it's too complex + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Navigation | Hierarchical organisation over flat lists | Categorised menu instead of 40 links | +| Icons | Simple, recognisable shapes | Magnifying glass for search, not a detailed binoculars illustration | +| Layouts | Clean grids over chaotic arrangements | Uniform card grid instead of scattered elements | +| Onboarding | Step-by-step over all-at-once | Wizard with 4 clear steps instead of one overwhelming form | + +## Principle Interactions + +Gestalt principles don't work in isolation. They interact, reinforce, and sometimes conflict. + +### Reinforcement (Stronger Together) + +| Combination | Effect | +|-------------|--------| +| Proximity + Similarity | Elements that are close AND look alike are very strongly grouped | +| Common Region + Proximity | Cards with tight internal spacing -- double grouping signal | +| Continuity + Uniform Connectedness | Steps connected by a line AND aligned -- maximum sequence clarity | +| Figure-Ground + Focal Points | High-contrast CTA on dimmed background -- maximum attention | + +### Conflicts (Resolution Required) + +| Conflict | Resolution | +|----------|------------| +| Proximity suggests group A, but Similarity suggests group B | Common Region overrides both -- use a container | +| Uniform Connectedness creates unwanted association | Increase spacing (Proximity) AND change styling (Similarity) to counteract | +| Closure implies content exists but it doesn't | Remove the visual cue -- don't show a partial card if there's nothing to scroll to | + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Equal spacing everywhere | Removes all visual grouping -- everything looks equally related | Use a spacing scale: tighter within groups, looser between | +| Too many containers/borders | Visual noise, every element screams "I'm a group" | Use proximity and whitespace first; add borders only when needed | +| Inconsistent interactive styling | Users can't predict what's clickable | Audit all links, buttons, and interactive elements for visual consistency | +| Ambiguous figure-ground | Users don't know where to focus | Increase contrast on focal elements; dim/blur backgrounds | +| Accidental similarity | Unrelated elements look alike, implying false relationships | Vary colour, size, or shape to differentiate distinct element types | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you tell which elements are grouped without reading labels? | Spacing doesn't communicate structure | Adjust proximity: tighter within groups, larger gaps between | +| Do all interactive elements of the same type look the same? | Inconsistent similarity | Audit and unify link, button, and input styling | +| Is there one clear focal point per screen/section? | Everything competes for attention | Reduce visual weight on secondary elements; increase on primary | +| Do cards/containers have clear internal hierarchy? | Flat visual weight inside containers | Apply figure-ground and size contrast within cards | +| Can users predict what happens when they interact with an element? | Weak signifiers | Strengthen similarity with other interactive elements of the same type | + +## Reference Files + +- [references/proximity-similarity.md](references/proximity-similarity.md) -- Deep dive on Proximity and Similarity with spacing scale guidelines and examples +- [references/figure-ground-closure.md](references/figure-ground-closure.md) -- Figure-Ground relationships, Closure patterns, and elevation hierarchy +- [references/region-connectedness.md](references/region-connectedness.md) -- Common Region, Uniform Connectedness, and container design patterns + +## Further Reading + +- [Smashing Magazine: Design Principles — Visual Perception and the Principles of Gestalt](https://www.smashingmagazine.com/2014/03/design-principles-visual-perception-and-the-principles-of-gestalt/) +- [Laws of UX](https://lawsofux.com/) +- [Interaction Design Foundation: Gestalt Principles](https://www.interaction-design.org/literature/topics/gestalt-principles) diff --git a/gestalt-ui/references/figure-ground-closure.md b/gestalt-ui/references/figure-ground-closure.md new file mode 100644 index 0000000..fb0beb8 --- /dev/null +++ b/gestalt-ui/references/figure-ground-closure.md @@ -0,0 +1,124 @@ +# Figure-Ground & Closure -- Deep Dive + +How users distinguish foreground from background, and how the brain completes incomplete visual information. + +## Figure-Ground in Practice + +### Establishing Clear Figure-Ground + +The figure is what the user should focus on. The ground is everything else. Ambiguous figure-ground forces the brain to oscillate, causing confusion and cognitive load. + +**Techniques for stable figure-ground:** + +| Technique | How it works | Example | +|-----------|-------------|---------| +| **Contrast** | Higher contrast = figure | Dark text on light background; bright CTA on muted section | +| **Size** | Smaller overlapping element = figure | A modal (small) over a page (large) | +| **Elevation / Shadow** | Elevated elements = figure | Cards with shadow on flat background | +| **Blur / Dim** | Blurred elements = ground | Dimmed backdrop behind a modal dialog | +| **Saturation** | More saturated = figure | Colourful CTA on desaturated hero image | +| **Convexity** | Convex shapes = figure | Rounded buttons and badges on flat surfaces | + +### Elevation Hierarchy + +Use shadow depth to create consistent figure-ground layers: + +``` +Level 0 -- Flat surface (page background, ground) +Level 1 -- Subtle lift (cards, input fields) + box-shadow: 0 1px 3px rgba(0,0,0,0.12) +Level 2 -- Moderate elevation (dropdowns, popovers) + box-shadow: 0 4px 6px rgba(0,0,0,0.1) +Level 3 -- High elevation (modals, dialogs) + box-shadow: 0 10px 25px rgba(0,0,0,0.15) +Level 4 -- Maximum elevation (notifications, tooltips) + box-shadow: 0 15px 35px rgba(0,0,0,0.2) +``` + +**Rules:** +- Higher elevation = closer to the user = more attention +- Never place a lower-elevation element on top of a higher one +- Consistent shadow direction (typically top-left light source) +- Dark mode: use lighter surfaces instead of shadows for elevation + +### Figure-Ground for Modals + +Modals are the most explicit figure-ground pattern in UI: + +1. **Scrim:** Dark semi-transparent overlay (ground) behind the modal (figure) +2. **Blur:** Optional -- blurring the background further separates layers +3. **Focus trap:** Keyboard focus locked within the modal reinforces it as figure +4. **Dismiss:** Clicking the scrim closes the modal -- returning to the background as figure + +**Common mistakes:** +- Scrim too transparent -- ground competes with figure +- No scrim at all -- modal floats ambiguously over active content +- Multiple modals stacked -- figure-ground becomes figure-figure-ground (confusing) + +### Figure-Ground for Navigation + +Sidebar navigation uses figure-ground: +- Sidebar (darker background) = ground/context +- Main content (lighter, more spacious) = figure/focus +- Active nav item: inverted figure-ground within the sidebar (highlighted item = figure within the sidebar ground) + +--- + +## Closure in Practice + +### How Closure Works in UI + +The brain completes patterns when given enough visual information. This means you can communicate "more content exists" without showing it explicitly. + +### Carousel / Horizontal Scroll Patterns + +**The peek pattern:** Show 10-20% of the next item at the edge of the viewport. + +``` +[ Card 1 ][ Card 2 ][ Card 3 ][ Ca... + ^ + Partial card = "scroll for more" +``` + +**Rules:** +- Show enough of the next item to be recognisable (not just a sliver) +- Don't show a partial item if there's nothing to scroll to (false closure) +- Combine with scroll indicators (dots, arrows) for reinforcement +- Fade-out gradients can substitute for partial items + +### Progress and Completion + +Closure drives progress indicators: + +- **Progress bars:** Incomplete fill implies a complete target. The brain sees "how much is left" automatically. +- **Step indicators:** Completed steps (filled circles) vs incomplete (empty circles). The brain wants to fill them all. +- **Checklists:** Unchecked items create tension (Zeigarnik Effect + Closure) that motivates completion. +- **Circular progress:** Incomplete ring strongly implies the complete circle. + +### Truncation Patterns + +Text and content truncation relies on Closure: + +| Pattern | Signal | User inference | +|---------|--------|----------------| +| `"This is a long title that..."` | Ellipsis | "There's more text -- I can expand" | +| `"Showing 5 of 23 results"` | Count | "I can load more" | +| Gradient fade at bottom of a container | Visual fade | "Content continues below" | +| `"Read more"` link | Explicit | "There's more content -- click to see" | + +**Rules:** +- Always provide a way to see the full content (expand, navigate, tooltip) +- Never truncate critical information (prices, error messages, CTAs) +- Ellipsis should appear at word boundaries, not mid-word +- "Show more" is better than silent truncation for important content + +### False Closure (Anti-pattern) + +False closure occurs when visual cues suggest more content exists, but it doesn't: + +- A partial card at the carousel edge, but scrolling reveals nothing +- A "Load more" button that loads zero results +- A progress bar that jumps from 90% to stuck at 99% +- An empty space at the bottom of a list that looks like it should scroll + +**Fix:** Only use closure cues when they're truthful. If there's no more content, don't show partial elements. diff --git a/gestalt-ui/references/proximity-similarity.md b/gestalt-ui/references/proximity-similarity.md new file mode 100644 index 0000000..c822735 --- /dev/null +++ b/gestalt-ui/references/proximity-similarity.md @@ -0,0 +1,116 @@ +# Proximity & Similarity -- Deep Dive + +The two most frequently applied Gestalt principles in UI design. Master these and you solve 80% of layout problems. + +## Proximity in Practice + +### The Spacing Scale + +A consistent spacing scale is the implementation of Proximity. Use a base unit (4px or 8px) and build a scale: + +``` +4px -- tight: related inline elements (icon + label) +8px -- compact: items within a list, input padding +12px -- snug: related form fields within a group +16px -- default: between standard list items +24px -- comfortable: between form groups, content blocks +32px -- spacious: between major content sections +48px -- generous: between page-level sections +64px -- dramatic: hero sections, major visual breaks +``` + +**The rule:** Space within a group < space between groups. Always. If intra-group and inter-group spacing are equal, the grouping is invisible. + +### Proximity Rules for Forms + +Forms are where Proximity matters most: + +1. **Label-to-field distance:** 4-8px. The label must be unmistakably attached to its field. +2. **Field-to-field distance (within group):** 12-16px. Close enough to be one unit. +3. **Group-to-group distance:** 24-32px. Noticeably larger than field-to-field. +4. **Section-to-section distance:** 32-48px. Clear separation. + +**Test:** If you removed all borders and backgrounds, could a user still tell which fields belong together? If yes, your proximity is correct. + +### Proximity Rules for Navigation + +- Primary nav items: 8-16px between items in the same group +- Group separators: 24-32px or a visible divider +- Utility links (login, cart, search): spatially separated from primary nav +- Mobile: vertical stacking maintains proximity within tap-friendly spacing + +### Proximity Rules for Cards + +- Internal padding: 16-24px +- Between elements inside a card: 8-12px (title → description → meta) +- Between cards in a grid: 16-24px +- Between card groups/sections: 32-48px + +### Common Proximity Mistakes + +| Mistake | Result | Fix | +|---------|--------|-----| +| Labels far from their fields | Users associate label with wrong field | Reduce label-to-field gap to 4-8px | +| Equal spacing everywhere | No visual grouping | Use the spacing scale: vary gaps deliberately | +| Huge padding inside small cards | Content floats, feels disconnected | Match padding to content density | +| No gap increase between sections | Page feels like one flat list | Double the gap between logical sections | + +--- + +## Similarity in Practice + +### The Similarity Audit + +Review your interface for these consistency requirements: + +**Links:** All text links must share identical styling. +- Same colour (e.g., blue, brand accent) +- Same text decoration (underline, none on hover, etc.) +- Same hover/focus behaviour +- If some links look different from others, users can't predict clickability + +**Buttons:** Buttons of the same importance level must look identical. +- Primary buttons: same fill colour, border radius, padding, font weight +- Secondary buttons: same outline style, same colour but lower visual weight +- Destructive buttons: consistently different (typically red or with warning icon) +- Never mix 3+ button styles at the same hierarchy level + +**Icons:** Icon families must be visually uniform. +- Same stroke weight (1px, 1.5px, 2px -- pick one) +- Same dimensions (24x24, 20x20 -- pick one per context) +- Same style (outlined, filled, or duotone -- don't mix within a set) +- Same corner radius and line cap + +**Form inputs:** All inputs of the same type must look identical. +- Same border colour, radius, and width +- Same padding, font size, and placeholder colour +- Same focus ring colour and width +- Disabled/readonly states consistent across all inputs + +**Status indicators:** Consistent colour-meaning mapping. +- Green = success/active +- Yellow/amber = warning/pending +- Red = error/inactive/destructive +- Blue = informational/neutral +- Never reuse a status colour for a different meaning + +### Breaking Similarity Intentionally + +Breaking similarity creates a focal point. Use this for: + +1. **Primary CTA:** One button that's visually different from all others on the page +2. **Error states:** Red border on the invalid field among normal-bordered fields +3. **Highlighted row:** One table row with a different background +4. **Featured item:** One card with a different border, shadow, or badge + +**Rule:** Only one element per context should break similarity. Multiple breaks compete and cancel each other out. + +### Similarity + Proximity Combined + +The strongest non-connected grouping: elements that are both close together AND look alike. + +Example: A dashboard with three metric cards (same size, same style, same spacing) reads as "these metrics belong together" without any labels or borders saying so. + +When Similarity and Proximity conflict (elements look alike but are far apart, or look different but are close), resolve by: +1. Adding Common Region (a container) to override both +2. Or adjusting one principle to align with the other diff --git a/gestalt-ui/references/region-connectedness.md b/gestalt-ui/references/region-connectedness.md new file mode 100644 index 0000000..0e5a9f2 --- /dev/null +++ b/gestalt-ui/references/region-connectedness.md @@ -0,0 +1,139 @@ +# Common Region & Uniform Connectedness -- Deep Dive + +Container-based and connection-based grouping -- the explicit tools for when spacing and similarity aren't enough. + +## Common Region in Practice + +### When to Use Containers + +Containers (cards, panels, fieldsets, coloured backgrounds) explicitly group elements. Use them when: + +1. **Proximity alone is ambiguous** -- elements from different groups are too close to separate spatially +2. **Mixed content types** -- grouped elements don't share visual similarity (image + text + button) +3. **Interaction boundaries** -- the user needs to know "this is one clickable unit" (cards) +4. **Section identity** -- the group needs a visible identity (settings panels, feature blocks) + +### Container Patterns + +| Pattern | Structure | Use case | +|---------|-----------|----------| +| **Card** | Border or shadow + padding | Discrete content units (products, articles, users) | +| **Panel** | Background colour + padding | Settings groups, sidebar sections | +| **Fieldset** | Border + legend/label | Form field groups | +| **Well / Inset** | Recessed background | Code blocks, quoted content, secondary info | +| **Stripe** | Full-width background colour | Page sections (hero, features, testimonials) | +| **Chip / Tag** | Tight border + small padding | Labels, categories, filters | + +### Card Design Rules + +Cards are the most common Common Region pattern. Rules: + +1. **One primary action per card.** The card itself should be the clickable target for the primary action. Secondary actions go in a menu or footer. +2. **Consistent dimensions** within a grid. Same height per row minimum; same width preferred. +3. **Internal hierarchy:** Image > Title > Description > Meta. Apply Proximity within the card. +4. **Maximum 3-4 pieces of information.** Beyond that, the card loses scanability. +5. **Don't overload.** If a card needs tabs or scrolling, it's not a card -- it's a page. + +### Container Nesting Rules + +Avoid deep nesting. Maximum 2 levels: page → card, or page → panel → card. + +``` +❌ Bad: Page → Section → Panel → Card → Nested Card +✅ Good: Page → Section → Card +✅ Good: Page → Panel → Card (2 levels max) +``` + +**Why:** Each nesting level adds visual complexity (borders, shadows, backgrounds stacking). Beyond 2 levels, the interface becomes noisy and the grouping hierarchy is lost. + +### Container vs Spacing + +**Use spacing (Proximity) when:** +- The grouping is within a single context (fields in a form, items in a list) +- Adding a container would create unnecessary visual noise +- The layout is simple and spacing alone communicates structure + +**Use containers (Common Region) when:** +- Multiple content types need to appear as one unit (card with image + text + button) +- The group needs to be interactive as a whole (clickable card) +- You need to override proximity-based grouping +- The group has a distinct identity or purpose within the page + +--- + +## Uniform Connectedness in Practice + +### The Strongest Grouping Principle + +Uniform connectedness -- visual connections between elements -- is the strongest Gestalt grouping principle. It overrides proximity, similarity, and common region. + +Use it for relationships that must be unambiguous. + +### Connection Patterns + +| Pattern | Implementation | Use case | +|---------|---------------|----------| +| **Step connector** | Horizontal or vertical line between numbered circles | Multi-step processes, wizards, checkout flows | +| **Tree connector** | Lines with branches | File trees, org charts, nested navigation | +| **Flow connector** | Arrows between boxes | Process diagrams, data flow, architecture | +| **Timeline connector** | Vertical line with branching events | Activity feeds, history, changelog | +| **Label connector** | Line from label to element | Annotations, tooltips, diagram callouts | + +### Step Indicator Design + +The most common Uniform Connectedness pattern in UI: + +``` +( 1 )----( 2 )----( 3 )----( 4 ) + Cart Shipping Payment Confirm +``` + +**Rules:** +1. Completed steps: filled circle, checkmark, or solid colour +2. Current step: highlighted, larger, or animated +3. Future steps: outlined, muted, or greyed +4. Connecting line: solid for completed transitions, dashed for pending +5. Labels below or beside each step -- never rely on numbers alone +6. Clickable completed steps allow backward navigation + +### Timeline / Activity Feed Design + +Vertical Uniform Connectedness: + +``` + ● Event 1 -- 2 hours ago + | Description... + | + ● Event 2 -- 5 hours ago + | Description... + | + ○ Event 3 -- Yesterday + Description... +``` + +**Rules:** +1. Continuous line connects all events +2. Most recent at top (reverse chronological) +3. Filled circles for significant events, empty for minor +4. Date/time stamps visible for each event +5. Line breaks or gaps signal time jumps + +### Conditional Form Connections + +Show relationships between form fields using visual connectors: + +``` +[ Country ▼ ] + | + ├── If "US": [ State ▼ ] [ ZIP Code ] + └── If "UK": [ County ] [ Postcode ] +``` + +Use indentation + connecting lines to show that sub-fields depend on the parent selection. This is clearer than dynamically showing/hiding fields without visual context. + +### When NOT to Use Connections + +- **Between all elements in a list** -- proximity is sufficient +- **Between unrelated content** -- connections imply relationships; don't create false ones +- **In dense layouts** -- too many lines create visual chaos; use proximity and similarity instead +- **For decoration** -- lines must communicate meaning; decorative lines add noise diff --git a/laws-of-ux/SKILL.md b/laws-of-ux/SKILL.md new file mode 100644 index 0000000..28c7d72 --- /dev/null +++ b/laws-of-ux/SKILL.md @@ -0,0 +1,333 @@ +--- +name: laws-of-ux +description: 'Apply evidence-based UX laws to interaction design decisions. Use when you need to: (1) size and position interactive targets effectively, (2) reduce cognitive load and decision complexity, (3) design progress indicators, feedback timing, and memory-friendly interfaces, (4) resolve design trade-offs with psychological evidence. Based on Laws of UX by Jon Yablonski, synthesising research from psychology, cognitive science, and HCI.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Laws of UX + +A framework of behavioural psychology principles applied to interface design. These laws describe how humans perceive, decide, and act -- use them to design interfaces that work with human cognition, not against it. + +This skill focuses on behavioural laws (Fitts's, Hick's, Miller's, etc.). For usability heuristics, see `ux-heuristics`. For visual grouping principles, see `gestalt-ui`. + +## Core Principle + +**Design for how humans actually behave, not how they should behave.** Users don't read -- they scan. They don't optimise -- they satisfice. They don't remember -- they recognise. Every interaction design decision should be grounded in observable human behaviour, not designer assumptions. + +## Scoring + +**Goal: 10/10.** When reviewing or designing interactions, rate 0-10 based on alignment with these behavioural laws. + +- **9-10:** Interactive targets are appropriately sized and placed. Choices are manageable. Response times feel instant. Progress is visible. Memory load is minimal. +- **7-8:** Most interactions follow the laws. Minor issues: a few small targets, one overloaded menu, occasional missing feedback. +- **5-6:** Some laws applied, others ignored. Noticeable friction: too many choices, missing progress indicators, slow feedback. +- **3-4:** Significant violations. Small touch targets, overwhelming option lists, no loading feedback, heavy memory demands. +- **1-2:** Laws systematically violated. Interface fights human cognition at every step. + +## The Laws of UX Framework + +### 1. Fitts's Law -- Size and Distance Matter + +**Core concept:** The time to reach a target is a function of the distance to and size of the target. Larger, closer targets are faster and easier to hit. + +**Why it works:** Motor control follows a logarithmic speed-accuracy trade-off. Smaller targets require slower, more precise movements. + +**Key insights:** +- Minimum touch target: **44x44 CSS pixels** (10mm x 10mm physical, per MIT Touch Lab) +- Add padding between adjacent interactive elements to prevent mis-taps +- Screen edges and corners are effectively infinite-size targets (cursor stops at edge) +- Place frequently used actions near the cursor's resting position or thumb zone +- Primary actions should be the largest interactive elements in their context + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Mobile | Thumb-zone placement for primary actions | FAB button in bottom-right (right-handed), tab bar at bottom | +| Forms | Full-width submit buttons on mobile | "Continue" button spanning the viewport width | +| Navigation | Adequately sized menu items with padding | 44px minimum height per nav link, 8px gap between | +| Dialogs | Large, separated action buttons | "Delete" and "Cancel" with generous spacing and size | + +**Ethical boundary:** Never make important actions (unsubscribe, delete account, reject cookies) deliberately small or hard to reach. + +See: [references/motor-laws.md](references/motor-laws.md) + +### 2. Hick's Law -- Fewer Choices, Faster Decisions + +**Core concept:** Decision time increases logarithmically with the number and complexity of choices. More options = more cognitive effort = slower action. + +**Why it works:** Each additional option requires evaluation and comparison. The brain processes choices sequentially, not in parallel. + +**Key insights:** +- Limit top-level navigation to **5-7 items** +- Use progressive disclosure: show details on demand, not all at once +- Break complex processes into sequential steps (wizards over mega-forms) +- Highlight recommended options to reduce decision effort +- Categorise long lists instead of presenting flat lists +- "Choice overload" causes decision paralysis when options exceed ~4 meaningful alternatives + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Navigation | Maximum 5-7 top-level items | Main nav: Home, Products, Pricing, Docs, Blog | +| Pricing | 3 plans with highlighted recommendation | Free / Pro (recommended) / Enterprise | +| Settings | Grouped into categories, not one long list | Account, Notifications, Privacy, Billing -- each expandable | +| Onboarding | One question per screen | Step 1: Role → Step 2: Team size → Step 3: Goals | +| Search | Filtered results with facets | Category tabs + sort options, not 500 unsorted results | + +See: [references/decision-laws.md](references/decision-laws.md) + +### 3. Miller's Law -- Chunk Information + +**Core concept:** Working memory holds approximately **7 +/- 2 items**. Beyond this, information overflows and is forgotten or confused. + +**Why it works:** Short-term memory has a fixed capacity. Chunking groups individual items into meaningful units, effectively multiplying capacity. + +**Key insights:** +- Break long sequences into chunks: `(555) 123-4567` not `5551234567` +- Limit items per group to 5-9 (navigation sections, tab groups, option lists) +- Use headings and visual separators to chunk content on a page +- Don't interpret this as "menus must have exactly 7 items" -- it's about cognitive load, not a magic number + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Phone numbers | Chunked with formatting | `+49 (171) 234-5678` | +| Credit cards | 4-digit groups | `4242 4242 4242 4242` | +| Long forms | Grouped into sections | Personal info (3 fields) → Address (4 fields) → Payment (3 fields) | +| Dashboards | Metrics grouped into panels | Revenue panel (3 KPIs), Users panel (3 KPIs), Performance panel (3 KPIs) | + +See: [references/memory-laws.md](references/memory-laws.md) + +### 4. Jakob's Law -- Users Expect Convention + +**Core concept:** Users spend most of their time on **other** sites. They prefer your interface to work the same way as interfaces they already know. + +**Why it works:** Familiar patterns leverage existing mental models. Users don't need to learn new interactions -- they transfer knowledge from past experience. + +**Key insights:** +- Logo top-left links to home (universal convention) +- Search in the top-right or top-centre +- Shopping cart icon for e-commerce +- Hamburger menu = hidden navigation (mobile) +- "Settings" = gear icon; "Profile" = avatar/circle +- Innovate on content and value, not on basic interaction patterns +- When you must break convention, provide clear signifiers and instructions + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| E-commerce | Standard cart/checkout flow | Cart icon with badge → Cart page → Checkout → Confirmation | +| SaaS | Standard dashboard layout | Sidebar nav + top bar + main content area | +| Auth | Standard login/signup patterns | Email + password + "Forgot password?" + social login | +| Mobile | Platform-specific patterns | iOS: back in top-left; Android: back via system gesture | + +**Critical rule:** Every deviation from convention must earn its place. If users need to learn something new, the benefit must clearly outweigh the learning cost. + +See: [references/decision-laws.md](references/decision-laws.md) + +### 5. Doherty Threshold -- Speed Builds Flow + +**Core concept:** Productivity soars when response time is under **400ms**. Above this, users perceive a delay and lose their sense of flow. + +**Why it works:** Below 400ms, the interaction feels instantaneous -- the brain doesn't register waiting. Above it, the user's attention shifts from the task to the system. + +**Key insights:** +- < 100ms: Feels instantaneous. No feedback needed for direct manipulation (clicks, toggles) +- 100-400ms: Subtle indicator (button state change, micro-animation) +- 400ms-2s: Spinner or skeleton screen required +- 2-10s: Progress bar with percentage +- > 10s: Progress bar + status messages explaining what's happening +- Use optimistic UI: show the result immediately, sync in the background +- Animate transitions (300-500ms) to mask loading time + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Form submission | Optimistic success state | "Message sent!" appears immediately; actual API call happens in background | +| Page navigation | Skeleton screens | Grey placeholder blocks matching the layout, replaced by real content | +| Data loading | Progressive loading | Table header + first rows appear instantly; remaining rows stream in | +| Search | Debounced live results | Results update 200ms after user stops typing | + +See: [references/motor-laws.md](references/motor-laws.md) + +### 6. Von Restorff Effect -- Distinctiveness Creates Memory + +**Core concept:** When multiple similar objects are present, the one that **differs** from the rest is most likely to be remembered. + +**Why it works:** The brain allocates more attention and memory to novel or distinctive stimuli. Contrast is a survival mechanism. + +**Key insights:** +- Make the primary CTA visually distinct from all other buttons +- Highlight the recommended pricing plan with a different style +- Use distinctive styling for important notifications or alerts +- Sparingly: if everything is highlighted, nothing stands out (see Focal Points in `gestalt-ui`) +- Accessibility: don't rely on colour alone for distinctiveness -- use size, shape, position, and text + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Pricing | Recommended plan visually different | "Pro" plan with coloured border, "Popular" badge, slightly larger | +| CTAs | Primary button distinct from secondary | Blue filled "Submit" among grey outlined "Cancel" and "Back" | +| Notifications | Critical alerts visually unique | Red banner for errors among blue info notifications | +| Tables | Important row highlighted | Overdue invoice row with coloured background | + +### 7. Peak-End Rule -- Moments That Matter + +**Core concept:** People judge an experience by its **peak moment** (most intense point) and its **ending**, not by the average of all moments. + +**Why it works:** Memory is constructive, not comprehensive. The brain stores emotional highlights and the final state, then generalises from those. + +**Key insights:** +- Optimise the first impression (landing, onboarding) and the final interaction (confirmation, thank-you) +- Error recovery is a peak moment -- handle it gracefully and users forgive other friction +- A frustrating checkout can ruin an otherwise excellent browsing experience +- Celebratory moments (achievement unlocked, order confirmed) create positive peaks +- The last step of any flow disproportionately influences overall satisfaction + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Onboarding | Delightful first experience | Personalised welcome, quick first success ("Your workspace is ready!") | +| Checkout | Smooth final step + celebration | Confetti animation on order confirmation | +| Error recovery | Helpful, specific error messages | "Payment failed -- try a different card or contact support" with direct link | +| Cancellation | Respectful exit experience | "We're sorry to see you go" with clear confirmation, no guilt-tripping | + +### 8. Aesthetic-Usability Effect -- Beauty Buys Tolerance + +**Core concept:** Users perceive aesthetically pleasing designs as **more usable**, even when they're objectively not. + +**Why it works:** Visual appeal creates positive emotional responses that bias perception. Users are more patient, more forgiving, and more willing to explore beautiful interfaces. + +**Key insights:** +- Visual polish increases tolerance for minor usability issues +- First impressions are disproportionately influenced by visual quality +- But: aesthetics cannot compensate for fundamentally broken interactions +- Invest in visual refinement **after** getting the interaction model right +- A beautiful but unusable interface is worse than an ugly but functional one + +### 9. Tesler's Law -- Complexity Must Live Somewhere + +**Core concept:** Every system has **irreducible complexity** that cannot be eliminated. The question is whether the user or the system deals with it. + +**Why it works:** Complexity is conserved -- simplifying the user's experience means the system absorbs that complexity. The goal is to move complexity away from the user wherever possible. + +**Key insights:** +- Smart defaults reduce decisions the user must make +- Auto-detection (location, language, currency, timezone) absorbs complexity +- Pre-filling forms with known data moves complexity to the system +- But: don't hide essential controls behind too much "magic" -- users need to feel in control +- The simplest UI is not always the best UI -- sometimes showing complexity is appropriate (power tools) + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Forms | Smart defaults | Country pre-selected based on IP, currency auto-set | +| Search | Auto-correct and suggestions | "Did you mean..." + filtered suggestions | +| Settings | Sensible defaults with override option | Notifications on by default, customisable per channel | +| Scheduling | Timezone auto-detection | "Meeting at 3pm your time (PST)" | + +### 10. Postel's Law -- Be Forgiving with Input + +**Core concept:** Be **liberal in what you accept**, conservative in what you send. Accommodate varied input; produce clean output. + +**Why it works:** Users input data in unpredictable formats. Fighting their format creates friction. Accepting and normalising silently creates flow. + +**Key insights:** +- Accept phone numbers with or without country code, spaces, dashes, parentheses +- Accept dates in multiple formats and normalise to one display format +- Trim whitespace, fix capitalisation, strip formatting silently +- Display output in a clean, consistent format regardless of input +- Forgive typos in search (fuzzy matching, "did you mean...?") + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Phone input | Accept any format | `+1 555 123 4567`, `(555) 123-4567`, `5551234567` all valid | +| Date input | Accept multiple formats | `12/25/2025`, `25.12.2025`, `Dec 25 2025` all parsed correctly | +| Search | Fuzzy matching | "javascrpt" → shows results for "javascript" | +| Names | Flexible validation | Accept O'Brien, García, 山田, hyphenated names | + +### 11. Goal-Gradient Effect -- Proximity to Finish Motivates + +**Core concept:** Motivation increases as users **approach their goal**. The closer to completion, the harder they'll work. + +**Why it works:** Progress toward a visible goal triggers dopamine release. The brain rewards effort more as the finish line approaches. + +**Key insights:** +- Show progress bars in multi-step processes +- Start progress slightly filled (artifical advancement increases completion) +- "Step 2 of 4" is more motivating than showing all steps as equally distant +- Checklists with some items pre-checked leverage this effect +- Loyalty programs and streaks use goal-gradient extensively + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Onboarding | Progress bar with steps completed | "Profile 60% complete -- add a photo to reach 80%" | +| Checkout | Step indicator with progress | Steps 1-4 with current position highlighted | +| Gamification | Achievement nearly unlocked | "3 more reviews to earn Gold Reviewer badge" | +| Forms | Section progress within long forms | "Section 2 of 3: Shipping Details" | + +## Combining Laws + +Laws work together. The strongest designs apply multiple laws simultaneously: + +| Combination | Effect | Example | +|-------------|--------|---------| +| Fitts + Hick | Large targets + few choices = fast action | 3 large pricing plan buttons | +| Miller + Goal-Gradient | Chunked steps + progress visibility | 4-step wizard with progress bar | +| Jakob + Postel | Conventional layout + flexible input | Standard checkout flow accepting varied address formats | +| Doherty + Peak-End | Fast responses + celebratory ending | Instant "Added to cart" + confetti on order confirmation | +| Von Restorff + Fitts | Distinctive + large = unmissable CTA | One bright, large "Get Started" button on muted page | + +## Common Mistakes + +| Mistake | Law Violated | Fix | +|---------|-------------|-----| +| Tiny click/tap targets | Fitts's Law | Minimum 44x44px; add padding between targets | +| 15+ navigation items in one level | Hick's Law | Categorise into 5-7 groups; use progressive disclosure | +| Requiring users to remember values between screens | Miller's Law | Show context persistently; use breadcrumbs and summaries | +| Reinventing standard interaction patterns | Jakob's Law | Follow conventions; innovate on value, not on UI mechanics | +| No feedback for actions > 400ms | Doherty Threshold | Add spinners, skeleton screens, or optimistic UI | +| Every element equally emphasised | Von Restorff Effect | One focal point per context; mute everything else | +| Frustrating final step in a flow | Peak-End Rule | Polish the ending: confirmation, success animation, next steps | +| Rejecting valid but oddly-formatted input | Postel's Law | Parse and normalise silently; accept what you can | +| No progress indicator in multi-step process | Goal-Gradient Effect | Show step count, progress bar, or checklist | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Are all touch targets >= 44x44px? | Fitts violation | Increase size; add padding | +| Can users complete the primary task in < 3 decisions? | Hick violation | Reduce choices; use progressive disclosure | +| Is information chunked into groups of <= 7? | Miller violation | Group, chunk, and label information | +| Does the interface follow platform conventions? | Jakob violation | Audit against standard patterns; align | +| Is feedback visible within 400ms of every action? | Doherty violation | Add optimistic UI, skeletons, or spinners | +| Is there exactly one visually dominant CTA per view? | Von Restorff gap | Emphasise one; de-emphasise others | +| Is the final step of key flows polished and positive? | Peak-End gap | Add confirmation, celebration, clear next steps | + +## Reference Files + +- [references/motor-laws.md](references/motor-laws.md) -- Fitts's Law and Doherty Threshold with sizing tables and response time guidelines +- [references/decision-laws.md](references/decision-laws.md) -- Hick's Law, Jakob's Law, choice architecture, and progressive disclosure +- [references/memory-laws.md](references/memory-laws.md) -- Miller's Law, Serial Position Effect, Zeigarnik Effect, and chunking strategies + +## Further Reading + +- Jon Yablonski, [Laws of UX](https://lawsofux.com/) +- Paul Fitts, "The Information Capacity of the Human Motor System" (1954) +- William Hick, "On the Rate of Gain of Information" (1952) +- George Miller, "The Magical Number Seven" (1956) diff --git a/laws-of-ux/references/decision-laws.md b/laws-of-ux/references/decision-laws.md new file mode 100644 index 0000000..e55858d --- /dev/null +++ b/laws-of-ux/references/decision-laws.md @@ -0,0 +1,114 @@ +# Decision Laws -- Hick's Law & Jakob's Law + +How users make choices and what they expect from interfaces. + +## Hick's Law Deep Dive + +### The Formula + +``` +RT = a + b × log₂(n + 1) +``` + +Where: +- **RT** = Reaction Time +- **n** = Number of choices +- **a, b** = Constants + +The logarithmic relationship means going from 2 to 4 options has more impact than going from 20 to 22. The first few additional options cost the most cognitive effort. + +### Choice Reduction Strategies + +| Strategy | How it works | Example | +|----------|-------------|---------| +| **Progressive disclosure** | Show only what's needed now; reveal more on demand | "Advanced settings" expandable section | +| **Categorisation** | Group options into meaningful categories | Settings → Account / Notifications / Privacy | +| **Recommended option** | Highlight one choice to short-circuit decision-making | "Most popular" plan badge | +| **Smart defaults** | Pre-select the most common option | Country pre-selected based on IP | +| **Recent/frequent** | Surface previously chosen options | "Recent searches" dropdown | +| **Search + filter** | Let users narrow large sets themselves | Product filters: price, size, colour | + +### Navigation Limits + +| Level | Maximum items | Strategy beyond limit | +|-------|--------------|----------------------| +| Top-level nav | 5-7 | Merge, categorise, or use mega-menu with clear sections | +| Dropdown menu | 7-10 | Add search within dropdown; categorise with headers | +| Tab bar (mobile) | 5 | "More" tab for additional items | +| Action menu | 5-7 | Group into sections with dividers | +| Toolbar | 5-7 visible | Overflow menu (...) for additional actions | + +### Choice Architecture + +The way choices are presented influences decisions: + +1. **Default bias:** Users tend to accept pre-selected options. Use ethical defaults. +2. **Order effect:** First and last options are chosen more often (Serial Position Effect). +3. **Decoy effect:** An inferior option can make a target option look better (pricing tiers). +4. **Anchoring:** The first number seen influences subsequent judgments (original price shown with discount). + +**Ethical boundary:** Choice architecture must serve the user's interest. Manipulative defaults (pre-checked newsletter signup, harder-to-find unsubscribe) are dark patterns. + +### Progressive Disclosure Patterns + +| Pattern | Implementation | Use case | +|---------|---------------|----------| +| Accordion | Click to expand one section at a time | FAQ, settings categories | +| "Show more" | Button reveals additional items | Product features, search results | +| Tabs | Switch between content panels | Dashboard views, profile sections | +| Wizard / Stepper | One step at a time in sequence | Onboarding, checkout, complex forms | +| Tooltip / Popover | Hover or click for details | Feature explanations, data tooltips | +| Detail panel | Select item to show details in adjacent panel | Email clients, admin dashboards | + +--- + +## Jakob's Law Deep Dive + +### Universal Web Conventions (2024+) + +| Element | Expected position | Expected behaviour | +|---------|------------------|-------------------| +| Logo | Top-left | Links to homepage | +| Primary navigation | Top horizontal bar or left sidebar | Visible on desktop; hamburger on mobile | +| Search | Top-right or top-centre | Magnifying glass icon; expands on click/tap | +| Login / Account | Top-right | Avatar or "Sign in" text | +| Shopping cart | Top-right (e-commerce) | Icon with item count badge | +| Footer | Bottom | Contact, legal, sitemap links | +| "Back" | Top-left (mobile) or browser back | Returns to previous page | +| Breadcrumbs | Below top nav, above content | Clickable path: Home > Category > Page | + +### Platform-Specific Conventions + +| Platform | Convention | Breaking it causes | +|----------|-----------|-------------------| +| **iOS** | Back button top-left; tab bar bottom | Navigation confusion | +| **Android** | System back gesture; FAB bottom-right | Broken navigation flow | +| **Desktop web** | Right-click context menu; Ctrl/Cmd shortcuts | Frustration for power users | +| **Desktop apps** | Menu bar top; File/Edit/View order | Disorientation | + +### When to Break Convention + +Breaking convention is expensive. Only do it when: + +1. **The new pattern is clearly better** AND you can teach it quickly +2. **The convention doesn't exist** for your use case (novel interaction type) +3. **Platform guidelines** explicitly recommend a different approach + +**How to break convention safely:** +- Provide onboarding / tooltip for the new pattern +- Offer the conventional alternative as a fallback (e.g., drag-to-reorder + manual sort button) +- Test with real users -- what seems intuitive to you may confuse them + +### Mental Model Alignment + +Users arrive with mental models from prior experience: + +| User expects | Because of | If you break it | +|-------------|-----------|-----------------| +| "Delete" is reversible (trash/undo) | Desktop OS, Gmail | Data loss, anger, support tickets | +| Swiping left in a list reveals actions | iOS Mail, messaging apps | Nothing happens, confusion | +| Clicking a logo goes home | Every website ever | Users get lost | +| Red means error/danger | Traffic lights, fire, blood | Misinterpretation of status | +| Search returns relevant results | Google | Frustration, abandonment | + +**Rule:** When your mental model differs from the user's, the user's model wins. Adapt the interface, not the user. diff --git a/laws-of-ux/references/memory-laws.md b/laws-of-ux/references/memory-laws.md new file mode 100644 index 0000000..01c3a48 --- /dev/null +++ b/laws-of-ux/references/memory-laws.md @@ -0,0 +1,156 @@ +# Memory Laws -- Miller's Law, Serial Position, Zeigarnik Effect + +How human memory limitations and biases affect interface design. + +## Miller's Law Deep Dive + +### What Miller Actually Said + +George Miller's 1956 paper is often misquoted as "the magic number 7." What he actually demonstrated: + +- Short-term memory can hold approximately **7 +/- 2 chunks** of information +- The key word is **chunks** -- grouped, meaningful units, not individual items +- Chunking is the strategy: group items into meaningful patterns to increase effective capacity +- Modern research suggests the actual limit may be closer to **4 +/- 1** for novel information + +### Chunking Strategies for UI + +| Content type | Without chunking | With chunking | +|-------------|------------------|---------------| +| Phone number | 5551234567 | (555) 123-4567 | +| Credit card | 4242424242424242 | 4242 4242 4242 4242 | +| IBAN | DE89370400440532013000 | DE89 3704 0044 0532 0130 00 | +| Serial number | A8B2C4D6E9F1 | A8B2-C4D6-E9F1 | +| Long content | 15 paragraphs in sequence | 5 sections with 3 paragraphs each | +| Navigation | 20 flat links | 4 categories with 5 links each | +| Settings | 30 toggles | 6 groups with 5 settings each | + +### Input Masking Implements Miller's Law + +Automatically format user input into chunks: + +``` +Input: 4242424242424242 +Display: 4242 4242 4242 4242 + +Input: 15551234567 +Display: +1 (555) 123-4567 + +Input: 12252025 +Display: 12/25/2025 +``` + +**Implementation rules:** +- Apply formatting as the user types (not just on blur) +- Never reject input because of formatting -- strip formatting before validation +- Show the formatted version in the field +- Allow paste of unformatted values + +### Dashboard Design and Miller's Law + +Dashboards are the most common Miller's Law violation: + +**Problem:** 20+ metrics visible simultaneously, each competing for attention. +**Solution:** Group into panels of 3-5 related metrics. + +``` +┌─ Revenue ─────────┐ ┌─ Users ───────────┐ ┌─ Performance ─────┐ +│ Total: $142K │ │ Active: 12,450 │ │ Uptime: 99.97% │ +│ Growth: +12% │ │ New: 1,230 │ │ Avg Response: 82ms│ +│ MRR: $48K │ │ Churn: 2.1% │ │ Error Rate: 0.3% │ +└────────────────────┘ └────────────────────┘ └────────────────────┘ +``` + +Each panel is one "chunk" -- the brain processes 3 panels (within capacity) instead of 9 individual metrics. + +--- + +## Serial Position Effect + +### The Pattern + +Users remember: +- **First items** (primacy effect) -- they get the most rehearsal +- **Last items** (recency effect) -- they're still in short-term memory +- **Middle items** -- most likely to be forgotten + +### Design Implications + +| Context | First position | Last position | Middle | +|---------|---------------|---------------|--------| +| Navigation | Most important link | Second most important | Less critical links | +| Lists | Key item or recommended option | CTA or summary | Supporting details | +| Onboarding | Most impactful feature | Clear next step | Additional features | +| Pricing | Free/entry plan | Enterprise/contact | Standard plans | +| Tab bars | Home/primary screen | Profile/account | Secondary screens | + +### Practical Application + +- **Tab bar:** Home (first) and Profile (last) are most used; middle tabs get less engagement +- **Feature lists:** Lead with the strongest feature; end with the CTA. Middle features are skimmed. +- **Error messages:** Start with what went wrong; end with how to fix it. Middle context is often skipped. + +--- + +## Zeigarnik Effect + +### The Pattern + +People remember **uncompleted tasks** better than completed ones. Interrupted activities create cognitive tension that persists until resolution. + +### Design Applications + +| Pattern | How it leverages Zeigarnik | Example | +|---------|---------------------------|---------| +| **Progress bars** | Incomplete fill creates tension to complete | "Profile 70% complete" | +| **Saved drafts** | Unfinished work stays salient in memory | "You have an unfinished post" | +| **Streak indicators** | Breaking a streak creates tension | "15-day streak -- don't break it!" | +| **Abandoned cart emails** | Reminding of unfinished purchase | "You left items in your cart" | +| **Checklists** | Unchecked items demand completion | "3 of 5 setup steps completed" | +| **Cliffhangers** | Incomplete content motivates return | "Next episode in 5..." | + +### Ethical Considerations + +The Zeigarnik Effect is powerful for engagement but easily abused: + +**Ethical uses:** +- Helping users complete tasks they started and want to finish (onboarding, checkout) +- Saving progress so users can return without starting over +- Showing progress toward a goal the user set themselves + +**Unethical uses:** +- Artificial incompleteness to manufacture engagement ("Profile incomplete" when it's perfectly functional) +- Pressure through streaks that penalise breaks +- Guilt-inducing notifications about "unfinished" tasks the user abandoned intentionally +- Fake urgency ("Your cart is expiring!") + +**Rule:** Use Zeigarnik to help users accomplish **their** goals, not to manufacture anxiety that serves **your** metrics. + +--- + +## Recognition vs Recall + +### The Principle + +Recognition (identifying among options) is easier than recall (retrieving from memory). Interfaces should minimise recall demands. + +### Design Checklist + +| Recall (avoid) | Recognition (prefer) | +|----------------|---------------------| +| "Enter the product code" | Dropdown/search with product names and images | +| "Type your previous search" | Recent searches shown on focus | +| "Remember your settings from last time" | Settings visible and pre-filled | +| Blank text field for category | Tags, pills, or checkboxes to select | +| "Which page were you on?" | Breadcrumbs showing current path | +| "Enter the file path" | File browser with visual thumbnails | + +### Search Design for Recognition + +Search should show recognition cues, not demand recall: + +1. **Autocomplete:** Suggest matches as the user types +2. **Recent searches:** Show on focus (before typing) +3. **Search results:** Include images, descriptions, and context -- not just titles +4. **Filters as recognition:** Faceted search with visible categories +5. **"Did you mean...":** Correct spelling without demanding the user recall the exact term diff --git a/laws-of-ux/references/motor-laws.md b/laws-of-ux/references/motor-laws.md new file mode 100644 index 0000000..c1dfce3 --- /dev/null +++ b/laws-of-ux/references/motor-laws.md @@ -0,0 +1,125 @@ +# Motor Laws -- Fitts's Law & Doherty Threshold + +Physical interaction and response time: how size, distance, and speed affect usability. + +## Fitts's Law Deep Dive + +### The Formula + +``` +MT = a + b × log₂(2D/W) +``` + +Where: +- **MT** = Movement Time +- **D** = Distance to target +- **W** = Width (size) of target +- **a, b** = Device-dependent constants + +The practical implication: **doubling the target size** reduces movement time more than **halving the distance**. + +### Touch Target Sizing Guide + +| Element | Minimum size | Recommended | Notes | +|---------|-------------|-------------|-------| +| Primary button | 44x44px | 48x48px | Full-width on mobile for maximum Fitts advantage | +| Secondary button | 36x36px | 44x44px | Smaller acceptable if not primary action | +| Icon button | 44x44px | 48x48px | Tap target larger than visual icon (padding) | +| Navigation link | 44px height | 48px height | Full-width hit area, not just text | +| List item (tappable) | 44px height | 56-72px | Taller for comfortable repeated tapping | +| Checkbox / Radio | 44x44px | 44x44px | Tap target includes label, not just the box | +| Close button (X) | 44x44px | 44x44px | Never smaller, even if visually minimal | + +### Thumb Zone (Mobile) + +On mobile, the thumb has natural reach zones: + +``` +┌─────────────────────┐ +│ Hard Easy Hard │ ← Top: hardest to reach +│ │ +│ Easy Easy Easy │ ← Middle: comfortable +│ │ +│ Easy Easy Easy │ ← Bottom: natural resting zone +└─────────────────────┘ +``` + +**Rules:** +- Primary actions belong in the bottom third (natural thumb zone) +- Destructive actions in the top corners (harder to reach accidentally) +- Navigation tabs at the bottom for easy switching +- FABs (floating action buttons) in the bottom-right for right-handed users + +### Edge and Corner Targets + +Screen edges are "infinitely deep" -- the cursor can't overshoot them. This makes edge and corner targets extremely fast to acquire. + +**Use this for:** +- Menu bars pinned to screen edges (macOS menu bar) +- Scroll bars at viewport edges +- Side panels / drawers anchored to viewport edges +- Desktop: corners are the fastest targets (infinite in two dimensions) + +**Don't break this:** +- Never add padding/margin between a clickable element and the screen edge +- Sub-pixel gaps between the element and the edge negate the advantage + +### Spacing Between Targets + +Adjacent interactive elements need sufficient gap to prevent mis-taps: + +| Context | Minimum gap | Recommended | +|---------|-------------|-------------| +| Buttons side-by-side | 8px | 16px | +| List items (tappable) | 4px | 8px | +| Icon buttons | 8px | 12px | +| Toolbar items | 4px | 8px | + +--- + +## Doherty Threshold Deep Dive + +### Response Time Categories + +| Duration | User perception | Required feedback | +|----------|----------------|-------------------| +| 0-100ms | Instantaneous | None -- feels like direct manipulation | +| 100-400ms | Slight delay | Subtle: button state change, micro-animation | +| 400ms-1s | Noticeable wait | Spinner or skeleton screen | +| 1-2s | Definite wait | Spinner with context ("Loading messages...") | +| 2-5s | Uncomfortable | Progress bar (determinate if possible) | +| 5-10s | Frustrating | Progress bar + percentage + status messages | +| 10s+ | Unacceptable for foreground | Background processing + notification on completion | + +### Optimistic UI Pattern + +Show the result immediately. Sync in the background. Roll back only if the server rejects. + +**When to use:** +- Actions with > 95% success rate (likes, follows, toggles, saves) +- Actions where the user expects instant feedback +- Non-destructive actions that can be retried + +**When NOT to use:** +- Payment processing (must wait for confirmation) +- Destructive actions (deletion must confirm) +- Actions with complex validation (form submissions with server-side rules) + +### Skeleton Screen Pattern + +Replace loading spinners with grey placeholder blocks matching the content layout: + +**Rules:** +1. Mirror the exact layout of the content being loaded +2. Use subtle shimmer/pulse animation to indicate activity +3. Replace with real content progressively (don't flash blank → skeleton → content) +4. Better than spinners for content-heavy pages (reduces perceived load time by 20-30%) + +### Animation as Perceived Speed + +Transitions and animations can mask loading time: + +- 300-500ms ease-in-out transitions feel natural +- Staggered content appearance (items appearing 50ms apart) feels faster than all-at-once +- Skeleton → content morphing feels smoother than instant replacement +- Progress bars that start fast and slow near the end feel faster than linear progress diff --git a/ui-patterns/SKILL.md b/ui-patterns/SKILL.md new file mode 100644 index 0000000..f32bdfe --- /dev/null +++ b/ui-patterns/SKILL.md @@ -0,0 +1,319 @@ +--- +name: ui-patterns +description: 'Apply proven UI component patterns and scanning behaviour to build effective interfaces. Use when you need to: (1) design navigation, forms, buttons, cards, modals, or tables, (2) understand how users scan pages and place content accordingly, (3) choose between competing UI patterns (dropdown vs radio, modal vs inline, carousel vs static), (4) build loading states, notifications, and search interfaces. Complements gestalt-ui (visual grouping) and laws-of-ux (behavioural principles) with concrete component-level guidance.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# UI Patterns + +Concrete, evidence-based patterns for building common UI components. This skill answers the question: **"How should I build this specific component?"** + +For visual grouping theory, see `gestalt-ui`. For behavioural psychology laws, see `laws-of-ux`. For visual hierarchy and spacing systems, see `refactoring-ui`. For usability audits, see `ux-heuristics`. + +## Core Principle + +**Follow proven patterns. Innovate on value, not on interaction mechanics.** Users spend most of their time on other sites (Jakob's Law). Every component you build should feel familiar unless you have strong evidence that a novel pattern is significantly better. + +## Scoring + +**Goal: 10/10.** When reviewing or building components, rate 0-10 based on adherence to proven patterns. + +- **9-10:** Every component follows established patterns. Scanning flow is optimised. Decision reference followed for all pattern choices. +- **7-8:** Most components are well-patterned. Minor issues: one unconventional choice, missing loading state. +- **5-6:** Mixed adherence. Some components feel right, others require learning or cause confusion. +- **3-4:** Significant pattern violations. Users struggle to predict behaviour. +- **1-2:** Components invented from scratch. Nothing feels familiar or predictable. + +## The UI Patterns Framework + +### 1. Scanning Patterns -- How Users Actually Look at Pages + +**Core concept:** Users don't read pages linearly -- they scan in predictable patterns. Place content where the eye naturally goes. + +**Why it works:** Eye-tracking research reveals consistent scanning behaviours driven by reading habits and cognitive efficiency. + +**Key insights:** + +#### F-Pattern (Text-Heavy Pages) + +The eye moves: +1. Horizontal scan across the top (headline area) +2. Shorter horizontal scan slightly below (subheading / first paragraph) +3. Vertical scan down the left edge, looking for visual cues + +**Design rules for F-pattern pages:** +- First two paragraphs carry the most important information +- Start headings and bullet points with information-carrying words ("Users" not "In the case of users") +- Left-aligned content gets 2-3x more fixation than right-aligned +- Break walls of text with bold keywords, headings, and bullet points +- The F-pattern is the **default** when no visual cues exist -- good design breaks it + +#### Z-Pattern (Minimal-Text Pages) + +The eye moves: top-left → top-right → diagonal to bottom-left → bottom-right. + +**Design rules for Z-pattern pages:** +- Logo/brand: top-left +- CTA or key action: top-right +- Key message or value proposition: along the diagonal +- Primary CTA or conversion action: bottom-right + +Best for: landing pages, hero sections, splash screens, marketing pages. + +#### Visual Weight Factors + +Elements attract attention based on (strongest to weakest): +1. **Size** -- larger elements dominate +2. **Colour and contrast** -- vivid/saturated over muted +3. **Whitespace** -- isolated elements gain prominence +4. **Shape** -- distinctive shapes among uniform ones +5. **Position** -- top-left dominance in LTR languages +6. **Imagery** -- photos of people naturally attract the eye + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Landing pages | Z-pattern with CTA bottom-right | Hero image → headline → feature blocks → "Start free trial" | +| Blog / docs | F-pattern with scannable headings | Bold heading → summary → bulleted details → next heading | +| Dashboards | Top-left for most critical KPI | Revenue chart in top-left, secondary metrics below | +| Search results | Left-aligned titles, information-dense | Title (bold) → URL → description → metadata | + +See: [references/scanning-patterns.md](references/scanning-patterns.md) + +### 2. Navigation Patterns + +**Core concept:** Every page must answer three questions: (1) Where am I? (2) Where can I go? (3) Where have I been? + +**Why it works:** Users need orientation, options, and history. Most responsive navigation handles only "where can I go?" and forgets the other two. + +**Key insights:** + +| Pattern | Use when | Avoid when | +|---------|----------|------------| +| **Persistent top nav** | <= 7 items, flat hierarchy | Complex multi-level structures | +| **Simple toggle (hamburger)** | Single-level, many items on mobile | Multi-level hierarchies | +| **Multi-level toggle** | 2-level hierarchy (sweet spot for most sites) | > 2 levels of depth | +| **Off-canvas / drawer** | Complex menus, mobile-first | Desktop with sufficient space | +| **Tab bar (mobile)** | 3-5 primary destinations | > 5 items | +| **Sidebar** | Many sections, persistent access (apps, dashboards) | Content-focused sites (blogs, marketing) | + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| SaaS dashboard | Sidebar nav + top bar | Slack, Notion, Linear | +| E-commerce | Top nav with categories + breadcrumbs | Product categories as top-level, breadcrumbs on product pages | +| Marketing site | Simple top nav (5-7 links) | Home, Features, Pricing, Docs, Blog, Login | +| Mobile app | Bottom tab bar (4-5 tabs) | Home, Search, Create, Notifications, Profile | + +**Navigation rules:** +- Always label hamburger icons with "Menu" text -- icons alone are ambiguous +- Show breadcrumbs at all viewport sizes, not just desktop +- Build navigation progressively -- it must work without JavaScript +- Current page indicator must remain visible in responsive navigation +- No mega-menus on mobile; no more than 3 levels of nesting + +See: [references/navigation-forms.md](references/navigation-forms.md) + +### 3. Form Patterns + +**Core concept:** Forms are the highest-friction UI pattern. Every unnecessary field, confusing label, or validation delay reduces completion rates. + +**Why it works:** Research shows most forms can remove 20-60% of their fields without impacting data quality. Perceived complexity reduces completion rates more than actual complexity. + +**Key insights:** + +#### Layout +- **Labels above fields** -- always. Closest visual proximity. +- **One column** for forms -- multi-column increases completion time by 15-25% +- **Group related fields** with visible boundaries and tighter spacing within groups +- **Auto-focus the first field** to reduce interaction cost +- **Size fields proportionally** to expected input (postcode = short, address = long) + +#### Input Optimisation +- Match keyboard to input type: `type="email"`, `type="tel"`, `type="number"`, `type="date"` +- Use input masking for formatted data (phone, dates, credit cards) +- Enable browser autocomplete / autofill (30% faster completion per Google research) +- Show/hide password toggle instead of "confirm password" field +- Avoid dropdowns on mobile -- prefer radio buttons, segmented controls, or steppers + +#### Validation +- Validate inline **after the user leaves the field** (on blur), not while typing +- Show errors **next to the field**, not only in a top summary +- Plain language: "Email must include @" not "Error: invalid format" +- Never rely on colour alone for error indication -- add icons and text +- Preserve user input when errors occur -- never clear fields on error +- Show all errors at once, not one at a time + +#### Friction Reduction +- Remove every non-essential field +- Explain why sensitive data is needed ("We need your phone for delivery updates") +- Mark only optional fields (if most are required); use "Optional" text, not asterisks +- Persist form data across accidental page reloads + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Signup | Minimal fields (email + password) | Defer profile completion to after signup | +| Checkout | Auto-fill + address API + card scanning | Google Places autocomplete, camera card capture | +| Contact | Name + email + message (3 fields) | No phone, no company, no dropdown for "topic" | +| Settings | Section-by-section with inline save | Each section has its own "Save" button | + +See: [references/navigation-forms.md](references/navigation-forms.md) + +### 4. Button Patterns + +**Core concept:** Buttons must look clickable, communicate their action, and follow a clear visual hierarchy. + +**Key insights:** + +#### Visual Hierarchy + +| Level | Style | Examples | +|-------|-------|---------| +| **Primary** | Filled, high contrast, strongest visual weight | "Create Account", "Submit Order", "Get Started" | +| **Secondary** | Outlined or ghost, lower visual weight | "Cancel", "Back", "Learn More" | +| **Tertiary** | Text-only, minimal visual weight | "Skip", "Maybe Later", "Dismiss" | +| **Destructive** | Distinct colour (typically red), requires confirmation | "Delete Account", "Remove Item" | + +**Rule:** Never give "Cancel" the same visual weight as "Submit". The primary action must dominate. + +#### Sizing and Touch Targets +- Minimum: **44x44 CSS pixels** (10mm physical) +- Primary action: largest button in context +- Breathing room between adjacent buttons (minimum 8px, recommended 16px) +- Full-width on mobile for primary actions + +#### Labeling +- **Action verbs** describing the outcome: "Create Account", "Send Message", "Download PDF" +- Must answer: "What happens when I click this?" +- Avoid: "OK", "Submit", "Yes/No", "Click Here" + +#### Required States +- **Default** -- resting appearance +- **Hover** -- cursor feedback (desktop) +- **Active/Pressed** -- click confirmation +- **Focused** -- keyboard navigation indicator (never remove without replacement) +- **Disabled** -- muted with explanation (prefer enabled + validate on submit) +- **Loading** -- spinner or progress during async operations + +### 5. Card Patterns + +**Core concept:** Cards group heterogeneous content into discrete, scannable, often interactive units. + +**Key insights:** +- One primary action per card; secondary actions in overflow menu +- Entire card clickable for the primary action (not just a "Read more" link) +- Consistent dimensions within a grid (same height per row minimum) +- Internal hierarchy: Image > Title > Description > Meta +- Maximum 3-4 pieces of information per card + +### 6. Modal & Dialog Patterns + +**Core concept:** Modals interrupt flow and demand immediate attention. Use only when interruption is justified. + +**When to use:** Destructive action confirmation, short decision-required forms, critical alerts. + +**When NOT to use:** Informational content, long forms, marketing/upsells, errors (use inline). + +**Rules:** +- Always provide visible close button (X) AND Escape key +- Dim/blur the background (figure-ground separation) +- Focus trap: tab cycling stays within the modal +- Return focus to trigger element on close +- Never stack modals +- Mobile: consider full-screen or bottom sheet instead of centred modal + +### 7. Loading State Patterns + +**Core concept:** Every async operation needs appropriate feedback based on its duration. + +| Duration | Pattern | Example | +|----------|---------|---------| +| < 100ms | No indicator | Direct manipulation (toggle, click) | +| 100-400ms | Subtle indicator | Button state change, micro-animation | +| 400ms-2s | Spinner or skeleton | Content loading, navigation | +| 2-10s | Progress bar + percentage | File upload, data processing | +| > 10s | Progress + status messages | "Generating report... Analysing data..." | + +**Skeleton screens:** +- Mirror the layout of the content being loaded +- Subtle shimmer/pulse animation +- Replace with real content progressively (no flash) +- Better than spinners for content-heavy pages + +### 8. Notification Patterns + +| Type | Persistence | Position | Use case | +|------|-------------|----------|----------| +| **Toast** | Auto-dismiss (3-5s) | Top-right or bottom | Success confirmations, non-critical info | +| **Banner** | Persistent until dismissed | Top of page/section | System messages, warnings | +| **Inline** | Persistent | Next to source element | Validation errors, field-level feedback | +| **Modal** | Requires user action | Centre overlay | Destructive action confirmation | + +**Rules:** +- Success notifications auto-dismiss; errors persist until acknowledged +- Errors always colour-independent (icon + text, not just red colour) +- Stack multiple notifications vertically, don't overlap +- Include an action when recovery is possible ("Undo", "Retry") + +## Pattern Decision Reference + +When choosing between competing patterns, use this table: + +| Decision | Choose A | Choose B | Why | +|----------|----------|----------|-----| +| Hamburger vs visible nav | Visible when space allows | Hamburger on mobile only | Hidden nav reduces discoverability by 50%+ | +| Dropdown vs radio buttons (mobile) | Radio / segmented control | Dropdown only for 10+ options | Dropdowns need 2 taps and hide options | +| Placeholder vs label | Always visible labels | Never placeholder-only | Placeholders disappear (recognition > recall) | +| Modal vs inline | Inline when possible | Modal only for interruption | Modals interrupt flow; require focus management | +| Carousel vs static | Static content | Carousel only for media galleries | < 1% interaction past first slide | +| Infinite scroll vs pagination | Pagination for goal-oriented tasks | Infinite scroll for browsing/feeds | Pagination preserves position and back button | +| Icon-only vs icon + label | Icon + label | Icon-only for universal icons (X, search, home) | Most icons are ambiguous without text | +| Confirm password vs toggle | Show/hide toggle | Never confirm password | Single field + toggle reduces errors | +| Disabled button vs enabled | Enabled + validate on submit | Disabled only with visible explanation | Disabled buttons don't explain what's wrong | +| Skeleton vs spinner | Skeleton for content loading | Spinner for actions (submit, search) | Skeletons reduce perceived wait time | +| Bottom sheet vs modal (mobile) | Bottom sheet for selections/actions | Modal for critical confirmations | Bottom sheets are thumb-friendly and dismissible | +| Tabs vs accordion | Tabs when sections are equal priority | Accordion for progressive disclosure | Tabs show all labels; accordions save space | + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Form labels as placeholders | Labels disappear on focus | Always use visible labels above inputs | +| Multi-column forms | 15-25% slower completion | Use single-column layout | +| Validate while user is still typing | Premature errors frustrate and distract | Validate on blur (when user leaves field) | +| Icon-only navigation without labels | Users can't predict meaning | Add text labels to all navigation icons | +| Equal-weight Cancel and Submit buttons | Users click the wrong one | Primary action gets strong visual weight; secondary gets weak | +| Carousel for important content | < 1% see past first slide | Use static layout or prioritise content | +| Modal for non-critical information | Unnecessary interruption | Use inline content, banners, or tooltips | +| No loading feedback for actions > 400ms | Users think the system is broken | Add spinners, skeletons, or optimistic UI | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Does every page answer "Where am I?" | Missing current location indicator | Add active nav state, breadcrumbs, or page title | +| Do forms use labels above fields (not placeholders)? | Recognition violation | Add persistent labels | +| Is there exactly one primary CTA per view? | Competing actions | Demote secondary actions to outlined/text style | +| Do all async actions show feedback within 400ms? | Doherty violation | Add loading states appropriate to duration | +| Are dropdown menus avoided on mobile? | Hick's Law + friction | Replace with radio buttons or segmented controls | +| Can users dismiss modals with X, Escape, and backdrop click? | Control violation | Add all three dismissal methods | + +## Reference Files + +- [references/scanning-patterns.md](references/scanning-patterns.md) -- F-pattern, Z-pattern, visual weight, and content placement strategies +- [references/navigation-forms.md](references/navigation-forms.md) -- Navigation patterns, form design rules, and validation strategies +- [references/tables-search-loading.md](references/tables-search-loading.md) -- Table design, search patterns, loading states, and notification patterns + +## Further Reading + +- Smashing Magazine: [Responsive Navigation Patterns](https://www.smashingmagazine.com/2017/04/overview-responsive-navigation-patterns/) +- Smashing Magazine: [Mobile Form Design](https://www.smashingmagazine.com/2018/08/best-practices-for-mobile-form-design/) +- Smashing Magazine: [Button Design](https://www.smashingmagazine.com/2016/11/a-quick-guide-for-designing-better-buttons/) +- Nielsen Norman Group: [F-Shaped Reading Pattern](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/) diff --git a/ui-patterns/references/navigation-forms.md b/ui-patterns/references/navigation-forms.md new file mode 100644 index 0000000..c6ab677 --- /dev/null +++ b/ui-patterns/references/navigation-forms.md @@ -0,0 +1,190 @@ +# Navigation & Form Patterns -- Deep Dive + +Detailed guidance for the two highest-impact component categories. + +## Navigation Deep Dive + +### The Three Questions Framework + +Every navigation system must answer: + +| Question | Implementation | Common failure | +|----------|---------------|----------------| +| **"Where am I?"** | Active nav state, breadcrumbs, page title | Responsive nav hides current page indicator | +| **"Where can I go?"** | Visible menu items, category structure | Too many items or hidden behind hamburger | +| **"Where have I been?"** | Visited link state, breadcrumbs, history | No visited state; breadcrumbs missing | + +### Mobile Navigation Patterns + +#### Bottom Tab Bar (3-5 Primary Destinations) + +``` +┌────────────────────────────────┐ +│ │ +│ Page Content │ +│ │ +├──────┬──────┬──────┬──────┬────┤ +│ Home │Search│ Add │ Inbox│ Me │ +│ 🏠 │ 🔍 │ ➕ │ 📥 │ 👤 │ +└──────┴──────┴──────┴──────┴────┘ +``` + +**Rules:** +- Maximum 5 tabs; use "More" for additional destinations +- Icon + label always (never icon-only) +- Active tab visually distinct (colour, weight, fill) +- Centre tab can be elevated for primary action (FAB style) +- Tab labels: 1-2 words maximum + +#### Hamburger Menu (Complex Navigation) + +**When to use:** Mobile viewport with > 5 navigation items or multi-level hierarchy. + +**Rules:** +- Label with "Menu" text alongside the hamburger icon +- Full-screen or drawer overlay (not tiny dropdown) +- Show current page indicator within the expanded menu +- Allow closing via X button, swipe, and backdrop tap +- Animate open/close (slide or fade, 200-300ms) + +#### Pull-to-Refresh + +- Use only for content feeds (timeline, inbox, news) +- Show clear indicator (spinner + "Pull to refresh" text) +- Provide loading feedback during refresh +- Don't use for non-feed content (settings, profiles, forms) + +### Desktop Navigation Patterns + +#### Sidebar Navigation (Apps / Dashboards) + +``` +┌──────────┬────────────────────┐ +│ Logo │ Top Bar / Search │ +├──────────┤ │ +│ Dashboard│ │ +│ Projects │ Main Content │ +│ Team │ │ +│ Settings │ │ +│ │ │ +│ ──────── │ │ +│ Help │ │ +│ Logout │ │ +└──────────┴────────────────────┘ +``` + +**Rules:** +- Collapsible to icons-only for more content space +- Active item clearly highlighted (background colour, left border) +- Group items with dividers or section headers +- Sticky/pinned items at bottom (help, logout, settings) +- Width: 200-280px expanded, 56-72px collapsed + +#### Breadcrumbs + +``` +Home > Products > Electronics > Headphones +``` + +**Rules:** +- All items except the current page are clickable links +- Separator: ">" or "/" (consistent throughout the site) +- Current page in bold or non-linked text +- Don't use for flat site structures (no hierarchy = no breadcrumbs) +- Show on all viewport sizes, not just desktop +- Truncate middle items on mobile: Home > ... > Headphones + +--- + +## Form Design Deep Dive + +### Label Placement Evidence + +| Position | Completion time | Error rate | Best for | +|----------|----------------|------------|----------| +| **Above field** | Fastest | Lowest | All forms (default choice) | +| Left-aligned | Slower (eye movement) | Higher | Dense admin forms | +| Right-aligned | Medium | Medium | Compact horizontal layouts | +| Inside (placeholder) | Varies | Highest | Never (disappears on focus) | + +**Verdict:** Labels above fields is the only universally recommended pattern. + +### Input Field Patterns + +#### Text Input + +```html + + +``` + +- `type` controls validation +- `inputmode` controls mobile keyboard +- `autocomplete` enables browser autofill +- `placeholder` shows format hint (but is NOT a label) + +#### Common Input Types and Keyboards + +| Data | HTML type | inputmode | Keyboard shown | +|------|-----------|-----------|----------------| +| Email | `email` | `email` | @ symbol visible | +| Phone | `tel` | `tel` | Numeric with + | +| Number | `text` | `numeric` | Number pad | +| URL | `url` | `url` | .com shortcut | +| Search | `search` | `search` | Search/Go button | +| Password | `password` | -- | Default with show/hide toggle | +| Currency | `text` | `decimal` | Numbers + decimal | + +**Note:** Use `type="text"` with `inputmode="numeric"` for numbers you don't want browser up/down arrows on (credit cards, PINs). + +### Validation Patterns + +#### Timing + +| When | How | Use for | +|------|-----|---------| +| On blur (leaving field) | Show error below field | Most fields (default) | +| On change (after first error) | Clear error when corrected | Recovery from initial error | +| On submit | Show all errors | Final validation pass | +| Real-time (while typing) | Only for format feedback | Character count, password strength | + +#### Error Message Formula + +**What happened** + **How to fix it** + +| Bad | Good | +|-----|------| +| "Invalid input" | "Email address must include @" | +| "Error in field 3" | "Phone number must be 10 digits" | +| "Required" | "Please enter your first name" | +| "Password too weak" | "Password must include a number and a special character" | + +#### Error Display + +``` +┌─────────────────────────────┐ +│ Email address │ +│ ┌────────────────────────┐ │ +│ │ not-an-email │ │ +│ └────────────────────────┘ │ +│ ⚠ Email must include @ │ +└─────────────────────────────┘ +``` + +**Rules:** +- Error message directly below the field (not in a distant summary) +- Icon + coloured text (never colour alone) +- Field border colour changes (reinforcement, not sole indicator) +- Error message visible without scrolling +- Don't clear the user's input on error + +### Mobile Form Optimisations + +1. **Full-width inputs** -- easier to tap, more typing space +2. **Large touch targets** -- 44px minimum field height +3. **Sticky submit button** -- fixed at bottom on long forms +4. **Section-by-section** -- break long forms into collapsible or stepped sections +5. **Address autocomplete** -- Google Places API or similar +6. **Camera card scanning** -- credit card capture for payment forms +7. **Biometric auth** -- fingerprint / face for login instead of password diff --git a/ui-patterns/references/scanning-patterns.md b/ui-patterns/references/scanning-patterns.md new file mode 100644 index 0000000..6911ade --- /dev/null +++ b/ui-patterns/references/scanning-patterns.md @@ -0,0 +1,139 @@ +# Scanning Patterns -- Deep Dive + +How users visually process web pages and how to design for their scanning behaviour. + +Source: Nielsen Norman Group eye-tracking research, Interaction Design Foundation. + +## The F-Pattern + +### When It Occurs + +The F-pattern emerges under three conditions: +1. Text lacks web formatting (no bolding, bullets, subheadings) +2. Users prioritise efficiency (scanning, not reading) +3. Users lack strong motivation to read every word + +It is the **default** scanning pattern -- the fallback when no visual hierarchy guides the eye. Good design prevents F-pattern scanning by providing clear entry points. + +### Eye-Tracking Findings + +Research shows: +- First lines receive significantly more fixations than subsequent lines +- Initial words on the left of each line get more attention than words further right +- The pattern holds on both desktop and mobile +- In RTL languages (Arabic, Hebrew), the pattern mirrors to a flipped F +- Users skip large chunks of content based on how text flows in a column + +### Eight Techniques to Combat F-Pattern Scanning + +1. **Place the most important points in the first two paragraphs** -- these get the most attention +2. **Use visually prominent headings and subheadings** -- they act as scanning anchors +3. **Start headings with information-carrying words** -- users may see only the first 2-3 words +4. **Visually group related content** with borders, backgrounds, or proximity +5. **Bold critical words and phrases** within body text +6. **Use distinct link styling** with information-bearing words (never "click here") +7. **Use bullets and numbered lists** for sequences and feature lists +8. **Remove unnecessary content** -- every word competes with every other word + +### Content Placement Rules + +| Position | Attention level | Best for | +|----------|----------------|----------| +| Top-left | Highest | Brand, primary heading, most critical info | +| Top horizontal band | High | Headlines, navigation, key message | +| Left edge (vertical) | Medium-high | Headings, bullet starts, labels | +| Right side | Lower | Secondary info, sidebar, ads | +| Below the fold | Low (unless scrolling is encouraged) | Supporting content, details | + +--- + +## The Z-Pattern + +### When to Use + +The Z-pattern applies to pages with minimal text and a clear visual flow: +- Landing pages and hero sections +- Splash screens and app store listings +- Print ads and poster layouts +- Marketing emails (above the fold) + +### The Four Zones + +``` +Zone 1 (top-left) ──────→ Zone 2 (top-right) + ↘ + ↘ + ↘ +Zone 3 (bottom-left) ───→ Zone 4 (bottom-right) +``` + +| Zone | Content to place | Example | +|------|-----------------|---------| +| Zone 1 | Logo, brand mark | Company logo | +| Zone 2 | CTA or key action | "Sign Up Free" button | +| Zone 3 | Key message, value prop | "Build faster with AI" headline | +| Zone 4 | Primary CTA (conversion) | "Start Your Free Trial" button | + +### Repeated Z-Patterns + +Long landing pages use **zig-zag layouts** -- alternating image-left/text-right and text-left/image-right sections: + +``` +[Image] [Text + CTA] +[Text + CTA] [Image] +[Image] [Text + CTA] +``` + +Each row follows a mini Z-pattern, creating a natural reading flow down the page. + +--- + +## Visual Weight + +### What Creates Visual Weight + +Visual weight determines which elements attract the eye first. From strongest to weakest: + +| Factor | How it works | High weight | Low weight | +|--------|-------------|-------------|------------| +| **Size** | Larger = heavier | 48px heading | 14px body text | +| **Contrast** | More contrast = heavier | Dark text on white | Light grey on white | +| **Colour saturation** | Vivid = heavier | Bright red CTA | Muted grey link | +| **Whitespace** | More surrounding space = heavier | Isolated hero heading | Dense paragraph | +| **Density / complexity** | More detail = heavier | Photo or illustration | Solid colour block | +| **Position** | Top and left = heavier (LTR) | Top-left content | Bottom-right content | +| **Imagery** | Faces > objects > text | Portrait photo | Icon | + +### The Three-Level Hierarchy + +Every page needs exactly three distinct visual weight levels: + +| Level | Role | Visual treatment | +|-------|------|-----------------| +| **Dominant** | Single entry point -- what users see first | Largest, highest contrast, most whitespace | +| **Sub-dominant** | Secondary focal points | Medium size, accent colour, moderate contrast | +| **Subordinate** | Supporting content | Body text, muted colours, standard sizing | + +**Critical rule:** Create distinct levels, not a continuum. If users can't tell which level an element belongs to, the hierarchy is too subtle. + +### Visual Weight and Content Priority + +Map visual weight to content importance: + +1. Determine content priority: What must users see first? Second? Third? +2. Assign visual weight: Highest priority gets most weight (dominant level) +3. Create clear separation: Each level must be noticeably different from the others +4. Test by squinting: If you blur the page, can you still identify the three levels? + +### Visual Direction + +Visual direction guides the eye from one element to the next: + +| Technique | How it creates direction | Example | +|-----------|------------------------|---------| +| Lines and arrows | Explicit directional cue | Step connectors, flow diagrams | +| Pointing imagery | People looking / pointing toward content | Person looking at CTA | +| Size gradient | Eye moves from large to small | Hero heading → subheading → body | +| Colour gradient | Eye follows colour intensity | Saturated header → muted body | +| Alignment | Eye follows alignment axis | Left-aligned elements guide downward | +| Whitespace channel | Eye follows the open path | Gutters between columns guide vertical flow | diff --git a/ui-patterns/references/tables-search-loading.md b/ui-patterns/references/tables-search-loading.md new file mode 100644 index 0000000..fcb009b --- /dev/null +++ b/ui-patterns/references/tables-search-loading.md @@ -0,0 +1,258 @@ +# Tables, Search, Loading & Notifications -- Deep Dive + +Patterns for data display, search interfaces, async feedback, and user notifications. + +## Table Patterns + +### Design Rules + +| Rule | Why | Implementation | +|------|-----|----------------| +| Right-align numbers | Easier decimal/digit comparison | `text-align: right` on numeric columns | +| Left-align text | Natural reading direction (LTR) | Default alignment | +| Sticky headers | Column labels stay visible during scroll | `position: sticky; top: 0` | +| Row distinction | Scanability in dense data | Zebra striping OR subtle bottom borders (not both) | +| Sortable columns | User-driven data organisation | Click column header; show sort direction icon | +| Row hover | Help track the eye across wide tables | Subtle background change on `:hover` | + +### Responsive Table Strategies + +| Strategy | How it works | Best for | +|----------|-------------|----------| +| **Horizontal scroll** | Table scrolls horizontally in a container | Complex data tables with many columns | +| **Priority columns** | Show critical columns; hide others behind "expand" | Tables with clear primary/secondary columns | +| **Stacked cards** | Each row becomes a card on mobile | < 20 rows, heterogeneous content | +| **Collapsed rows** | Show summary; expand for full row | Large datasets with detail-on-demand | + +**Rules:** +- Always indicate horizontal scroll (shadow, fade, or partial column visible) +- Never make the table wider than the viewport without scroll indication +- Maintain column header association when stacking (label: value format) +- Keep the primary action column (checkboxes, actions) visible during scroll + +### Data Table Interactions + +| Feature | When to include | How | +|---------|----------------|-----| +| **Sort** | Any tabular data | Click column header; toggle asc/desc; show arrow | +| **Filter** | > 20 rows | Filter controls above table; show active filter count | +| **Search** | > 50 rows | Search input above table; highlight matching text | +| **Pagination** | > 25-50 rows | Below table; show total count; adjustable page size | +| **Select / bulk actions** | Admin interfaces | Checkboxes on rows; floating action bar on selection | +| **Inline edit** | Frequently updated data | Click cell to edit; save on blur or explicit action | +| **Export** | Analytics, reporting | Button above table; CSV/Excel format options | + +--- + +## Search Patterns + +### Core Search UI + +``` +┌──────────────────────────────────┐ +│ 🔍 Search products... │ +├──────────────────────────────────┤ +│ Recent searches │ +│ • blue running shoes │ +│ • wireless headphones │ +├──────────────────────────────────┤ +│ Suggested │ +│ • bluetooth speaker │ +│ • bluetooth headphones │ +└──────────────────────────────────┘ +``` + +### Search Design Rules + +| Rule | Why | Implementation | +|------|-----|----------------| +| Prominent placement | Users expect to find search easily | Top of page, centred or right-aligned | +| Magnifying glass icon | Universal search signifier | Icon inside or beside input | +| Autocomplete / suggestions | Recognition over recall | Debounced suggestions (200-300ms after typing stops) | +| Preserve query | Users need to modify searches | Keep search text in input after results load | +| Result count | Orientation and expectation setting | "Showing 12 of 156 results" | +| No-results state | Prevent dead ends | Show suggestions, categories, or contact support | +| Recent searches | Recognition over recall | Show on focus before typing begins | + +### Search Result Design + +| Element | Purpose | Rules | +|---------|---------|-------| +| Title | Primary match identifier | Bold, clickable, highlight matching terms | +| Snippet | Context for the match | 1-2 lines, highlight matching terms in context | +| URL / path | Location context | Muted, truncated, shows hierarchy | +| Metadata | Secondary info | Date, author, category -- muted styling | +| Image | Visual recognition | Thumbnail if available | +| Action | Direct interaction | "Add to cart", "Open", "Preview" | + +### Null State Design + +When search returns no results: + +1. **Acknowledge** the search: "No results for 'xyzzy'" +2. **Check spelling**: "Did you mean 'xyz'?" +3. **Suggest alternatives**: "Try these popular searches..." +4. **Offer help**: "Browse categories" or "Contact support" +5. **Never show an empty page** with no guidance + +--- + +## Loading State Patterns + +### The Loading Decision Tree + +``` +Duration known? +├── Yes → Determinate progress bar (percentage, steps) +└── No + ├── Duration < 400ms → No indicator needed + ├── Duration 400ms-2s → Indeterminate spinner or skeleton + └── Duration > 2s → Spinner + status text ("Loading messages...") +``` + +### Skeleton Screen Design + +Skeleton screens are grey placeholder blocks that mirror the layout of the content being loaded. + +**Rules:** +1. **Match the layout exactly** -- skeleton should be indistinguishable from content at a glance +2. **Use subtle animation** -- shimmer (left-to-right gradient) or pulse (opacity animation) +3. **Replace progressively** -- content appears section by section, not all at once +4. **Don't flash** -- if content loads in < 300ms, don't show skeleton (show nothing instead) + +**Skeleton block styling:** +- Background: neutral grey (`#e0e0e0` or equivalent) +- Border radius: match the content it represents (rounded for avatars, straight for text) +- Height: match the content height (don't collapse or expand when real content loads) +- Animation: 1.5-2s cycle, ease-in-out + +### Progress Bar Design + +| Type | When to use | Implementation | +|------|-------------|----------------| +| **Determinate** | Known total (file upload, multi-step) | Show percentage + progress fill | +| **Indeterminate** | Unknown duration | Animated bar moving back and forth | +| **Stepped** | Multi-step process | "Step 2 of 4" with segmented bar | +| **Circular** | Compact spaces | Circular progress ring (e.g., upload thumbnail) | + +**Progress bar rules:** +- Start with initial progress (5-10%) -- a bar at 0% feels stuck +- Non-linear perceived speed: faster at the start, slower near the end feels right +- Include percentage text for long operations +- Status messages for operations > 5s ("Processing payment...", "Generating report...") +- Allow cancellation for operations > 2s + +### Optimistic UI + +Show the result immediately. Sync in the background. Roll back only on failure. + +**Pattern:** + +``` +User clicks "Like" → + 1. Immediately: heart fills, count increments + 2. Background: API call to save + 3a. Success: no visible change (already shown) + 3b. Failure: heart unfills, count decrements, show toast error +``` + +**Candidates for optimistic UI:** +- Likes, follows, bookmarks (high success rate, low stakes) +- Message sending (show in chat immediately) +- Settings toggles (apply immediately) +- Adding to cart (show badge immediately) + +**Not candidates:** +- Payment processing +- Account deletion +- Publishing content (moderation required) +- File uploads (need actual transfer) + +--- + +## Notification Patterns + +### Notification Types + +#### Toast Notifications + +``` +┌──────────────────────────────┐ +│ ✓ Message sent successfully │ ← Auto-dismiss: 3-5 seconds +│ [Undo] │ ← Optional action +└──────────────────────────────┘ +``` + +**Rules:** +- Auto-dismiss after 3-5 seconds for success messages +- Position: top-right (desktop) or top-centre (mobile) +- Stack vertically if multiple appear +- Include undo action for reversible operations +- Never use for errors (errors must persist) + +#### Banner Notifications + +``` +┌──────────────────────────────────────────┐ +│ ⚠ Your subscription expires in 3 days. │ +│ [Renew] [✕] │ +└──────────────────────────────────────────┘ +``` + +**Rules:** +- Persistent until user dismisses or takes action +- Full-width, top of page or section +- Include clear action button and dismiss (X) +- Colour-coded: info (blue), warning (yellow), error (red), success (green) +- Maximum 2 banners visible simultaneously + +#### Inline Feedback + +``` +┌─────────────────────────────┐ +│ Email address │ +│ ┌────────────────────────┐ │ +│ │ not-valid │ │ +│ └────────────────────────┘ │ +│ ⚠ Email must include @ │ ← Inline, next to source +└─────────────────────────────┘ +``` + +**Rules:** +- Appears directly below or beside the source element +- Persistent until the issue is resolved +- Icon + text (never colour alone) +- Field border colour changes as reinforcement + +### Notification Stacking + +When multiple notifications appear simultaneously: + +1. Stack vertically with 8px gap +2. Newest on top (or bottom, but be consistent) +3. Maximum 3 visible at once; queue additional +4. Each independently dismissible +5. "Dismiss all" option when > 2 visible + +### Empty States + +Empty states are a type of notification -- they tell users "there's nothing here yet": + +**Required elements:** +1. Clear explanation of what would appear here +2. Visual (illustration or icon) to prevent the page from feeling broken +3. Action to resolve the empty state ("Create your first project") +4. Optional: link to help/documentation + +``` +┌──────────────────────────────────────┐ +│ │ +│ 📂 No projects yet │ +│ │ +│ Create your first project to │ +│ get started. │ +│ │ +│ [ Create Project ] │ +│ │ +└──────────────────────────────────────┘ +```