@hegemonart/get-design-done 1.18.0 → 1.19.0

package/reference/form-patterns.md

@@ -0,0 +1,245 @@
+# Form Patterns
+
+Forms are one of the highest-friction surfaces in any product. Every unnecessary click, ambiguous label, or poorly-timed error message is a conversion lost or a user abandoned mid-task. The patterns below are grounded in empirical research — primarily Luke Wroblewski's eye-tracking studies, WCAG 2.1 requirements, and NCSC/NIST guidance on authentication UX.
+
+---
+
+## 1. Label Position
+
+Wroblewski's eye-tracking research measured the number of eye fixations required to move from label to field across the three common label placements. The findings are decisive: top-aligned labels are fastest because the eye travels in one direction — down — without a horizontal context switch.
+
+**Top-aligned labels** are the default for most forms. Completion time is fastest because the label and input form a single vertical unit. They also accommodate longer translated strings without breaking layout, making them the correct default for internationalised products. Use top-aligned labels whenever form complexity is moderate to high or field types are mixed.
+
+**Left-aligned labels** create the slowest completion time because the eye must saccade horizontally from label to field on every row. They earn their place only when scannability of values matters more than speed — settings pages, data-entry tables, or read-heavy forms where users compare label and value together. In these contexts the horizontal alignment aids review, not input.
+
+**Floating labels (Material 3 style)** are an acceptable middle ground when screen real estate is severely constrained. The label begins as visible hint text above the field and remains visible (shrunk, repositioned) after the user starts typing. This pattern is distinct from — and incompatible with — placeholder-as-label. Never use placeholder text as the sole label: when the field receives focus the placeholder disappears, leaving the user to recall what was asked. This is a WCAG 2.1 failure under criterion 1.3.5 (Identify Input Purpose) and a general usability failure on any form longer than three fields.
+
+| Label position | Completion speed | Best use case |
+|---|---|---|
+| Top-aligned | Fastest | Most forms; mixed field types; long forms |
+| Left-aligned | Slowest | Settings pages; data comparison; values matter |
+| Floating (Material 3) | Medium | Space-constrained mobile forms |
+| Placeholder-only | — | **Never** — WCAG 1.3.5 failure |
+
+---
+
+## 2. Inline Validation Timing
+
+The timing of inline validation determines whether it helps or hinders. Validate too early and you penalise users for typing incomplete but valid input. Validate too late and users reach the submit button without knowing several fields are wrong.
+
+**On-submit only** carries the lowest cognitive load during form completion and is appropriate for short forms (three fields or fewer). The cost is UX debt on long forms: when multiple fields fail at once, the user must scroll up to find errors, fix one, scroll back, and repeat. Provide an error summary at the top if using submit-only validation on long forms (see Section 3).
+
+**On-blur (field exit)** is the recommended default for most forms. Validation fires after the user leaves the field, not while they are in it. This prevents the jarring experience of an error appearing mid-keystroke. The critical rule: never validate on first focus — only after the field has been blurred at least once. A pristine, untouched field should never show an error state.
+
+**On-change (real-time)** is appropriate for two specific cases: password strength meters and character counters. It is not appropriate for format validation such as email addresses. Validating email format on every keystroke flags `hello@` as invalid before the user has finished typing the domain — a false negative that erodes trust in the form.
+
+Never show a red error state before the user has had a realistic opportunity to complete the field. The error state is a signal that something is wrong; triggering it prematurely teaches users to ignore it.
+
+| Timing | When to use | When to avoid |
+|---|---|---|
+| On-submit | Short forms (≤ 3 fields) | Long multi-section forms |
+| On-blur | Default for most fields | — |
+| On-change | Password strength, character count | Format validation (email, phone) |
+
+---
+
+## 3. Error Placement and Recovery Copy
+
+Errors placed far from their source — in a top banner, a modal, or a footer — force the user to map the error message back to the problematic field. Errors belong immediately below the field they describe, appearing between the field and the next element in the flow.
+
+**Visual treatment**: error messages must never rely on color alone. A red border communicates nothing to users with red-green color deficiency. Use an error icon alongside the message text. The field border color change is acceptable as a supplemental indicator, not the primary one.
+
+**Copy quality matters enormously.** "Invalid input" is useless. The error message must name what went wrong and specify how to fix it. Write the copy in plain language from the user's perspective:
+
+| Poor copy | Better copy |
+|---|---|
+| Invalid input | Email must include an @ symbol |
+| Password error | Password must be at least 8 characters |
+| Required field | Enter your first name to continue |
+| Invalid date | Enter a date in DD/MM/YYYY format |
+
+**Focus management on submit**: when a form submits with errors, move programmatic focus to the first error field or to an error summary element. Leaving focus on the submit button and expecting the user to visually scan for errors is a significant accessibility failure and a poor experience on any device.
+
+**Error summary for long forms**: any form with more than five fields should include an error summary at the top of the form when the user attempts to submit. The summary lists each error with a jump-link that moves focus directly to the relevant field. The summary element should receive focus automatically on submit-with-errors. This pattern is required for WCAG 2.4.3 (Focus Order) on complex forms.
+
+```html
+<div role="alert" aria-labelledby="error-summary-title" tabindex="-1">
+  <h2 id="error-summary-title">There are 3 errors in this form</h2>
+  <ul>
+    <li><a href="#email">Email must include an @ symbol</a></li>
+    <li><a href="#phone">Enter a valid phone number</a></li>
+    <li><a href="#dob">Date of birth must be in the past</a></li>
+  </ul>
+</div>
+```
+
+---
+
+## 4. Required Field Conventions
+
+Marking required fields unambiguously prevents submission errors and sets accurate expectations before the user invests time in a form.
+
+The **asterisk (*) convention** is the web default. Mark every required field with `*` and place the legend "* Required" near the top of the form, before the first field. Users arriving mid-page may not see a legend placed at the bottom.
+
+The **"(optional)" alternative** is better when most fields are required and only a few are not. Marking three optional fields "(optional)" is less visual noise than marking fifteen fields with `*`. Choose one convention per form — never mix both. A form that marks some fields `*` and labels others "(optional)" implies that unlabelled fields are neither required nor optional, which is simply confusing.
+
+Regardless of which visual convention is used, every required field must carry `aria-required="true"` or the native `required` attribute. Screen readers announce the required state from these attributes, not from the visible asterisk.
+
+```html
+<!-- Native required attribute (preferred) -->
+<input type="email" id="email" name="email" required>
+
+<!-- Or explicit ARIA -->
+<input type="text" id="name" name="name" aria-required="true">
+```
+
+---
+
+## 5. Multi-Step Forms
+
+Multi-step forms break long processes into manageable stages, but they introduce navigation complexity that must be managed explicitly. A user who does not know how many steps remain cannot calibrate effort and is more likely to abandon.
+
+**Show total step count upfront** and maintain it throughout. "Step 2 of 4" gives the user a completion model. Never add steps mid-flow; if a conditional step becomes necessary, it must have been accounted for in the total from the beginning. Surprise steps feel like bait-and-switch.
+
+**Preserve state between steps** unconditionally. Browser back must restore the previous step with all previously-entered values intact. Losing data on back-navigation is one of the most damaging patterns in multi-step forms — it destroys user trust and forces re-entry of work already done. Use session storage, URL state, or in-memory state managed at the form's root level.
+
+**Allow non-linear completion where the domain permits.** If a user wants to skip to step 3 and complete step 2 later, let them. Stepped progress indicators (like a horizontal stepper component) should be interactive links, not decorative labels, unless there is a hard dependency that makes out-of-order completion genuinely impossible.
+
+**Summary step before final submission.** Any multi-step form that results in a consequential action — purchase, account creation, booking — should include a review step that shows all entered values before the commit action. The CTA on the summary step should name the action ("Place order", "Create account") not just "Submit".
+
+---
+
+## 6. Autofill Hints — `autocomplete` Taxonomy
+
+The `autocomplete` attribute tells the browser — and password managers, autofill services, and mobile OS keyboards — exactly what category of data a field expects. Proper use of `autocomplete` tokens reduces form completion time by 15–30% in controlled studies, primarily because browsers and password managers can populate multiple fields in a single tap. Always pair each token with the correct `input type`.
+
+| Token | Meaning | Recommended `input type` |
+|---|---|---|
+| `name` | Full name | `text` |
+| `email` | Email address | `email` |
+| `tel` | Full telephone number | `tel` |
+| `username` | Account username | `text` or `email` |
+| `current-password` | Existing password (login) | `password` |
+| `new-password` | New or changed password | `password` |
+| `street-address` | Full street address (multi-line) | `text` or `textarea` |
+| `postal-code` | Postal / zip code | `text` |
+| `country` | Country code (ISO 3166-1 alpha-2) | `select` |
+| `cc-number` | Credit/debit card number | `text` (`inputmode="numeric"`) |
+| `cc-exp` | Card expiry (MM/YY) | `text` (`inputmode="numeric"`) |
+| `cc-csc` | Card security code | `text` (`inputmode="numeric"`) |
+| `bday` | Full date of birth | `date` |
+| `sex` | Gender identity | `select` or `text` |
+| `language` | Preferred language | `select` |
+| `url` | Web address | `url` |
+
+For address fields that are split across multiple inputs, use the sub-tokens (`address-line1`, `address-line2`, `address-level1` for state/province, `address-level2` for city) rather than the generic `street-address` token.
+
+---
+
+## 7. Input Mode and Enter Key Hints
+
+On mobile devices, `inputmode` controls which virtual keyboard the OS presents, independently of the input's semantic type. `enterkeyhint` controls the label shown on the Enter/Go key. Both attributes are pure UX signals — they carry no validation meaning — and they cost nothing to add.
+
+### `inputmode` values
+
+| Value | Keyboard shown | Use for |
+|---|---|---|
+| `none` | No keyboard | Fields with custom picker UI (date pickers, custom selects) |
+| `text` | Standard keyboard | Default; general text |
+| `decimal` | Numeric with decimal separator | Prices, measurements, quantities with fractions |
+| `numeric` | Numeric only (0–9) | Quantities, PIN codes, verification codes |
+| `tel` | Phone dialpad | Phone numbers, even when `type="text"` |
+| `email` | Keyboard with @ and . prominent | Email; `type="email"` sets this implicitly |
+| `search` | Keyboard with Search action | Search fields |
+| `url` | Keyboard with / and . prominent | URLs; `type="url"` sets this implicitly |
+
+### `enterkeyhint` values
+
+| Value | Key label shown | Use for |
+|---|---|---|
+| `enter` | Return / Enter | Multi-line text areas; default where no hint applies |
+| `done` | Done | Last field in a form; closes keyboard |
+| `go` | Go | Single-field forms that submit on Enter |
+| `next` | Next | Fields where Enter moves to the next input |
+| `previous` | Previous | Back-navigation within a multi-step form |
+| `search` | Search | Search fields |
+| `send` | Send | Message composition fields |
+
+```html
+<input
+  type="text"
+  inputmode="numeric"
+  enterkeyhint="next"
+  autocomplete="cc-number"
+  placeholder="Card number"
+>
+```
+
+---
+
+## 8. Password UX
+
+Password fields carry more UX debt than almost any other input type, largely due to outdated security theatre that made passwords harder to use without making them more secure.
+
+**Show/hide toggle** is mandatory on any password field. The eye icon is the standard affordance. Both states must have accessible labels: `aria-label="Show password"` and `aria-label="Hide password"`. The toggle should be positioned as a button inside the trailing edge of the input, using `type="button"` to prevent accidental form submission.
+
+**Never block paste** on password fields. The UK National Cyber Security Centre (NCSC) explicitly recommends against paste-blocking. The rationale is simple: blocking paste discourages the use of password managers, which in turn pushes users toward shorter, simpler, more memorable — and therefore weaker — passwords. Paste-blocking does not prevent any known attack vector on the server side. Remove any `onpaste="return false"` or equivalent.
+
+**Password strength meters** belong on new-password creation flows only. Displaying a strength meter on a login form reveals information about the stored password and adds noise to a flow where speed matters. Use `zxcvbn` or an equivalent entropy-based library rather than simple length/character-class rules, which users learn to game (e.g., "Password1!" satisfies most naive rules but is trivially guessable).
+
+**Show requirements before the user types**, not as errors after they fail. If a password must be at least 10 characters and contain a number, display those requirements beneath the field before the field receives focus. The moment requirements appear only as error messages after submission, the form has trained the user to fail before they can succeed.
+
+```html
+<div class="field">
+  <label for="new-password">Create password</label>
+  <div class="input-with-toggle">
+    <input type="password" id="new-password" autocomplete="new-password" aria-describedby="pw-requirements">
+    <button type="button" aria-label="Show password"><!-- eye icon --></button>
+  </div>
+  <ul id="pw-requirements" class="requirements">
+    <li>At least 10 characters</li>
+    <li>At least one number or symbol</li>
+  </ul>
+</div>
+```
+
+---
+
+## 9. Consent, Confirmation, and Destructive-Confirmation
+
+These three patterns all involve the user acknowledging an outcome, but they operate at different risk levels and require different interaction costs to match.
+
+**Consent checkboxes** govern communication preferences and data use. For marketing communications, the checkbox must be unchecked by default — opt-in is required under GDPR and comparable legislation in most jurisdictions. Pre-checked opt-out is only permissible for certain transactional communications or in jurisdictions that explicitly permit it; assume opt-in required unless legal has confirmed otherwise. The checkbox label must be specific about what the user is consenting to — "I agree to receive marketing emails from Acme Ltd." rather than "I accept the terms."
+
+**Confirmation dialogs** are appropriate for irreversible actions that affect data the user owns — deleting a file, cancelling a subscription, archiving a project. The confirmation dialog must state exactly what will happen. "Are you sure?" is not a confirmation. "Delete the project 'Website Redesign'? This cannot be undone." is a confirmation. The destructive action button should be visually distinct (typically red or a warning tone) and should not be the default focused element.
+
+**Destructive-confirmation with typed phrase** applies to catastrophic, irreversible operations: deleting an account, purging all data, permanently revoking access. Require the user to type a specific phrase — the account name, the word "DELETE", the number of items being erased — before the action becomes available. This pattern exists not to prevent accidents but to ensure the user is making a conscious, deliberate decision. GitHub, Heroku, and most infrastructure tools use this pattern for account deletion. The required phrase should be shown plainly; do not require the user to guess it.
+
+| Risk level | Pattern | Example |
+|---|---|---|
+| Low — reversible | None needed | Moving a file to trash |
+| Medium — data loss possible | Confirmation dialog with specific text | Deleting a saved draft |
+| High — irreversible | Dialog + destructive button style | Cancelling a paid subscription |
+| Critical — catastrophic | Dialog + type-to-confirm phrase | Deleting an account and all its data |
+
+---
+
+## 10. CAPTCHA Ethics and Fallbacks
+
+CAPTCHA presents a genuine tension: friction added to stop bots is friction experienced by every human user, disproportionately by users with cognitive and motor disabilities.
+
+**Invisible CAPTCHA v3** (Google reCAPTCHA v3, Cloudflare Turnstile, hCaptcha Invisible) is the preferred approach. These services score user behaviour in the background and surface a challenge only when the risk score exceeds a threshold. Typical deployments have challenge rates under 1% for real users. There is no visible puzzle, no audio fallback needed for the happy path.
+
+**When a visible challenge is unavoidable**, WCAG 1.1.1 requires a non-visual alternative. Every visual CAPTCHA must have an audio alternative that is solvable with a screen reader and no visual ability. Text-based CAPTCHAs distorted beyond normal variance effectively exclude users with dyslexia and cognitive disabilities — treat this as a legal and ethical risk, not just a UX inconvenience.
+
+**Time-limited CAPTCHAs** — those that expire while a slow or motor-impaired user is completing them — are inaccessible by design and should never be used. If a CAPTCHA session can time out, the user must be able to request a refresh without losing their form data.
+
+**Progressive trust** is the most human approach for authenticated flows. A logged-in user with a verified email and account history presents a negligible bot risk. Do not require CAPTCHA from authenticated users unless there is a specific elevated-risk action (e.g., a bulk API call or mass send). Reserve CAPTCHA friction for unauthenticated, rate-limited, or anomalous-behaviour scenarios.
+
+| Approach | User friction | Accessibility | When to use |
+|---|---|---|---|
+| Invisible CAPTCHA v3 (Turnstile, reCAPTCHA v3) | None | Full | Default for public forms |
+| Visible challenge with audio fallback | Medium | Conditional (audio required) | High-risk unauthenticated flows |
+| Progressive trust (authenticated) | None | Full | Logged-in users with account history |
+| Time-limited CAPTCHA | High | Inaccessible | **Never** |
+| Inaccessible visual-only CAPTCHA | High | None | **Never** |

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 |