commit 0ac522161187c85f5c0225986797c21a18feb136 Author: zlei9 Date: Sun Mar 29 14:33:27 2026 +0800 Initial commit with translated description diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..151b67d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,39 @@ +# UI Audit Framework + +A comprehensive UI design decision-making framework. Use for rapid, intentional interface design. + +## When to Use + +- Making UI/UX design decisions under time pressure +- Evaluating design trade-offs with business context +- Choosing appropriate UI patterns for specific problems +- Reviewing designs for completeness and quality + +## Core Process + +1. **Weigh Information** — Institutional knowledge → User familiarity → Research +2. **Narrow Options** — Eliminate conflicts, prioritize by macro bet alignment +3. **Execute** — Apply relevant checklist + patterns + +## Reference Files + +Load as needed: + +| Category | File | +|----------|------| +| Core Framework | `references/00-core-framework.md` | +| New Interfaces | `references/10-checklist-new-interfaces.md` | +| Fidelity | `references/11-checklist-fidelity.md` | +| Visual Style | `references/12-checklist-visual-style.md` | +| Visual Hierarchy | `references/23-patterns-visual-hierarchy.md` | +| Social Proof | `references/24-patterns-social-proof.md` | +| Navigation | `references/31-patterns-navigation.md` | + +## Macro Bets + +| Bet | Design Implication | +|-----|-------------------| +| **Velocity** | Reuse patterns, find metaphors | +| **Efficiency** | Design systems, reduce WIP | +| **Accuracy** | Stronger research, instrumentation | +| **Innovation** | Novel patterns, cross-domain inspiration | diff --git a/README.md b/README.md new file mode 100644 index 0000000..a78b399 --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +

+ + + + UI Audit + +

+ +

+ AI skill for automated UI audits
+ Evaluate interfaces against proven UX principles. +

+ +

+ Guidelines • + ClawdHub • + npm +

+ +--- + +## What is this? + +A skill that gives AI assistants the ability to perform structured UI audits. Based on [Making UX Decisions](https://uxdecisions.com) by Tommy Geoco. + +**Audits include:** +- Visual hierarchy & typography +- Visual style & spacing +- Accessibility & contrast +- Navigation & wayfinding +- Cognitive load & information architecture +- Social proof & trust signals +- Onboarding & empty states + +## Installation + +```bash +# Agent Skills (Vercel) +npx skills add uxtools/ui-audit + +# ClawdHub +clawdhub install ui-audit + +# npm +npm install ui-audit +``` + +## Usage + +Ask your AI assistant: + +``` +Audit this design: [figma-url] +Review this landing page for accessibility issues +What visual hierarchy patterns should I use for a pricing page? +``` + +## What's Included + +``` +ui-audit/ +├── SKILL.md # Main skill instructions +├── CLAUDE.md # Claude-specific quick reference +└── references/ + ├── 00-core-framework.md # Decision-making process + ├── 10-checklist-*.md # Execution checklists + └── 2*-patterns-*.md # UI pattern libraries +``` + +## Guidelines + +View the full list of principles at **[audit.uxtools.co](https://audit.uxtools.co)** + +### Decisioning +- Weigh information in order: Institutional knowledge → User familiarity → Research +- Align every decision with macro bets: Velocity, Efficiency, Accuracy, or Innovation +- Define jobs-to-be-done first + +### Visual Hierarchy +- Primary action is obvious within 3 seconds +- 2:1 ratio minimum between heading levels +- Related items are grouped (Law of Proximity) + +### Accessibility +- Keyboard works everywhere +- Focus is always visible +- Color is not the only indicator + +[View all guidelines →](https://audit.uxtools.co) + +## Author + +**[Tommy Geoco](https://x.com/designertom)** — [uxtools.co](https://uxtools.co) • [uxdecisions.com](https://uxdecisions.com) + +## License + +MIT diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..1f3b2fe --- /dev/null +++ b/SKILL.md @@ -0,0 +1,181 @@ +--- +name: ui-audit +description: "用于自动化UI审计的AI技能。" +author: Tommy Geoco +homepage: https://audit.uxtools.co +logo: logo-light.png +logoDark: logo-dark.png +--- + +# UI Audit Skill + +Evaluate interfaces against proven UX principles. Based on [Making UX Decisions](https://uxdecisions.com) by Tommy Geoco. + +## When to Use This Skill + +- Making UI/UX design decisions under time pressure +- Evaluating design trade-offs with business context +- Choosing appropriate UI patterns for specific problems +- Reviewing designs for completeness and quality +- Structuring design thinking for new interfaces + +## Core Philosophy + +**Speed ≠ Recklessness.** Designing quickly is not automatically reckless. Recklessly designing quickly is reckless. The difference is intentionality. + +## The 3 Pillars of Warp-Speed Decisioning + +1. **Scaffolding** — Rules you use to automate recurring decisions +2. **Decisioning** — Process you use for making new decisions +3. **Crafting** — Checklists you use for executing decisions + +## Quick Reference Structure + +### Foundational Frameworks +- `references/00-core-framework.md` — 3 pillars, decisioning workflow, macro bets +- `references/01-anchors.md` — 7 foundational mindsets for design resilience +- `references/02-information-scaffold.md` — Psychology, economics, accessibility, defaults + +### Checklists (Execution) +- `references/10-checklist-new-interfaces.md` — 6-step process for designing new interfaces +- `references/11-checklist-fidelity.md` — Component states, interactions, scalability, feedback +- `references/12-checklist-visual-style.md` — Spacing, color, elevation, typography, motion +- `references/13-checklist-innovation.md` — 5 levels of originality spectrum + +### Patterns (Reusable Solutions) +- `references/20-patterns-chunking.md` — Cards, tabs, accordions, pagination, carousels +- `references/21-patterns-progressive-disclosure.md` — Tooltips, popovers, drawers, modals +- `references/22-patterns-cognitive-load.md` — Steppers, wizards, minimalist nav, simplified forms +- `references/23-patterns-visual-hierarchy.md` — Typography, color, whitespace, size, proximity +- `references/24-patterns-social-proof.md` — Testimonials, UGC, badges, social integration +- `references/25-patterns-feedback.md` — Progress bars, notifications, validation, contextual help +- `references/26-patterns-error-handling.md` — Form validation, undo/redo, dialogs, autosave +- `references/27-patterns-accessibility.md` — Keyboard nav, ARIA, alt text, contrast, zoom +- `references/28-patterns-personalization.md` — Dashboards, adaptive content, preferences, l10n +- `references/29-patterns-onboarding.md` — Tours, contextual tips, tutorials, checklists +- `references/30-patterns-information.md` — Breadcrumbs, sitemaps, tagging, faceted search +- `references/31-patterns-navigation.md` — Priority nav, off-canvas, sticky, bottom nav + +## Usage Instructions + +### For Design Decisions +1. Read `00-core-framework.md` for the decisioning workflow +2. Identify if this is a recurring decision (use scaffold) or new decision (use process) +3. Apply the 3-step weighing: institutional knowledge → user familiarity → research + +### For New Interfaces +1. Follow the 6-step checklist in `10-checklist-new-interfaces.md` +2. Reference relevant pattern files for specific UI components +3. Use fidelity and visual style checklists to enhance quality + +### For Pattern Selection +1. Identify the core problem (chunking, disclosure, cognitive load, etc.) +2. Load the relevant pattern reference +3. Evaluate benefits, use cases, psychological principles, and implementation guidelines + +## Decision Workflow Summary + +When facing a UI decision: + +``` +1. WEIGH INFORMATION + ├─ What does institutional knowledge say? (existing patterns, brand, tech constraints) + ├─ What are users familiar with? (conventions, competitor patterns) + └─ What does research say? (user testing, analytics, studies) + +2. NARROW OPTIONS + ├─ Eliminate what conflicts with constraints + ├─ Prioritize what aligns with macro bets + └─ Choose based on JTBD support + +3. EXECUTE + └─ Apply relevant checklist + patterns +``` + +## Macro Bet Categories + +Companies win through one or more of: + +| Bet | Description | Design Implication | +|-----|-------------|-------------------| +| **Velocity** | Features to market faster | Reuse patterns, find metaphors in other markets | +| **Efficiency** | Manage waste better | Design systems, reduce WIP | +| **Accuracy** | Be right more often | Stronger research, instrumentation | +| **Innovation** | Discover untapped potential | Novel patterns, cross-domain inspiration | + +Always align micro design bets with company macro bets. + +## Key Principle: Good Design Decisions Are Relative + +A design decision is "good" when it: +- Supports the product's jobs-to-be-done +- Aligns with company macro bets +- Respects constraints (time, tech, team) +- Balances user familiarity with differentiation needs + +There is no universally correct UI solution—only contextually appropriate ones. + +--- + +## Generating Audit Reports + +When asked to audit a design, generate a comprehensive report. Always include these sections: + +### Required Sections (always include) +1. **Visual Hierarchy** — Headings, CTAs, grouping, reading flow, type scale, color hierarchy, whitespace +2. **Visual Style** — Spacing consistency, color usage, elevation/depth, typography, motion/animation +3. **Accessibility** — Keyboard navigation, focus states, contrast ratios, screen reader support, touch targets + +### Contextual Sections (include when relevant) +4. **Navigation** — For multi-page apps: wayfinding, breadcrumbs, menu structure, information architecture +5. **Usability** — For interactive flows: discoverability, feedback, error handling, cognitive load +6. **Onboarding** — For new user experiences: first-run, tutorials, progressive disclosure +7. **Social Proof** — For landing/marketing pages: testimonials, trust signals, social integration +8. **Forms** — For data entry: labels, validation, error messages, field types + +### Audit Output Format + +```json +{ + "title": "Design Name — Screen/Flow", + "project": "Project Name", + "date": "YYYY-MM-DD", + "figma_url": "optional", + "screenshot_url": "optional - URL to screenshot", + + "macro_bets": [ + { "category": "velocity|efficiency|accuracy|innovation", "description": "...", "alignment": "strong|moderate|weak" } + ], + + "jtbd": [ + { "user": "User Type", "situation": "context without 'When'", "motivation": "goal without 'I want to'", "outcome": "benefit without 'so I can'" } + ], + + "visual_hierarchy": { + "title": "Visual Hierarchy", + "checks": [ + { "label": "Check name", "status": "pass|warn|fail|na", "notes": "Details" } + ] + }, + "visual_style": { ... }, + "accessibility": { ... }, + + "priority_fixes": [ + { "rank": 1, "title": "Fix title", "description": "What and why", "framework_reference": "XX-filename.md → Section Name" } + ], + + "notes": "Optional overall observations" +} +``` + +### Checks Per Section (aim for 6-10 each) + +**Visual Hierarchy**: heading distinction, primary action clarity, grouping/proximity, reading flow, type scale, color hierarchy, whitespace usage, visual weight balance + +**Visual Style**: spacing consistency, color palette adherence, elevation/shadows, typography system, border/radius consistency, icon style, motion principles + +**Accessibility**: keyboard operability, visible focus, color contrast (4.5:1), touch targets (44px), alt text, semantic markup, reduced motion support + +**Navigation**: clear current location, predictable menu behavior, breadcrumb presence, search accessibility, mobile navigation pattern + +**Usability**: feature discoverability, feedback on actions, error prevention, recovery options, cognitive load management, loading states diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..6466861 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn77js9mymrx3mfbzwyre847ex7zdnhj", + "slug": "ui-audit", + "version": "1.0.1", + "publishedAt": 1768701211826 +} \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..6bb5c8c --- /dev/null +++ b/package.json @@ -0,0 +1,40 @@ +{ + "name": "ui-audit", + "version": "1.0.1", + "description": "AI skill for automated UI audits. Evaluate interfaces against proven UX principles for visual hierarchy, accessibility, cognitive load, and more. Based on Making UX Decisions by Tommy Geoco.", + "keywords": [ + "ux", + "design", + "ui", + "audit", + "checklist", + "ai-skill", + "claude", + "codex", + "clawdbot", + "ui-audit", + "accessibility", + "visual-hierarchy" + ], + "author": "Tommy Geoco (https://uxtools.co)", + "license": "MIT", + "homepage": "https://audit.uxtools.co", + "repository": { + "type": "git", + "url": "https://github.com/tommygeoco/ui-audit" + }, + "files": [ + "SKILL.md", + "CLAUDE.md", + "references/" + ], + "exports": { + ".": "./SKILL.md", + "./skill": "./SKILL.md", + "./claude": "./CLAUDE.md", + "./references/*": "./references/*" + }, + "scripts": { + "postinstall": "echo '\\n📖 UI Audit skill installed. Add to your project:\\n - Clawdbot: Copy to ~/clawd/skills/ui-audit/\\n - Claude: Copy CLAUDE.md to your project root\\n'" + } +} diff --git a/references/00-core-framework.md b/references/00-core-framework.md new file mode 100644 index 0000000..67e1a9c --- /dev/null +++ b/references/00-core-framework.md @@ -0,0 +1,140 @@ +# Core Framework: Warp-Speed Decisioning + +## The 3 Pillars + +### 1. Scaffolding +Rules that automate recurring decisions. Pre-made defaults so you don't re-decide the same things. + +**Components:** +- Design psychology reference (laws, principles) +- Economics fundamentals (market forces) +- Accessibility reference (WCAG/POUR) +- Default typefaces and type scale +- Icon library choice +- Design system reference +- Default design rules + +### 2. Decisioning +Process for making new decisions when scaffolds don't apply. + +**Workflow:** +1. Inform simplicity — gather minimum viable context +2. Narrow options — eliminate conflicts, prioritize alignment +3. Weigh information — institutional knowledge → familiarity → research +4. Arrive at decision — commit and document reasoning + +### 3. Crafting +Checklists for executing decisions consistently. + +**Types:** +- Checklists for new interfaces +- Checklists for improving fidelity +- Checklists for visual style +- Checklists for innovation + +--- + +## The Decisioning Workflow (Detail) + +### Step 1: What Does Institutional Knowledge Say? + +Institutional knowledge = existing patterns, brand guidelines, tech stack, team capabilities, business constraints. + +**Questions:** +- Does an existing component/pattern solve this? +- What does our design system prescribe? +- What are our technical constraints? +- What has leadership/stakeholders indicated? + +**Rule:** Always check internal resources before external inspiration. + +### Step 2: What Are Users Familiar With? + +User familiarity = conventions from similar products, learned behaviors, competitor patterns. + +**Questions:** +- What do competitors do for this pattern? +- What's the platform convention (iOS/Android/Web)? +- What prior experience do users bring? +- Jakob's Law: Users spend most time on *other* sites + +**Rule:** Familiarity reduces cognitive load. Novelty requires justification. + +### Step 3: What Does Research Say? + +Research = user testing, analytics, academic studies, heuristic evaluation. + +**Questions:** +- Do we have usability data on this pattern? +- What does instrumentation tell us? +- Are there published studies on this interaction? +- Have we tested this with users? + +**Rule:** Research trumps opinion, but absence of research ≠ decision paralysis. + +### Arriving at a Decision + +After weighing all three sources: +1. If clear winner exists → choose it +2. If conflict exists → prioritize by macro bet alignment +3. If uncertainty remains → choose fastest to validate, plan to learn + +**Document your reasoning.** Future you (and teammates) will thank you. + +--- + +## Staging Your Bets + +### Why Bets Matter + +Every design decision is a bet. You're wagering time and resources on an outcome. The question is whether you're betting intentionally or accidentally. + +### Macro vs. Micro Bets + +**Macro bets** = Company-level strategic bets on how to win the market +**Micro bets** = Individual design decisions within an interface + +**Critical Rule:** Micro bets are only valid when intentionally supporting macro bets. + +### The 4 Categories of Macro Bets + +| Category | We win by... | Design implications | +|----------|--------------|---------------------| +| **Velocity** | Getting features to market faster | Reduce time-to-delivery, reuse components, find metaphors in other markets | +| **Efficiency** | Managing waste better | Design systems, reuse patterns, reduce WIP | +| **Accuracy** | Being right more frequently | Stronger research, measure with instrumentation, discovery sprints | +| **Innovation** | Discovering untapped market potential | Uncover "fog of war" with better discovery, find parallels in other markets | + +### How to Stage Your Bets + +1. **Analyze your industry** — Level of competition, market maturity, disruption threats +2. **Analyze competitors** — Leading vs. lagging, their bets, their gaps +3. **Define customer goals** — Jobs-to-be-done statements +4. **Name your bets** — Explicit statements of what you're betting on and why + +### Jobs-to-be-Done (JTBD) Format + +``` +When [situation], +I want to [motivation], +So I can [desired outcome]. +``` + +**Good JTBD:** "When I get emails, I want to organize them so I don't lose important information." + +**Bad JTBD:** "Let me add tags, labels, and folders to my email so I can sort things according to my system." + +The difference: Good JTBD focuses on outcome, bad focuses on feature. + +--- + +## Informing Simplicity + +Before diving into design: + +1. **Define 2-3 primary JTBD** — What are users trying to accomplish? +2. **Identify your macro bets** — Which category is the company prioritizing? +3. **Understand your constraints** — Time, team, tech, budget +4. **Know your competition** — Where are they winning/losing? + +**Author's Note:** Do this fast or don't do it at all. Don't get stuck whiteboarding JTBD. Trust your intuition. The goal is informed speed, not perfect analysis. diff --git a/references/01-anchors.md b/references/01-anchors.md new file mode 100644 index 0000000..8ff35b5 --- /dev/null +++ b/references/01-anchors.md @@ -0,0 +1,190 @@ +# The 7 Anchors: Foundational Mindsets + +Anchors are mental models and principles that form your foundation. They keep you grounded when product development gets chaotic. + +## Why Anchors Matter + +1. **Clarity in chaos** — Quickly align decisions with core values when juggling priorities +2. **Confidence** — Make bold decisions under pressure +3. **Resilience** — Bounce back from setbacks +4. **Growth** — Framework for continuous learning (anchors evolve with you) + +--- + +## Anchor 1: Pursue Your Purpose + +**What:** Connect your work to a larger purpose. Inspired by Ikigai (reason for being). + +**The 4 Elements:** +- What you love +- What you're good at +- What the world needs +- What you can be paid for + +**When to rely on it:** +- Deciding which projects to take on +- Feeling unfulfilled or burnt out +- Prioritizing features or initiatives +- Considering career moves + +**How to apply:** +- Define a personal mission statement +- Evaluate projects against the 4 elements +- Prioritize purpose-aligned work +- Connect even mundane tasks to larger goals +- Regularly reflect on alignment + +--- + +## Anchor 2: Embrace the Marathon Mindset + +**What:** Product design is a long game, not a sprint. Sustainable pace beats heroic bursts. + +**Key principles:** +- Burnout is a feature, not a bug, of unsustainable work +- Small consistent progress compounds +- Recovery is part of the work +- Career success is measured in decades, not sprints + +**When to rely on it:** +- Facing unrealistic deadlines +- Tempted to sacrifice quality for speed +- Building habits and systems +- Evaluating trade-offs with long-term consequences + +**How to apply:** +- Protect your energy and attention +- Build systems, not just outputs +- Say no to protect yes +- Invest in learning that compounds + +--- + +## Anchor 3: Be Intentional + +**What:** Every design decision should be traceable to a reason. Accidental design is reckless design. + +**Intentionality spectrum:** +- Unconscious incompetence (don't know what you don't know) +- Conscious incompetence (know gaps, learning) +- Conscious competence (deliberate, effortful mastery) +- Unconscious competence (intuitive mastery) + +**When to rely on it:** +- Making any design decision +- Explaining choices to stakeholders +- Reviewing others' work +- Feeling autopilot taking over + +**How to apply:** +- Document your reasoning +- Challenge "it's always been done this way" +- Ask "why this choice?" for every element +- Build decision logs + +--- + +## Anchor 4: Embrace Your Unique Perspective + +**What:** Your specific combination of experiences, skills, and viewpoints is an asset, not a liability. + +**Key insight:** The industry doesn't need more average designers. It needs your particular blend of weird. + +**When to rely on it:** +- Feeling imposter syndrome +- Comparing yourself to others +- Deciding what to learn next +- Positioning yourself professionally + +**How to apply:** +- Identify your unique combination of skills +- Lean into interests others find "off-topic" +- Share your perspective, especially when different +- Build on strengths rather than only fixing weaknesses + +--- + +## Anchor 5: Practice Just-in-Time Learning + +**What:** Learn what you need when you need it, not in advance "just in case." + +**Why it matters:** +- Knowledge decays without application +- The field changes faster than curricula +- Context makes learning stick +- You can't pre-learn everything + +**When to rely on it:** +- Feeling overwhelmed by what you "should" know +- Deciding what to learn next +- Facing an unfamiliar problem +- Evaluating courses/resources + +**How to apply:** +- Learn in response to real problems +- Apply immediately after learning +- Maintain a "learn when needed" list vs. "learn someday" list +- Trust your ability to figure things out + +--- + +## Anchor 6: Challenge Assumptions + +**What:** Actively question what "everyone knows" and what you've always believed. + +**Common assumption traps:** +- "Users would never..." +- "That's just how it's done..." +- "The data shows..." (but does it really?) +- "We tried that and it didn't work" (in what context?) + +**When to rely on it:** +- Inheriting existing designs +- Hearing "we've always done it this way" +- Receiving secondhand user feedback +- Feeling certain about something unvalidated + +**How to apply:** +- Ask "what would have to be true for this assumption to be false?" +- Seek disconfirming evidence, not just confirming +- Run cheap experiments before committing +- Distinguish observation from interpretation + +--- + +## Anchor 7: Two Truths Exist + +**What:** Seemingly contradictory ideas can both be true simultaneously. Embrace paradox instead of forcing false choices. + +**Examples:** +- Design can be both fast AND thoughtful +- Simplicity requires complexity in implementation +- User needs AND business needs can coexist +- Convention AND innovation both have value +- Data AND intuition are both valid inputs + +**When to rely on it:** +- Facing "either/or" framing +- Mediating stakeholder conflicts +- Feeling stuck between opposing ideas +- Making trade-off decisions + +**How to apply:** +- Reframe "or" as "and" — how might both be true? +- Look for higher-order solutions that satisfy multiple constraints +- Accept tension as feature, not bug +- Avoid premature resolution of ambiguity + +--- + +## Using Anchors in Practice + +**Before a project:** Review relevant anchors, set intentions + +**During pressure:** Pause, identify which anchor applies, act accordingly + +**After setbacks:** Return to anchors to regain footing + +**Periodically:** Reflect on how your anchors are evolving + +Anchors aren't rules to follow—they're foundations to build on. diff --git a/references/02-information-scaffold.md b/references/02-information-scaffold.md new file mode 100644 index 0000000..d590df6 --- /dev/null +++ b/references/02-information-scaffold.md @@ -0,0 +1,204 @@ +# Information Scaffold: Psychology, Economics, Accessibility, Defaults + +Your scaffold = pre-made decisions for recurring situations. Build once, reuse forever. + +--- + +## Design Psychology Reference + +Psychological principles categorized by the problem they solve: + +### Filtering (Helping users focus) + +| Principle | Definition | Application | +|-----------|------------|-------------| +| **Hick's Law** | More options = harder decisions | Reduce choices, progressive disclosure | +| **Law of Proximity** | Close objects perceived as related | Group related items spatially | +| **Law of Similarity** | Visually similar elements perceived as related | Consistent styling for related items | +| **Nudging** | Subtle cues influence behavior | Defaults, visual emphasis, copy | +| **Priming** | Cues influence decision-making | Strategic first impressions, context setting | +| **Progressive Disclosure** | Reveal information gradually | Hide complexity until needed | +| **Tesler's Law** | Complexity must exist somewhere | Absorb complexity in design, not user's head | +| **Von Restorff Effect** | Distinctive items remembered | Make key actions visually distinct | + +### Sense-making (Helping users understand) + +| Principle | Definition | Application | +|-----------|------------|-------------| +| **Chunking** | Group info into digestible units | Cards, sections, tabs | +| **Cognitive Load Theory** | Working memory is limited | Minimize extraneous info | +| **Jakob's Law** | Users expect your site to work like others | Follow conventions | +| **Law of Common Region** | Fenced objects perceived as related | Use containers, borders | +| **Law of Prägnanz** | Simpler objects easier to process | Reduce visual complexity | +| **Law of Uniform Connectedness** | Connected elements perceived as related | Use lines, shared containers | +| **Occam's Razor** | Prefer simpler explanations | Simplify UI and messaging | +| **Social Proof** | People conform to observed behavior | Testimonials, user counts | + +### Efficiency (Helping users act faster) + +| Principle | Definition | Application | +|-----------|------------|-------------| +| **Fitt's Law** | Larger, closer targets faster to hit | Size CTAs appropriately, reduce distance | +| **Goal Gradient Effect** | Motivation increases near goal completion | Progress indicators, milestone celebrations | +| **Hyperbolic Discounting** | Immediate rewards valued higher | Quick wins, instant feedback | +| **IKEA Effect** | People value what they helped create | Customization, personalization | +| **Investment Loops** | Engagement increases with investment | Progressive commitment | +| **Pareto Principle** | 80% of effects from 20% of causes | Optimize critical paths | +| **Parkinson's Law** | Work expands to fill time available | Set clear scope, deadlines | +| **Second-Order Effects** | Consequences have consequences | Consider downstream impact | +| **Sunk Cost Effect** | Continued investment despite poor returns | Beware over-commitment | +| **Weber's Law** | Large changes more noticeable | Meaningful differences in UI states | + +### Recall (Helping users remember) + +| Principle | Definition | Application | +|-----------|------------|-------------| +| **Fresh Start Effect** | Motivation at new beginnings | Leverage time-based resets | +| **Miller's Law** | 7±2 items in short-term memory | Chunk information | +| **Peak-End Rule** | Experiences judged by peak and end | Design strong endings | +| **Picture Superiority Effect** | Images more memorable than text | Use visuals for key info | +| **Serial Position Effect** | First/last items most memorable | Place key items at start/end | +| **Zeigarnik Effect** | Incomplete tasks remembered more | Use incomplete states strategically | + +--- + +## Economics Fundamentals + +Design decisions have business implications. Know these concepts: + +| Concept | Definition | Design Implication | +|---------|------------|-------------------| +| **Economies of Scale** | More production = lower unit cost | Reusable components pay dividends at scale | +| **Opportunity Cost** | What you give up by choosing | Every design choice excludes alternatives | +| **Time Value of Money** | Money now > money later | Ship valuable features sooner | +| **Supply & Demand** | Scarcity drives price | Exclusive features, limited access can increase perceived value | +| **Zero Marginal Cost** | Digital copies cost nothing extra | Design for scale, not scarcity | +| **Network Effects** | Value increases with users | Prioritize collaboration, sharing features | +| **Diseconomies of Scale** | Too big = inefficient | Complexity costs increase; keep systems manageable | +| **Economies of Scope** | Cheaper to do multiple things together | Shared components across products | +| **Veblen Goods** | Higher price = higher demand (luxury) | Premium positioning affects design choices | +| **Invisible Hand** | Markets self-regulate | User choice will surface winners | + +--- + +## Accessibility Reference (POUR) + +WCAG's four principles. Accessibility is not optional. + +### Perceivable +- Text alternatives for non-text content +- Captions/transcripts for multimedia +- User can change presentation +- Content easier to see and hear + +### Operable +- All functionality accessible via keyboard +- Users have enough time to read/use content +- No seizure-inducing content +- Easy navigation and content finding +- Input modalities beyond keyboard + +### Understandable +- Text and UI readable and understandable +- Content operates in predictable ways +- Help users avoid and correct mistakes + +### Robust +- Compatible with browsers and assistive tech +- Valid markup + +**Minimum baseline:** 4.5:1 contrast ratio for text, focus indicators, alt text, semantic HTML. + +--- + +## Default Typefaces + +Choose one neutral sans-serif to start. Add personality later. + +**Recommended starting typefaces:** +- Inter +- Nunito Sans +- Mona Sans +- SF Pro (Apple ecosystem) +- Segoe UI (Microsoft ecosystem) + +### Default Type Scale + +Start with 16px base (browser default). Use this scale: + +| Size | Use | +|------|-----| +| 12px | Captions, labels, metadata | +| 14px | Secondary text, descriptions | +| 16px | Body text (base) | +| 18px | Large body, intro text | +| 20px | Small headings | +| 24px | Section headings | +| 30px | Page headings | +| 36px | Feature headings | +| 48px | Hero headings | +| 60px+ | Display text | + +--- + +## Default Design Rules + +Establish these defaults to avoid re-deciding: + +### Spacing +- Base unit: 8px +- Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96 +- Use consistent rhythm + +### Colors +- One primary action color +- One or two neutral grays +- Semantic colors: error (red), success (green), warning (yellow), info (blue) +- Ensure contrast ratios + +### Icons +Pick one library and stick to it: +- Feather Icons (minimal) +- Heroicons (Tailwind) +- Phosphor Icons (flexible) +- Material Icons (comprehensive) + +### Radius +- Consistent border-radius across components +- Common: 4px (subtle), 8px (soft), 16px+ (rounded) + +### Shadows/Elevation +- 3-4 levels of elevation +- Consistent shadow direction +- Use for layering, not decoration + +--- + +## Atomic Design Principles + +Design systems built on composition: + +1. **Atoms** — Basic elements (buttons, inputs, labels) +2. **Molecules** — Simple component groups (search box = input + button) +3. **Organisms** — Complex components (header, card grid) +4. **Templates** — Page layouts without content +5. **Pages** — Templates with real content + +Build from small to large. Composition enables reuse. + +--- + +## Nielsen's 10 Usability Heuristics + +Quick reference for heuristic evaluation: + +1. **Visibility of system status** — Keep users informed +2. **Match between system and real world** — Speak users' language +3. **User control and freedom** — Support undo, exits +4. **Consistency and standards** — Follow conventions +5. **Error prevention** — Prevent problems before they occur +6. **Recognition over recall** — Make options visible +7. **Flexibility and efficiency** — Shortcuts for experts +8. **Aesthetic and minimalist design** — Remove unnecessary elements +9. **Help users recognize, diagnose, recover from errors** — Clear error messages +10. **Help and documentation** — Easy to search, task-focused diff --git a/references/10-checklist-new-interfaces.md b/references/10-checklist-new-interfaces.md new file mode 100644 index 0000000..681bbe1 --- /dev/null +++ b/references/10-checklist-new-interfaces.md @@ -0,0 +1,232 @@ +# Checklist: Designing New Interfaces + +A 6-step process for approaching any new interface from scratch. + +--- + +## Step 1: Define the System + +Understand the technical and contextual landscape before designing. + +### Key Questions + +☐ **What type of system is this?** +- Web application — Cross-platform, easy updates, limited hardware access +- Mobile app — Native performance, deep device integration, separate iOS/Android +- Desktop software — Full processing power, deep system access, requires updates +- Embedded system — Fixed hardware, task-specific, constrained resources + +☐ **What are the platform constraints?** +- Screen sizes and orientations +- Input methods (touch, mouse, keyboard, voice) +- Performance requirements +- Offline capabilities needed? + +☐ **What data inputs/outputs exist?** +- How do users get data in? +- How do users get data out? +- What integrations are required? + +### Best Practices +- Match the system type to user needs and contexts +- Consider browser extensions, mobile companions for web apps +- Prioritize input methods that fit user context + +--- + +## Step 2: Model User Tasks + +Define who users are and what they need to accomplish. + +### Key Questions + +☐ **Who are the different user types?** +- What roles exist? +- What permissions should each role have? +- What are their distinct needs? + +☐ **What are primary tasks users need to accomplish?** +- What are the jobs-to-be-done? +- How do tasks break into step-by-step workflows? +- What are entry points, decision points, and endpoints? + +☐ **How will users CRUD data?** +- Create, Read, Update, Delete flows +- Necessary sequencing and granularity +- Bulk operations needed? + +☐ **What are key data entities?** +- What objects do users interact with? +- How are entities related? (1:1, 1:many, many:many) +- What's the data model? + +### Best Practices +- Focus on most frequent and important tasks first +- Use simple, clear language for task descriptions +- Validate task models with user research or feedback +- Label buttons with actions ("Add Content" not "Submit") + +--- + +## Step 3: Organize Information + +Structure content and navigation before visual design. + +### Key Questions + +☐ **What are the high-level categories/sections?** +- Main content areas or features? +- How can categories be logically grouped? + +☐ **What are relationships and hierarchies?** +- What's the hierarchy of importance? +- Which entities relate to which? (1:many, many:many) + +☐ **What are primary and secondary navigation patterns?** +- Main nav menu structure? +- Contextual or in-page nav needed? +- Breadcrumbs? Secondary nav? + +☐ **What content and actions should be prioritized?** +- What info is critical for task completion? +- How can visual hierarchy guide users? + +### Best Practices +- Use card sorting or tree testing to validate IA +- Follow established conventions for nav +- Provide clear labels and signposts +- Use breadcrumbs for deep hierarchies + +--- + +## Step 4: Gather Design Inspiration + +Research before creating. Stand on shoulders of giants. + +### Choose Your Originality Level + +1. **Direct copies** — Replicate existing patterns exactly (fastest, least differentiation) +2. **Remixes** — Combine elements from multiple sources +3. **Indirect parallels** — Inspiration from different domains solving similar problems +4. **Metaphors/analogies** — Real-world concepts informing design +5. **True innovation** — New patterns from first principles (slowest, highest risk) + +### Inspiration Sources + +**Standard:** +- Dribbble, Behance, Awwwards, Pinterest + +**More interesting:** +- ProductHunt — How startups differentiate +- Layers.to — Higher quality than Dribbble +- Pageflows.com — User flows of popular apps +- Mobbin.com — Mobile pattern library +- Teardowns.ai — AI feature patterns + +### Best Practices +- Focus on examples matching your project constraints +- Look beyond direct competitors to adjacent domains +- Create moodboards and organized collections +- Annotate what works and what doesn't + +--- + +## Step 5: Generate Rapid Ideas + +Quantity before quality. Explore widely before refining. + +### Key Activities + +☐ **Sketch 6+ low-fidelity concepts** +- Don't judge while creating +- Set a timer (15-30 min) +- Explore diverse approaches + +☐ **Vary the fundamentals** +- Different layouts +- Different navigation approaches +- Different information hierarchies +- Different interaction patterns + +☐ **Focus on structure, not style** +- Boxes and labels, not colors and fonts +- Workflow and flow, not polish + +### Idea Generation Techniques + +- **Crazy 8s** — 8 ideas in 8 minutes +- **Worst possible idea** — Then invert +- **How would [X company] do this?** — Steal mental models +- **Analogy mapping** — How does [unrelated domain] solve this? +- **Constraint removal** — What if we had no [budget/time/tech] limits? + +### Best Practices +- Timebox ideation to prevent overthinking +- Don't fall in love with first idea +- Involve others for diverse perspectives +- Compare against JTBD to evaluate + +--- + +## Step 6: Enhance Fidelity + +Move from concept to detailed design. + +### Fidelity Progression + +1. **Wireframes** — Structure and layout +2. **Low-fi mockups** — Basic styling, real content +3. **High-fi mockups** — Full visual design +4. **Interactive prototypes** — Testable flows + +### Key Questions for Enhancement + +☐ **Are all component states defined?** +- Default, hover, active, focus, disabled, loading, error + +☐ **Are all interactions specified?** +- Primary interactions (clicks, taps) +- Secondary interactions (hovers, long-press) +- Gestures and shortcuts + +☐ **Is content scalability addressed?** +- Empty states +- Minimal content +- Maximum/overflow content +- Edge cases + +☐ **Is system feedback clear?** +- Loading states +- Success/error feedback +- Progress indicators + +☐ **Is user input handled?** +- Validation states +- Error messages +- Help text + +☐ **Is navigation complete?** +- All pages/views connected +- Back navigation +- Deep linking + +### Best Practices +- Apply fidelity checklists (see 11-checklist-fidelity.md) +- Apply visual style checklists (see 12-checklist-visual-style.md) +- Test with real content, not lorem ipsum +- Review against JTBD and macro bets + +--- + +## Quick Reference: 6-Step Summary + +| Step | Focus | Output | +|------|-------|--------| +| 1. Define System | Platform, constraints, data | System requirements doc | +| 2. Model Tasks | Users, workflows, entities | Task flows, CRUD maps | +| 3. Organize Info | Categories, hierarchy, nav | Information architecture | +| 4. Gather Inspiration | Research, patterns, references | Moodboard, pattern library | +| 5. Generate Ideas | Divergent exploration | 6+ wireframe concepts | +| 6. Enhance Fidelity | Detail, polish, edge cases | High-fi designs, prototypes | + +**Rule:** Resist the urge to skip to Step 6. Steps 1-5 make Step 6 dramatically faster and better. diff --git a/references/11-checklist-fidelity.md b/references/11-checklist-fidelity.md new file mode 100644 index 0000000..e207206 --- /dev/null +++ b/references/11-checklist-fidelity.md @@ -0,0 +1,269 @@ +# Checklist: Improving Fidelity + +Systematic checks for completing interface designs beyond the happy path. + +--- + +## Component States + +Every interactive component needs these states defined: + +### Core States + +☐ **Default** — Resting state, no interaction +☐ **Hover** — Cursor over element (desktop) +☐ **Active/Pressed** — During click/tap +☐ **Focus** — Keyboard navigation highlight +☐ **Disabled** — Not currently interactive +☐ **Loading** — Processing/fetching +☐ **Error** — Invalid state +☐ **Success** — Action completed + +### Additional States by Component Type + +**Buttons:** +☐ Primary, secondary, tertiary variants +☐ Icon-only versions +☐ With/without icons +☐ Size variants (small, medium, large) + +**Inputs:** +☐ Empty, filled, placeholder +☐ Valid, invalid, warning +☐ With helper text, error message +☐ Required indicator +☐ Read-only, disabled + +**Checkboxes/Radios:** +☐ Unchecked, checked, indeterminate +☐ Disabled states for each + +**Toggles:** +☐ On, off, disabled +☐ With labels, without labels + +**Links:** +☐ Default, visited, hover, active, focus + +--- + +## Primary Interactions + +Main actions users take with the interface. + +### Click/Tap Interactions + +☐ **Touch targets** — Minimum 44x44px (mobile), 32x32px (desktop) +☐ **Hit areas** — Larger than visual element when needed +☐ **Feedback** — Immediate visual response to tap +☐ **Double-click/tap** — Behavior defined or prevented + +### Form Submissions + +☐ **Submit button states** — Enabled only when valid +☐ **In-progress feedback** — Loading indicator +☐ **Success confirmation** — Clear completion message +☐ **Error handling** — What happens when it fails? +☐ **Re-submission** — Can users retry? + +### Selection Interactions + +☐ **Single selection** — Radio buttons, dropdowns +☐ **Multi-selection** — Checkboxes, multi-select +☐ **Range selection** — Shift-click behavior +☐ **Select all/none** — Bulk selection + +--- + +## Secondary Interactions + +Supporting interactions beyond primary actions. + +### Hover Interactions (Desktop) + +☐ **Tooltips** — Delay before showing (300-500ms) +☐ **Preview cards** — Information on hover +☐ **Menu reveals** — Dropdown on hover vs. click +☐ **State changes** — Visual feedback on hover + +### Long-Press (Mobile) + +☐ **Context menus** — What actions appear? +☐ **Drag initiation** — Does long-press start drag? +☐ **Haptic feedback** — Vibration on trigger? + +### Keyboard Interactions + +☐ **Tab order** — Logical focus sequence +☐ **Enter/Space** — Activate focused element +☐ **Escape** — Close modals, cancel actions +☐ **Arrow keys** — Navigate within components +☐ **Shortcuts** — Power user key combinations + +### Gestures (Mobile/Touch) + +☐ **Swipe** — Horizontal/vertical actions +☐ **Pinch/zoom** — Image viewing, maps +☐ **Pull-to-refresh** — List refresh +☐ **Drag and drop** — Reordering + +--- + +## Content Scalability + +Designs must handle variable content. + +### Empty States + +☐ **First-time user** — No data yet, clear CTA to start +☐ **No results** — Search/filter with no matches +☐ **Deleted content** — After removing items +☐ **Error state** — Failed to load + +**Empty state must include:** +- Explanation of why empty +- What user can do (CTA) +- Visual to reduce starkness + +### Minimal Content + +☐ **One item in list** — Does layout still work? +☐ **Short text** — Single word titles, descriptions +☐ **Missing optional fields** — Graceful absence + +### Maximum Content + +☐ **Long text** — Truncation with ellipsis, tooltips +☐ **Many items** — Pagination, infinite scroll, virtualization +☐ **Long words** — Word-break behavior +☐ **Large images** — Aspect ratio handling + +### Edge Cases + +☐ **Special characters** — Unicode, emoji, RTL text +☐ **Numbers** — Negative, decimals, large numbers +☐ **Dates** — Different formats, timezones +☐ **Names** — Mononyms, very long names, special characters + +--- + +## System Feedback + +How the interface communicates state to users. + +### Loading States + +☐ **Initial load** — Skeleton screens, spinners +☐ **Action processing** — Button loading state +☐ **Background loading** — Subtle indicators +☐ **Partial loading** — Progressive content reveal + +**Rules:** +- < 100ms: No indicator needed +- 100ms-1s: Simple spinner +- 1s+: Progress indicator or skeleton +- 10s+: Background processing with notification + +### Success Feedback + +☐ **Inline confirmation** — Check marks, color changes +☐ **Toast notifications** — Non-blocking success messages +☐ **Page transitions** — Navigate to success state +☐ **Celebrations** — Milestone achievements + +### Error Feedback + +☐ **Inline errors** — Field-level validation +☐ **Summary errors** — Form-level error list +☐ **System errors** — Server/network failures +☐ **Recovery guidance** — What can user do? + +### Progress Indicators + +☐ **Determinate** — Known duration (progress bar with %) +☐ **Indeterminate** — Unknown duration (spinner) +☐ **Steps** — Multi-step process indicator +☐ **Upload/download** — File transfer progress + +--- + +## User Input + +Handling all forms of user data entry. + +### Text Input + +☐ **Character limits** — Max length with counter +☐ **Input masks** — Phone, credit card, date formats +☐ **Autocomplete** — Suggestions while typing +☐ **Auto-capitalization** — Appropriate for input type +☐ **Spell check** — Enabled/disabled appropriately + +### Validation + +☐ **Real-time validation** — Validate as user types +☐ **On-blur validation** — Validate when leaving field +☐ **On-submit validation** — Final check before submit +☐ **Error message placement** — Below field, inline +☐ **Error message content** — Clear, actionable + +### Input Types + +☐ **Text** — Default, email, password, URL, search +☐ **Number** — With constraints (min, max, step) +☐ **Date/time** — Native or custom pickers +☐ **File upload** — Drag-drop, click to browse +☐ **Rich text** — Formatting toolbar + +### Accessibility + +☐ **Labels** — Every input has a label +☐ **Placeholders** — Not used as labels +☐ **Error announcements** — Screen reader accessible +☐ **Required fields** — Clearly indicated + +--- + +## Navigation + +Moving through the interface. + +### Global Navigation + +☐ **Current location** — Where am I? +☐ **Available destinations** — Where can I go? +☐ **Path taken** — How did I get here? (breadcrumbs) +☐ **Return path** — How do I go back? + +### State Preservation + +☐ **Browser back** — Does it work as expected? +☐ **Deep linking** — Can users share URLs to specific states? +☐ **Form state** — Is data preserved on navigation? +☐ **Scroll position** — Preserved or reset appropriately? + +### Transitions + +☐ **Page transitions** — Consistent animation pattern +☐ **Loading transitions** — Skeleton to content +☐ **Modal/drawer open/close** — Smooth animations +☐ **List additions/removals** — Animated changes + +--- + +## Quick Fidelity Audit + +Use this for rapid checks: + +| Category | ✓ | Notes | +|----------|---|-------| +| All component states defined | | | +| Primary interactions specified | | | +| Secondary interactions specified | | | +| Empty states designed | | | +| Max content handling defined | | | +| Loading states defined | | | +| Success/error feedback defined | | | +| All inputs validated | | | +| Navigation complete | | | +| Keyboard accessible | | | diff --git a/references/12-checklist-visual-style.md b/references/12-checklist-visual-style.md new file mode 100644 index 0000000..d08905e --- /dev/null +++ b/references/12-checklist-visual-style.md @@ -0,0 +1,296 @@ +# Checklist: Improving Visual Style + +Systematic checks for visual design consistency and quality. + +--- + +## Spacing + +Consistent rhythm creates visual harmony. + +### Spacing System + +☐ **Base unit defined** — Usually 4px or 8px +☐ **Scale established** — e.g., 4, 8, 12, 16, 24, 32, 48, 64 +☐ **Consistent application** — Same spacing for same relationships + +### Spacing Types + +☐ **Padding** — Space inside containers +☐ **Margin** — Space between elements +☐ **Gap** — Space in flex/grid layouts +☐ **Gutters** — Space between columns + +### Spacing Relationships + +☐ **Related items closer** — Law of Proximity +☐ **Unrelated items farther** — Visual grouping +☐ **Hierarchy through spacing** — More space = more importance +☐ **Breathing room** — Adequate whitespace + +### Common Issues + +- Inconsistent spacing between similar elements +- Too little whitespace (cramped) +- Too much whitespace (disconnected) +- Padding/margin not on the spacing scale + +--- + +## Colors + +Color communicates meaning and creates hierarchy. + +### Color System + +☐ **Primary color** — Brand/action color +☐ **Secondary color** — Supporting accent +☐ **Neutral palette** — Grays for text, backgrounds, borders +☐ **Semantic colors** — Error, success, warning, info + +### Color Usage + +☐ **Text colors** — Primary, secondary, disabled, placeholder +☐ **Background colors** — Surface hierarchy (elevated, base, sunken) +☐ **Border colors** — Default, focus, error +☐ **Interactive states** — Hover, active, focus variations + +### Color Accessibility + +☐ **Contrast ratios** — 4.5:1 for normal text, 3:1 for large text +☐ **Not color alone** — Don't rely solely on color to convey info +☐ **Color blindness** — Test with simulators +☐ **Dark mode** — Colors work in both modes + +### Common Issues + +- Too many colors (lack of cohesion) +- Insufficient contrast +- Inconsistent semantic usage (different reds for errors) +- Color used as only differentiator + +--- + +## Elevation + +Visual layers create depth and hierarchy. + +### Elevation Levels + +☐ **Level 0** — Base surface (no shadow) +☐ **Level 1** — Slight elevation (cards, sections) +☐ **Level 2** — Moderate elevation (dropdowns, popovers) +☐ **Level 3** — High elevation (modals, dialogs) +☐ **Level 4** — Highest elevation (toasts, tooltips above modals) + +### Shadow Properties + +☐ **Consistent direction** — Light source consistent +☐ **Blur radius** — Increases with elevation +☐ **Spread** — Usually minimal +☐ **Opacity** — Decreases with distance +☐ **Color** — Usually dark gray/black, can be colored + +### Elevation Usage + +☐ **Interactive elements** — Buttons may elevate on hover +☐ **Overlay content** — Modals, drawers clearly elevated +☐ **Sticky elements** — Headers/navs elevated when scrolling +☐ **Focus indication** — Can supplement or replace outlines + +### Common Issues + +- Inconsistent shadow direction +- Too many elevation levels +- Shadows too harsh or too subtle +- Elevation doesn't match interaction hierarchy + +--- + +## Iconography + +Icons support comprehension and reduce text. + +### Icon System + +☐ **Single icon library** — Consistent style +☐ **Consistent stroke/fill** — Don't mix styles +☐ **Size scale** — 16, 20, 24, 32, 48 (or similar) +☐ **Consistent grid** — Icons align to same grid + +### Icon Usage + +☐ **With text labels** — For unclear icons +☐ **Standalone** — Only for universally understood (close, search, home) +☐ **In buttons** — Left or right of text consistently +☐ **In navigation** — Supplement text, not replace +☐ **As status** — Error, success, warning indicators + +### Icon Accessibility + +☐ **Alt text/aria-label** — For meaningful icons +☐ **aria-hidden** — For decorative icons +☐ **Touch targets** — 44x44px minimum for tappable icons +☐ **Color contrast** — Icons meet contrast requirements + +### Common Issues + +- Mixed icon styles (outline + filled) +- Icons without labels where meaning unclear +- Inconsistent icon sizes +- Too many unique icons + +--- + +## Typography + +Text is the primary interface. Make it work. + +### Type Scale + +☐ **Scale established** — Limited set of sizes (7-10) +☐ **Consistent usage** — Same size for same purpose +☐ **Responsive scaling** — Appropriate for device + +### Type Hierarchy + +☐ **H1-H6** — Clear heading hierarchy +☐ **Body text** — Primary and secondary +☐ **Captions/labels** — Small supporting text +☐ **Display text** — Hero/feature text + +### Type Properties + +☐ **Line height** — 1.4-1.6 for body, 1.1-1.3 for headings +☐ **Letter spacing** — Adjusted for size (tighter large, looser small) +☐ **Font weight** — 2-3 weights max +☐ **Max line length** — 45-75 characters for readability + +### Type Accessibility + +☐ **Minimum size** — 16px for body text +☐ **Contrast** — 4.5:1 ratio +☐ **Scalability** — Works when user zooms +☐ **Font choice** — Legible at small sizes + +### Common Issues + +- Too many font sizes +- Inconsistent line heights +- Lines too long (hard to read) +- Insufficient contrast on secondary text + +--- + +## Imagery & Illustrations + +Visual content enhances understanding and tone. + +### Image Usage + +☐ **Consistent style** — Photography style or illustration style +☐ **Appropriate aspect ratios** — Consistent crops +☐ **Quality** — High resolution, appropriate compression +☐ **Relevance** — Images support content, not decorate + +### Image Treatments + +☐ **Placeholders** — Loading states for images +☐ **Error states** — Broken image handling +☐ **Cropping** — Consistent crop ratios +☐ **Filters/overlays** — Consistent treatment + +### Image Accessibility + +☐ **Alt text** — Descriptive for meaningful images +☐ **Empty alt** — For decorative images +☐ **Text in images** — Avoided or duplicated in HTML +☐ **Color contrast** — Text over images readable + +### Illustration Guidelines + +☐ **Consistent style** — Same illustrator or style guide +☐ **Color palette** — Within brand colors +☐ **Stroke weights** — Consistent with icons +☐ **Character design** — If using people, consistent representation + +--- + +## Motion & Animation + +Movement creates meaning and delight. + +### Animation Purposes + +☐ **Feedback** — Response to user action +☐ **Orientation** — Help users understand spatial relationships +☐ **Attention** — Draw focus to important changes +☐ **Continuity** — Smooth transitions between states + +### Animation Properties + +☐ **Duration** — 100-500ms typical (faster = less important) +☐ **Easing** — Ease-out for entrances, ease-in for exits +☐ **Consistency** — Same duration for same type of animation +☐ **Purpose** — Every animation has a reason + +### Animation Best Practices + +☐ **Prefer transforms** — translate, scale, rotate, opacity (performant) +☐ **Avoid layout thrash** — Don't animate width, height, position +☐ **Reduce motion** — Respect prefers-reduced-motion +☐ **Subtlety** — Most animations should be barely noticed + +### Common Issues + +- Animations too slow (feel sluggish) +- Animations too fast (miss the feedback) +- Gratuitous animation (no purpose) +- Inconsistent easing/duration +- Ignoring accessibility preferences + +--- + +## Texture & Patterns + +Surface treatments add depth and character. + +### Texture Types + +☐ **Subtle gradients** — Add depth without distraction +☐ **Background patterns** — Subtle, non-distracting +☐ **Noise/grain** — Adds warmth to flat colors +☐ **Glass effects** — Blur, transparency (use sparingly) + +### Usage Guidelines + +☐ **Subtlety** — Textures shouldn't compete with content +☐ **Purpose** — Differentiate surfaces, add depth +☐ **Consistency** — Same treatment for same surface type +☐ **Performance** — Consider render cost + +### Common Issues + +- Textures too prominent +- Inconsistent texture usage +- Performance impact from complex textures +- Reduced legibility from background patterns + +--- + +## Visual Style Audit + +Quick checks for visual consistency: + +| Element | ✓ | Notes | +|---------|---|-------| +| Spacing on scale | | | +| Color palette limited | | | +| Contrast accessible | | | +| Elevation consistent | | | +| Single icon style | | | +| Type scale limited | | | +| Line heights consistent | | | +| Images consistent style | | | +| Animations purposeful | | | +| Reduced motion respected | | | diff --git a/references/13-checklist-innovation.md b/references/13-checklist-innovation.md new file mode 100644 index 0000000..ab1bbce --- /dev/null +++ b/references/13-checklist-innovation.md @@ -0,0 +1,296 @@ +# Checklist: Innovation & Originality + +The 5 levels of the originality spectrum and when to use each. + +--- + +## The Originality Spectrum + +Not all design work requires innovation. Choose your level intentionally. + +``` +Lower Risk Higher Risk +Faster Slower +├─────────┼─────────┼─────────┼─────────┼─────────┤ +Direct Remixes Indirect Metaphors True +Copies Parallels & Analogies Innovation +``` + +--- + +## Level 1: Direct Copies + +**What:** Replicate existing design patterns exactly. + +### When to Use + +- Velocity is critical, differentiation isn't +- Users expect familiar patterns +- Internal tools, admin interfaces +- Proven patterns for common problems +- Low-stakes decisions + +### How to Execute + +☐ Identify the pattern you're copying +☐ Understand *why* it works (not just *what*) +☐ Copy the principles, adapt the details +☐ Ensure it fits your context +☐ Give credit where appropriate + +### Examples + +- Using a competitor's checkout flow structure +- Implementing Material Design's data table exactly +- Copying iOS settings page patterns + +### Risks + +- Legal issues (if copying proprietary designs too closely) +- Doesn't differentiate your product +- May not fit your specific context + +--- + +## Level 2: Remixes + +**What:** Combine elements from multiple sources into a new composition. + +### When to Use + +- Want some differentiation with low risk +- Multiple good patterns exist, none perfect +- Combining best practices from different products +- Adapting patterns to new contexts + +### How to Execute + +☐ Identify 2-3 source patterns +☐ Extract the best elements from each +☐ Combine intentionally (not randomly) +☐ Test the combination works cohesively +☐ Document the sources and your reasoning + +### Examples + +- Slack's message composer (combines messaging patterns from multiple products) +- Notion's database views (combines spreadsheet + database + card patterns) +- A mobile nav that combines iOS and Android conventions + +### Risks + +- Frankensteining (incoherent combinations) +- Losing what made original patterns work +- Overcomplicating by adding too many elements + +--- + +## Level 3: Indirect Parallels + +**What:** Draw inspiration from designs in different domains that solve similar problems. + +### When to Use + +- Direct competitors have similar solutions +- Looking for fresh perspectives +- The core problem is domain-agnostic +- Want to surprise users (positively) + +### How to Execute + +☐ Define the core problem (abstractly) +☐ Identify other domains with the same problem +☐ Research how those domains solve it +☐ Translate the solution to your context +☐ Validate it works for your users + +### Examples + +- Netflix content discovery → B2B product recommendations +- Video game skill trees → Learning platform progression +- Restaurant reservation flow → Meeting scheduling +- Music playlist curation → Content organization + +### Good Cross-Domain Sources + +- Gaming (engagement, progression, feedback) +- E-commerce (conversion, product display) +- Social media (engagement, sharing, discovery) +- Maps/navigation (wayfinding, spatial organization) +- Publishing (content hierarchy, reading experience) + +### Risks + +- Translation may not work across domains +- Users may not understand the metaphor +- Over-reaching can feel forced + +--- + +## Level 4: Metaphors & Analogies + +**What:** Use concepts from the real world to inform your design. + +### When to Use + +- Introducing new/unfamiliar concepts +- Making abstract concepts concrete +- Creating memorable mental models +- Building on existing user knowledge + +### How to Execute + +☐ Identify the concept users need to understand +☐ Find a familiar real-world analog +☐ Map the relationships (what matches, what doesn't) +☐ Use language and visuals from the metaphor +☐ Don't over-extend the metaphor + +### Classic Metaphors in Software + +| Metaphor | Software Concept | +|----------|-----------------| +| Desktop | OS file management | +| Folder | Directory | +| Trash can | Deleted files | +| Shopping cart | Checkout | +| Inbox | Messages | +| Library | Content collection | +| Dashboard | Metrics overview | +| Workspace | Project environment | + +### Creating New Metaphors + +☐ The metaphor should simplify, not complicate +☐ The mapping should be intuitive +☐ Don't force all aspects to match +☐ Test if users understand the metaphor +☐ Be consistent once you commit + +### Risks + +- Metaphor breaks down at edge cases +- Users don't share the cultural reference +- Constrains design to fit the metaphor +- Can feel gimmicky if overdone + +--- + +## Level 5: True Innovation + +**What:** Create entirely new design patterns from first principles. + +### When to Use + +- Existing patterns don't solve the problem +- Creating a new product category +- Technical breakthrough enables new interactions +- Differentiation is critical competitive advantage +- You have time and resources to iterate + +### How to Execute + +☐ Define the problem from first principles +☐ Question all assumptions about current solutions +☐ Explore multiple radical approaches +☐ Prototype and test extensively +☐ Be prepared to fail and iterate +☐ Document your learnings + +### First Principles Questions + +- What is the user actually trying to accomplish? +- Why do we do it this way? What if we didn't? +- What constraints are real vs. assumed? +- What would this look like with no constraints? +- What new technology/capability enables a different approach? + +### Examples of True Innovation + +- iPhone's multitouch interface (2007) +- Notion's blocks-based content model +- Figma's multiplayer design editing +- Linear's keyboard-first interface +- Superhuman's command-k pattern + +### Risks + +- High failure rate +- Significant time and resource investment +- Users may not adopt unfamiliar patterns +- May solve a problem users don't have +- Competitors can copy if successful + +--- + +## Choosing Your Level + +### Decision Framework + +| Factor | Lower Originality | Higher Originality | +|--------|------------------|-------------------| +| Time available | Limited | Ample | +| Risk tolerance | Low | High | +| User sophistication | General | Early adopters | +| Market maturity | Established | Emerging | +| Differentiation need | Low | Critical | +| Pattern clarity | Clear best practice | No clear winner | + +### By Context + +| Context | Recommended Level | +|---------|------------------| +| Internal tools | 1 (Direct copies) | +| Commodity features | 1-2 (Copies, Remixes) | +| Core product features | 2-3 (Remixes, Parallels) | +| Key differentiators | 3-4 (Parallels, Metaphors) | +| New categories | 4-5 (Metaphors, Innovation) | + +--- + +## Innovation Process + +When pursuing higher originality levels: + +### 1. Diverge Widely + +- Generate many options (10+) +- Include "bad" ideas +- Cross-pollinate from unexpected sources +- Don't evaluate while generating + +### 2. Prototype Rapidly + +- Build to learn, not to ship +- Test core assumptions early +- Fail fast, learn faster +- Increase fidelity incrementally + +### 3. Validate Thoroughly + +- Test with real users +- Measure against JTBD +- Compare to existing solutions +- Be willing to abandon + +### 4. Document Learnings + +- What worked and didn't +- Unexpected discoveries +- Principles that emerged +- Recommendations for future + +--- + +## Innovation Audit + +Before pursuing originality: + +| Question | Answer | +|----------|--------| +| Why is innovation needed here? | | +| What's the risk if we fail? | | +| Do we have time to iterate? | | +| What's our differentiation goal? | | +| What's the simplest option that might work? | | +| Have we validated user need? | | diff --git a/references/20-patterns-chunking.md b/references/20-patterns-chunking.md new file mode 100644 index 0000000..3a8de18 --- /dev/null +++ b/references/20-patterns-chunking.md @@ -0,0 +1,273 @@ +# Patterns: Chunking + +Patterns for breaking content into digestible, organized units. + +--- + +## What is Chunking? + +Breaking complex information into smaller, manageable pieces that users can process and remember more easily. Based on Miller's Law (7±2 items in working memory). + +**Core principle:** Users can't process everything at once. Group related items, separate unrelated items. + +--- + +## Card-Based Layouts + +**What:** Contained units of related content with clear boundaries. + +### Benefits & Use Cases + +- **Scannable** — Users quickly identify relevant cards +- **Self-contained** — Each card is a complete unit +- **Flexible** — Cards work in grids, lists, or carousels +- **Actionable** — Cards can be interactive (click, expand, drag) + +### Psychological Principles + +- **Law of Common Region** — Boundary creates relatedness +- **Chunking** — Content grouped into digestible units +- **Recognition over recall** — Visual cards easier to scan + +### Implementation Guidelines + +**DO:** +- Clear visual boundary (border, shadow, or background) +- Consistent card structure across the set +- Visual hierarchy within the card (image → title → description → actions) +- Appropriate sizing for content (not too cramped or empty) +- Interactive states (hover, selected) + +**DON'T:** +- Mix card sizes without purpose +- Overload cards with too much content +- Use cards for single items (overkill) +- Nest cards inside cards +- Forget empty states + +### Common Variants + +| Variant | Use Case | +|---------|----------| +| Media card | Image/video prominent | +| Stat card | Single metric focus | +| Action card | Primary CTA emphasis | +| Profile card | Person/account info | +| Preview card | Summary with expand | + +--- + +## Tabs & Accordions + +**What:** Show/hide content sections to reduce visible complexity. + +### When to Use Tabs vs. Accordions + +| Tabs | Accordions | +|------|------------| +| 2-7 peer sections | Many sections (5+) | +| Mutually exclusive content | Content can stack | +| Horizontal space available | Vertical list format | +| Users need to switch frequently | Users view one at a time | + +### Benefits & Use Cases + +- **Space efficient** — Show only relevant content +- **User control** — Users choose what to see +- **Progressive disclosure** — Reduce cognitive load +- **Organization** — Clear content categorization + +### Psychological Principles + +- **Hick's Law** — Fewer visible options = easier decisions +- **Progressive disclosure** — Reveal complexity gradually +- **Miller's Law** — Chunk content into sections + +### Implementation Guidelines (Tabs) + +**DO:** +- Clear active state +- Limit to 7 tabs (use dropdown for more) +- Descriptive labels (2-3 words) +- Logical order (frequency or process) +- Preserve state when switching + +**DON'T:** +- Use tabs for sequential steps (use steppers) +- Mix tabs with different content types +- Use very long labels +- Nest tabs within tabs +- Auto-switch tabs without user action + +### Implementation Guidelines (Accordions) + +**DO:** +- Clear expand/collapse indicators (chevron, +/-) +- Allow multiple open (usually) or single open (sometimes) +- Animate expansion smoothly +- Keyboard accessible (Enter/Space to toggle) +- Consider default-expanded first item + +**DON'T:** +- Nest accordions deeply +- Hide critical information in collapsed sections +- Use vague headers +- Make all sections collapsed by default if users need most of them + +--- + +## Grouped Form Fields + +**What:** Related form fields visually grouped together. + +### Benefits & Use Cases + +- **Scannable** — Related fields easy to locate +- **Logical** — Reflects user mental model +- **Reduced errors** — Related info filled together +- **Progress sense** — Completing groups feels like progress + +### Psychological Principles + +- **Law of Proximity** — Close items perceived as related +- **Chunking** — Smaller groups easier to process +- **Goal gradient** — Visible progress motivates completion + +### Implementation Guidelines + +**DO:** +- Group by relationship (personal info, shipping, payment) +- Use visual separation (whitespace, lines, containers) +- Label groups with clear headers +- 3-5 fields per group typically +- Consider two-column layout for short fields + +**DON'T:** +- Create groups that are too large +- Separate clearly related fields (first/last name) +- Use inconsistent grouping across forms +- Over-decorate group boundaries + +### Common Groupings + +| Group | Fields | +|-------|--------| +| Personal | Name, email, phone | +| Address | Street, city, state, zip, country | +| Payment | Card, expiry, CVV, billing address | +| Credentials | Username/email, password, confirm | +| Preferences | Notification settings, privacy | + +--- + +## Pagination + +**What:** Breaking large lists into discrete pages. + +### Pagination vs. Infinite Scroll vs. Load More + +| Pattern | Use When | +|---------|----------| +| **Pagination** | User needs to locate specific items, page numbers meaningful, SEO important | +| **Infinite scroll** | Browsing/discovery, no specific target, continuous consumption (social feeds) | +| **Load more** | Compromise between above, user controls when to load | + +### Benefits & Use Cases + +- **Orientation** — Users know where they are (page 3 of 10) +- **Shareable** — Deep links to specific pages +- **Performance** — Predictable page loads +- **Completion sense** — Can reach "the end" + +### Psychological Principles + +- **Chunking** — Content in manageable batches +- **Progress** — Page numbers show advancement +- **Control** — User decides when to load more + +### Implementation Guidelines + +**DO:** +- Show current page and total pages +- Provide first/last page shortcuts (for many pages) +- Truncate middle pages with ellipsis (1 2 3 ... 10) +- Show items per page (and allow customization) +- Preserve page in URL (deep linking) + +**DON'T:** +- Use pagination for < 20 items +- Hide page count +- Break in the middle of logical groups +- Require clicking through many pages for common tasks +- Forget keyboard navigation + +### Page Size Guidelines + +| Context | Items/Page | +|---------|------------| +| Data tables | 10-50, user configurable | +| Search results | 10-25 | +| Product listings | 12-48 | +| Blog/articles | 5-10 | + +--- + +## Carousels & Sliders + +**What:** Horizontal scrollable content, often auto-advancing. + +### Benefits & Use Cases + +- **Space efficient** — Many items in limited space +- **Visual interest** — Dynamic, engaging +- **Feature highlights** — Hero promotions, featured content +- **Related content** — "You might also like" + +### Psychological Principles + +- **Curiosity** — Partial visibility entices exploration +- **Chunking** — Subset of content at a time +- **Serial position** — First items get most attention + +### Implementation Guidelines + +**DO:** +- Show partial next item (indicates more content) +- Clear navigation controls (arrows, dots) +- Allow touch/swipe on mobile +- Consider auto-advance carefully (user control preferred) +- Pause auto-advance on hover/focus + +**DON'T:** +- Auto-advance too fast (5+ seconds minimum) +- Use for critical content (users miss it) +- Hide navigation controls +- Use multiple carousels on same page +- Rely on carousel for primary navigation + +### Critical Warnings + +⚠️ Carousels have notoriously low engagement beyond first item +⚠️ Users often miss carousel content entirely +⚠️ Auto-advance frustrates users trying to read +⚠️ Consider if content is important enough to warrant space without hiding + +### Better Alternatives + +- Grid of items (all visible) +- Horizontal scroll (user-controlled) +- Featured + list (primary + secondary) +- Accordion (if order matters less) + +--- + +## Chunking Pattern Selection Guide + +| User Need | Pattern | +|-----------|---------| +| Compare items | Cards in grid | +| View details on demand | Accordions | +| Switch between categories | Tabs | +| Fill related information | Grouped forms | +| Navigate large sets | Pagination | +| Browse highlights | Carousel (with caution) | diff --git a/references/21-patterns-progressive-disclosure.md b/references/21-patterns-progressive-disclosure.md new file mode 100644 index 0000000..fb70ec4 --- /dev/null +++ b/references/21-patterns-progressive-disclosure.md @@ -0,0 +1,320 @@ +# Patterns: Progressive Disclosure + +Patterns for revealing information gradually, on demand. + +--- + +## What is Progressive Disclosure? + +Showing only the information users need at each moment, with additional details available on demand. Reduces cognitive load while maintaining access to complexity. + +**Core principle:** Simple by default, powerful when needed. + +--- + +## Tooltips & Popovers + +**What:** Small overlays triggered by hover/focus/tap showing additional context. + +### Tooltips vs. Popovers + +| Tooltips | Popovers | +|----------|----------| +| Text only | Rich content (images, links, actions) | +| Hover-triggered | Click-triggered usually | +| Auto-dismiss | User dismisses | +| Brief explanation | Detailed information | +| No interaction | Can contain interactions | + +### Benefits & Use Cases + +- **Explanation** — Clarify icon meanings, abbreviations +- **Guidance** — Inline help without cluttering UI +- **Preview** — Peek at content before committing +- **Details** — Additional info for power users + +### Psychological Principles + +- **Progressive disclosure** — Detail available when needed +- **Recognition over recall** — Explanation in context +- **Filtering** — Non-essential info hidden until requested + +### Implementation Guidelines (Tooltips) + +**DO:** +- Delay appearance (300-500ms) to avoid flicker +- Position to not obscure related content +- Keep text brief (1-2 sentences max) +- Provide keyboard access (show on focus) +- Use arrow pointing to trigger element + +**DON'T:** +- Use for essential information +- Require tooltips to complete tasks +- Show on touch without alternative (no hover on mobile) +- Put interactive elements in tooltips +- Make them too long to read quickly + +### Implementation Guidelines (Popovers) + +**DO:** +- Clear close mechanism (X, click outside) +- Appropriate max-width for content +- Position dynamically (flip if near edge) +- Allow interactions within +- Consider mobile-specific behavior (bottom sheets) + +**DON'T:** +- Nest popovers within popovers +- Put critical actions only in popovers +- Open on hover (confusing behavior) +- Make too large (use a modal instead) + +--- + +## Nested Menus + +**What:** Multi-level dropdown menus for hierarchical navigation. + +### Benefits & Use Cases + +- **Hierarchy** — Navigate deep category structures +- **Space efficient** — Many options in small trigger +- **Organization** — Group related actions +- **Power users** — Complex command palettes + +### Psychological Principles + +- **Chunking** — Options grouped logically +- **Progressive disclosure** — Deeper options revealed on demand +- **Hick's Law** — Hierarchy reduces visible choices at each level + +### Implementation Guidelines + +**DO:** +- Limit nesting depth (2-3 levels max) +- Clear visual indicator for submenus (arrow) +- Appropriate hover delay for submenus (300ms) +- Keep submenus visible while navigating +- Keyboard navigation (arrows to navigate, Enter to select) + +**DON'T:** +- Deeply nest menus (hard to navigate) +- Make menus too narrow for content +- Require precise mouse movements +- Hide critical actions in deep nests +- Mix menu types inconsistently + +### Positioning Guidelines + +- Open toward available space (flip if at edge) +- Submenus open to side with most room +- Consider mobile alternatives (drill-down, bottom sheets) + +--- + +## Expandable Rows + +**What:** Table or list rows that expand to reveal details. + +### Benefits & Use Cases + +- **Overview first** — Scannable summary view +- **Details on demand** — Expand for more +- **In-context** — Details appear near summary +- **Comparison** — Compare multiple expanded rows + +### Psychological Principles + +- **Progressive disclosure** — Detail when needed +- **Filtering** — Hide details unless requested +- **Recall** — Summary aids memory; details available + +### Implementation Guidelines + +**DO:** +- Clear expand/collapse indicator +- Smooth animation +- Distinct visual treatment for expanded content +- Allow multiple rows expanded (usually) +- Preserve expanded state during interactions + +**DON'T:** +- Auto-collapse other rows (usually—unless space critical) +- Nest expandable rows within expandable rows +- Put primary actions only in expanded view +- Make expanded content too tall (becomes a page) +- Forget keyboard accessibility + +### Content in Expanded Rows + +- Additional metadata +- Action buttons +- Related items +- Full description +- Inline forms (for edit-in-place) + +--- + +## Drawers & Sheets + +**What:** Panels that slide in from screen edge, overlaying content. + +### Side Drawers vs. Bottom Sheets + +| Side Drawers | Bottom Sheets | +|--------------|---------------| +| Desktop primary | Mobile primary | +| Navigation menus | Actions, options | +| Longer content | Shorter content | +| Wider content | Full-width content | +| Slide from left/right | Slide from bottom | + +### Benefits & Use Cases + +- **Context preservation** — Main content visible behind +- **Temporary focus** — Complete task then return +- **Space efficient** — Off-screen until needed +- **Navigation** — Mobile nav menus +- **Filters** — Search refinement panels + +### Psychological Principles + +- **Progressive disclosure** — Reveal when needed +- **Context maintenance** — Don't lose place +- **Filtering** — Focused attention on drawer content + +### Implementation Guidelines + +**DO:** +- Clear close mechanism (X, tap outside, swipe) +- Appropriate width (280-400px for side drawers) +- Overlay/scrim behind to focus attention +- Animate open/close smoothly +- Trap focus within drawer (accessibility) + +**DON'T:** +- Make drawers too wide (becomes a page) +- Put critical info only in drawers +- Stack multiple drawers +- Open automatically without user action +- Forget keyboard users (Escape to close) + +### Mobile Considerations + +- Bottom sheets generally preferred on mobile +- Allow swipe to dismiss +- Consider detent heights (partial, full) +- Respect safe areas + +--- + +## Modals (Dialogs) + +**What:** Overlays that demand attention and require dismissal. + +### When to Use Modals + +- Require user decision (confirm, choose) +- Critical information that can't be missed +- Focused task (compose, edit) +- Interrupt current flow intentionally + +### When NOT to Use Modals + +- Showing information (use popover, drawer) +- Non-blocking notifications (use toast) +- Navigation (use page, drawer) +- Error messages (use inline feedback) + +### Benefits & Use Cases + +- **Focus** — Block other interaction +- **Confirmation** — Prevent accidental actions +- **Interruption** — Force user to acknowledge +- **Isolation** — Complete task before continuing + +### Psychological Principles + +- **Attention capture** — Demands response +- **Decision forcing** — User must act +- **Context switch** — Clear change of task + +### Implementation Guidelines + +**DO:** +- Clear title describing the modal purpose +- Primary action prominent (visual emphasis) +- Secondary action available (cancel/back) +- Close via X button AND clicking backdrop AND Escape key +- Focus first interactive element on open +- Return focus to trigger on close + +**DON'T:** +- Overuse modals (modal fatigue) +- Stack modals (one modal opening another) +- Require scrolling in modals (usually) +- Use for errors that don't need confirmation +- Auto-open modals without user action +- Disable backdrop click to close (unless destructive action) + +### Modal Sizes + +| Size | Use Case | +|------|----------| +| Small (400px) | Simple confirmations | +| Medium (600px) | Forms, content preview | +| Large (800px+) | Complex tasks, multi-step | +| Full screen | Immersive tasks (mobile common) | + +--- + +## Read More Links + +**What:** Truncated content with option to reveal full text. + +### Benefits & Use Cases + +- **Overview** — Scannable summaries +- **Choice** — User decides what to read +- **Space efficient** — Long content doesn't dominate +- **SEO-friendly** — Full content in DOM + +### Implementation Guidelines + +**DO:** +- Natural truncation point (sentence break, not mid-word) +- Clear "Read more" link/button +- Consider inline expansion vs. navigate to full page +- Show character count or reading time for long content +- Animate expansion smoothly + +**DON'T:** +- Truncate critically important content +- Use arbitrary truncation lengths (vary by content) +- Truncate to single words ("...") +- Hide the only instance of information +- Make "Read more" the only way to access content + +### Truncation Guidelines + +| Content Type | Truncation Point | +|--------------|------------------| +| Card descriptions | 2-3 lines | +| Table cells | 1 line with tooltip | +| List item descriptions | 1-2 sentences | +| Blog excerpts | 150-250 characters | + +--- + +## Progressive Disclosure Pattern Selection + +| Need | Pattern | +|------|---------| +| Quick explanation | Tooltip | +| Rich preview | Popover | +| Deep navigation | Nested menus | +| Detail on demand (lists) | Expandable rows | +| Temporary panel | Drawer/sheet | +| Required decision | Modal | +| Optional full content | Read more | diff --git a/references/22-patterns-cognitive-load.md b/references/22-patterns-cognitive-load.md new file mode 100644 index 0000000..e830357 --- /dev/null +++ b/references/22-patterns-cognitive-load.md @@ -0,0 +1,283 @@ +# Patterns: Cognitive Load + +Patterns for reducing mental effort and preventing user overwhelm. + +--- + +## What is Cognitive Load? + +The mental effort required to process information and make decisions. Working memory is limited. Exceed it, and users struggle. + +**Three types:** +1. **Intrinsic** — Complexity of the task itself +2. **Extraneous** — Complexity from poor design +3. **Germane** — Effort spent learning (good complexity) + +**Goal:** Minimize extraneous load. Respect intrinsic load. Enable germane load. + +--- + +## Pagination & Infinite Scroll + +**What:** Breaking large content sets into manageable chunks. + +### Cognitive Load Impact + +- **Pagination** — Clear mental boundaries, sense of progress +- **Infinite scroll** — No landmarks, can feel endless +- **Load more** — User-controlled expansion + +### When to Use Each + +| Pattern | Best For | +|---------|----------| +| **Pagination** | Search results, data tables, e-commerce, SEO-critical pages | +| **Infinite scroll** | Social feeds, discovery browsing, image galleries | +| **Load more** | Balanced approach, when users may want more but need control | + +### Implementation Guidelines + +**Pagination:** +- 10-50 items per page +- Show total count +- Deep linking support +- Consider "jump to page" for large sets + +**Infinite Scroll:** +- Clear loading indicator +- "Back to top" button +- Preserve scroll position on return +- Consider footer accessibility + +**Load More:** +- Show count loaded vs. total +- Consistent batch size +- Clear button placement + +--- + +## Steppers & Wizards + +**What:** Breaking complex processes into sequential steps. + +### Benefits + +- **Reduced load** — One step at a time +- **Progress visibility** — Know where you are +- **Confidence** — Clear path to completion +- **Error isolation** — Fix issues step by step + +### Psychological Principles + +- **Chunking** — Break complexity into parts +- **Goal gradient** — Motivation increases near completion +- **Zeigarnik effect** — Incomplete tasks create engagement + +### Implementation Guidelines + +**DO:** +- Show all steps upfront (numbered or named) +- Indicate current step clearly +- Allow back navigation (within reason) +- Validate before proceeding +- Save progress (in case of abandonment) +- Show summary/review before final submission + +**DON'T:** +- Use for < 3 logical steps (overkill) +- Use for > 7 steps (too daunting) +- Hide step count (anxiety-inducing) +- Require linear completion if not necessary +- Lose user data if they navigate away + +### Step Design + +| Element | Guideline | +|---------|-----------| +| Step count | 3-7 steps ideal | +| Step names | Action-oriented ("Review" not "Step 3") | +| Progress | Visual indicator (bar, dots, numbers) | +| Validation | Per-step before allowing next | +| Summary | Final review before commit | + +--- + +## Minimalist Navigation + +**What:** Reducing navigation options to essential items. + +### Benefits + +- **Reduced decisions** — Fewer choices = easier choices +- **Faster scanning** — Find items quickly +- **Focus** — Attention on primary actions +- **Cleaner interface** — Less visual noise + +### Psychological Principles + +- **Hick's Law** — More options = longer decision time +- **Paradox of choice** — Too many options = worse decisions +- **Filtering** — Less to filter through + +### Implementation Guidelines + +**Primary Navigation:** +- 5-7 items maximum +- Most important items visible +- Group secondary items in "More" or submenus +- Use icons + labels (not just icons) + +**Strategies:** +- Priority+ navigation (show what fits, collapse rest) +- Hamburger menu (hide until needed) +- Mega menus (for large sites, used carefully) +- Command palette (power users) + +**DON'T:** +- Hide everything behind hamburger on desktop +- Use icons without labels for unfamiliar actions +- Create deep navigation hierarchies +- Change navigation per page without reason + +--- + +## Chunked Lists + +**What:** Breaking long lists into visually grouped sections. + +### Benefits + +- **Scannable** — Headers enable skipping +- **Findable** — Alphabetical, categorical, or chronological grouping +- **Memorable** — Sections aid recall +- **Manageable** — Each section is digestible + +### Psychological Principles + +- **Chunking** — Groups easier than flat lists +- **Law of Proximity** — Grouped items relate +- **Serial position** — Section headers become anchors + +### Implementation Guidelines + +**DO:** +- Clear section headers +- Consistent grouping logic +- Sticky headers during scroll (for long sections) +- Empty states per section if needed +- Consider collapsible sections + +**DON'T:** +- Create too many sections (defeats purpose) +- Use inconsistent grouping logic +- Make headers look like list items +- Group unrelated items + +### Grouping Strategies + +| Strategy | Use When | +|----------|----------| +| Alphabetical | Long known lists (contacts, countries) | +| Categorical | Distinct types exist | +| Chronological | Time-based relevance | +| Frequency | Most-used items first | +| Custom | User-defined groups | + +--- + +## Simplified Forms + +**What:** Forms designed to minimize cognitive effort. + +### Strategies + +1. **Reduce fields** — Only ask what's necessary +2. **Smart defaults** — Pre-fill when possible +3. **Progressive disclosure** — Show fields as needed +4. **Inline validation** — Feedback as you go +5. **Logical grouping** — Related fields together + +### Implementation Guidelines + +**Reduce Fields:** +- Audit every field: "Do we *need* this?" +- Make optional fields truly optional +- Consider progressive profiling (ask over time) +- Derive what you can (city from zip, etc.) + +**Smart Defaults:** +- Geo-location for country +- Today's date for date fields +- Most common option pre-selected +- Remember user's previous choices + +**Progressive Disclosure:** +- Show advanced fields only when needed +- "Add more details" expand pattern +- Conditional fields based on previous answers + +**Inline Validation:** +- Validate on blur (not on every keystroke) +- Clear, specific error messages +- Success indicators for valid fields +- Don't prevent typing valid values + +**Field Layout:** +- Single column preferred (easier scanning) +- Labels above fields (faster) +- Consistent field widths +- Adequate spacing between fields + +--- + +## Cognitive Load Reduction Principles + +### 1. Eliminate Non-Essential Elements + +- Remove purely decorative content +- Hide rarely-used options +- Simplify language +- Reduce color/visual noise + +### 2. Leverage Recognition + +- Show options, don't require recall +- Use familiar patterns +- Provide examples +- Use icons + labels + +### 3. Offload to the System + +- Auto-save +- Auto-fill +- Smart suggestions +- Error prevention + +### 4. Support Scanning + +- Clear headings +- Bullet points +- Visual hierarchy +- Whitespace + +### 5. Reduce Decisions + +- Smart defaults +- Recommendations +- Limited choices +- Clear primary action + +--- + +## Cognitive Load Audit + +| Check | Impact | +|-------|--------| +| ☐ Navigation items < 7 | Decision fatigue | +| ☐ Form fields minimized | Input effort | +| ☐ Smart defaults used | Decision effort | +| ☐ Content chunked | Processing load | +| ☐ Clear visual hierarchy | Scanning effort | +| ☐ Recognition over recall | Memory load | +| ☐ Progressive disclosure used | Initial overwhelm | +| ☐ Consistent patterns | Learning load | diff --git a/references/23-patterns-visual-hierarchy.md b/references/23-patterns-visual-hierarchy.md new file mode 100644 index 0000000..2b77c0f --- /dev/null +++ b/references/23-patterns-visual-hierarchy.md @@ -0,0 +1,328 @@ +# Patterns: Visual Hierarchy + +Patterns for guiding attention and creating clear content structure. + +--- + +## What is Visual Hierarchy? + +The arrangement of elements to show relative importance. Users should instantly understand what's most important without reading everything. + +**Core principle:** Design tells users where to look. Make it intentional. + +--- + +## Typography Hierarchy + +**What:** Using type size, weight, and style to establish importance. + +### Hierarchy Levels + +| Level | Purpose | Typical Treatment | +|-------|---------|-------------------| +| **Display** | Hero content, page title | Largest, boldest | +| **H1** | Page heading | Large, bold | +| **H2** | Section heading | Medium-large, semibold | +| **H3** | Subsection | Medium, semibold | +| **Body** | Primary content | Base size, regular | +| **Secondary** | Supporting text | Smaller, lighter color | +| **Caption** | Labels, metadata | Smallest, light | + +### Implementation Guidelines + +**DO:** +- 2:1 ratio minimum between heading levels +- Consistent application across pages +- Weight AND size differences (not just one) +- Appropriate line height per level +- Limit to 4-5 distinct levels + +**DON'T:** +- Use more than 2 typefaces +- Make headings barely bigger than body +- Use color alone for hierarchy +- Skip heading levels (H1 → H3) +- Use all caps for long text + +### Type Scale Example + +``` +Display: 48px / Bold +H1: 36px / Bold +H2: 24px / Semibold +H3: 20px / Semibold +Body: 16px / Regular +Small: 14px / Regular +Caption: 12px / Regular +``` + +--- + +## Color Hierarchy + +**What:** Using color intensity, saturation, and contrast to direct attention. + +### Hierarchy Through Color + +| Element | Color Treatment | +|---------|-----------------| +| Primary action | Brand color, high saturation | +| Secondary action | Muted/outline variant | +| Primary text | Darkest (near black) | +| Secondary text | Medium gray | +| Disabled | Light gray | +| Destructive | Red family | +| Success | Green family | + +### Implementation Guidelines + +**DO:** +- High contrast for primary elements +- Reserve saturated colors for actions/emphasis +- Use color consistently (same action = same color) +- Ensure 4.5:1 contrast ratio minimum +- Test with color blindness simulators + +**DON'T:** +- Use more than 3-4 colors for UI elements +- Use red for non-destructive actions +- Rely on color alone to convey meaning +- Make secondary elements more colorful than primary +- Use low contrast for important elements + +### Color Application + +``` +Primary action: Blue-600 (saturated) +Secondary action: Blue-100 bg + Blue-700 text +Tertiary action: Gray-200 bg + Gray-800 text +Disabled: Gray-100 bg + Gray-400 text +``` + +--- + +## Whitespace Hierarchy + +**What:** Using space to group related items and separate unrelated ones. + +### Principles + +- More space between unrelated items +- Less space between related items +- Space increases with hierarchy level +- Consistent spacing scale throughout + +### Spacing Scale + +``` +4px - Tight (icon + label) +8px - Related elements +16px - Related groups +24px - Section spacing +32px - Major section breaks +48px+ - Page-level separation +``` + +### Implementation Guidelines + +**DO:** +- Follow Law of Proximity religiously +- Use consistent spacing scale +- More space above headings than below +- Generous margins at page level +- Space proportional to importance + +**DON'T:** +- Use arbitrary spacing values +- Cram elements together +- Use equal spacing everywhere +- Separate clearly related items +- Waste space inconsistently + +--- + +## Size Hierarchy + +**What:** Using element size to indicate importance. + +### Size Principles + +- Larger = more important +- Primary actions larger than secondary +- Main content larger than supporting +- Size differences should be noticeable (1.5x minimum) + +### Button Size Example + +``` +Large: 48px height (primary page actions) +Medium: 40px height (standard actions) +Small: 32px height (inline/secondary) +X-Small: 24px height (compact contexts) +``` + +### Card Size Hierarchy + +| Purpose | Size | +|---------|------| +| Featured | Largest, spans multiple columns | +| Primary | Standard size, prominent | +| Secondary | Smaller, supporting content | +| Compact | Minimal, high-density contexts | + +--- + +## Proximity & Grouping + +**What:** Using spatial relationships to show content relationships. + +### The 4 Gestalt Laws for Hierarchy + +1. **Proximity** — Close items are related +2. **Similarity** — Similar items are related +3. **Common Region** — Items in same container are related +4. **Connectedness** — Items connected by lines are related + +### Application Examples + +**Proximity:** +- Form label + input (tight spacing) +- Form group + next group (more spacing) +- Card content grouped tightly +- Cards separated from each other + +**Similarity:** +- All navigation items styled the same +- All buttons of same importance styled the same +- All card components share style + +**Common Region:** +- Related items in same card/container +- Form fields in fieldset +- Related actions in button group + +**Connectedness:** +- Breadcrumbs connected by separators +- Stepper stages connected by line +- Related items connected by visual element + +--- + +## Contrast Hierarchy + +**What:** Using contrast differences to establish visual priority. + +### Contrast Types + +| Type | Application | +|------|-------------| +| **Color contrast** | Light/dark, saturated/muted | +| **Size contrast** | Large/small | +| **Weight contrast** | Bold/regular | +| **Density contrast** | Busy/sparse areas | +| **Motion contrast** | Static/animated | + +### Creating Focus + +**High contrast for:** +- Primary CTAs +- Important information +- Error states +- Current/active states + +**Low contrast for:** +- Secondary actions +- Supporting text +- Disabled states +- Background elements + +--- + +## Position Hierarchy + +**What:** Leveraging natural reading patterns and expectations. + +### Reading Patterns + +**F-Pattern (text-heavy pages):** +- Users scan horizontally at top +- Then vertically down left side +- Place key content along the F + +**Z-Pattern (sparse pages):** +- Users scan top left to right +- Then diagonally to bottom left +- Then across bottom +- Place CTAs at end of Z + +**Gutenberg Diagram:** +- Top left: Primary optical area (high attention) +- Top right: Strong fallow area +- Bottom left: Weak fallow area +- Bottom right: Terminal area (natural end, place CTAs) + +### Position Guidelines + +**DO:** +- Most important content top-left +- Primary actions top-right or bottom-right +- Navigation where expected (top, left) +- CTAs at natural stopping points + +**DON'T:** +- Bury primary actions bottom-left +- Place important info in weak fallow area +- Violate expectations without reason +- Scatter actions unpredictably + +--- + +## Hierarchy Patterns by Component + +### Cards + +1. **Image/media** — Visual hook, top +2. **Title** — Primary info, prominent +3. **Description** — Supporting context +4. **Metadata** — Secondary info, muted +5. **Actions** — Clear CTA, bottom + +### Tables + +1. **Header row** — Bold, sticky +2. **Key column** — Left-most, often linked +3. **Data columns** — Clear alignment +4. **Actions column** — Right side +5. **Pagination** — Below, muted + +### Forms + +1. **Form title** — Clear purpose +2. **Section headers** — Group labels +3. **Labels** — Above fields, clear +4. **Inputs** — Prominent +5. **Help text** — Below fields, muted +6. **Primary action** — Emphasized +7. **Secondary action** — De-emphasized + +### Pages + +1. **Page title** — Clear orientation +2. **Primary content** — Center/prominent +3. **Supporting content** — Secondary/sidebar +4. **Navigation** — Consistent location +5. **Actions** — Contextual, accessible + +--- + +## Hierarchy Audit + +| Element | Clear Hierarchy? | +|---------|------------------| +| ☐ Headings distinct from body | | +| ☐ Primary action obvious | | +| ☐ Related items grouped | | +| ☐ Unrelated items separated | | +| ☐ Reading flow logical | | +| ☐ Most important content prominent | | +| ☐ Consistent hierarchy across pages | | diff --git a/references/24-patterns-social-proof.md b/references/24-patterns-social-proof.md new file mode 100644 index 0000000..2ff1b77 --- /dev/null +++ b/references/24-patterns-social-proof.md @@ -0,0 +1,321 @@ +# Patterns: Social Proof + +Patterns for leveraging social influence to build trust and encourage action. + +--- + +## What is Social Proof? + +People look to others' behavior to guide their own decisions. When uncertain, we assume the crowd knows something we don't. + +**Core principle:** Show users that others have chosen, trusted, and succeeded with your product. + +--- + +## Testimonials & Reviews + +**What:** Direct quotes from satisfied users. + +### Types + +| Type | Use Case | +|------|----------| +| **Quote testimonials** | Brand credibility, landing pages | +| **Star ratings** | Quick quality signal | +| **Written reviews** | Detailed feedback, product pages | +| **Video testimonials** | High-trust, emotional impact | +| **Case studies** | B2B, complex products | + +### Psychological Principles + +- **Social proof** — Others' positive experience signals quality +- **Authority** — Expert testimonials add credibility +- **Similarity** — Relatable testimonials more persuasive + +### Implementation Guidelines + +**DO:** +- Real names, photos, roles (specific > anonymous) +- Include measurable results when possible +- Show diversity in testimonials +- Place near decision points (CTAs, pricing) +- Keep quotes concise and specific + +**DON'T:** +- Fabricate testimonials (ever) +- Use generic/vague praise ("Great product!") +- Hide negative reviews entirely (looks suspicious) +- Overwhelm with too many testimonials +- Use testimonials without permission + +### Testimonial Structure + +``` +"[Specific benefit achieved] since using [product]. +[Quantifiable result if possible]." + +— [Full Name], [Role] at [Company] +[Photo] [Logo optional] +``` + +--- + +## User-Generated Content (UGC) + +**What:** Content created by users (photos, reviews, posts) displayed as social proof. + +### Types + +- Customer photos/videos using product +- Social media posts featuring product +- Community forum activity +- User-submitted tips/guides + +### Benefits + +- **Authenticity** — Real users, not marketing +- **Scale** — Users create content for you +- **Community** — Shows active user base +- **Trust** — Peer recommendations > brand claims + +### Implementation Guidelines + +**DO:** +- Curate quality examples +- Credit creators +- Show recent activity (freshness matters) +- Include variety +- Make submission easy + +**DON'T:** +- Display low-quality content +- Use without permission +- Fake UGC +- Show outdated content +- Over-moderate (loses authenticity) + +--- + +## Activity & Usage Indicators + +**What:** Showing aggregate user behavior as social signal. + +### Types + +| Indicator | Example | +|-----------|---------| +| **User count** | "Join 50,000+ users" | +| **Activity count** | "2.5M projects created" | +| **Live activity** | "42 people viewing this" | +| **Popularity** | "Bestseller", "Trending" | +| **Engagement** | "10K+ likes" | + +### Psychological Principles + +- **Bandwagon effect** — Popular = good +- **FOMO** — Others are acting now +- **Trust numbers** — Large numbers = established + +### Implementation Guidelines + +**DO:** +- Use real, verifiable numbers +- Update numbers regularly +- Round for readability (50K not 49,847) +- Choose impressive metrics +- Place near CTAs + +**DON'T:** +- Show embarrassingly low numbers +- Fabricate statistics +- Show stale data +- Over-precise numbers (looks fake) +- Show metrics that don't matter + +### When to Show vs. Hide + +**Show when:** +- Numbers are impressive +- Metric is relevant +- Adds credibility + +**Hide when:** +- Numbers are low (new product) +- Metric is vanity +- Would cause FOMO negatively + +--- + +## Trust Badges & Certifications + +**What:** Third-party credibility signals. + +### Types + +| Badge Type | Purpose | +|------------|---------| +| **Security** | SSL, payment security, privacy compliance | +| **Certifications** | ISO, SOC2, industry standards | +| **Reviews** | G2, Capterra, TrustPilot ratings | +| **Press** | "As seen in" media logos | +| **Awards** | Industry recognition | +| **Associations** | Professional memberships | + +### Placement Guidelines + +- **Security badges** — Near payment forms, account creation +- **Certifications** — Footer, pricing page, enterprise pages +- **Review badges** — Product pages, comparison pages +- **Press logos** — Homepage, about page +- **Awards** — Wherever credibility needed + +### Implementation Guidelines + +**DO:** +- Use recognizable badges +- Link to verification where possible +- Keep current (expired certs = worse than none) +- Place near relevant decision points +- Limit quantity (3-5 max per area) + +**DON'T:** +- Use fake/made-up badges +- Overwhelm with too many badges +- Use outdated certifications +- Place irrelevant badges +- Make badges too prominent (distraction) + +--- + +## Social Media Integration + +**What:** Showing social media presence and activity. + +### Types + +- Follower counts +- Recent posts +- Share counters +- Social login options +- Embedded feeds + +### Psychological Principles + +- **Social proof** — Large following = legitimacy +- **Familiarity** — Platform logos provide comfort +- **Activity** — Active social presence = alive business + +### Implementation Guidelines + +**DO:** +- Show impressive follower counts +- Display recent, positive social activity +- Enable easy sharing +- Use recognizable social icons + +**DON'T:** +- Show low follower counts +- Embed feeds with negative comments visible +- Show outdated social activity +- Require social login as only option +- Overwhelm with too many platforms + +--- + +## Scarcity & Urgency + +**What:** Social proof through limited availability or time pressure. + +### Types + +| Pattern | Example | +|---------|---------| +| **Stock scarcity** | "Only 3 left in stock" | +| **Demand scarcity** | "12 people viewing this" | +| **Time urgency** | "Sale ends in 2:15:00" | +| **Social urgency** | "5 purchased in last hour" | + +### Psychological Principles + +- **Scarcity principle** — Less available = more valuable +- **Loss aversion** — Fear of missing out +- **Social proof** — Others want it too + +### Implementation Guidelines + +**DO:** +- Use real scarcity data +- Be truthful about urgency +- Make scarcity relevant (matters for that product) +- Use sparingly for maximum impact + +**DON'T:** +- Fake scarcity (destroys trust) +- Use constant urgency (loses impact) +- Create anxiety unnecessarily +- Use dark patterns (fake timers that reset) + +### Warning + +⚠️ Fake scarcity is a dark pattern. Users recognize it, and it destroys trust. Only use genuine scarcity signals. + +--- + +## Recommendations & Similar Users + +**What:** "People like you" suggestions. + +### Types + +- "Customers also bought" +- "Popular with [segment]" +- "Recommended for you" +- "People in [industry] love this" + +### Psychological Principles + +- **Similarity** — People like us make good choices for us +- **Authority** — Relevant peer group recommendations +- **Social proof** — Aggregated wisdom + +### Implementation Guidelines + +**DO:** +- Make the similarity relevant and specific +- Show why similar (explicit connection) +- Use real data for recommendations +- Personalize when possible +- Test recommendation algorithms + +**DON'T:** +- Use vague similarity ("customers") +- Show irrelevant recommendations +- Over-personalize (creepy) +- Recommend low-quality items +- Fabricate similarity claims + +--- + +## Social Proof Placement + +| Page/Context | Best Social Proof | +|--------------|-------------------| +| Homepage | User counts, press logos, featured testimonials | +| Pricing | Testimonials near CTAs, trust badges | +| Product page | Reviews, ratings, popularity indicators | +| Checkout | Security badges, trust signals | +| Sign-up | User counts, social login | +| Features | Case studies, specific testimonials | + +--- + +## Social Proof Audit + +| Element | Present? | Effective? | +|---------|----------|------------| +| ☐ Testimonials with real names | | | +| ☐ Quantifiable social proof | | | +| ☐ Trust badges near decisions | | | +| ☐ Social proof near CTAs | | | +| ☐ Authentic, not fabricated | | | +| ☐ Appropriate scarcity (if used) | | | diff --git a/references/25-patterns-feedback.md b/references/25-patterns-feedback.md new file mode 100644 index 0000000..a52ab77 --- /dev/null +++ b/references/25-patterns-feedback.md @@ -0,0 +1,316 @@ +# Patterns: System Feedback + +Patterns for communicating system status and action outcomes to users. + +--- + +## What is System Feedback? + +Communication from the system that keeps users informed about what's happening. Based on Nielsen's first heuristic: "Visibility of system status." + +**Core principle:** Users should never wonder what's happening. The system should always speak. + +--- + +## Progress Indicators + +**What:** Visual communication of ongoing processes. + +### Types + +| Type | Use When | +|------|----------| +| **Determinate** | Duration known (upload 45%, step 2/4) | +| **Indeterminate** | Duration unknown (spinner, loading bar) | +| **Skeleton screens** | Loading structured content | +| **Background indicator** | Process running but not blocking | + +### Timing Guidelines + +| Duration | Feedback | +|----------|----------| +| < 100ms | None needed | +| 100ms - 1s | Simple spinner | +| 1s - 10s | Progress indicator with context | +| 10s+ | Background process with notification | + +### Implementation Guidelines + +**DO:** +- Show progress immediately on action +- Use determinate when possible (more reassuring) +- Include text explaining what's happening +- Allow cancellation for long processes +- Celebrate completion (subtle success state) + +**DON'T:** +- Leave users staring at nothing +- Use spinners for > 10 seconds +- Show fake progress +- Block unnecessarily (show skeleton, load in background) +- Forget edge cases (slow connections, failures) + +### Skeleton Screens + +Best practices: +- Match layout of loading content +- Animate subtly (pulse or shimmer) +- Show as soon as structure is known +- Replace with content progressively +- Don't make more complex than the content + +--- + +## Notifications & Alerts + +**What:** System messages about events, status changes, or required attention. + +### Types by Urgency + +| Type | Persistence | Attention Level | +|------|-------------|-----------------| +| **Toast** | Auto-dismiss (3-5s) | Low, informational | +| **Banner** | Persistent until dismissed | Medium, action needed | +| **Alert/Modal** | Blocks interaction | High, immediate action | +| **Inline** | Contextual, persistent | Medium, related to specific element | + +### Notification Anatomy + +``` +[Icon] [Title] (optional) +[Message explaining what happened] +[Action button] [Dismiss] +``` + +### Implementation Guidelines (Toasts) + +**DO:** +- Brief, clear message +- Auto-dismiss (3-5 seconds typical) +- Allow manual dismiss +- Stack if multiple +- Position consistently (top-right or bottom-right common) + +**DON'T:** +- Use for errors requiring action +- Auto-dismiss critical information +- Cover important content +- Show too many simultaneously +- Require immediate reading + +### Implementation Guidelines (Banners) + +**DO:** +- Span full width (usually top of page) +- Clear close/dismiss button +- Explain what and why +- Include action if applicable +- Use semantic colors (red=error, yellow=warning, blue=info) + +**DON'T:** +- Stack multiple banners +- Use for non-critical info +- Make hard to dismiss +- Show vague messages + +--- + +## Validation Feedback + +**What:** Communicating input validity to users. + +### Validation Timing + +| Timing | Best For | +|--------|----------| +| **Real-time** | Format validation (email, phone) | +| **On blur** | Field completion check | +| **On submit** | Final validation | +| **Debounced** | Async validation (username availability) | + +### Validation States + +``` +Empty → Neutral (no validation shown) +Typing → Neutral or real-time hints +Valid → Success indicator (green check) +Invalid → Error state (red, message) +``` + +### Error Message Guidelines + +**DO:** +- Explain what's wrong specifically +- Explain how to fix it +- Place near the field +- Use plain language +- Persist until fixed + +**DON'T:** +- Use generic messages ("Invalid input") +- Blame the user ("You entered wrong value") +- Use technical jargon +- Place far from the field +- Show all errors at once without field highlighting + +### Examples + +| Bad | Good | +|-----|------| +| "Invalid email" | "Enter a valid email address (e.g., name@example.com)" | +| "Required field" | "Email is required" | +| "Password error" | "Password must be at least 8 characters" | +| "Error" | "This username is already taken. Try another." | + +--- + +## Success Feedback + +**What:** Confirming successful completion of actions. + +### Types + +| Type | Use Case | +|------|----------| +| **Inline** | Form field valid, item added | +| **Toast** | Action completed successfully | +| **Success page** | Major workflow complete | +| **Animation** | Delightful confirmation | + +### Success Message Guidelines + +**DO:** +- Confirm what was accomplished +- Indicate next steps if applicable +- Be brief but clear +- Match tone to significance +- Celebrate appropriately + +**DON'T:** +- Over-celebrate minor actions +- Be vague about what succeeded +- Require action to dismiss (usually) +- Miss the success feedback entirely + +### Examples + +``` +Minor: ✓ (checkmark appears) +Standard: "Changes saved" +Significant: "Your order is confirmed! Check your email for details." +Major: [Success page with next steps] +``` + +--- + +## Contextual Help + +**What:** In-context guidance and explanation. + +### Types + +| Type | Use Case | +|------|----------| +| **Tooltips** | Icon/term explanations | +| **Inline hints** | Form field guidance | +| **Helper text** | Persistent guidance below inputs | +| **Info icons** | "What's this?" explanations | +| **Empty states** | Guidance when no content | + +### Implementation Guidelines + +**DO:** +- Explain *why*, not just *what* +- Use plain language +- Keep contextual (near related element) +- Make optional (not blocking) +- Provide examples when helpful + +**DON'T:** +- Over-explain obvious things +- Use tooltips for critical info +- Write novels in helper text +- Hide essential instructions +- Require reading help to complete task + +### Help Text Examples + +**Form fields:** +``` +Label: Password +Input: ******** +Helper: At least 8 characters with one number and symbol. +``` + +**Feature explanation:** +``` +[i] What are workspaces? +→ Workspaces let you organize projects into separate + areas. Each workspace has its own members and settings. +``` + +--- + +## Empty States + +**What:** Feedback when there's no content to display. + +### Empty State Anatomy + +``` +[Illustration/Icon] (optional) +[Title explaining the state] +[Description of what goes here and why it's empty] +[CTA to add content or take action] +``` + +### Types + +| Type | Cause | Response | +|------|-------|----------| +| **First use** | New user, no data | Guide to create first item | +| **No results** | Search/filter with no matches | Suggest adjustments | +| **Cleared** | User deleted content | Confirm empty, offer restore | +| **Error** | Failed to load | Explain and offer retry | + +### Implementation Guidelines + +**DO:** +- Explain why it's empty +- Provide clear action to fix +- Match tone to context +- Design for the state (don't ignore it) +- Use as opportunity to educate + +**DON'T:** +- Leave completely blank +- Just say "No results" +- Make user feel they did something wrong +- Offer irrelevant actions +- Use generic illustration for every state + +--- + +## Feedback Timing Matrix + +| Action Type | Immediate | Short Delay | Background | +|-------------|-----------|-------------|------------| +| Button click | Visual state change | - | - | +| Form submit | Disable + spinner | Success/error toast | - | +| Save | Inline "saving..." | "Saved" confirmation | - | +| Upload | Progress bar | Completion toast | Status in UI | +| Long process | Initiated message | - | Notification when done | + +--- + +## Feedback Audit + +| Element | Feedback Present? | +|---------|-------------------| +| ☐ Loading states defined | | +| ☐ Success feedback clear | | +| ☐ Error states helpful | | +| ☐ Validation timing appropriate | | +| ☐ Empty states designed | | +| ☐ Help available in context | | +| ☐ Progress visible for long actions | | diff --git a/references/26-patterns-error-handling.md b/references/26-patterns-error-handling.md new file mode 100644 index 0000000..fdfa156 --- /dev/null +++ b/references/26-patterns-error-handling.md @@ -0,0 +1,288 @@ +# Patterns: Error Prevention & Handling + +Patterns for preventing errors and helping users recover gracefully. + +--- + +## Core Philosophy + +**Prevention > Recovery > Graceful Failure** + +The best error is the one that never happens. The second best is the one users can easily fix. + +--- + +## Error Prevention + +### Constraints + +**What:** Limiting input to valid options. + +| Technique | Example | +|-----------|---------| +| **Input masks** | Phone: (___) ___-____ | +| **Dropdowns** | Choose from valid options | +| **Date pickers** | Can't type invalid dates | +| **Range limits** | min/max on number inputs | +| **Character limits** | maxlength on text | +| **Disabled states** | Can't click invalid options | + +### Guidance + +**What:** Helping users get it right the first time. + +| Technique | Example | +|-----------|---------| +| **Inline hints** | "Password must be 8+ characters" | +| **Examples** | "e.g., name@example.com" | +| **Format indicators** | Showing expected format | +| **Real-time validation** | Check as user types | +| **Autocomplete** | Suggest valid values | + +### Confirmations + +**What:** Verifying destructive or irreversible actions. + +**Use confirmation dialogs for:** +- Deleting data +- Canceling subscriptions +- Sending to many recipients +- Actions that can't be undone +- Financial transactions + +**Don't overuse:** Confirmation fatigue makes users click through without reading. + +--- + +## Form Validation + +### Validation Approaches + +| Approach | Pros | Cons | +|----------|------|------| +| **On blur** | Good balance, validates after field | Slight delay | +| **On submit** | Simple to implement | Errors appear late | +| **Real-time** | Immediate feedback | Can be annoying | +| **Debounced** | Good for async checks | Timing tuning needed | + +### Recommended Approach + +1. **Format validation** → Real-time or on blur +2. **Required fields** → On blur or on submit +3. **Async validation** → Debounced (300-500ms) +4. **Cross-field validation** → On submit + +### Error Display Guidelines + +**DO:** +- Show error adjacent to the field +- Use red color + icon (accessible) +- Explain the problem specifically +- Explain how to fix it +- Highlight invalid field +- Scroll to first error + +**DON'T:** +- Show only at page top +- Clear user input on error +- Use only color to indicate error +- Show technical error codes +- Reset the entire form + +### Error Message Template + +``` +[What's wrong] + [How to fix it] + +Examples: +"Email must include @" → "Enter a valid email (e.g., name@example.com)" +"Password too short" → "Password must be at least 8 characters" +"Username taken" → "This username is taken. Try adding numbers or underscores." +``` + +--- + +## Undo & Redo + +**What:** Allowing users to reverse their actions. + +### When to Implement Undo + +- Destructive actions (delete, archive, remove) +- Significant changes (formatting, reorganizing) +- Accidental actions (easy to mis-click) +- Actions without confirmation dialog + +### Implementation Patterns + +**Soft delete:** +- Move to trash instead of permanent delete +- Show "Undo" toast with time limit +- Allow recovery from trash + +**Action undo:** +- "Undo" button in success toast +- Keyboard shortcut (Cmd/Ctrl+Z) +- Undo stack for multiple actions + +**Draft preservation:** +- Auto-save drafts +- Recover unsaved work +- Version history + +### Guidelines + +**DO:** +- Provide undo for destructive actions +- Show clear undo affordance +- Time-limit undo window (5-30 seconds) +- Make undo discoverable +- Support keyboard shortcuts + +**DON'T:** +- Require confirmation AND undo (choose one) +- Make undo window too short +- Hide undo affordance +- Forget redo after undo + +--- + +## Error Dialogs + +**What:** Communicating system errors to users. + +### Error Dialog Anatomy + +``` +[Icon] [Error Title] + +[Clear explanation of what happened] +[What the user can do about it] + +[Primary Action] [Secondary Action] +``` + +### Error Types + +| Type | Tone | Recovery Options | +|------|------|------------------| +| **User error** | Helpful, not blaming | Explain how to fix | +| **System error** | Apologetic | Retry, contact support | +| **Network error** | Informative | Retry when connected | +| **Permission error** | Clear | Request access, explain why | + +### Error Message Examples + +| Bad | Good | +|-----|------| +| "Error 500" | "Something went wrong on our end. Please try again." | +| "Invalid operation" | "You don't have permission to delete this. Contact an admin." | +| "Failed" | "Couldn't save your changes. Check your connection and try again." | +| "Null pointer exception" | "Something unexpected happened. Our team has been notified." | + +### Guidelines + +**DO:** +- Use human language +- Explain what happened +- Offer recovery action +- Log details for debugging (not shown to user) +- Apologize when it's system's fault + +**DON'T:** +- Show technical details to users +- Blame the user +- Leave users stuck +- Use jargon +- Panic the user ("FATAL ERROR") + +--- + +## Autosave & Data Recovery + +**What:** Preventing data loss through automatic preservation. + +### Autosave Strategies + +| Strategy | Best For | +|----------|----------| +| **Continuous** | Text editors, forms (debounced) | +| **On change** | Settings, toggles | +| **On blur** | Form fields | +| **Periodic** | Long-form content (every 30-60s) | +| **Before navigation** | Forms with unsaved changes | + +### Implementation Guidelines + +**DO:** +- Indicate save status ("Saved", "Saving...", "Changes pending") +- Save to server when possible +- Fall back to local storage +- Recover on return +- Warn before navigating away with unsaved changes + +**DON'T:** +- Save too frequently (server load) +- Save too infrequently (data loss risk) +- Fail silently +- Overwrite without user awareness +- Rely only on local storage (not synced) + +### Unsaved Changes Warning + +``` +[Modal] +"You have unsaved changes" + +If you leave, your changes will be lost. + +[Leave anyway] [Stay and save] +``` + +--- + +## Graceful Degradation + +**What:** Maintaining functionality when things go wrong. + +### Strategies + +| Failure | Graceful Response | +|---------|-------------------| +| Network down | Show cached data, queue actions | +| Feature fails | Disable feature, don't crash | +| Image fails | Show placeholder | +| Third-party down | Fallback or skip gracefully | +| Timeout | Auto-retry, then explain | + +### Guidelines + +**DO:** +- Anticipate failure modes +- Provide fallbacks +- Inform users of degraded state +- Maintain core functionality +- Auto-retry where appropriate + +**DON'T:** +- Let one failure cascade +- Show blank screens +- Hide degraded state +- Require user action for every failure +- Give up on first error + +--- + +## Error Prevention Checklist + +| Area | Techniques Applied | +|------|-------------------| +| ☐ Input constraints (masks, limits) | | +| ☐ Guidance before errors occur | | +| ☐ Confirmation for destructive actions | | +| ☐ Appropriate validation timing | | +| ☐ Clear, actionable error messages | | +| ☐ Undo for reversible actions | | +| ☐ Autosave for data preservation | | +| ☐ Graceful handling of system errors | | +| ☐ Recovery options always available | | diff --git a/references/27-patterns-accessibility.md b/references/27-patterns-accessibility.md new file mode 100644 index 0000000..4bde846 --- /dev/null +++ b/references/27-patterns-accessibility.md @@ -0,0 +1,333 @@ +# Patterns: Accessibility + +Patterns for ensuring interfaces are usable by everyone. + +--- + +## Why Accessibility Matters + +- **Legal** — ADA, Section 508, WCAG compliance requirements +- **Ethical** — Equal access is a design responsibility +- **Business** — 15%+ of users have some disability +- **Quality** — Accessible design improves UX for everyone + +**Core principle:** Accessibility is not a checklist item—it's a design approach. + +--- + +## Keyboard Navigation + +**What:** Full functionality without a mouse. + +### Requirements + +| Pattern | Keyboard Support | +|---------|------------------| +| **Focus order** | Tab moves logically through page | +| **Focus visible** | Current focus always visible | +| **Activation** | Enter/Space activates buttons/links | +| **Navigation** | Arrow keys navigate within components | +| **Escape** | Escape closes modals/popups | +| **Shortcuts** | Common shortcuts available | + +### Focus Order Principles + +1. Follow visual reading order (left-to-right, top-to-bottom) +2. Skip decorative/non-interactive elements +3. Group related controls +4. Don't trap focus (except in modals) +5. Return focus appropriately after interactions + +### Implementation Guidelines + +**DO:** +- Use semantic HTML (inherits keyboard support) +- Provide visible focus indicators (not outline: none) +- Test with keyboard only +- Support standard keyboard patterns +- Announce changes to screen readers + +**DON'T:** +- Use div/span for interactive elements (without ARIA) +- Remove focus outlines without replacement +- Create custom interactions without keyboard support +- Change focus order unpredictably +- Trap users in infinite tab loops + +### Focus Indicator Styling + +```css +/* Visible, high contrast focus */ +:focus-visible { + outline: 2px solid #2563eb; + outline-offset: 2px; +} + +/* Remove default only when custom is applied */ +button:focus { + outline: none; + box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.5); +} +``` + +--- + +## ARIA Attributes + +**What:** Accessible Rich Internet Applications—additional semantics for assistive technology. + +### Core ARIA Rules + +1. **First rule:** Don't use ARIA if native HTML works +2. **Second rule:** Don't change native semantics +3. **Third rule:** All interactive ARIA must be keyboard accessible +4. **Fourth rule:** Don't use role="presentation" on focusable elements +5. **Fifth rule:** All interactive elements must have accessible names + +### Essential ARIA Attributes + +| Attribute | Purpose | Example | +|-----------|---------|---------| +| `aria-label` | Accessible name | `` | +| `aria-describedby` | Additional description | Links to help text | +| `aria-hidden` | Hide from assistive tech | Decorative elements | +| `aria-expanded` | Toggle state | Accordions, dropdowns | +| `aria-selected` | Selection state | Tabs, list items | +| `aria-live` | Announce changes | Dynamic content | +| `aria-invalid` | Invalid state | Form validation | +| `aria-required` | Required field | Form fields | + +### Common Patterns + +**Button with icon only:** +```html + +``` + +**Accordion:** +```html + + +``` + +**Live region:** +```html +
+ +
+``` + +--- + +## Alternative Text + +**What:** Text equivalents for non-text content. + +### Alt Text Guidelines + +**Informative images:** +- Describe the content/function +- Be concise but complete +- Don't include "image of" or "picture of" + +**Decorative images:** +- Use empty alt: `alt=""` +- Or use `aria-hidden="true"` + +**Functional images (buttons/links):** +- Describe the action, not the image +- "Submit form" not "arrow icon" + +**Complex images:** +- Provide detailed description nearby +- Use `aria-describedby` to link +- Consider data tables for charts + +### Examples + +| Image | Bad Alt | Good Alt | +|-------|---------|----------| +| Logo | "Logo" | "Acme Corp" | +| Search icon | "Magnifying glass" | "Search" | +| Product photo | "Photo" | "Blue cotton t-shirt, front view" | +| Decorative border | "Border" | `alt=""` (empty) | +| Chart | "Chart" | "Sales increased 25% from Q1 to Q2" + full data table | + +--- + +## Color & Contrast + +**What:** Ensuring content is perceivable regardless of color vision. + +### Contrast Requirements + +| Content | Minimum Ratio | Target Ratio | +|---------|---------------|--------------| +| Normal text | 4.5:1 | 7:1 (AAA) | +| Large text (18px+) | 3:1 | 4.5:1 (AAA) | +| UI components | 3:1 | 4.5:1 | +| Focus indicators | 3:1 | 4.5:1 | + +### Color Guidelines + +**DO:** +- Use high contrast combinations +- Include patterns/icons in addition to color +- Test with color blindness simulators +- Provide color contrast alternatives +- Verify with automated tools + +**DON'T:** +- Use color as the only indicator +- Use low contrast text +- Place colored text on similar backgrounds +- Assume everyone sees the same colors +- Use red/green as the only differentiator + +### Color + Pattern Example + +``` +✓ Success (green check icon + green color) +✗ Error (red X icon + red color + border) +! Warning (yellow triangle icon + yellow background) +``` + +--- + +## Text & Readability + +**What:** Ensuring text is readable by all users. + +### Guidelines + +**Font size:** +- Minimum 16px for body text +- Support browser zoom up to 200% +- Use relative units (rem, em) + +**Line length:** +- 45-75 characters per line +- Max-width on text containers + +**Line height:** +- 1.5 minimum for body text +- 1.2 minimum for headings + +**Font choice:** +- Sans-serif for UI +- Avoid decorative fonts for body +- Adequate x-height + +**Text resizing:** +- Content must remain usable at 200% zoom +- No horizontal scrolling at 320px width + +--- + +## Interactive Elements + +**What:** Making interactive elements accessible. + +### Minimum Sizes + +| Element | Minimum Size | Target Size | +|---------|--------------|-------------| +| Touch targets | 44x44px | 48x48px | +| Click targets | 24x24px | 32x32px | +| Spacing between | 8px | 12px | + +### Element Guidelines + +**Links:** +- Descriptive text (not "click here") +- Distinguish from regular text +- Show visited state +- Focus + hover states + +**Buttons:** +- Clear labels +- Sufficient size +- Visible states (hover, focus, active, disabled) +- Keyboard accessible + +**Forms:** +- Labels associated with inputs +- Error messages linked (aria-describedby) +- Required fields indicated +- Group related fields (fieldset/legend) + +--- + +## Motion & Animation + +**What:** Respecting user preferences for reduced motion. + +### Guidelines + +**DO:** +- Respect `prefers-reduced-motion` +- Keep animations subtle +- Allow users to pause/stop animations +- Avoid flashing content (seizure risk) + +**DON'T:** +- Auto-play video with motion +- Use fast/flashing animations +- Create vestibular triggers +- Force users to watch animations + +### Implementation + +```css +@media (prefers-reduced-motion: reduce) { + * { + animation: none !important; + transition: none !important; + } +} +``` + +--- + +## Screen Reader Testing + +**What:** Verifying experience for screen reader users. + +### Testing Checklist + +☐ All images have appropriate alt text +☐ Headings create logical outline (H1 → H2 → H3) +☐ Links and buttons have descriptive names +☐ Form labels are associated with inputs +☐ Error messages are announced +☐ Dynamic content changes are announced +☐ Focus management works after interactions +☐ Page title is descriptive + +### Screen Readers to Test + +- **VoiceOver** — macOS/iOS (built-in) +- **NVDA** — Windows (free) +- **JAWS** — Windows (paid, enterprise standard) +- **TalkBack** — Android (built-in) + +--- + +## Accessibility Checklist + +| Category | Requirements | +|----------|--------------| +| ☐ **Keyboard** | All functions keyboard accessible | +| ☐ **Focus** | Visible focus indicators | +| ☐ **Semantics** | Proper HTML elements + ARIA | +| ☐ **Images** | Alt text for all meaningful images | +| ☐ **Color** | Not the only differentiator | +| ☐ **Contrast** | 4.5:1 for text, 3:1 for UI | +| ☐ **Text** | Resizable, readable, proper hierarchy | +| ☐ **Motion** | Reducible, not seizure-inducing | +| ☐ **Forms** | Labels, errors, required indicators | +| ☐ **Testing** | Verified with screen reader | diff --git a/references/28-patterns-personalization.md b/references/28-patterns-personalization.md new file mode 100644 index 0000000..bf2da39 --- /dev/null +++ b/references/28-patterns-personalization.md @@ -0,0 +1,332 @@ +# Patterns: Personalization + +Patterns for adapting interfaces to individual users. + +--- + +## What is Personalization? + +Tailoring the interface, content, or functionality based on user data, preferences, or behavior. The goal is relevance—showing users what matters to them. + +**Spectrum:** +- **Customization** — User explicitly sets preferences +- **Personalization** — System adapts based on data/behavior + +--- + +## Customizable Dashboards + +**What:** User-configured layouts and widgets. + +### Benefits + +- **Relevance** — Users see what matters to them +- **Ownership** — IKEA effect (they built it) +- **Efficiency** — Quick access to frequent needs + +### Implementation Guidelines + +**DO:** +- Provide useful defaults (don't start empty) +- Make customization discoverable but not required +- Allow adding, removing, rearranging widgets +- Save preferences across sessions +- Offer presets/templates + +**DON'T:** +- Require customization to use the product +- Make defaults unusable +- Overwhelm with options +- Reset customization without warning +- Hide the reset/restore option + +### Widget Patterns + +| Pattern | Use For | +|---------|---------| +| **Drag-and-drop** | Rearranging layout | +| **Widget picker** | Adding new widgets | +| **Resize handles** | Adjusting widget size | +| **Edit mode** | Toggled customization state | +| **Templates** | Starting point presets | + +--- + +## Adaptive Content + +**What:** Content that changes based on user behavior or context. + +### Types + +| Type | Basis | Example | +|------|-------|---------| +| **Role-based** | User role/permissions | Admin vs. user views | +| **Behavior-based** | Past actions | "Continue where you left off" | +| **Context-based** | Current state | Location, device, time | +| **Preference-based** | Explicit settings | Language, theme | + +### Implementation Guidelines + +**DO:** +- Explain why content is personalized +- Allow users to dismiss/adjust +- Respect privacy expectations +- Provide value (not just surveillance) +- Fall back gracefully to defaults + +**DON'T:** +- Be creepy (mentioning private data) +- Over-personalize (filter bubble) +- Personalize without value +- Remove access to non-personalized views +- Trap users in narrow recommendations + +### Transparency Patterns + +``` +"Based on your recent projects" +"Because you viewed [X]" +"Popular in your region" +[See all] | [Hide these suggestions] +``` + +--- + +## User Preferences + +**What:** Settings users explicitly configure. + +### Common Preference Categories + +| Category | Examples | +|----------|----------| +| **Display** | Theme, density, font size | +| **Communication** | Email frequency, notification types | +| **Privacy** | Data sharing, tracking | +| **Regional** | Language, timezone, currency | +| **Workflow** | Default views, keyboard shortcuts | + +### Implementation Guidelines + +**DO:** +- Group preferences logically +- Provide clear defaults +- Explain impact of settings +- Apply immediately (or show preview) +- Sync across devices + +**DON'T:** +- Create endless settings pages +- Hide important preferences +- Require restart for simple changes +- Use jargon in preference names +- Set anti-user defaults + +### Settings Page Patterns + +**Grouped settings:** +``` +Account + - Profile + - Security + - Privacy + +Preferences + - Appearance + - Notifications + - Language & Region + +Integrations + - Connected apps + - API keys +``` + +**Inline settings:** +``` +[Toggle] Enable email notifications + Get notified about new messages + +[Dropdown] Frequency: [Daily digest ▼] +``` + +--- + +## Localization (l10n) + +**What:** Adapting interfaces for different languages and regions. + +### Key Considerations + +| Element | Localization Needs | +|---------|-------------------| +| **Text** | Translation, expansion space | +| **Dates** | Format varies by region | +| **Numbers** | Decimal/thousand separators | +| **Currency** | Symbol, position, format | +| **Direction** | LTR vs. RTL layouts | +| **Images** | Cultural appropriateness | +| **Legal** | Region-specific requirements | + +### Implementation Guidelines + +**DO:** +- Design for text expansion (German ~30% longer) +- Use Unicode/UTF-8 throughout +- Externalize strings (no hardcoding) +- Support RTL layouts +- Test with real translations +- Consider cultural context + +**DON'T:** +- Concatenate strings for sentences +- Use flags for language selection +- Assume formats (dates, addresses) +- Hardcode text in images +- Use culturally specific idioms + +### Text Expansion Guidelines + +| Language | Expansion vs. English | +|----------|----------------------| +| German | +30% | +| French | +20% | +| Spanish | +20% | +| Chinese | -30% (but vertical space) | +| Japanese | -20% | +| Arabic | +25% (RTL) | + +--- + +## Smart Defaults + +**What:** Pre-selecting the most likely option. + +### Default Sources + +| Source | Example | +|--------|---------| +| **User history** | Last used option | +| **User profile** | Location-based defaults | +| **Behavior patterns** | Most common choice | +| **Context** | Time-appropriate defaults | +| **System intelligence** | ML-predicted preference | + +### Implementation Guidelines + +**DO:** +- Save and reuse user preferences +- Use sensible fallbacks +- Make overriding easy +- Be transparent about defaults +- Respect explicit user choices + +**DON'T:** +- Force users into defaults +- Reset preferences unexpectedly +- Use defaults against user interest +- Make changing defaults hard +- Assume all users are the same + +### Examples + +``` +New document: Default to last-used template +Date picker: Default to today +Country: Default to detected location +Currency: Default to account currency +Recipient: Default to recent contacts +``` + +--- + +## Recommendation Systems + +**What:** Suggesting content based on user data. + +### Types + +| Type | Basis | Example | +|------|-------|---------| +| **Collaborative** | Similar users' behavior | "Users like you also bought" | +| **Content-based** | Item similarity | "Similar to items you viewed" | +| **Hybrid** | Combined approaches | "Recommended for you" | + +### Implementation Guidelines + +**DO:** +- Explain recommendation basis +- Allow feedback (helpful/not helpful) +- Include diversity (avoid filter bubble) +- Update recommendations regularly +- Provide "see more like this" options + +**DON'T:** +- Show only narrow recommendations +- Recommend items already purchased/viewed +- Use recommendations for upselling only +- Hide non-recommended options +- Persist stale recommendations + +### Recommendation UI Patterns + +``` +"Because you watched [X]" +[Thumbnail] [Thumbnail] [Thumbnail] + [See all →] + +"Popular with marketers" +[Item] [Item] [Item] +[Not interested] +``` + +--- + +## Progressive Profiles + +**What:** Building user profiles over time rather than all at once. + +### Benefits + +- **Reduced friction** — Don't ask everything upfront +- **Better data** — Ask in context when relevant +- **Ongoing relationship** — Learn more over time + +### Implementation Guidelines + +**DO:** +- Ask for minimum to start +- Request additional info contextually +- Explain why you're asking +- Make additions optional +- Show value of providing info + +**DON'T:** +- Front-load all questions +- Ask for irrelevant information +- Require full profiles to start +- Nag for profile completion +- Ask repeatedly for declined info + +### Contextual Profile Building + +``` +[First use] → Email only +[First project] → "What type of project is this?" (improves suggestions) +[Two weeks in] → "Add profile photo for team collaboration" +[First export] → "What file formats do you prefer?" (remembers choice) +``` + +--- + +## Personalization Audit + +| Element | Implemented? | Value to User? | +|---------|--------------|----------------| +| ☐ Customizable dashboard | | | +| ☐ Saved preferences | | | +| ☐ Smart defaults | | | +| ☐ Content recommendations | | | +| ☐ Regional localization | | | +| ☐ Progressive profiling | | | +| ☐ User-controlled options | | | +| ☐ Transparency about personalization | | | diff --git a/references/29-patterns-onboarding.md b/references/29-patterns-onboarding.md new file mode 100644 index 0000000..9ea895d --- /dev/null +++ b/references/29-patterns-onboarding.md @@ -0,0 +1,351 @@ +# Patterns: Onboarding + +Patterns for introducing users to your product and helping them reach value quickly. + +--- + +## What is Onboarding? + +The process of helping new users understand and succeed with your product. Goal: Get users to their "aha moment" as fast as possible. + +**Core principle:** Onboarding isn't about teaching features—it's about delivering value. + +--- + +## Product Tours + +**What:** Guided walkthroughs highlighting key features. + +### Types + +| Type | Best For | +|------|----------| +| **Linear tour** | Simple products, sequential workflows | +| **Spotlight tour** | Complex products, key features only | +| **Interactive tour** | Learning by doing | +| **Video tour** | Complex concepts, emotional connection | + +### Implementation Guidelines + +**DO:** +- Keep it short (3-5 steps max) +- Focus on value, not features +- Allow skipping +- Make it contextual (trigger at right moment) +- Test completion rates + +**DON'T:** +- Force users to complete tour +- Cover every feature +- Block user from exploring +- Repeat tour without consent +- Show tour to returning users + +### Tour Step Anatomy + +``` +[Highlight area] + +Step 2 of 4 + +Create your first project +Click here to start building. Projects +organize your work and team collaboration. + +[Got it] [Skip tour] + +● ● ○ ○ (progress dots) +``` + +--- + +## Contextual Tips + +**What:** Help that appears when and where relevant. + +### Types + +| Type | Trigger | Example | +|------|---------|---------| +| **Tooltips** | Hover/focus | Icon explanations | +| **Coach marks** | First visit to area | Feature introduction | +| **Hotspots** | Available anytime | Pulsing indicator for help | +| **Inline hints** | Contextual | Empty state guidance | + +### Implementation Guidelines + +**DO:** +- Appear at point of need +- Dismiss after shown once (usually) +- Focus on one thing at a time +- Be genuinely helpful +- Allow users to re-access tips + +**DON'T:** +- Interrupt user workflows +- Show too many at once +- Repeat dismissed tips +- Block interaction +- State the obvious + +### Contextual Tip Timing + +| Trigger | When to Show | +|---------|--------------| +| First visit | User reaches feature for first time | +| Feature discovery | User hovers/focuses on new element | +| Error recovery | User makes mistake, offer guidance | +| Idle state | User seems stuck | +| Feature release | New feature for existing users | + +--- + +## Interactive Tutorials + +**What:** Learning by doing within the product. + +### Benefits + +- **Active learning** — More effective than passive +- **Real context** — Learning in actual interface +- **Immediate value** — Complete real tasks +- **Verification** — Confirm understanding + +### Implementation Guidelines + +**DO:** +- Use real product, not simulated +- Start with high-value task +- Provide clear success criteria +- Celebrate completion +- Allow exploration + +**DON'T:** +- Create fake practice environments +- Make tutorials too long +- Prevent users from deviating +- Penalize mistakes +- Make completion mandatory + +### Interactive Tutorial Structure + +``` +1. Introduction (why this matters) +2. Task instruction (what to do) +3. Action (user does the thing) +4. Confirmation (success feedback) +5. Context (what else you can do) +``` + +--- + +## Checklists + +**What:** Progress trackers for setup or learning. + +### Benefits + +- **Clear progress** — Sense of advancement +- **Motivation** — Goal gradient effect +- **Structure** — Know what's next +- **Completion drive** — Zeigarnik effect + +### Implementation Guidelines + +**DO:** +- Start with easy wins (first items) +- Show progress percentage +- Celebrate completions +- Make items actionable (link to action) +- Allow dismissal + +**DON'T:** +- Include too many items (5-7 max) +- Make all items mandatory +- Reset progress +- Hide the checklist +- Nag about incomplete items + +### Checklist UI Pattern + +``` +Get Started with [Product] +━━━━━━━━━━░░░░░░ 60% complete + +✓ Create your account +✓ Add your first project +✓ Invite a team member +○ Connect your calendar +○ Set your preferences + +[Continue →] + +[Dismiss for now] +``` + +--- + +## Empty States + +**What:** Onboarding when there's no content yet. + +### Empty State as Onboarding + +| State | Opportunity | +|-------|-------------| +| No projects | "Create your first project" | +| No data | "Import your existing data" | +| No connections | "Connect your tools" | +| No team | "Invite your team" | + +### Implementation Guidelines + +**DO:** +- Explain what goes here +- Provide clear CTA to populate +- Show what it will look like (sample data) +- Offer templates/presets +- Be encouraging + +**DON'T:** +- Leave completely empty +- Use generic "No data" messages +- Assume user knows what to do +- Hide the empty state help +- Make user feel lost + +### Empty State Anatomy + +``` +[Illustration] + +No projects yet + +Projects help you organize your work and +collaborate with your team. + +[Create your first project] + +or [Start with a template] +``` + +--- + +## Progressive Onboarding + +**What:** Spreading onboarding over time vs. all at once. + +### Approach + +| Time | Onboarding Focus | +|------|------------------| +| **Signup** | Absolute minimum (email, password) | +| **First session** | Core value action only | +| **Second session** | Secondary features | +| **First week** | Deeper functionality | +| **Ongoing** | Advanced features, tips | + +### Implementation Guidelines + +**DO:** +- Front-load value, not setup +- Introduce features when relevant +- Remember what's been shown +- Personalize based on behavior +- Celebrate milestones + +**DON'T:** +- Dump everything at once +- Show irrelevant features +- Repeat already-learned content +- Ignore user progress +- Rush to "completion" + +### Progressive Disclosure Example + +``` +Day 1: "Create your first [X]" +Day 3: "You've created 3 projects! Try organizing with folders." +Day 7: "Ready for advanced filters? Here's a quick tip." +Day 14: "Power user tip: keyboard shortcuts" +``` + +--- + +## Onboarding for Different Users + +### By User Type + +| User Type | Onboarding Approach | +|-----------|---------------------| +| **New to category** | Concept education + product tour | +| **Experienced user** | Skip basics, highlight differentiators | +| **Returning user** | Show what's new | +| **Invited user** | Context about who invited and why | + +### Segmented Onboarding + +``` +[During signup or first run] + +What brings you here today? + +○ I'm exploring [category] for the first time +○ I'm switching from another tool +○ I was invited by my team +○ Just browsing + +[Continue] +``` + +--- + +## Measuring Onboarding Success + +### Key Metrics + +| Metric | What it Tells You | +|--------|-------------------| +| **Activation rate** | % reaching first value moment | +| **Time to value** | How long to reach aha moment | +| **Tour completion** | % completing onboarding steps | +| **Drop-off points** | Where users abandon | +| **Feature adoption** | Which features stick | + +### Optimization + +1. Define your activation event (what = success?) +2. Measure current baseline +3. Identify friction points +4. Test improvements +5. Monitor retention correlation + +--- + +## Onboarding Anti-Patterns + +| Anti-Pattern | Problem | +|--------------|---------| +| **Tour torture** | Forced, unskippable 15-step tour | +| **Sign-up interrogation** | 10 fields before seeing product | +| **Feature vomit** | Explaining everything at once | +| **Permanent tooltips** | Tips that never go away | +| **Guilt tripping** | "You haven't completed setup!" | +| **Fake progress** | Progress bars that reset | +| **No escape** | Can't use product without tutorial | + +--- + +## Onboarding Checklist + +| Element | Implemented? | +|---------|--------------| +| ☐ Clear value proposition upfront | | +| ☐ Minimal signup friction | | +| ☐ First-run experience designed | | +| ☐ Empty states guide action | | +| ☐ Contextual tips available | | +| ☐ Progress indicators visible | | +| ☐ Tours skippable | | +| ☐ Success celebrations | | +| ☐ Measuring activation | | diff --git a/references/30-patterns-information.md b/references/30-patterns-information.md new file mode 100644 index 0000000..46ab606 --- /dev/null +++ b/references/30-patterns-information.md @@ -0,0 +1,397 @@ +# Patterns: Information Relationships + +Patterns for organizing, relating, and surfacing content. + +--- + +## What are Information Relationships? + +How content connects, relates, and is organized. Good information architecture makes content findable and understandable. + +**Core principle:** Users should always know where they are, how they got there, and where they can go. + +--- + +## Breadcrumbs + +**What:** Hierarchical trail showing location in site structure. + +### Types + +| Type | Use Case | +|------|----------| +| **Hierarchy-based** | Shows parent/child path (Home > Category > Item) | +| **History-based** | Shows pages visited (like browser back) | +| **Attribute-based** | Shows filters/selections applied | + +### Benefits + +- **Orientation** — Users know where they are +- **Efficiency** — Quick navigation to parent levels +- **Context** — Understand content hierarchy +- **Recovery** — Easy return to previous levels + +### Implementation Guidelines + +**DO:** +- Use for sites with 3+ hierarchy levels +- Link all but current page +- Use separator (/ or >) between levels +- Truncate long trails intelligently +- Position consistently (top of content area) + +**DON'T:** +- Use for flat site structures +- Make current page a link +- Use breadcrumbs as primary navigation +- Show breadcrumbs on homepage +- Inconsistent placement across pages + +### Breadcrumb Examples + +**Standard:** +``` +Home / Products / Electronics / Headphones +``` + +**Attribute-based:** +``` +Headphones > Over-ear > Wireless > Sony +``` + +**Truncated:** +``` +Home / ... / Category / Subcategory / Item +``` + +--- + +## Sitemaps & Information Architecture + +**What:** Structured overview of all site content. + +### Sitemap Types + +| Type | Purpose | +|------|---------| +| **Visual sitemap** | Design/planning tool | +| **HTML sitemap** | User-facing page listing | +| **XML sitemap** | SEO, search engine crawling | + +### IA Organization Schemes + +| Scheme | Examples | +|--------|----------| +| **Alphabetical** | Directories, glossaries | +| **Chronological** | News, blog archives | +| **Geographical** | Store locators, regional content | +| **Topical** | Subject-based categories | +| **Task-based** | What users want to do | +| **Audience-based** | By user type (admin, user) | + +### IA Principles + +**DO:** +- Organize by user mental model +- Use card sorting to validate +- Limit depth (3-4 levels max) +- Use clear, descriptive labels +- Cross-link related content + +**DON'T:** +- Organize by org structure +- Create deep hierarchies +- Use internal jargon +- Duplicate content in multiple places +- Forget search as navigation + +--- + +## Tagging & Categorization + +**What:** Metadata that makes content findable and relatable. + +### Categories vs. Tags + +| Categories | Tags | +|------------|------| +| Hierarchical | Flat | +| Mutually exclusive | Multiple allowed | +| Pre-defined | Often user-created | +| Broad classification | Specific descriptors | +| Navigation structure | Discovery/filtering | + +### Implementation Guidelines + +**DO:** +- Define clear taxonomy +- Limit tag proliferation (governance) +- Show related content via shared tags +- Allow multiple tags per item +- Make tags clickable (for discovery) + +**DON'T:** +- Over-tag content +- Create overlapping categories +- Use inconsistent naming +- Hide tag functionality +- Ignore tag maintenance + +### Tag UI Patterns + +**Tag display:** +``` +[UX Design] [Mobile] [Case Study] +``` + +**Tag filtering:** +``` +Filter by tag: +☑ UX Design (24) +☐ Mobile (18) +☐ Case Study (12) +``` + +**Tag input:** +``` +Tags: [UX Design ×] [Mobile ×] [Add tag...] + Suggested: Case Study, Research +``` + +--- + +## Faceted Search & Filters + +**What:** Multi-dimensional filtering to narrow results. + +### Components + +| Component | Function | +|-----------|----------| +| **Facets** | Filter categories (price, size, color) | +| **Values** | Options within facets | +| **Counts** | Number of results per value | +| **Applied filters** | Currently active filters | +| **Clear all** | Reset to unfiltered state | + +### Benefits + +- **Precision** — Find exactly what's needed +- **Exploration** — Discover by browsing facets +- **Transparency** — See how results are filtered +- **Control** — User-driven refinement + +### Implementation Guidelines + +**DO:** +- Show result counts per facet value +- Allow multiple selections within facets +- Update results immediately (or on apply) +- Show applied filters prominently +- Provide clear "reset all" + +**DON'T:** +- Show zero-result facet values (or mark unavailable) +- Hide facet values users might need +- Create too many facets +- Remove facets that would narrow to zero +- Make filters hard to clear + +### Faceted Search UI + +``` +Filters [Clear all] + +Price +○ Under $50 (120) +○ $50-$100 (85) +● $100-$200 (42) +○ Over $200 (23) + +Brand +☑ Nike (35) +☑ Adidas (28) +☐ Puma (15) +☐ Under Armour (12) + +[Show 42 results] +``` + +--- + +## Related Content + +**What:** Surfacing connections between content. + +### Types + +| Type | Basis | +|------|-------| +| **Manual curation** | Editor-selected relations | +| **Automatic** | Shared tags, categories, keywords | +| **Behavioral** | "Users also viewed" | +| **Temporal** | "Recent" or "trending" | + +### Placement + +- End of content (post-consumption) +- Sidebar (during consumption) +- Inline (contextual mentions) +- Below fold (scroll to discover) + +### Implementation Guidelines + +**DO:** +- Show genuinely related content +- Limit quantity (3-5 items) +- Include visual preview +- Vary recommendation types +- Track click-through + +**DON'T:** +- Show unrelated content +- Overwhelm with recommendations +- Use only one recommendation type +- Show same recommendations everywhere +- Link to outdated content + +### Related Content UI + +``` +Related Articles + +[Image] How to improve your UX process + 3 min read + +[Image] Design systems for startups + 5 min read + +[Image] User research on a budget + 4 min read +``` + +--- + +## Cross-Linking & Content Discovery + +**What:** Connecting content through intentional links. + +### Cross-Link Types + +| Type | Purpose | +|------|---------| +| **See also** | Alternative content | +| **Learn more** | Deeper dive | +| **Prerequisites** | Required knowledge | +| **Next steps** | Sequential content | +| **Examples** | Illustrative content | + +### Implementation Guidelines + +**DO:** +- Link to genuinely useful content +- Use descriptive anchor text +- Open external links appropriately +- Maintain links (fix broken) +- Use bidirectional linking + +**DON'T:** +- Use "click here" as anchor text +- Link excessively (every paragraph) +- Link to irrelevant pages +- Open all links in new tabs +- Create orphan pages (no inbound links) + +### Link Patterns + +**Inline:** +``` +For more details, see our guide to [user research methods]. +``` + +**Call-out:** +``` +📚 Related: [Complete guide to design systems →] +``` + +**Footer:** +``` +Learn more: +• User research fundamentals +• Conducting user interviews +• Analyzing research findings +``` + +--- + +## Search + +**What:** Finding content through queries. + +### Search Components + +| Component | Function | +|-----------|----------| +| **Search box** | Query input | +| **Suggestions** | Autocomplete, recent, popular | +| **Results** | Matched content | +| **Filters** | Refine results | +| **Sort** | Order results | +| **No results** | Empty state handling | + +### Implementation Guidelines + +**DO:** +- Make search prominent +- Support autocomplete +- Show result count +- Highlight matched terms +- Handle no results gracefully +- Remember recent searches + +**DON'T:** +- Hide search (especially on content-heavy sites) +- Require exact matches +- Show empty results without guidance +- Ignore typos/synonyms +- Make filters hard to find + +### Search UI Patterns + +**Search box:** +``` +🔍 [Search products, articles... ] + Recent: shoes, headphones + Popular: new arrivals, sale +``` + +**Search results:** +``` +42 results for "wireless headphones" + +[Filter by: Price ▼] [Category ▼] [Sort by: Relevance ▼] + +Sony WH-1000XM5 +Wireless noise-canceling **headphones** with... +$349 ★★★★★ (2,341) + +AirPods Max +Premium **wireless headphones** from Apple... +$549 ★★★★☆ (1,892) +``` + +--- + +## Information Architecture Checklist + +| Element | Implemented? | +|---------|--------------| +| ☐ Clear hierarchy (3-4 levels max) | | +| ☐ Breadcrumbs for deep content | | +| ☐ Consistent categorization | | +| ☐ Useful tagging system | | +| ☐ Effective search | | +| ☐ Faceted filtering where appropriate | | +| ☐ Related content surfacing | | +| ☐ Cross-linking strategy | | +| ☐ No orphan content | | diff --git a/references/31-patterns-navigation.md b/references/31-patterns-navigation.md new file mode 100644 index 0000000..565bcfc --- /dev/null +++ b/references/31-patterns-navigation.md @@ -0,0 +1,426 @@ +# Patterns: Navigation & Wayfinding + +Patterns for helping users move through interfaces and find content. + +--- + +## What is Navigation? + +The system that lets users move through your interface. Navigation answers three questions: +1. **Where am I?** +2. **Where can I go?** +3. **How do I get there?** + +**Core principle:** Users should never feel lost. + +--- + +## Priority+ Navigation + +**What:** Show important items, collapse the rest. + +### How It Works + +1. Display as many items as fit +2. Collapse remaining into "More" menu +3. Responsive—adapts to screen width + +### Benefits + +- **Responsive** — Works at any width +- **Priority-aware** — Most important items visible +- **Clean** — Avoids overflow/wrapping + +### Implementation Guidelines + +**DO:** +- Order items by importance +- Use clear "More" or "..." indicator +- Test at various breakpoints +- Include current item (even if in overflow) +- Make overflow menu discoverable + +**DON'T:** +- Put critical items in overflow +- Hide "More" when items overflow +- Change item order at breakpoints +- Use tiny touch targets for "More" + +### Pattern Example + +``` +Desktop (1200px+): +[Dashboard] [Projects] [Team] [Reports] [Settings] [Help] + +Tablet (768px): +[Dashboard] [Projects] [Team] [Reports] [More ▼] + └─ Settings + └─ Help + +Mobile (375px): +[☰] [Dashboard] [More ▼] +``` + +--- + +## Off-Canvas / Hamburger Menu + +**What:** Navigation hidden behind a toggle, typically a ☰ icon. + +### When to Use + +- Mobile layouts (space constraint) +- Secondary navigation +- Settings/admin menus +- Large navigation structures + +### When NOT to Use + +- Desktop with adequate space +- Primary navigation (if room exists) +- Only 3-5 nav items + +### Implementation Guidelines + +**DO:** +- Use recognizable icon (☰) +- Add text label when space permits +- Animate open/close smoothly +- Allow close via tap outside +- Show current location indication + +**DON'T:** +- Hide all navigation on desktop +- Use non-standard icons +- Make menu hard to close +- Nest menus too deeply +- Forget keyboard accessibility + +### Hamburger Menu Anatomy + +``` +[☰ Menu] + +────────────────────── +[Avatar] User Name + user@email +────────────────────── +🏠 Dashboard +📁 Projects +👥 Team +📊 Reports +⚙️ Settings +────────────────────── +🚪 Sign out +``` + +--- + +## Sticky/Fixed Navigation + +**What:** Navigation that stays visible while scrolling. + +### Types + +| Type | Behavior | +|------|----------| +| **Always fixed** | Always visible, takes space | +| **Scroll-up reveal** | Appears on scroll up, hides on scroll down | +| **Compact on scroll** | Shrinks when scrolling | +| **Below-fold sticky** | Becomes sticky after scrolling past hero | + +### Benefits + +- **Always accessible** — No scrolling to navigate +- **Orientation** — Constant location indicator +- **Efficiency** — Quick access to common actions + +### Implementation Guidelines + +**DO:** +- Keep sticky nav compact +- Use shadow to indicate elevation +- Consider scroll direction hiding +- Test on various content lengths +- Ensure doesn't block content + +**DON'T:** +- Take excessive vertical space +- Forget mobile (screen height matters) +- Cover content on tap +- Make too visually heavy +- Forget z-index conflicts + +### Scroll Behavior Patterns + +```css +/* Always visible */ +.nav { position: fixed; top: 0; } + +/* Compact on scroll */ +.nav.scrolled { height: 48px; /* vs 64px default */ } + +/* Hide on scroll down, show on scroll up */ +.nav.hidden { transform: translateY(-100%); } +``` + +--- + +## Bottom Navigation (Mobile) + +**What:** Tab bar at bottom of screen for primary navigation. + +### When to Use + +- Mobile apps with 3-5 primary sections +- Frequent switching between sections +- iOS and Android native patterns + +### Implementation Guidelines + +**DO:** +- Limit to 3-5 items +- Use icon + label +- Show active state clearly +- Make touch targets 48px+ +- Consider safe area (notch, home indicator) + +**DON'T:** +- Use for > 5 items +- Use icons alone (without labels) +- Put scrollable content in bottom nav +- Forget selected state +- Nest navigation actions + +### Bottom Nav Anatomy + +``` +┌──────────────────────────────┐ +│ │ +│ [Content Area] │ +│ │ +├──────────────────────────────┤ +│ 🏠 📁 ➕ 👤 ⚙️ │ +│ Home Files New Profile More│ +└──────────────────────────────┘ +``` + +### Icon + Label Guidelines + +| Item Count | Label Visibility | +|------------|-----------------| +| 3 items | Labels always visible | +| 4-5 items | Labels always visible or active only | +| 5+ items | Consider other navigation pattern | + +--- + +## Sidebar Navigation + +**What:** Vertical navigation, typically on left side. + +### Types + +| Type | Use Case | +|------|----------| +| **Fixed sidebar** | Dashboard apps, admin tools | +| **Collapsible** | Space optimization | +| **Icon-only (rail)** | Minimal footprint | +| **Expandable** | Icon-only → full on hover | + +### Benefits + +- **Scalable** — Handles many items +- **Visible** — Always accessible +- **Scannable** — Vertical list easy to scan +- **Groupable** — Sections and hierarchy + +### Implementation Guidelines + +**DO:** +- Group related items with headers +- Show current location clearly +- Allow collapse (icons only) +- Remember collapsed state +- Consider nesting (2 levels max) + +**DON'T:** +- Create too many groups +- Nest more than 2 levels +- Use icons alone for unfamiliar actions +- Make collapsed state too narrow +- Forget mobile adaptation + +### Sidebar Anatomy + +``` +┌──────────────────────────────────────┐ +│ [Logo] [Collapse] │ +├──────────────────────────────────────┤ +│ MAIN │ +│ 🏠 Dashboard │ +│ 📁 Projects │ +│ 📊 Analytics │ +├──────────────────────────────────────┤ +│ WORKSPACE │ +│ 👥 Team │ +│ ⚙️ Settings │ +├──────────────────────────────────────┤ +│ [Avatar] User Name [▼] │ +└──────────────────────────────────────┘ +``` + +--- + +## Tabs (In-Page Navigation) + +**What:** Switching between content sections within a page. + +### When to Use + +- Related content that's mutually exclusive +- User needs to compare/switch frequently +- 2-7 equal-weight sections + +### Implementation Guidelines + +**DO:** +- Clear active state +- Descriptive labels (2-3 words) +- Logical order +- Preserve content on tab switch +- Support keyboard navigation + +**DON'T:** +- Use for sequential steps (use stepper) +- Use for > 7 tabs without overflow +- Change tab content while in progress +- Use tabs within tabs +- Forget about URL state (deep linking) + +### Tab Variants + +| Variant | Use Case | +|---------|----------| +| **Text tabs** | Standard, most common | +| **Icon + text** | When icons aid recognition | +| **Scrollable** | Many tabs, mobile | +| **Fitted** | Equal-width tabs | + +--- + +## Mega Menus + +**What:** Large dropdown menus showing multiple categories. + +### When to Use + +- Large sites with many categories +- E-commerce, enterprise, media sites +- Categories benefit from visual display + +### Implementation Guidelines + +**DO:** +- Organize into clear groups +- Include images when helpful +- Provide direct links to popular items +- Support keyboard navigation +- Close on click outside + +**DON'T:** +- Make too tall (don't push footer) +- Include too much content +- Auto-open on hover (click better) +- Nest mega menus +- Forget mobile adaptation (often drawer/accordion) + +### Mega Menu Anatomy + +``` +Products ▼ +┌─────────────────────────────────────────────────────┐ +│ ELECTRONICS APPAREL HOME │ +│ Phones Women's Furniture │ +│ Laptops Men's Kitchen │ +│ Tablets Kids Decor │ +│ Accessories Shoes Bedding │ +│ │ +│ [Featured: New MacBook →] │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## Command Palette + +**What:** Keyboard-driven navigation and command execution. + +### Benefits + +- **Speed** — Expert users navigate instantly +- **Discovery** — Search for features +- **Accessibility** — Keyboard-first users +- **Unified access** — One place for everything + +### Implementation Guidelines + +**DO:** +- Trigger with Cmd/Ctrl + K +- Search items AND actions +- Show keyboard shortcuts +- Group results by type +- Support recent/frequent items + +**DON'T:** +- Make it the only way to access features +- Require memorization to use +- Forget fuzzy search +- Limit to just navigation + +### Command Palette UI + +``` +⌘K +┌────────────────────────────────────────┐ +│ 🔍 Type a command or search... │ +├────────────────────────────────────────┤ +│ RECENT │ +│ 📄 Project Alpha │ +│ 📊 Analytics Dashboard │ +├────────────────────────────────────────┤ +│ ACTIONS │ +│ ➕ Create new project ⌘N │ +│ 👤 Invite team member ⌘I │ +│ ⚙️ Open settings ⌘, │ +└────────────────────────────────────────┘ +``` + +--- + +## Navigation Selection Guide + +| Context | Recommended Pattern | +|---------|---------------------| +| Web app, many sections | Sidebar | +| Mobile app, 3-5 sections | Bottom nav | +| Content site, many categories | Mega menu | +| Power users | Command palette | +| Limited nav items | Priority+ | +| Mobile, complex nav | Hamburger + drawer | +| Dashboard, multiple views | Tabs | + +--- + +## Navigation Audit + +| Requirement | Implemented? | +|-------------|--------------| +| ☐ Current location clear | | +| ☐ Available destinations visible | | +| ☐ Primary nav always accessible | | +| ☐ Mobile navigation works | | +| ☐ Keyboard navigation supported | | +| ☐ Deep linking possible | | +| ☐ Consistent across pages | | +| ☐ Active states clear | |