@hegemonart/get-design-done 1.18.0 → 1.19.5

package/reference/information-architecture.md

@@ -0,0 +1,255 @@
+# Information Architecture
+
+Information architecture (IA) is the structural design of shared information environments. In practice, it answers three questions for every user at every moment: Where am I? Where can I go? What will I find there? Poor IA is invisible to designers because they already know the answers — it becomes visible only when users get lost, give up, or call support. The sections below cover navigation patterns, depth rules, research methods, wayfinding signals, and the IA decisions embedded in URLs and search.
+
+---
+
+## 1. Navigation Pattern Catalog
+
+No single navigation pattern fits all products. The right choice depends on content volume, user task type, frequency of use, and platform constraints. Each pattern below carries a definition, the conditions under which it is the correct choice, the conditions under which it is the wrong choice, and the mistakes that appear most often in implementations.
+
+### Hub-and-Spoke
+
+**Definition:** A central home or dashboard acts as the hub; users travel outward to destination screens and return to the hub to begin the next task. There is no direct path between spokes — every journey passes through the center.
+
+**When to use:** Hub-and-spoke is correct for mobile applications where tasks are discrete and sequential — banking apps, food delivery, ride-hailing, onboarding flows, and multi-step transaction flows all fit this model. It is also appropriate when users complete one task at a time and context from one task does not carry over to another.
+
+**When NOT to use:** Do not use hub-and-spoke when users need to cross-reference content across destinations, move fluidly between sections, or maintain spatial awareness of a larger content body. A CMS, a design tool, or an analytics dashboard all require users to hold multiple contexts simultaneously — forcing every transition through a hub creates unnecessary friction.
+
+**Common mistakes:** Adding too many spokes to the hub turns the dashboard into an unnavigable index. More than seven to nine top-level destinations on the hub signals that the IA needs a different model, not more spokes. A second mistake is designing spokes that are so isolated they cannot share context — users who need to compare information from two spokes are forced into a hub-and-spoke-and-hub-and-spoke sequence that creates unnecessary cognitive overhead.
+
+---
+
+### Nested (Hierarchical)
+
+**Definition:** Content is organized as a tree: parent categories contain child categories, which contain grandchild items. Navigation moves explicitly from broader to narrower — drilling down to reach specific content.
+
+**When to use:** Nested navigation suits content that is genuinely taxonomic — file explorers, e-commerce category trees, documentation sites with chapters and sub-chapters, and administrative settings panels. The model works when the hierarchy reflects real-world mental models that users arrive with. A user who already knows they want "Electronics → Laptops → 15-inch" will find nested navigation fast and satisfying.
+
+**When NOT to use:** Do not use nested navigation when items belong to more than one parent category, when users lack a pre-formed mental model of the hierarchy, or when the tree depth exceeds four levels. Nested navigation also breaks down when the category labels are ambiguous — users cannot commit to a branch when they are uncertain which branch contains their target.
+
+**Common mistakes:** The most damaging mistake is designing a hierarchy that reflects the organization's internal structure rather than the user's mental model. An insurance company's product hierarchy follows business lines; a customer's mental model follows life events ("I'm buying a car," "I'm having a baby"). These rarely align without deliberate IA research. A second mistake is creating leaf nodes that are too shallow — a category containing only two or three items signals that the hierarchy was over-specified and should be collapsed upward.
+
+---
+
+### Faceted
+
+**Definition:** Content is filtered through multiple parallel, independent attributes simultaneously. Users narrow a result set by selecting values across dimensions — price range, color, brand, rating — without committing to a single hierarchical path.
+
+**When to use:** Faceted navigation is correct for large, multi-attribute content sets where users approach from different starting points. Product catalogs, job boards, property listings, academic literature search, and any context where users have heterogeneous filtering priorities all benefit from faceted navigation. It respects the fact that different users weight attributes differently — one shopper leads with price, another with brand, another with availability.
+
+**When NOT to use:** Do not apply faceted navigation to small content sets (fewer than ~50 items), to content where attributes are not independent of each other, or to contexts where discovery is the primary goal. A curated editorial experience should not be faceted — it should be sequenced. Faceted navigation also fails when the attribute vocabulary is opaque to users: if users do not understand what a facet means, they cannot use it to filter.
+
+**Common mistakes:** Showing too many facets at once overwhelms users and buries the most useful filters beneath low-value ones. The correct approach is to surface the three to five highest-signal facets and hide the rest behind progressive disclosure. A second mistake is allowing facet combinations that produce zero results without feedback — a user who selects three facets and sees an empty state has been failed by the system, which should prevent impossible combinations or warn before they occur.
+
+---
+
+### Flat (Same-Level)
+
+**Definition:** All content lives at a single depth. There are no parent-child relationships — every item is a peer. Navigation means moving laterally across a collection rather than drilling down into it.
+
+**When to use:** Flat navigation is correct for streams, feeds, and timelines — social media feeds, notification inboxes, activity logs, and news aggregators. It is also appropriate for small, finite content sets where every item is equally accessible and no meaningful taxonomy exists. A settings panel with twelve options can be flat; a settings panel with sixty options cannot.
+
+**When NOT to use:** Do not use flat navigation for large content sets. A flat structure with more than thirty to forty items becomes a scroll-based search problem, not a navigation problem. Flat navigation also fails when items have meaningful relationships that should be surfaced — if items cluster into natural groups, those groups should be represented in the structure.
+
+**Common mistakes:** Treating flat navigation as the absence of IA rather than a deliberate structural choice. Flat does not mean unorganized — items in a flat structure still need to be sequenced, grouped visually, or sorted in a way that supports the user's task. A flat feed with no sorting or grouping is a list of equal noise.
+
+---
+
+### Mega-Menu
+
+**Definition:** A persistent top navigation bar expands on hover or click to reveal a large, structured panel — often with multiple columns, category headers, images, and links — without navigating away from the current page.
+
+**When to use:** Mega-menus are correct for large e-commerce sites, enterprise software with many feature areas, and any product where users need to move between dozens of top-level destinations without losing their current context. They are effective when the content taxonomy is stable, well-understood by users, and dense enough that a standard dropdown would require three or more levels of nesting.
+
+**When NOT to use:** Do not use a mega-menu for products with fewer than eight to ten top-level destinations — a standard nav bar or sidebar handles this more cleanly. Mega-menus are also wrong for mobile-first products, where the interaction model (hover) does not translate to touch and the screen real estate does not accommodate wide panels.
+
+**Common mistakes:** Hover-triggered mega-menus introduce a Fitts's Law problem — users must move the pointer from the trigger to the panel without accidentally leaving the hover zone, which closes the menu. The fix is a diagonal tolerance zone (mouse movement toward the panel keeps the menu open) or switching to click-triggered behavior. A second mistake is including too many items without meaningful grouping — a mega-menu with sixty links in a single undifferentiated column is not better than a standard dropdown; it is worse.
+
+---
+
+### Command Palette (Cmd+K)
+
+**Definition:** A modal search-and-command interface, triggered by a keyboard shortcut, that allows users to navigate to any destination, trigger any action, or run any command by typing a query — without using the visible navigation at all.
+
+**When to use:** Command palettes are correct for developer tools, design applications, text editors, and any product where a significant portion of users are power users who build muscle memory for frequent actions. They are additive, not primary — they exist alongside conventional navigation and accelerate users who have internalized the product's vocabulary.
+
+**When NOT to use:** Do not treat a command palette as a substitute for coherent navigation. A command palette cannot help a user who does not know what to ask for — it is a speed tool for users who already know the destination, not a discovery tool for users who do not. It is also inappropriate as a primary navigation mechanism in consumer products where most users are occasional visitors.
+
+**Common mistakes:** Omitting fuzzy matching forces users to type exact command names, which punishes imperfect recall. The palette should match partial strings and surface close alternatives. A second mistake is limiting the palette to navigation links and excluding commands — the value of a command palette compounds when it surfaces actions (create new file, assign to user, publish draft) that would otherwise require three or four clicks through modal interfaces.
+
+---
+
+## 2. Menu Depth Rules
+
+### The 3-Click Rule Debunked
+
+The "3-click rule" — the folk wisdom that users should reach any content within three clicks or they will abandon the site — has been tested empirically and found to be false. Research by Joshua Porter (2003) showed no significant increase in task abandonment at three clicks compared to twelve clicks, provided that each click felt like progress. Users tolerate many clicks when they trust that each click is moving them toward their goal. They abandon quickly when a single click feels uncertain or misdirected. The implication is that click count is the wrong metric; navigational confidence is the right one.
+
+### Scent-of-Information
+
+Information scent is the term usability researchers use for the cues that tell users whether they are on the right path. Strong scent means the link label, category name, or navigation item clearly implies the content waiting behind it. Weak scent means the label is ambiguous, jargon-heavy, or internally meaningful but user-opaque. Users follow high-scent paths confidently; they hesitate at low-scent labels and backtrack when the destination does not match their expectation. This means that IA quality is determined more by label writing than by structural depth. A five-level hierarchy with precise, descriptive labels will outperform a two-level hierarchy with vague ones.
+
+### Practical Depth Limits
+
+Research on spatial disorientation in hierarchical navigation consistently finds that users begin to lose track of their location at depth four and beyond. Three levels is comfortable for most users; four is acceptable with strong wayfinding support; five or more requires aggressive orientation aids and should be avoided unless the content taxonomy genuinely demands it. The practical guidance is:
+
+| Depth | Requirement |
+|-------|-------------|
+| 1–2 levels | Standard navigation; no special wayfinding required |
+| 3 levels | Breadcrumbs required on all interior pages |
+| 4 levels | Breadcrumbs required; consider collapsing the hierarchy |
+| 5+ levels | Structural problem; restructure before shipping |
+
+### Wide vs. Deep
+
+When the content volume forces a choice between a wide structure (many items per level, fewer levels) and a deep structure (fewer items per level, more levels), prefer wide. Seven options across two levels gives the user a manageable decision at each step — they scan seven options, make a choice, scan seven options again. Three options across four levels forces four sequential decisions with three options each, compounding uncertainty at every step. The combinatorial clarity of a wide structure is almost always easier to navigate than the sequential uncertainty of a deep one.
+
+---
+
+## 3. Card Sort Output Interpretation
+
+Card sorting is a generative research method that reveals users' mental models for organizing content. The three variants produce different outputs and serve different purposes in the IA design process.
+
+### Open Card Sort
+
+In an open card sort, participants are given cards labeled with content items and asked to group the cards however makes sense to them, then name each group. The designer provides no predefined categories. The output is a collection of emergent groupings and participant-generated labels. Analysis identifies clusters — items that multiple participants placed together — and the vocabulary participants used to name those clusters. Open card sorts are the right method when the IA is being designed from scratch or when there is genuine uncertainty about how users conceptualize the content domain.
+
+### Closed Card Sort
+
+In a closed card sort, participants sort cards into predefined categories chosen by the designer. The output is a fit score: what percentage of participants placed each item in the intended category. High fit scores confirm that the proposed structure matches users' mental models; low fit scores identify items that users associate with a different category than the designer assumed. Closed card sorts are the right method for validating a proposed structure before it is built.
+
+### Hybrid Card Sort
+
+In a hybrid card sort, participants sort into predefined categories but may also create new categories when existing ones do not fit. This balances validation (closed) with discovery (open). Hybrid sorts are best for early-stage IA validation when the designer has a candidate structure but wants to discover blind spots — items that users persistently refuse to place in the predefined categories signal that the taxonomy is missing a meaningful grouping.
+
+### Reading a Dendrogram
+
+Card sort analysis tools generate a dendrogram — a tree diagram showing how often items were placed together across participants. Items that cluster at the top of the dendrogram (joined early, with high similarity scores) belong together in the navigation; items that cluster late (joined only because everything must eventually merge) are weakly associated. Items that appear in multiple clusters across different participants are IA ambiguities: users genuinely disagree about where they belong, which signals that the item's label or scope is unclear. Ambiguous items require either better labeling, placement in multiple locations, or redesign of the item's concept before the IA can be finalized.
+
+---
+
+## 4. Tree Testing
+
+Tree testing validates an IA structure by presenting users with the navigation tree — text only, no visual design — and asking them to find specific items. Because there is no visual design to influence behavior, tree testing isolates the IA's structural clarity from its visual presentation.
+
+### Success Rate
+
+Success rate measures the percentage of participants who found the correct item. The interpretation thresholds are:
+
+| Success Rate | Interpretation |
+|--------------|----------------|
+| >75% | Good IA; proceed with confidence |
+| 60–75% | Acceptable; improve labeling before launch |
+| <60% | Structural problem; restructure required |
+
+A success rate below 60% is not a labeling problem — it is a structure problem. Improving labels on a fundamentally wrong structure will raise the score modestly but will not fix the underlying mismatch between the IA and users' mental models.
+
+### Directness
+
+Directness measures what percentage of users navigated directly to the correct branch without backtracking. A high success rate with low directness reveals a specific failure mode: users eventually found the item, but only after exploring wrong branches first. This pattern indicates that labels are misleading even when the structure is correct — users are being drawn to the wrong branch by a label that implies the target content, then redirected. Low directness is a reliable signal that high-scent labels on incorrect branches are competing with the correct destination.
+
+### Time-on-Task
+
+Time-on-task compares user navigation time against an expert baseline. An expert who knows the structure performs the task to establish a reference time. Users who take more than twice the expert time are experiencing significant navigational friction — they are backtracking, hesitating at ambiguous labels, or exploring dead ends before finding the correct path. Time-on-task above 2× the expert baseline should trigger qualitative follow-up to understand where users are stalling.
+
+---
+
+## 5. Wayfinding
+
+Wayfinding is the set of signals that answer the user's question "where am I?" at every point in the product. Users need orientation cues at every level of the hierarchy — without them, the product feels like a maze even when the structure is correct.
+
+### Breadcrumbs
+
+Breadcrumbs are mandatory at navigation depth three and above. They provide both a location signal (you are here) and an escape route (return to a higher level without using the back button). Implementation requires two accessibility attributes: `aria-label="Breadcrumb"` on the containing `<nav>` element, and `aria-current="page"` on the final item in the trail. Breadcrumbs should reflect the IA hierarchy, not the user's click history — they are a map, not a path trace. Do not use breadcrumbs at depth one or two; they add visual noise without navigational value at shallow depths.
+
+### Progress Indicators
+
+Progress indicators serve wayfinding in multi-step flows by answering "how far along am I and how much remains?" They should communicate the total number of steps upfront — users make commitment decisions based on total cost, and hiding the endpoint is a dark pattern that erodes trust when the true length is revealed. Never add steps to a flow mid-sequence after the user has begun; if the flow must branch, show the branch as a conditional path rather than as a surprise extension. The visual treatment should distinguish completed steps, the current step, and remaining steps — active state alone is insufficient.
+
+### Orientation Cues
+
+Every screen needs at least three orientation signals: the active state in the navigation (which section is selected), the page title (what this page is called), and section headings within the content (how this page is organized). These signals work together to maintain the user's spatial model of the product. When any of the three is missing, users compensate by re-reading navigation labels or scrolling back to the top — both are friction that well-designed orientation cues eliminate.
+
+### Back-Button Contract
+
+The browser back button carries a strong user expectation: pressing it returns to the previous logical state. This contract is violated whenever back navigates to an unexpected location, triggers a data loss warning, or causes a full page reload that discards scroll position or filled form data. Single-page applications must manage browser history explicitly to honor this contract — pushState for new views, replaceState for filter changes that should not create new history entries. A back-button that shows a "you will lose your changes" modal is almost always a sign that the state management design is wrong, not that users should save more often.
+
+---
+
+## 6. URL Design as IA
+
+### URL Structure Reflects IA
+
+The URL is the IA made visible. A well-structured URL encodes the user's location in the hierarchy and gives users a mental model of the content space before the page loads. `/products/electronics/laptops/macbook-pro` communicates four levels of IA at a glance; a user who reads that URL understands where they are, what the parent categories are, and can predict what they will find by truncating the path. URLs should be designed in parallel with the IA structure, not retrofitted afterward — mismatches between the URL structure and the navigation structure create disorientation.
+
+### Canonical URLs
+
+Every content page should have exactly one canonical URL. Parameter proliferation — multiple URL forms that all resolve to the same content — fragments link equity, confuses users who share URLs, and makes it impossible to use the URL as an orientation tool. Filter and sort parameters in primary navigation (category pages, search results) should use clean path segments or a minimal, consistent parameter scheme. Session tokens, tracking parameters, and internal state identifiers should not appear in canonical URLs. The `<link rel="canonical">` tag is a fallback for URL normalization, not a substitute for URL discipline.
+
+### Semantic Slugs
+
+Content URLs should use human-readable slugs derived from the content title, not opaque numeric identifiers. `/articles/how-to-center-a-div` tells a user — and a search engine — what the page contains before they visit it. `/articles/1234` communicates nothing. Semantic slugs serve three IA purposes: they reinforce content identity, they aid orientation in the URL bar, and they build trust by making the destination legible before the page loads. When titles change, retain the original slug and redirect to the new one rather than changing the canonical URL — URL stability is a form of user trust.
+
+---
+
+## 7. Search vs. Browse Trade-offs
+
+Search and browse are complementary navigation strategies, not competing ones. They serve different user states, and a product that forces users to choose only one will fail a significant portion of its audience.
+
+### When Search Wins
+
+Search is the fastest path for users who know what they want and can express it in words. A user who wants "MacBook Pro 14-inch M3" will find it faster by typing than by navigating five levels of product hierarchy. Search also scales to large content sets where browse becomes impractical — a catalog of one million products cannot be browsed; it must be searched. The failure mode for search is vocabulary mismatch: users who do not know the product's terminology cannot formulate a successful query. A user who wants "noise-canceling headphones" may not know a specific brand name or model identifier, and a search engine that requires precise vocabulary will return nothing useful.
+
+### When Browse Wins
+
+Browse is necessary for discovery — users who are exploring rather than seeking a specific target, users who are learning the product's content space, and users who do not yet know the vocabulary of the domain. A first-time visitor to an e-commerce site discovers product categories by browsing; they cannot search for a category they did not know existed. Browse also serves users who make decisions through comparison — seeing all options in a category simultaneously is a different cognitive task than searching for options one at a time.
+
+### Providing Both
+
+The rule is to provide both search and browse, and to ensure that neither is the only path to deep content. Placing valuable content behind search-only access excludes users who browse; placing it behind browse-only access excludes users who search. The two systems should be complementary: browsing should surface search when the category is large; search should surface browsing when the query is broad or ambiguous.
+
+### Autocomplete
+
+Autocomplete reduces the vocabulary mismatch problem by surfacing valid query terms as users type. It must handle synonyms (headphones / earphones / earbuds should all surface the same category), common misspellings (a typo-tolerant matching algorithm, not exact string matching), and partial matches (the query "mac" should surface MacBook before the user has finished typing). Autocomplete that returns zero results for a near-miss query fails silently — the user sees nothing and concludes that the content does not exist. The system should always return something, even if it is a suggestion to browse a related category.
+
+---
+
+## 8. Faceted Navigation
+
+Faceted navigation is a specific navigation pattern that deserves its own detailed treatment because its implementation quality directly determines whether large content sets are navigable or overwhelming.
+
+### Attribute Facets
+
+Attribute facets are non-hierarchical, independent dimensions — color, size, price range, rating, availability. Users may select multiple values within a single facet (red or blue) and across multiple facets (red, size M, under $50) simultaneously. Each selection narrows the result set by the intersection of all active filters. Attribute facets should be multi-select by default within a single facet — requiring users to choose only one value per facet (single-select) is a common implementation mistake that forces sequential filtering rather than parallel narrowing.
+
+### Hierarchical Facets
+
+Hierarchical facets have parent-child relationships: selecting a parent value constrains the available child values. A "Category" facet that shows Electronics → Laptops → Gaming Laptops is hierarchical — selecting "Laptops" hides subcategories from other categories and reveals laptop-specific subcategories. Hierarchical facets are appropriate when the attribute space is genuinely taxonomic and when child values are meaningless without their parent context. They are inappropriate when users need to select values from multiple branches of the hierarchy simultaneously.
+
+### Progressive Disclosure of Facets
+
+Showing all available facets simultaneously creates a filtering interface that resembles a form more than a navigation tool. The correct approach is progressive disclosure: surface the three to five facets that are most frequently used and most useful for narrowing the result set, then hide the remaining facets behind a "More filters" or "Advanced filters" control. Which facets to surface by default should be determined by usage data, not by the designer's assumptions about what users care about. Surfacing rarely-used facets above frequently-used ones is a common IA mistake that buries the most valuable filtering controls.
+
+### Facet Count Display
+
+Showing the item count beside each facet value communicates two things: the density of information behind that filter value, and whether a given combination is possible. A facet value showing "(0)" tells users that selecting it in combination with existing filters will produce an empty result — this information should be surfaced before the user clicks, not after. Count display also helps users calibrate their filtering strategy: a facet value with 847 items and one with 3 items communicate different search territory. Hiding counts forces users to click and discover, which creates unnecessary round-trips between the filter controls and the result set.
+
+---
+
+## Audit Checklist
+
+Use this checklist when reviewing the IA of an existing product or evaluating a proposed structure.
+
+| Check | Pass criteria |
+|-------|--------------|
+| Navigation pattern matches content type | The structural model (hub-and-spoke, nested, faceted, etc.) fits the content volume and user task type |
+| Depth is ≤4 levels | No path from root to leaf requires more than four navigation steps |
+| Breadcrumbs present at depth ≥3 | All pages at depth three and above display a breadcrumb with correct ARIA attributes |
+| Labels use user vocabulary | Navigation labels match the words users use, not internal jargon or org-chart terms |
+| Search and browse both provided | Users can reach all content by both search and browsing |
+| URLs are semantic and canonical | Every content page has one clean, readable, stable URL |
+| Facet counts are visible | Each facet value shows item count; zero-result combinations are flagged before selection |
+| Back button behaves predictably | Pressing back returns to the previous logical state without data loss warnings |
+| Tree test success rate >75% | Validated by tree testing before launch, or flagged for post-launch testing |
+| Progress indicators show total steps | Multi-step flows communicate total step count upfront |

package/reference/onboarding-progressive-disclosure.md

@@ -0,0 +1,250 @@
+# Onboarding & Progressive Disclosure
+
+New-user experience is the highest-leverage surface in any product. A user who does not reach the aha moment in the first session almost never returns. These guidelines encode the research and failure patterns accumulated across thousands of product launches into concrete, actionable rules.
+
+---
+
+## 1. First-Run Pattern Matrix
+
+Four dominant patterns exist for first-run experiences. Choosing the wrong one for your product type is one of the most common causes of early churn.
+
+| Pattern | When to use | Cognitive load | Completion rate signal | Best for product type |
+|---|---|---|---|---|
+| **Empty-state onboarding** | Product value is only visible once data exists; blank canvas is the default state | Low — user acts on their own terms | First meaningful action taken (e.g. first item created) | Creation tools, CRMs, project trackers |
+| **Product tour** | Interface is dense or non-obvious; terminology requires context | Medium — user is passive during tour | Tour completion rate (misleading — see note) | Feature-rich SaaS dashboards, admin tools |
+| **Checklist-style** | Value comes from setup completion; multiple required steps exist | Medium-high — visible task debt | Checklist completion %, items checked per session | Configuration-heavy tools, integrations |
+| **Progressive disclosure** | Product has many features but a clear primary use case; depth should follow intent | Low at entry, scales with engagement | Feature adoption breadth over time | Consumer apps, platforms with power users |
+
+**Empty-state onboarding** works because the blank state communicates what belongs there. A well-designed empty state — with a clear headline, one CTA, and an illustrative hint — removes the need for any separate tutorial. The first action the user takes is the onboarding. The empty state must not look like an error; it should look like an invitation. Use an illustration or icon that visually previews the populated state, so users understand what they are working toward.
+
+**Product tours** have notoriously misleading completion metrics. A user who clicks through all seven steps of a tour has not learned the product; they have dismissed it. Tours are most defensible when they label unfamiliar terminology (e.g. "This is your Workspace — all your projects live here") rather than demonstrating features the user should simply use. If you do run a tour, keep it to five steps maximum, make every step skippable, and allow re-entry from a persistent help menu.
+
+**Checklist-style onboarding** creates explicit visible progress. The risk is that users who skip to step 4 feel the overhead of incomplete items above them. Keep checklists short (five items maximum) and mark steps as skippable where appropriate. Celebrate completion with a visual reward. Progress bars within checklists should start at roughly 20% complete before the user takes any action — starting at zero signals a daunting amount of work ahead.
+
+**Progressive disclosure** is the correct default for most modern products. Surface only what is needed at each stage of the user's journey and reveal depth as intent emerges. The cost of this approach is instrumentation: you must know what your users are actually doing in order to know what to surface next. Without event tracking and funnel analysis, progressive disclosure devolves into guesswork about which features to promote and when.
+
+---
+
+## 2. Feature Discovery Patterns
+
+### Tooltip Hints
+
+Tooltips surface contextual information at the moment of relevance without blocking interaction. Follow these placement rules strictly:
+
+- Position tooltips above the target element by default; fall back to right, left, then below only when viewport space requires it.
+- Never place a tooltip over the element it describes — it should annotate without obscuring.
+- A dismiss button (×) is required on any tooltip that is not triggered by hover alone. Users must always have a clear, explicit path to close.
+- Cap tooltip hints at **three per session**. A fourth tooltip in the same session means the user has seen enough hints that the interface should simply be better, not that more hints are needed.
+- Do not re-show a dismissed tooltip within the same session. Respecting the dismissal is the contract.
+
+### Spotlight / Coach Marks
+
+Spotlight overlays draw attention to a specific UI element by dimming the surrounding interface. Use them only for genuinely non-obvious interaction points — elements whose purpose or location a reasonable user would not discover through normal exploration.
+
+Never use coach marks for:
+
+- Buttons with clear labels and standard placements (Save, Submit, Add)
+- Navigation items that follow a platform convention (hamburger menu, tab bar, breadcrumb)
+- Anything that should be self-evident from the design itself
+
+If a feature requires a spotlight to be understood, the spotlight is a symptom. The root cause is an affordance problem in the design that should be fixed first.
+
+### Pulsing Nudges
+
+Animation draws the eye. That is precisely why animation budgets must be strictly managed:
+
+- **Only one pulsing element may be active on screen at any time.** Two simultaneous pulses cancel each other's signal and create anxiety rather than direction.
+- Stop showing the pulse after the user has seen it across **three separate sessions** without interacting. After three exposures without action, the user has seen the nudge and chosen not to act. Continuing to pulse is nagging, not guidance.
+- Use a subtle scale pulse (1.0 → 1.08 → 1.0, ease-in-out, 1.2s, 2-second delay between cycles) rather than color flashing, which creates accessibility issues for users with photosensitive conditions.
+- Store the "seen count" in persistent state (user record or localStorage as a fallback) so the counter survives page reloads.
+
+### Contextual Help
+
+Help icons, drawers, and inline `?` affordances provide depth on demand without occupying primary UI real estate:
+
+- Place `?` icons immediately to the right of the label they annotate, at the same vertical center.
+- Use a help drawer (slide-in panel) when the content exceeds three sentences. Modals are inappropriate for help content because they block the interface the user is trying to understand.
+- Distinguish between hover-triggered tooltips (quick factual answers, ≤ 20 words) and click-triggered drawers (procedural explanations, examples, links to documentation).
+- Help icons should use a consistent icon throughout the product — do not mix `?`, `ℹ`, and `…` as help affordances in the same interface.
+
+---
+
+## 3. Tutorial Sequencing
+
+### Before Value, Not Before Use
+
+The most common tutorial design mistake is gating access to the product behind tutorial completion. This inverts the relationship between value and instruction. The correct principle is: **teach before the moment of value, not before the moment of entry.**
+
+A user who has already experienced value will sit through a brief explanation of how to get more value. A user who has not yet experienced anything will resent being forced through a walkthrough of a product they are not yet convinced is worth their time.
+
+Concretely: let the user reach their first meaningful outcome, then surface the "here's how to go further" guidance immediately after.
+
+### Activation Metric vs. Habituation Metric
+
+These two metrics measure different things and should never be conflated:
+
+**Activation metric** — the event that indicates a user has experienced the product's core value for the first time. It is a binary event measured once. Examples: first project created, first file synced, first message sent.
+
+**Habituation metric** — the behavioral pattern that indicates a user has formed a habit around the product. It is a frequency measure over a time window. Examples: 3 sessions per week for 4 consecutive weeks, 5 actions per session on 7 of the last 10 days.
+
+Activation predicts retention at day 7. Habituation predicts retention at day 30 and beyond. Optimizing only for activation produces users who try the product once and never return. Optimizing for habituation without a clear activation path means most users never get far enough to form the habit.
+
+### Tutorial Abandonment and Step Budget
+
+Research across SaaS products consistently shows that **mean drop-off occurs at step 3** in multi-step onboarding flows. Users who reach step 4 are disproportionately engaged; steps beyond 4 reach a small fraction of users.
+
+The implication is direct: **keep required onboarding to three steps or fewer.** Optional depth can exist beyond step 3, but nothing essential to basic product use should require more than three steps to reach.
+
+If your product genuinely requires more than three setup steps before value is deliverable, that is a product architecture problem, not an onboarding problem.
+
+### Deferred Tutorial
+
+Users who land in a product for the first time are in a state of orienting, not learning. They are trying to understand whether the product is relevant to them, not how to become experts.
+
+Surface a "Start guided tour" CTA on the **second session**, not the first. By the second session, the user has self-selected — they came back, which means something in the first session was interesting enough to return to. They are now in a learning state, not an evaluation state, and will benefit from structured guidance.
+
+First-session tutorials should be limited to a single contextual hint or a dismissible welcome banner — not a step-by-step walkthrough.
+
+---
+
+## 4. The 5-Second Rule
+
+Within five seconds of landing on a product for the first time, users form judgments on three dimensions that are extremely difficult to revise:
+
+1. **Value proposition clarity** — Do I understand what this product does and who it is for?
+2. **Trust signals** — Does this look credible, maintained, and professional?
+3. **Visual confidence** — Does the design itself inspire confidence in the product's quality?
+
+These are not conscious evaluations. They are fast, affective responses to visual and linguistic signals. A product that fails the 5-second test loses users before any feature or flow is ever reached.
+
+**How to test:** Show the homepage or first screen to a user for exactly five seconds (a timer-based first-click test works well). Then hide the screen and ask: "What does this product do? Who is it for? Would you trust it with your data?" Correct answers on all three indicate the screen passes.
+
+**What passing looks like:**
+- The headline names the outcome, not the mechanism ("Ship faster without context switching" rather than "A collaborative project management platform")
+- At least one social proof or trust signal is visible above the fold (customer count, recognizable logo, security badge)
+- The visual design is internally consistent — font pairing, spacing, and color are coherent enough that the product feels intentional
+
+A screen that takes longer than five seconds to parse is not being evaluated — it is being abandoned.
+
+**Common failures:**
+
+| Signal | Why it fails the test |
+|---|---|
+| Headline is the product's name only | Communicates nothing about value or audience |
+| Hero image is abstract or decorative | Wastes the most valuable visual real estate |
+| No price or pricing signal | Triggers "is this for me?" uncertainty |
+| Social proof is below the fold | Trust is not established before the judgment is made |
+| CTA is "Learn more" | Does not indicate what action the user should take |
+
+Run the 5-second test on every major entry point: homepage, onboarding email landing, in-app feature announcements, and pricing page. Each is a first impression for a different user segment.
+
+---
+
+## 5. Aha-Moment Mapping
+
+### Defining the Aha Moment
+
+The aha moment is the first time a user experiences the core value the product was built to deliver. It is not a feature adoption event and not an engagement metric — it is the specific moment when the product's promise becomes real and personal to the user.
+
+Without a defined aha moment, onboarding cannot be optimized because there is no agreed destination to optimize toward.
+
+### Reference Examples
+
+The most cited aha moments in product history illustrate what the concept means in practice:
+
+- **Twitter**: Users who followed at least 10 accounts within their first 48 hours retained at a dramatically higher rate than those who did not. The aha moment was not "post a tweet" — it was "see a feed of people you actually care about."
+- **Slack**: Teams that exchanged at least 2,000 messages retained at over 90%. The aha moment emerged from the accumulated experience of communication flow, not from any single interaction.
+- **Dropbox**: Users who synced at least one file experienced the aha moment. The product's promise — "your files everywhere" — only became real once the first file was genuinely accessible on a second device.
+
+In all three cases, the aha moment is an outcome state, not a feature interaction. This distinction matters for instrumentation.
+
+### Instrumentation and Cohort Analysis
+
+To find your product's aha moment, run the following analysis:
+
+1. **Define candidate activation events** — identify 5–10 behavioral events that plausibly represent first value (first export, first share, first search with results, first item added, etc.).
+2. **Build retention cohorts by activation event** — for each candidate event, create two cohorts: users who performed the event in their first session vs. users who did not. Measure day-7 and day-30 retention for each cohort.
+3. **Identify the event with the largest retention delta** — the event whose presence most strongly predicts that users will still be active 30 days later is your aha moment proxy.
+4. **Validate with qualitative research** — confirm with user interviews that users who performed the event actually experienced a moment of genuine value, not just navigated through a flow.
+5. **Reduce the time-to-aha** — once the event is identified, redesign onboarding to move the user toward that event as quickly as possible, removing every unnecessary step in between.
+
+The aha moment is a hypothesis that must be re-evaluated as the product evolves. A feature change or new user segment can shift the activation event.
+
+---
+
+## 6. Anti-Patterns
+
+### Forced Tours
+
+A forced tour blocks access to the product until the user completes a tutorial sequence. This pattern consistently destroys retention because it starts the relationship with a power imbalance: the product demands the user's time before delivering any value in return.
+
+Users who complete forced tours do so under duress, not interest. Their completion rate looks healthy in analytics, but their recall of tour content is near zero. More critically, the forced-tour experience establishes a negative first emotional association with the product that carries forward into subsequent sessions.
+
+**Never gate the product behind tutorial completion.** The skip button is not a concession — it is a requirement.
+
+### Blocking Modal Overlays
+
+Modal overlays that cover the interface to display instructional content are problematic on two grounds. First, they prevent the user from interacting with the very interface they are being instructed about — learning by doing is impossible when the interface is obscured. Second, full-screen modal overlays frequently fail WCAG 2.1 Success Criterion 1.3.4 (Orientation) and 2.1.2 (No Keyboard Trap) when implemented without proper focus management, making them inaccessible to keyboard and screen reader users.
+
+Use inline empty states, contextual tooltips, or side drawers for instructional content. Reserve modals for actions that require a decision before proceeding, not for passive information delivery.
+
+### Tooltip Spam
+
+Displaying more than three tooltips simultaneously creates cognitive overload. The user cannot process multiple concurrent annotations — they will either dismiss all of them without reading or abandon the session. Three concurrent tooltips is already at the upper threshold of what users will tolerate; two is better; one is the correct default.
+
+If your interface requires more than three tooltips to be usable, the interface needs redesign, not more tooltips.
+
+### Feature Announcements on Every Login
+
+Surfaces that display feature announcement banners, modals, or toasts on every login train users to dismiss without reading. After two or three sessions of seeing a banner, dismissal becomes an automatic motor behavior, not a reading behavior. This renders the announcement channel useless for future communications that actually matter.
+
+Feature announcements should be shown once per feature, in context (near the new feature), and only to users for whom the feature is relevant. A user who has never used the reporting module should not see an announcement about reporting improvements.
+
+### Onboarding for Features They Did Not Request
+
+Proactively onboarding users to features they have not expressed interest in violates their intent. A user who opened the product to complete a specific task and is instead walked through an unrelated feature experiences the tutorial as an interruption, not a benefit.
+
+Progressive disclosure exists precisely to prevent this: surface depth in response to observed intent, not on a broadcast schedule. If a user navigates to a feature for the first time, that is the correct moment to offer brief guidance. If they have never navigated to it, it is not the correct moment to introduce it.
+
+---
+
+## 7. Measuring Onboarding Health
+
+Onboarding is only improvable if it is measured. The following metrics form the minimum instrumentation layer for any product with an intentional onboarding strategy.
+
+**Time-to-activation** measures how long it takes a new user to reach the defined activation event from their first login. Expressed as a median and p75 (the slowest 25% of activating users). A rising time-to-activation without a corresponding increase in activation rate indicates that the activation path has grown longer or more confusing.
+
+**Activation rate** is the percentage of new users who reach the activation event within a defined window (typically 7 days). Baseline activation rates vary widely by product category, but any activation rate below 40% warrants investigation. An activation rate above 70% is a strong signal.
+
+**Onboarding funnel drop-off** tracks step-by-step completion rates through any sequential onboarding flow. Every step should be instrumented individually. Drop-off above 30% at any single step is a red flag requiring immediate qualitative investigation — user interviews, session recordings, or both.
+
+**Feature discovery breadth** measures how many distinct features or feature areas a user touches in their first 14 days. Low breadth in early sessions is not necessarily a problem — focused users often have the highest retention — but anomalously low breadth combined with low retention indicates that users are not finding the product's range of value.
+
+| Metric | Healthy range | Warning threshold |
+|---|---|---|
+| Time-to-activation (median) | < 5 minutes | > 20 minutes |
+| Activation rate (7-day) | > 50% | < 30% |
+| Step drop-off (any single step) | < 20% | > 35% |
+| Day-7 retention | > 40% | < 20% |
+| Day-30 retention | > 20% | < 10% |
+
+These thresholds are reference points drawn from cross-industry SaaS benchmarks. They will vary by product category, pricing model, and acquisition channel. Calibrate against your own historical baseline before treating any single number as universal.
+
+---
+
+## Quick-Reference Decision Rules
+
+The rules below consolidate the most common judgment calls into explicit thresholds. Apply them as defaults; deviate only with data.
+
+| Question | Rule |
+|---|---|
+| How many tooltip hints per session? | Maximum 3 |
+| How many pulsing elements on screen? | Maximum 1 |
+| How many steps in required onboarding? | Maximum 3 |
+| When to surface guided tour CTA? | Second session, not first |
+| When to stop showing a pulsing nudge? | After 3 sessions seen without interaction |
+| Can a tutorial block product access? | Never |
+| How many concurrent tooltips? | Maximum 1 (hard ceiling 3) |
+| How often to repeat a feature announcement? | Once per feature, in context |
+| What determines the aha moment? | Largest day-30 retention delta across cohorts |
+| What does passing the 5-second test require? | Correct answers on value, audience, and trust |