@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/typography.md

@@ -1,4 +1,4 @@
-# Typography — Scale, Pairing, and Hierarchy
+# Typography - Scale, Pairing, and Hierarchy
 
 ---
 
@@ -12,14 +12,14 @@ Choose a ratio and base size. Common ratios:
 |---|---|---|
 | 1.067 | Minor Second | Dense UIs, data-heavy dashboards |
 | 1.125 | Major Second | Conservative, corporate |
-| 1.200 | Minor Third | Balanced — most SaaS products |
+| 1.200 | Minor Third | Balanced - most SaaS products |
 | 1.250 | Major Third | Consumer, editorial |
 | 1.333 | Perfect Fourth | Strong hierarchy, marketing |
 | 1.414 | Augmented Fourth | Bold, magazine-style |
 | 1.500 | Perfect Fifth | Very dramatic hierarchy |
 | 1.618 | Golden Ratio | Maximum visual drama |
 
-**Standard scale (base 16px, ratio 1.25 — Major Third):**
+**Standard scale (base 16px, ratio 1.25 - Major Third):**
 
 | Token | Size | Use |
 |---|---|---|
@@ -35,7 +35,7 @@ Choose a ratio and base size. Common ratios:
 
 Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
 
-**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales — when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
+**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales - when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
 
 ---
 
@@ -71,9 +71,9 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 | Display headings | **700 – 900** | Bold commands attention |
 | Page headings | **600 – 700** | Strong but not display-level |
 | Section headings | **500 – 600** | Distinguish from body |
-| Body text | **400** | Regular — no emphasis weight |
+| Body text | **400** | Regular - no emphasis weight |
 | UI labels | **500** | Slightly heavier than body |
-| Captions | **400** | Regular — size reduces emphasis |
+| Captions | **400** | Regular - size reduces emphasis |
 | Monospace code | **400 – 500** | |
 
 **Rule**: Never use `font-weight: 300` (light) on small text. It becomes illegible below 16px.
@@ -83,51 +83,51 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 ## Proven Font Pairings
 
 ### For SaaS / Productivity
-- **Plus Jakarta Sans** (headers) + **Plus Jakarta Sans** (body) — single-family, geometric, modern
-- **DM Sans** (headers) + **DM Sans** (body) — clean, contemporary
-- **Outfit** + **Work Sans** — geometric, startup feel
+- **Plus Jakarta Sans** (headers) + **Plus Jakarta Sans** (body) - single-family, geometric, modern
+- **DM Sans** (headers) + **DM Sans** (body) - clean, contemporary
+- **Outfit** + **Work Sans** - geometric, startup feel
 
 ### For Consumer / Marketing
-- **Playfair Display** + **Inter** — editorial contrast (serif header, sans body)
-- **Cormorant Garamond** + **Montserrat** — luxury, refined
-- **Syne** + **Manrope** — fashion-forward, editorial
+- **Playfair Display** + **Inter** - editorial contrast (serif header, sans body)
+- **Cormorant Garamond** + **Montserrat** - luxury, refined
+- **Syne** + **Manrope** - fashion-forward, editorial
 
 ### For Finance / Enterprise
-- **IBM Plex Sans** (all) — technical, neutral, reliable
-- **Lexend** + **Source Sans 3** — corporate, trustworthy, accessible
-- **Libre Bodoni** + **Public Sans** — news editorial, authority
+- **IBM Plex Sans** (all) - technical, neutral, reliable
+- **Lexend** + **Source Sans 3** - corporate, trustworthy, accessible
+- **Libre Bodoni** + **Public Sans** - news editorial, authority
 
 ### For Developer Tools / Technical
-- **JetBrains Mono** (code) + **IBM Plex Sans** (UI) — technical, consistent
-- **Fira Code** + **Fira Sans** — same family, harmonious
-- **Geist Mono** + **Geist** (Vercel) — modern technical
+- **JetBrains Mono** (code) + **IBM Plex Sans** (UI) - technical, consistent
+- **Fira Code** + **Fira Sans** - same family, harmonious
+- **Geist Mono** + **Geist** (Vercel) - modern technical
 
 ### For Bold / Expressive
-- **Bebas Neue** + **Source Sans 3** — display contrast, impactful
-- **Syne** + **Epilogue** — editorial, contemporary
-- **Clash Display** + **Satoshi** — startup bold, premium
+- **Bebas Neue** + **Source Sans 3** - display contrast, impactful
+- **Syne** + **Epilogue** - editorial, contemporary
+- **Clash Display** + **Satoshi** - startup bold, premium
 
 ### For Accessibility-First
-- **Atkinson Hyperlegible** (all) — designed for low-vision readers
-- **Lexend** (all) — designed to improve reading fluency
+- **Atkinson Hyperlegible** (all) - designed for low-vision readers
+- **Lexend** (all) - designed to improve reading fluency
 
 ---
 
 ## Typographic Anti-Patterns
 
-**Inter as the default** — Inter is excellent but requires a reason. "I used Inter" is not a typographic decision. If there's no brand reason for Inter specifically, explore the pairing list above.
+**Inter as the default** - Inter is excellent but requires a reason. "I used Inter" is not a typographic decision. If there's no brand reason for Inter specifically, explore the pairing list above.
 
-**Space Grotesk without purpose** — frequently used as a "quirky technical" font. Overused.
+**Space Grotesk without purpose** - frequently used as a "quirky technical" font. Overused.
 
-**Mismatched personality** — serif heading on a developer tool, playful font on a medical platform, condensed display on body text.
+**Mismatched personality** - serif heading on a developer tool, playful font on a medical platform, condensed display on body text.
 
-**Too many families** — maximum **2 font families** in a UI. More than that = chaos. (Exceptions: monospace for code is a 3rd that doesn't count.)
+**Too many families** - maximum **2 font families** in a UI. More than that = chaos. (Exceptions: monospace for code is a 3rd that doesn't count.)
 
-**Light weights on small text** — `font-weight: 300` below 16px fails contrast and readability.
+**Light weights on small text** - `font-weight: 300` below 16px fails contrast and readability.
 
-**All caps body text** — reserved for: labels, badges, category markers, short UI labels only. Never for sentences or paragraphs.
+**All caps body text** - reserved for: labels, badges, category markers, short UI labels only. Never for sentences or paragraphs.
 
-**Inconsistent tracking** — only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability. Random tracking changes across components signal lack of system.
+**Inconsistent tracking** - only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability. Random tracking changes across components signal lack of system.
 
 ---
 
@@ -179,7 +179,7 @@ as a starting point (adjust for specific constraints).
 
 | Archetype | Character | Recommended Pairing |
 |-----------|-----------|---------------------|
-| SaaS / productivity | clear, neutral, utilitarian | Inter (UI) + Inter (body) — single family |
+| SaaS / productivity | clear, neutral, utilitarian | Inter (UI) + Inter (body) - single family |
 | Consumer / editorial | warm, opinionated, expressive | Fraunces or GT Sectra (display) + Inter (body) |
 | Enterprise / finance | authoritative, conservative | IBM Plex Sans (UI) + IBM Plex Serif (body) |
 | Developer tools | technical, efficient | Geist (UI) + Geist Mono (code) |
@@ -193,7 +193,7 @@ as a starting point (adjust for specific constraints).
 
 Variable fonts expose typographic axes that can be animated or set per-context
 via `font-variation-settings`. Prefer variable fonts over static family fallbacks
-when available — one file covers all weights and widths.
+when available - one file covers all weights and widths.
 
 ### Common axes
 
@@ -235,7 +235,7 @@ font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
 ---
 
 ## Micro-Typography
-Source: jakubkrehel/make-interfaces-feel-better (MIT) — typography.md
+Source: jakubkrehel/make-interfaces-feel-better (MIT) - typography.md
 
 ### text-wrap
 
@@ -243,7 +243,7 @@ Use `text-wrap: balance` for headings to prevent orphaned single words:
 ```css
 h1, h2, h3 { text-wrap: balance; }
 ```
-Chromium supports up to 6 lines, Firefox up to 10. Do not apply to body text (performance cost scales with line count). For body copy and captions, use `text-wrap: pretty` instead — it prevents widows (dangling last words) without the line-count restriction.
+Chromium supports up to 6 lines, Firefox up to 10. Do not apply to body text (performance cost scales with line count). For body copy and captions, use `text-wrap: pretty` instead - it prevents widows (dangling last words) without the line-count restriction.
 
 ### Font smoothing
 
@@ -254,7 +254,7 @@ Apply antialiasing at root level only:
   -moz-osx-font-smoothing: grayscale;
 }
 ```
-Never apply per-element — this creates inconsistency within a single text block and is one of the most common micro-typography mistakes. The antialiased value makes text appear slightly thinner/lighter, which is generally preferred for UI type at modern screen densities.
+Never apply per-element - this creates inconsistency within a single text block and is one of the most common micro-typography mistakes. The antialiased value makes text appear slightly thinner/lighter, which is generally preferred for UI type at modern screen densities.
 
 ### Tabular numerals
 
@@ -262,52 +262,52 @@ Use tabular-nums on any surface where numbers change dynamically or need to alig
 ```css
 .counter, .price, .timer, .table-cell { font-variant-numeric: tabular-nums; }
 ```
-Proportional numerals (the default) cause text to shift width when numbers change, creating a distracting jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums — test at your numeric composition before committing.
+Proportional numerals (the default) cause text to shift width when numbers change, creating a distracting jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums - test at your numeric composition before committing.
 
 ## Font Pairings Catalog
-Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/typography.csv
+Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) - data/typography.csv
 
 57 professionally curated pairings grouped by use-case vertical. For font loading, see `reference/data/google-fonts.csv` for the full 1923-font reference.
 
 ### SaaS / Productivity
-- **Inter + Inter** (mono weight hierarchy) — The "safe default" for app UIs. Use regular (400) for body, medium (500) for labels, semibold (600) for headings. Consistent x-height, excellent at small sizes.
-- **Inter + JetBrains Mono** — For dev tools and dashboards with code display. JetBrains Mono has excellent legibility at 12-14px.
-- **Geist Sans + Geist Mono** — Vercel's pair; clean, modern, designed together.
-- **Outfit + DM Mono** — Friendly SaaS feel with clear code fallback.
+- **Inter + Inter** (mono weight hierarchy) - The "safe default" for app UIs. Use regular (400) for body, medium (500) for labels, semibold (600) for headings. Consistent x-height, excellent at small sizes.
+- **Inter + JetBrains Mono** - For dev tools and dashboards with code display. JetBrains Mono has excellent legibility at 12-14px.
+- **Geist Sans + Geist Mono** - Vercel's pair; clean, modern, designed together.
+- **Outfit + DM Mono** - Friendly SaaS feel with clear code fallback.
 
 ### Consumer / Marketing
-- **Satoshi + Cabinet Grotesk** — High-energy, modern consumer feel.
-- **Plus Jakarta Sans + Syne** — Playful but legible; works for creative consumer apps.
-- **DM Sans + DM Serif Display** — Classic pairing; editorial headers, clean body.
-- **Nunito + Source Code Pro** — Approachable and friendly.
+- **Satoshi + Cabinet Grotesk** - High-energy, modern consumer feel.
+- **Plus Jakarta Sans + Syne** - Playful but legible; works for creative consumer apps.
+- **DM Sans + DM Serif Display** - Classic pairing; editorial headers, clean body.
+- **Nunito + Source Code Pro** - Approachable and friendly.
 
 ### Finance / Enterprise
-- **IBM Plex Sans + IBM Plex Mono** — Authoritative, systematic, designed for data-heavy interfaces.
-- **Source Sans 3 + Source Code Pro** — Adobe's workhorse pair; widely trusted.
-- **Lato + Roboto Mono** — Clean, neutral enterprise pair.
+- **IBM Plex Sans + IBM Plex Mono** - Authoritative, systematic, designed for data-heavy interfaces.
+- **Source Sans 3 + Source Code Pro** - Adobe's workhorse pair; widely trusted.
+- **Lato + Roboto Mono** - Clean, neutral enterprise pair.
 
 ### Editorial / Publishing
-- **Playfair Display + Source Serif 4** — High contrast serif headers with readable body serif.
-- **Cormorant Garamond + Proza Libre** — Elegant luxury/editorial tone.
-- **Libre Baskerville + Libre Franklin** — Free-license editorial pair.
-- **EB Garamond + Lato** — Classic print feel with modern body.
+- **Playfair Display + Source Serif 4** - High contrast serif headers with readable body serif.
+- **Cormorant Garamond + Proza Libre** - Elegant luxury/editorial tone.
+- **Libre Baskerville + Libre Franklin** - Free-license editorial pair.
+- **EB Garamond + Lato** - Classic print feel with modern body.
 
 ### Wellness / Health
-- **Nunito + Nunito Sans** — Soft, approachable, consistent x-height.
-- **Quicksand + Work Sans** — Rounded, friendly, healthcare-appropriate.
-- **Raleway + Open Sans** — Clean and welcoming.
+- **Nunito + Nunito Sans** - Soft, approachable, consistent x-height.
+- **Quicksand + Work Sans** - Rounded, friendly, healthcare-appropriate.
+- **Raleway + Open Sans** - Clean and welcoming.
 
 ### Dev Tools
-- **JetBrains Mono + Inter** — Code-first, UI-second; natural for developer tools.
-- **Fira Code + Fira Sans** — Cohesive family; ligatures available.
-- **Cascadia Code + Segoe UI** — Microsoft's modern dev pair.
+- **JetBrains Mono + Inter** - Code-first, UI-second; natural for developer tools.
+- **Fira Code + Fira Sans** - Cohesive family; ligatures available.
+- **Cascadia Code + Segoe UI** - Microsoft's modern dev pair.
 
 ### Luxury / Fashion
-- **Cormorant + Montserrat** — High contrast serif + geometric sans; classic luxury.
-- **Bodoni Moda + Jost** — Fashion editorial feel.
-- **Playfair Display + Raleway** — Elegant header + clean body.
+- **Cormorant + Montserrat** - High contrast serif + geometric sans; classic luxury.
+- **Bodoni Moda + Jost** - Fashion editorial feel.
+- **Playfair Display + Raleway** - Elegant header + clean body.
 
 ### Gaming / Entertainment
-- **Syne + DM Sans** — Bold, energetic headers; clean readable body.
-- **Bebas Neue + Open Sans** — Impact headlines; neutral body.
-- **Exo 2 + Roboto** — Futuristic but readable.
+- **Syne + DM Sans** - Bold, energetic headers; clean readable body.
+- **Bebas Neue + Open Sans** - Impact headlines; neutral body.
+- **Exo 2 + Roboto** - Futuristic but readable.

package/reference/user-research.md

@@ -17,7 +17,7 @@ Every method sits in one of four quadrants defined by two axes: whether the goal
 
 **Evaluative research** answers "Does this solution work, and how well?" It is appropriate once a concept, prototype, or live product exists. Outputs are pass/fail rates, benchmarks, and ranked preference scores.
 
-Mixing quadrants in the same study is usually a mistake — participants primed by evaluation tasks answer generative questions defensively. Plan separate sessions or separate phases.
+Mixing quadrants in the same study is usually a mistake - participants primed by evaluation tasks answer generative questions defensively. Plan separate sessions or separate phases.
 
 ---
 
@@ -25,7 +25,7 @@ Mixing quadrants in the same study is usually a mistake — participants primed
 
 ### Contextual Interviews / User Interviews
 
-A contextual interview is a structured or semi-structured conversation conducted in the environment where the work actually happens — at a desk, in a kitchen, on a shop floor. A plain user interview happens in a neutral setting (a conference room, a video call) and relies on self-report rather than observation. Contextual interviews surface discrepancies between what people say they do and what they actually do; plain interviews are faster to schedule and sufficient when behavior is verbal or cognitive.
+A contextual interview is a structured or semi-structured conversation conducted in the environment where the work actually happens - at a desk, in a kitchen, on a shop floor. A plain user interview happens in a neutral setting (a conference room, a video call) and relies on self-report rather than observation. Contextual interviews surface discrepancies between what people say they do and what they actually do; plain interviews are faster to schedule and sufficient when behavior is verbal or cognitive.
 
 **When to use:** Early discovery, when you need to understand goals, mental models, workarounds, and emotional context before any design artifact exists.
 
@@ -34,14 +34,14 @@ A contextual interview is a structured or semi-structured conversation conducted
 **Key pitfalls:**
 - Asking leading questions ("Do you find the checkout confusing?") primes the answer
 - Asking hypothetical questions ("Would you use a feature that…?") produces aspirational fiction, not real behavior
-- Failing to probe the last three minutes of a story — "tell me more about that" almost always yields the real insight
+- Failing to probe the last three minutes of a story - "tell me more about that" almost always yields the real insight
 - Recording without consent, or failing to inform participants how data will be used
 
 ---
 
 ### Field Observation (Diary Studies, Shadowing)
 
-Field observation captures behavior as it naturally unfolds, without a researcher present (diary study) or with a researcher silently present (shadowing). In a **diary study**, participants self-report via a structured log — a form, a voice note, or a photo — triggered by an event or a fixed schedule over days to weeks. In **shadowing**, the researcher follows a participant through a real work session and takes notes or records video.
+Field observation captures behavior as it naturally unfolds, without a researcher present (diary study) or with a researcher silently present (shadowing). In a **diary study**, participants self-report via a structured log - a form, a voice note, or a photo - triggered by an event or a fixed schedule over days to weeks. In **shadowing**, the researcher follows a participant through a real work session and takes notes or records video.
 
 **When to use:** When the behavior of interest is distributed across time (diary) or deeply embedded in a physical environment (shadowing); when recall in an interview would be too compressed or distorted.
 
@@ -49,7 +49,7 @@ Field observation captures behavior as it naturally unfolds, without a researche
 
 **Key pitfalls:**
 - Diary prompts that are too long or too frequent cause abandonment
-- Shadowing creates an observer effect — participants perform "correct" behavior rather than habitual behavior; use this method alongside analytics to cross-check
+- Shadowing creates an observer effect - participants perform "correct" behavior rather than habitual behavior; use this method alongside analytics to cross-check
 - Diary data requires significant cleaning before synthesis; budget time accordingly
 
 ---
@@ -63,25 +63,25 @@ A survey collects self-reported data at scale through a fixed set of questions d
 **Sample size:** For a ±5% margin of error at 95% confidence in a large population, n = 385. For ±3%, n = 1067. Smaller populations require proportionally larger samples relative to population size.
 
 **Key pitfalls:**
-- Question order effects — put sensitive or demographic questions last
-- Acquiescence bias — respondents agree with statements regardless of content; use balanced scales (Likert with both positive and negative anchors)
-- Survivorship bias — survey respondents are not the same as non-respondents; a 10% response rate produces a self-selected sample
+- Question order effects - put sensitive or demographic questions last
+- Acquiescence bias - respondents agree with statements regardless of content; use balanced scales (Likert with both positive and negative anchors)
+- Survivorship bias - survey respondents are not the same as non-respondents; a 10% response rate produces a self-selected sample
 - Treating ordinal Likert data as interval data for arithmetic mean comparisons
 
 ---
 
 ### Card Sorting
 
-Card sorting asks participants to organize a set of labeled cards (representing content, features, or navigation items) into groups that make sense to them. **Open card sorting** lets participants create their own group names — this reveals the mental model. **Closed card sorting** provides predefined categories — this tests whether an existing structure matches expectations. **Hybrid card sorting** asks participants to sort into predefined categories but allows them to create new ones when nothing fits.
+Card sorting asks participants to organize a set of labeled cards (representing content, features, or navigation items) into groups that make sense to them. **Open card sorting** lets participants create their own group names - this reveals the mental model. **Closed card sorting** provides predefined categories - this tests whether an existing structure matches expectations. **Hybrid card sorting** asks participants to sort into predefined categories but allows them to create new ones when nothing fits.
 
-**Output:** Group labels (open) surface vocabulary and categories that match user language. A **dendrogram** — a tree diagram produced by cluster analysis — shows which cards are grouped together most consistently across participants, revealing the underlying mental model numerically.
+**Output:** Group labels (open) surface vocabulary and categories that match user language. A **dendrogram** - a tree diagram produced by cluster analysis - shows which cards are grouped together most consistently across participants, revealing the underlying mental model numerically.
 
 **When to use:** Before designing information architecture; after tree testing reveals a structure that is failing.
 
 **Sample size:** 15–20 participants for open sorting; 30+ for closed sorting where you want statistical confidence in the clusters.
 
 **Key pitfalls:**
-- Cards that are ambiguous produce noise, not insight — pilot test card labels first
+- Cards that are ambiguous produce noise, not insight - pilot test card labels first
 - Too many cards (>60) causes fatigue; split into focused subsets
 - Dendrograms look authoritative but are sensitive to the distance algorithm chosen; report the algorithm and test alternative cuts
 
@@ -89,12 +89,12 @@ Card sorting asks participants to organize a set of labeled cards (representing
 
 ### Tree Testing
 
-Tree testing evaluates an information architecture by asking participants to find content using only the text labels of a navigation tree — no visual design, no search, no breadcrumbs. Participants are given a task ("Find the return policy for a purchased item") and navigate the tree until they select a destination. The test isolates whether the structure and labeling work, independent of visual presentation.
+Tree testing evaluates an information architecture by asking participants to find content using only the text labels of a navigation tree - no visual design, no search, no breadcrumbs. Participants are given a task ("Find the return policy for a purchased item") and navigate the tree until they select a destination. The test isolates whether the structure and labeling work, independent of visual presentation.
 
 **Output:**
-- **Success rate** — percentage of participants who reached the correct destination. >75% = good; >60% = acceptable; below 60% = the path needs redesign.
-- **Directness** — percentage of successful participants who reached the answer without backtracking. High directness means the path is intuitive; high success with low directness means participants found it eventually but the labels are misleading.
-- **Time on task** — useful for comparing two versions of a tree; not meaningful in isolation.
+- **Success rate** - percentage of participants who reached the correct destination. >75% = good; >60% = acceptable; below 60% = the path needs redesign.
+- **Directness** - percentage of successful participants who reached the answer without backtracking. High directness means the path is intuitive; high success with low directness means participants found it eventually but the labels are misleading.
+- **Time on task** - useful for comparing two versions of a tree; not meaningful in isolation.
 
 **When to use:** Before building navigation; after card sorting to validate that an IA derived from participant groups actually works for task completion.
 
@@ -102,7 +102,7 @@ Tree testing evaluates an information architecture by asking participants to fin
 
 **Key pitfalls:**
 - Tasks that hint at the answer ("Find the Privacy section in Settings") teach rather than test
-- A tree that passes at 76% success for one task may still fail for a different task — test all high-traffic paths
+- A tree that passes at 76% success for one task may still fail for a different task - test all high-traffic paths
 - Do not test more than 10 tasks per session without randomization to prevent fatigue effects
 
 ---
@@ -116,7 +116,7 @@ Preference testing presents two or more design options and asks participants to
 **Sample size:** 50–100 participants for a binary preference test to achieve statistically meaningful proportions.
 
 **Key pitfalls:**
-- Preference does not equal usability — participants consistently prefer interfaces they can use, but can prefer a beautiful interface they cannot use over an ugly one they can
+- Preference does not equal usability - participants consistently prefer interfaces they can use, but can prefer a beautiful interface they cannot use over an ugly one they can
 - Options must be shown in randomized order to control for primacy and recency bias
 - "Why did you choose this?" follow-ups suffer from post-hoc rationalization; treat qualitative reasons as directional, not causal
 
@@ -131,7 +131,7 @@ A first-click test measures where participants click first when presented with a
 **Sample size:** 20–40 participants provides sufficient data for heatmap patterns and task success rates.
 
 **Key pitfalls:**
-- A click in the right location for the wrong reason (the participant was guessing) is not a pass — follow up with "why did you click there?"
+- A click in the right location for the wrong reason (the participant was guessing) is not a pass - follow up with "why did you click there?"
 - First-click tests do not account for context built up from prior pages; test each page in context when the flow matters
 - Heatmaps with small n look authoritative but individual outlier clicks distort the visualization
 
@@ -146,9 +146,9 @@ A 5-second test exposes participants to a design for exactly five seconds, then
 **Sample size:** 20–50 participants; the test is fast enough that larger samples are easy to recruit.
 
 **Key pitfalls:**
-- Questions asked immediately after exposure must be closed or very specific — open-ended questions produce memory artifacts, not design feedback
+- Questions asked immediately after exposure must be closed or very specific - open-ended questions produce memory artifacts, not design feedback
 - The 5-second window captures attention and memory, not comprehension or usability; do not use this to predict task performance
-- Results are highly sensitive to the specific question asked — "What is this page for?" and "What do you remember?" produce different data from the same exposure
+- Results are highly sensitive to the specific question asked - "What is this page for?" and "What do you remember?" produce different data from the same exposure
 
 ---
 
@@ -165,7 +165,7 @@ The rule does **not** apply to:
 - Surveys where you need generalizable proportions (requires hundreds)
 - A/B tests where you need to detect a treatment effect (requires thousands)
 - Tree tests where success-rate benchmarks must be reliable (requires 50+)
-- Studies with heterogeneous populations — run 5 users per distinct segment
+- Studies with heterogeneous populations - run 5 users per distinct segment
 
 Misapplying the "5 users" rule to quantitative contexts is a common and costly error. A sample of five will tell you which problems exist, not how often they occur.
 
@@ -198,7 +198,7 @@ For smaller populations, apply the finite population correction. These figures a
 
 ## Synthesis Techniques
 
-Raw research data — interview transcripts, survey responses, diary entries — does not become insight until it is actively interpreted and structured. Three frameworks cover most synthesis needs.
+Raw research data - interview transcripts, survey responses, diary entries - does not become insight until it is actively interpreted and structured. Three frameworks cover most synthesis needs.
 
 ### Affinity Diagrams (KJ Method)
 
@@ -206,11 +206,11 @@ An affinity diagram (developed by Jiro Kawakita, hence KJ method) organizes qual
 
 **Process:**
 1. Write each distinct observation, quote, or behavior on a separate note (physical or digital)
-2. Silently sort notes into groups based on natural similarity — team members work in parallel, moving notes without discussion
+2. Silently sort notes into groups based on natural similarity - team members work in parallel, moving notes without discussion
 3. Once sorting slows, name each cluster with a header that captures the insight, not just the topic ("Users abandon checkout when shipping cost appears late" rather than "Shipping")
 4. Merge or split clusters until the structure is stable
 
-**When done:** Clustering is complete when new data no longer creates new groups — typically after three to four passes with a complete data set. If a new interview consistently produces notes that fit existing clusters without creating new ones, theoretical saturation has been reached.
+**When done:** Clustering is complete when new data no longer creates new groups - typically after three to four passes with a complete data set. If a new interview consistently produces notes that fit existing clusters without creating new ones, theoretical saturation has been reached.
 
 ### Jobs-to-be-Done
 
@@ -219,9 +219,9 @@ Jobs-to-be-Done (JTBD) frames user behavior around the progress a person is tryi
 > **"When I [situation], I want to [motivation/goal], so I can [expected outcome]."**
 
 JTBD distinguishes three job layers:
-- **Functional job** — the practical task being accomplished ("When I'm running low on groceries, I want to reorder my usual items quickly, so I can avoid running out")
-- **Social job** — how the person wants to be perceived while doing it ("so my family sees me as organized and dependable")
-- **Emotional job** — how the person wants to feel ("so I don't feel the anxiety of an empty fridge")
+- **Functional job** - the practical task being accomplished ("When I'm running low on groceries, I want to reorder my usual items quickly, so I can avoid running out")
+- **Social job** - how the person wants to be perceived while doing it ("so my family sees me as organized and dependable")
+- **Emotional job** - how the person wants to feel ("so I don't feel the anxiety of an empty fridge")
 
 Designs that serve only the functional job often feel transactional. Designs that also address emotional and social jobs create habitual use and preference. Surface all three layers during synthesis by asking "and why does that matter to you?" until the answer is about identity or feeling, not functionality.
 
@@ -230,11 +230,11 @@ Designs that serve only the functional job often feel transactional. Designs tha
 A user journey map visualizes the sequence of steps a user takes to accomplish a goal, annotated with emotional valence, touchpoints, and observations at each step.
 
 **Key components:**
-- **Stages** — the high-level phases of the experience (Awareness, Onboarding, First Use, Routine Use, Problem Recovery)
-- **Touchpoints** — every channel or interface the user contacts (email, app, support chat, physical receipt)
-- **Emotional valence** — a curve showing frustration, confusion, delight, or confidence at each step, derived from research data, not assumed
-- **Moments of truth** — the two or three steps where user trust is won or lost; these are the highest-leverage design targets
-- **Pain points and gains** — specific friction (long wait, confusing label, missing feedback) and specific delights (unexpected shortcut, empathetic error message)
+- **Stages** - the high-level phases of the experience (Awareness, Onboarding, First Use, Routine Use, Problem Recovery)
+- **Touchpoints** - every channel or interface the user contacts (email, app, support chat, physical receipt)
+- **Emotional valence** - a curve showing frustration, confusion, delight, or confidence at each step, derived from research data, not assumed
+- **Moments of truth** - the two or three steps where user trust is won or lost; these are the highest-impact design targets
+- **Pain points and gains** - specific friction (long wait, confusing label, missing feedback) and specific delights (unexpected shortcut, empathetic error message)
 
 A journey map built from assumed experience is a risk document, not a research artifact. Only map journeys from observed or reported user behavior; mark any step built on assumption explicitly so it can be validated.
 
@@ -247,21 +247,21 @@ A/B testing (controlled experiment) measures the causal effect of a design chang
 ### Sample Size and Power
 
 Pre-register the following before running any experiment:
-- **Primary metric** — the single metric the test is designed to move (conversion rate, session length, activation)
-- **MDE** — the smallest relative improvement worth shipping; smaller MDEs require larger samples
-- **Baseline rate** — the current value of the primary metric, measured over a representative period
-- **Power** — 80% (β = 0.20) is the standard minimum; 90% is appropriate when the cost of a missed effect is high
-- **Significance threshold** — α = 0.05 (5% Type I error rate) is standard; use α = 0.01 for high-stakes decisions or multiple simultaneous tests
+- **Primary metric** - the single metric the test is designed to move (conversion rate, session length, activation)
+- **MDE** - the smallest relative improvement worth shipping; smaller MDEs require larger samples
+- **Baseline rate** - the current value of the primary metric, measured over a representative period
+- **Power** - 80% (β = 0.20) is the standard minimum; 90% is appropriate when the cost of a missed effect is high
+- **Significance threshold** - α = 0.05 (5% Type I error rate) is standard; use α = 0.01 for high-stakes decisions or multiple simultaneous tests
 
 ### Sequential vs Fixed-Horizon Testing
 
-**Fixed-horizon testing** requires committing to a sample size before the experiment begins and not checking results until that sample is collected. Peeking at results and stopping early when significance is reached inflates the Type I error rate dramatically — running 20 checks at α = 0.05 raises the effective false-positive rate to ~64%.
+**Fixed-horizon testing** requires committing to a sample size before the experiment begins and not checking results until that sample is collected. Peeking at results and stopping early when significance is reached inflates the Type I error rate dramatically - running 20 checks at α = 0.05 raises the effective false-positive rate to ~64%.
 
 **Sequential testing** (e.g., using always-valid confidence sequences or mSPRT methods) allows early stopping while controlling error rates. It is safer when experiments run on volatile traffic or when shipping quickly matters. Sequential tests typically require 20–30% more total sample on average but eliminate the false-positive inflation from peeking. Use sequential testing as the default when your tooling supports it.
 
 ### Primary Metric vs Guardrail Metrics
 
-Before launching any test, define the **guardrail metrics** — the metrics that must not decline as a condition of shipping, regardless of the primary metric result.
+Before launching any test, define the **guardrail metrics** - the metrics that must not decline as a condition of shipping, regardless of the primary metric result.
 
 - **Primary metric:** checkout completion rate
 - **Guardrail metrics:** page load time (must not increase >50ms), return rate (must not increase >1pp), customer support contact rate (must not increase)
@@ -270,7 +270,7 @@ A treatment that improves checkout completion by 8% while increasing support con
 
 ### Novelty Effect
 
-New UI patterns, colors, or flows often see inflated positive effects in the first week because users engage with anything that is different. To avoid shipping a change that performs well only because it is new, run experiments for **at least two full business cycles** (typically two weeks for B2C products) before reading results. Monitor the treatment effect over time — a novelty lift decays; a genuine improvement holds flat or grows.
+New UI patterns, colors, or flows often see inflated positive effects in the first week because users engage with anything that is different. To avoid shipping a change that performs well only because it is new, run experiments for **at least two full business cycles** (typically two weeks for B2C products) before reading results. Monitor the treatment effect over time - a novelty lift decays; a genuine improvement holds flat or grows.
 
 ---
 
@@ -282,9 +282,9 @@ Quantitative analytics tells you what users are doing at scale, but it cannot te
 
 A funnel analysis counts users at each step of a defined sequence (landing → sign-up → onboarding → first key action → activation) and reports the drop-off rate between steps. A large drop between two steps identifies a problem worth investigating; it does not explain the cause.
 
-**Correct interpretation:** "60% of users who start sign-up do not complete it — this step warrants usability testing and exit surveys."
+**Correct interpretation:** "60% of users who start sign-up do not complete it - this step warrants usability testing and exit surveys."
 
-**Incorrect interpretation:** "The sign-up form is confusing — we should simplify it." Funnels explain what, not why. The drop may be caused by form friction, price discovery too late, technical errors on specific devices, or users deliberately deferring. Research the step before redesigning it.
+**Incorrect interpretation:** "The sign-up form is confusing - we should simplify it." Funnels explain what, not why. The drop may be caused by form friction, price discovery too late, technical errors on specific devices, or users deliberately deferring. Research the step before redesigning it.
 
 ### Cohort Retention Curves
 
@@ -292,7 +292,7 @@ A cohort retention curve shows what percentage of users acquired in a given peri
 
 - **Early drop (Day 1–3):** Users are not completing onboarding or are not reaching the first moment of value; the onboarding flow is the design target
 - **Mid drop (Day 7–14):** Users completed onboarding but are not forming a usage habit; engagement features (reminders, progress, social hooks) and the core loop are the design targets
-- **Late drop (Day 30+):** Users had a habit but lost it; this indicates habit failure, not acquisition or onboarding issues — investigate trigger frequency, competing alternatives, and changing life context
+- **Late drop (Day 30+):** Users had a habit but lost it; this indicates habit failure, not acquisition or onboarding issues - investigate trigger frequency, competing alternatives, and changing life context
 
 A flat retention curve (asymptoting above zero) is the signal that product-market fit exists for at least a subset of users.
 
@@ -304,17 +304,17 @@ Heatmaps aggregate mouse movement, scroll depth, and click positions across many
 - **Click heatmaps lie on dynamic content.** Carousels, tabs, and modal triggers change what is rendered at a coordinate; aggregated clicks on a static screenshot misrepresent where those clicks actually landed.
 - **Move maps are proxies.** Eye-tracking research shows mouse position correlates with gaze only roughly (r ≈ 0.64); do not treat move heatmaps as attention maps.
 
-Use heatmaps to generate hypotheses ("Almost nobody clicks the secondary CTA — maybe it is not visible enough at typical scroll depths") and confirm those hypotheses with usability testing or A/B tests.
+Use heatmaps to generate hypotheses ("Almost nobody clicks the secondary CTA - maybe it is not visible enough at typical scroll depths") and confirm those hypotheses with usability testing or A/B tests.
 
 ### Session Recordings
 
 Session recordings capture individual user interactions as video replays. They are the analytics tool closest to observational research and the most time-intensive to analyze at scale.
 
 **Patterns that indicate design problems:**
-- **Rage clicks** — repeated rapid clicks on an element, indicating the user believes something should be clickable and it is not (or it is broken)
-- **Dead clicks** — clicks on non-interactive elements, indicating visual affordance is misleading
-- **Scroll-and-return patterns** — the user scrolls past a point, returns, and re-reads it, indicating the content is ambiguous or the action they need is not where they expected it
-- **U-turns on multi-step flows** — navigating forward then immediately back, indicating confusion or missing information at the forward step
+- **Rage clicks** - repeated rapid clicks on an element, indicating the user believes something should be clickable and it is not (or it is broken)
+- **Dead clicks** - clicks on non-interactive elements, indicating visual affordance is misleading
+- **Scroll-and-return patterns** - the user scrolls past a point, returns, and re-reads it, indicating the content is ambiguous or the action they need is not where they expected it
+- **U-turns on multi-step flows** - navigating forward then immediately back, indicating confusion or missing information at the forward step
 
 Sampling strategy matters: watch recordings filtered by the segment of users you are trying to understand (new users on mobile, users who abandoned checkout) rather than random sessions. Random sessions produce anecdote, not insight.
 
@@ -322,28 +322,28 @@ Sampling strategy matters: watch recordings filtered by the segment of users you
 
 ## Research Ethics
 
-Ethical research practice is not only a moral obligation — it also produces better data. Participants who feel respected and safe give more candid and accurate responses.
+Ethical research practice is not only a moral obligation - it also produces better data. Participants who feel respected and safe give more candid and accurate responses.
 
 ### Informed Consent
 
-Every participant must be told, before the session begins: what they will be asked to do, how long it will take, whether the session will be recorded (audio, video, or screen), who will have access to recordings and data, and how data will be stored and eventually deleted. Consent must be explicit and voluntary — a participant who feels they cannot say no has not given meaningful consent.
+Every participant must be told, before the session begins: what they will be asked to do, how long it will take, whether the session will be recorded (audio, video, or screen), who will have access to recordings and data, and how data will be stored and eventually deleted. Consent must be explicit and voluntary - a participant who feels they cannot say no has not given meaningful consent.
 
 For unmoderated remote studies (tree tests, surveys, unmoderated usability tests), informed consent is captured in a pre-task screen that participants must actively acknowledge before proceeding.
 
 ### Observer Effect
 
-The presence of a researcher — or even the knowledge that behavior is being observed — changes that behavior. Participants tend to perform more carefully, ask more clarifying questions, and avoid the shortcuts and workarounds that characterize natural use. This is the Hawthorne effect applied to usability research.
+The presence of a researcher - or even the knowledge that behavior is being observed - changes that behavior. Participants tend to perform more carefully, ask more clarifying questions, and avoid the shortcuts and workarounds that characterize natural use. This is the Hawthorne effect applied to usability research.
 
 **Mitigations:**
 - Use diary studies and screen recordings to capture naturalistic behavior without researcher presence
 - In moderated sessions, use indirect tasks ("Show me how you would accomplish X") rather than direct observation ("Try to do X while I watch")
-- Cross-reference moderated findings with analytics — discrepancies between observed behavior and logged behavior indicate observer effect
+- Cross-reference moderated findings with analytics - discrepancies between observed behavior and logged behavior indicate observer effect
 
 ### Data Minimization
 
 Collect only the data you will actually analyze. If the research question does not require knowing a participant's age, do not ask for it. If screen recordings will not be reviewed, do not record them. At rest, research data should be:
 - Stored in access-controlled systems, not personal drives or shared folders
-- Anonymized or pseudonymized — names replaced with participant IDs, identifying details removed from quotes before sharing
+- Anonymized or pseudonymized - names replaced with participant IDs, identifying details removed from quotes before sharing
 - Deleted on a defined schedule once the synthesis is complete
 
 Retaining raw recordings indefinitely is a liability, not a resource.
@@ -354,7 +354,7 @@ Research involving **children under 13**, **users with cognitive or developmenta
 
 - Parental or guardian consent for minors, in addition to the participant's own assent
 - Simplified consent language and extended time for participants with cognitive disabilities
-- Safeguarding protocols — a defined plan for what happens if a participant discloses distress during a session
+- Safeguarding protocols - a defined plan for what happens if a participant discloses distress during a session
 - Avoiding incentive structures that exploit vulnerability (large cash payments to economically precarious participants create coercive pressure)
 
 When in doubt about whether a population qualifies for heightened review, treat them as though they do. The cost of over-protecting participants is low; the cost of under-protecting them is not.