@3xhaust/oh-my-design 0.16.1

package/core/theory/color.md

@@ -0,0 +1,285 @@
+# Colour — decision material
+
+The question "what colour should this be" is not answered by preference. It is answered by
+the domain the product sits in, the register the concept demands, and what the colour will
+be required to do. Preference is the noise; these are the signal.
+
+---
+
+## Domain conventions and why they exist
+
+Colour conventions are not arbitrary. They are residues of what worked — or what users
+learned to expect — in each industry. Violating them requires a reason proportional to the
+cost of breaking the expectation.
+
+**Fintech and banking.** Blue, deployed consistently since the 1980s, carries a specific
+claim: trustworthiness and institutional stability. Elliot & Maier (2014,
+*Color-in-Context*) map blue to cognitive associations with calm, reliability, and
+competence — properties banking literally sells. Navy amplifies authority; desaturated
+mid-blue reads as honest and measured; bright cobalt reads as technology-forward. If your
+fintech product is positioning *against* legacy banking (neobanks, crypto wallets), the
+blue is exactly what you reject — but you are then making a claim and you must support it.
+Breaking the convention is valid. Breaking it without knowing you broke it is not.
+
+**Healthcare.** Green and white. White signals cleanliness — a hospital ceiling rather than
+a brand choice, but one that research has made load-bearing. Green is associated with
+healing and growth in Western contexts (Itten, *The Art of Color*, 1961). The danger zone
+is red: Elliot & Maier's color-in-context research documents a reliable anxiety response to
+red in evaluative contexts — patients waiting for results are already in an elevated state.
+High-saturation red raises it further. Red is reserved for confirmed errors only; everything
+else uses softer treatment.
+
+**Education.** Warm palettes — orange, amber, warm yellow — encode approachability and
+curiosity. IBM Design Language classifies warm hues as "energetic and optimistic," which
+is correct for learning contexts where the interaction cost is effort. Blue appears in
+formal educational contexts (universities, certifications) where authority is the value
+being sold.
+
+**Food and beverage.** Red and yellow reliably increase appetite and urgency — McDonald's
+is not branding folklore, it is a tested outcome. Brown and warm earth tones signal
+naturalness and craft (artisan bread, coffee, fermented anything). Green signals health and
+freshness, especially in plant-based or organic positioning. Cold blues and purples suppress
+appetite; avoid them unless the product is a diet tool and suppression is the point.
+
+**Developer tools.** Dark backgrounds with green or blue accent are so established they
+read as genre, not style. If you are building a developer tool, dark mode is not an
+aesthetic option — it is the expected register. Material Design classifies this as a "dark
+theme" preference, not a style preference, for productivity contexts. Deviating succeeds
+only when the product is deliberately positioned at non-technical users who happen to use
+developer tooling (Vercel's white marketing site, Linear's light mode). Colour the UI dark
+and the marketing light.
+
+**Luxury.** Black, deep navy, warm off-white, metallics. High contrast without brightness.
+The signal is restraint: a luxury product does not shout. IBM Design Language codes the
+"premium" register as low saturation, high value contrast, accents used sparingly. Any
+saturated colour in a luxury context reads as a mistake unless it is the brand's exact
+signature colour.
+
+---
+
+## Harmony schemes: when to use each
+
+These are not visual preferences. Each scheme produces a different relationship between
+elements, and the wrong scheme undermines the concept regardless of the individual colours.
+
+**Complementary** (opposite on the hue wheel — blue/orange, red/green, purple/yellow):
+high tension, high contrast, high energy. Use when the concept demands urgency or power.
+Use for a single CTA accent against a neutral ground — never for large fields of both
+colours simultaneously, which produces visual vibration that is measurably harder to read.
+
+**Analogous** (adjacent hues — blue/blue-green/green): low tension, harmonious, cohesive.
+Use when the concept demands calm, trust, or continuity. Fintech blue into teal is
+analogous; its visual cohesion is the point, not the accident.
+
+**Triadic** (three equally spaced hues): balanced energy, more complex than analogous but
+less aggressive than complementary. Use when the product has genuinely distinct feature
+areas that benefit from colour differentiation. Hard to execute; requires one dominant, one
+secondary, one accent — not three equals competing for attention.
+
+---
+
+## The 60-30-10 distribution
+
+60% dominant (backgrounds, large surfaces), 30% secondary (components, containers), 10%
+accent (CTAs, active states, critical notifications). This is not aesthetic orthodoxy — it
+is a reading law. Eye-tracking research (NN/g, "Visual Hierarchy and Attention") shows that
+equal colour distribution eliminates hierarchy: the eye cannot rank what weighs the same.
+The 60-30-10 split creates a reading order by making some things obviously heavier.
+
+Invert it and you get AI slop: the accent colour used for backgrounds, the dominant colour
+used for highlights. Everything reads as equally important, so nothing is important.
+
+---
+
+## Saturation and register
+
+Saturation is a signal about urgency and authority. This relationship is consistent across
+Itten's original colour theory and validated in Material Design's colour system (2023):
+
+**High saturation** reads as urgent, energetic, playful. Appropriate for: alerts, primary
+CTAs, food brands, entertainment, consumer apps targeting younger users. Inappropriate for:
+banking, legal software, health monitoring, anything where the user is already in an
+elevated state. Anxiety does not need more stimulation.
+
+**Mid saturation** reads as friendly and accessible without aggression. The safe register
+for most consumer products — present without shouting.
+
+**Low saturation (muted)** reads as authoritative, mature, premium. Appropriate for:
+enterprise tools, luxury brands, healthcare, editorial products. IBM Design Language
+explicitly codes low-saturation palettes as "professional" and reserves high saturation for
+interactive states only.
+
+A colour decision without a saturation decision is half a decision. The hue is the genre;
+the saturation is the register within that genre. Choosing green for a healthcare product
+is a start; choosing muted sage green instead of saturated lime is the actual decision.
+
+---
+
+## Background temperature
+
+Backgrounds are not neutral. A warm background (slightly yellow, cream, warm grey) creates
+a different psychological environment than a cool one (blue-grey, neutral-white, near-black).
+
+**Warm backgrounds**: approachable, organic, human. Appropriate for products where
+connection and warmth are the value proposition — communication tools, creative tools,
+consumer apps. The warmth carries even at very low saturation; a barely-tinted cream reads
+differently from a cool white.
+
+**Cool backgrounds**: crisp, precise, efficient. Appropriate for productivity tools,
+fintech, developer tools. Signals that the environment is here to help you work, not to be
+pleasant. Cool surfaces say "focus."
+
+**True neutral** (pure white or near-black): no temperature signal. Appropriate when the
+content itself must carry all the temperature — photography sites, portfolio tools, editorial
+platforms. The absence of warmth or coolness is deliberate.
+
+The background temperature sets the emotional register for every colour that sits on it.
+A warm accent on a cool background reads as a guest; the same accent on a warm background
+reads as native. Choose the temperature before choosing the accent, not after.
+
+---
+
+## Dark mode: the rules for colour adjustment
+
+Dark mode is not "light mode inverted." It is a different palette built on different
+physics. The three most common errors:
+
+**Pure black (#000000) is the wrong dark background.** On OLED panels, pure black pixels
+are off — the transition between lit and unlit pixels as you scroll produces a strobing
+effect that users feel as discomfort without being able to name. More importantly, pure
+black gives zero depth: every surface is on the same plane, so the elevation system
+(cards, modals, tooltips) collapses. Google's Material Design dark theme specification uses
+#121212 as the baseline surface; layers of elevation are expressed as white-tint overlays
+at increasing opacity (4%, 8%, 12%, 16%, 24%). This preserves the depth system without
+fighting the contrast requirements.
+
+**Saturated accent colours vibrate on dark backgrounds.** A brand colour calibrated for
+a white ground carries too much energy when placed over dark grey — the eye perceives it as
+louder than intended, a phenomenon called simultaneous contrast. The fix is desaturation:
+reduce the accent's saturation by 20–30% for the dark palette. The colour reads as the same
+brand colour; it no longer shouts. Uxcel's dark mode guidelines and Material Design 3's
+tonal palette system both prescribe this adjustment explicitly.
+
+**Text hierarchy uses opacity, not grey values.** On dark surfaces, secondary text is not
+a specific grey hex — it is white at reduced opacity. Material Design's dark theme
+recommendation: primary text at 87% opacity, secondary text at 60%, disabled/hint text at
+38%. The reason is practical: the surface colour changes across the elevation system, and
+fixed hex values for text will fail the contrast requirements on the wrong surface. Opacity
+scales with whatever it sits on; a fixed grey does not.
+
+Condition → choice → reason: when the background lightness is below L\* 25 (very dark),
+desaturate all chromatic accents and express text hierarchy through white-opacity tiers,
+not through separate grey values.
+
+---
+
+## Accessibility contrast: APCA vs WCAG 2
+
+The WCAG 2.x contrast ratio (minimum 4.5:1 for body text, 3:1 for large text) has been
+the accessibility floor since 2008. It has a fundamental flaw: it computes contrast as a
+static ratio between two colours, and treats a light-weight 12px label identically to a
+bold 24px heading at the same colour values. The same contrast ratio on different text
+produces radically different readability outcomes.
+
+The Advanced Perceptual Contrast Algorithm (APCA), developed by Andrew Somers, corrects
+this. APCA calculates a lightness contrast value (Lc) that accounts for font size and
+weight simultaneously — a thin 14px label and a bold 32px heading require different
+minimum contrast scores. The model is based on human visual perception of spatial frequency
+and luminance, not arithmetic ratios. The W3C has confirmed APCA as the contrast model for
+the forthcoming WCAG 3.0 standard.
+
+The practical consequence today: WCAG 2.x compliance is required for legal accessibility
+standards in most jurisdictions — it is the floor. APCA thinking is the ceiling: use it to
+catch situations where a WCAG 2.x-passing colour combination still fails at small sizes or
+light weights. A muted secondary label in a fintech dashboard might pass 4.5:1 against its
+background while being genuinely difficult to read at 11px regular weight. APCA flags it;
+WCAG 2.x does not.
+
+Condition → choice → reason: when the design includes small text (below 16px) or thin
+weights (300–400) in informational roles, verify not just the WCAG 2.x ratio but the Lc
+score under APCA. The APCA Contrast Checker tool at git.apcacontrast.com provides the
+calculation. Do not stop at compliance; stop at legibility.
+
+---
+
+## Cultural colour conventions: East Asian and Korean markets
+
+Western colour psychology does not travel without adjustment. The two most commercially
+significant divergences for Korean and East Asian markets:
+
+**Red signals prosperity, not danger.** In Western UI convention, red is reserved for
+errors, alerts, and destructive actions — a reliable association built on traffic signals,
+fire, and blood. In Korean and broader East Asian contexts, red historically signals good
+fortune, celebration, and vitality. Red envelopes (홍보봉투) carry money at celebrations;
+red text appears in festive and auspicious contexts. A Korean e-commerce product using red
+for a sale badge is following cultural convention, not violating the error-colour rule. The
+consequence for product design: the error-state semantic for red must be established
+explicitly through context (icon, label, placement) when designing for Korean audiences,
+not assumed from the colour alone.
+
+**White carries mourning associations.** In Western contexts, white is sterile, clean,
+minimal. In traditional Korean and East Asian mourning customs, white is the colour of
+death and funerals. Contemporary Korean design has largely absorbed the global white-equals-
+clean convention for digital products, but white-dominant aesthetics in healthcare or
+financial products touching elderly Korean users carry a risk of misread that does not
+exist in Western markets. A warm off-white or a cream-tinted background removes the
+ambiguity without sacrificing the clean register.
+
+**Gold and yellow signal prestige.** Where luxury Western products typically reach for
+black, navy, and restraint, East Asian luxury context extends to gold as a prestige signal
+— associated with royalty, success, and premium quality across Korean, Chinese, and
+Japanese markets. This legitimises gold accents in premium Korean product design in ways
+that would read as garish in a Western luxury context.
+
+Condition → choice → reason: when the primary market is Korean or East Asian, audit every
+colour's semantic layer against the target culture's conventions before treating Western
+colour psychology as ground truth.
+
+---
+
+## Data visualisation palettes vs UI palettes
+
+These are different systems serving different purposes, and conflating them produces both
+ugly charts and a broken UI colour system.
+
+**UI palettes** are built for hierarchy. The accent is one colour, used at one saturation,
+in one role. Introducing six distinct categorical colours into a UI palette creates visual
+chaos: the eye cannot rank what cannot be compared. UI palettes need three to five tones
+from one or two hue families, and one semantically loaded accent.
+
+**Data visualisation palettes** are built for distinction. The primary requirement is that
+every category is unambiguously different from every other under multiple viewing conditions
+— colour blindness, screen glare, printout. The standard approach (Color Brewer, a research
+project by Cynthia Brewer at Penn State) provides tested categorical palettes of 3–12
+colours calibrated for perceptual distance. These palettes are deliberately non-hierarchical:
+no one colour should read as more important than another in a categorical context.
+
+The failure mode is using the UI brand colour as the first category colour in a chart and
+the UI secondary as the second. The user reads the first bar as "primary action" and the
+second bar as "secondary action" — a UI reading that corrupts the data reading. Separate
+the systems. The chart's categorical blue is not the button's blue; they are different
+tokens with different semantics.
+
+Condition → choice → reason: when the product includes data visualisation, create and
+maintain a separate visualisation token set. Borrow nothing from the UI palette except the
+neutral surfaces and the background.
+
+---
+
+## Sources
+
+- Itten, *The Art of Color* (1961) — hue relationships and the psychological force of colour
+- Elliot & Maier, "Color-in-Context Theory" (2014) — empirical mapping of colour to
+  psychological state in evaluative contexts
+- IBM Design Language (2023) — enterprise colour system and saturation register
+  classification
+- Material Design 3 (2023) — dynamic colour system, role definitions, tonal palettes, dark
+  theme surface specification (#121212 baseline, white overlay elevation)
+- NN/g, "Visual Hierarchy and Attention" — eye-tracking evidence for the reading-order
+  effect of colour weight distribution
+- Uxcel, "12 Principles of Dark Mode Design" (2023) — desaturation guidelines for accent
+  colours on dark surfaces
+- APCA / Andrew Somers, git.apcacontrast.com — Advanced Perceptual Contrast Algorithm;
+  the contrast model for forthcoming WCAG 3.0
+- Brewer, Color Brewer (colorbrewer2.org) — perceptually calibrated categorical palettes
+  for data visualisation

package/core/theory/components.md

@@ -0,0 +1,272 @@
+# Components — decision material
+
+A component is not a widget. It is the materialisation of a decision about what a
+particular kind of interaction should feel like. The button is not a rectangle with a
+label — it is a commitment about hierarchy, risk level, and action weight. Get the
+component wrong and you get the interaction wrong regardless of how well everything else
+was designed.
+
+---
+
+## Buttons: hierarchy and the destructive case
+
+Buttons communicate hierarchy before the label is read. The visual treatment — fill, stroke,
+or text — signals importance. The order is not convention; it is a reading rule.
+
+**Primary (filled)**: the most important action on the current view. There should be at
+most one primary button per context. Two filled buttons of equal visual weight cancel each
+other — the user cannot tell which to press, which is the same as not telling them at all.
+Material Design and Carbon Design System both specify single primary-per-view as an
+explicit constraint, not a preference.
+
+**Secondary (outlined or tonal)**: an alternative action — not less important in absolute
+terms, but less important than the primary in this context. A "Save Draft" alongside a
+"Publish" is a secondary. An "Export" alongside a "Save" is a secondary. The outline
+signals presence without competing with the fill for attention.
+
+**Tertiary (text or ghost)**: low-stakes or escape actions. "Cancel," "Back," "Skip for
+now" — actions the user needs available but should not be nudged toward. The absence of
+visual container makes these recede from attention deliberately.
+
+**Three tiers is the ceiling.** Four button types on one screen is four sentences spoken
+simultaneously. Helios Design System (HashiCorp) and most mature design systems cap
+hierarchy at three tiers. If the design requires a fourth tier, the problem is not a
+missing button variant — it is too many actions on one view.
+
+**Destructive actions sit outside the hierarchy and require explicit treatment.** A
+"Delete," "Cancel Subscription," "Remove Account" action should never be styled as a
+primary button unless deletion is the only thing the current view exists to do. The
+destructive variant — typically a red or amber filled button — communicates risk at a
+glance. Position destructive buttons away from the primary CTA: the spatial separation is
+the last friction before an irreversible action. The Carbon Design System specifies a
+"danger" semantic variant with its own colour role precisely because the danger cannot be
+communicated by label alone — a user scanning quickly will press the large filled button.
+If that button is "Delete," the fill is a trap.
+
+Condition → choice → reason: when a view contains a destructive action, create a dedicated
+destructive variant (never reuse primary styling), position it away from the primary CTA,
+and consider a confirmation step for irreversible actions.
+
+---
+
+## Form inputs: validation timing
+
+Inline validation — showing error or success state as the user types — changes
+completion rates, but timing matters more than presence.
+
+Validating on each keystroke is the worst option. The field fails before the user has
+finished typing the correct answer. An email address field that flags an error after "user"
+(before "@domain.com" is typed) teaches the user that the form is hostile. The error state
+is wrong, and the user did nothing wrong.
+
+Validating on blur (when the user leaves the field) is the standard and usually correct
+timing. The user has completed their answer; now the system responds. Errors are surfaced
+at the moment they can be acted upon, without interrupting the act of entering them.
+
+Validating only on submit is appropriate for short forms (2–3 fields) where the
+relationship between fields matters (password and password-confirmation must match). It is
+wrong for long forms — an error at the top of a 20-field form that only surfaces on submit
+sends the user back to the beginning.
+
+The Baymard Institute's form usability research (baymard.com, "Avoid Extensive Multi-column
+Layouts") documents the failure mode: inline validation errors that fire too early increase
+form abandonment rates because users interpret them as the form rejecting valid input.
+
+Condition → choice → reason: validate on blur for single-field validation; validate on
+submit when validation requires cross-field data; never validate on keystroke unless the
+field has a live counter (character limit, password strength meter) where the feedback is
+progress information rather than error state.
+
+---
+
+## Navigation: Miller's Law, misused
+
+Miller's Law — "The Magical Number Seven, Plus or Minus Two" (Miller, 1956, Psychological
+Review) — established that working memory can hold approximately 7 items at once. It has
+been misused as a design rule for navigation: "keep navigation under 7 items because of
+Miller." This is a misapplication.
+
+Miller's original finding was about chunking in working memory under experimental
+conditions, not about navigation comprehension in visual scanning. Navigation items are
+not memorised serially — they are scanned visually. The eye finds familiar labels through
+pattern recognition, not sequential recall. A navigation bar with 8 items is not harder to
+use than one with 7 because of working memory limits; it is harder to use if the visual
+weight is too high, the labels are ambiguous, or the hierarchy is unclear.
+
+The legitimate constraint is visual: navigation items compete for attention with the
+content. Too many items reduce the available space per item, force abbreviation or wrapping,
+and reduce the visual weight of each label below the scannable threshold. The practical
+ceiling for top-level navigation is 5–7 items — not because of Miller, but because above
+that count, the labels are too compressed to scan reliably at normal reading distance.
+
+**Mobile: bottom tab bar vs hamburger menu.** Research (NN/g, "Hamburger Menus and Hidden
+Navigation Hurt UX Metrics", 2016) measured the effect of hiding navigation behind a
+hamburger icon: discoverability, engagement, and user satisfaction all dropped when
+navigation was hidden. Bottom tab bars — persistent, always-visible — produce higher
+engagement with navigation items than hamburger menus, because visible options are more
+likely to be used than hidden ones. The tab bar is the better choice for the primary
+navigation of any mobile product where the user's destination is not always the same.
+The hamburger is legitimate for secondary or overflow navigation — options that the user
+knows to look for but does not need on every session.
+
+Condition → choice → reason: use a persistent bottom tab bar for the 3–5 primary
+destinations of a mobile app; reserve the hamburger for secondary settings, profile, and
+overflow items.
+
+---
+
+## Tables: density, alignment, and column locking
+
+A table is a spatial argument. The row is a record; the column is a property. Every
+decision in a table design either supports or undermines the user's ability to compare
+across rows and navigate down columns.
+
+**Column alignment follows data type.** Text columns are left-aligned — the eye enters
+text from the left and left-alignment provides a consistent anchor column for scanning.
+Numeric columns are right-aligned — this places the least significant digit at a fixed
+horizontal position, which enables numerical comparison down the column at a glance.
+Dates are right-aligned when used for sorting comparison; they may be left-aligned in
+conversational contexts (an activity log) where the date is a label, not a value.
+Misaligned numeric columns make comparison impossible regardless of the data they contain.
+Use `font-variant-numeric: tabular-nums` to ensure digits are the same width; proportional
+digits misalign even in right-aligned columns.
+
+**Density is a tradeoff between information per screen and cognitive load.** Compact rows
+(24–32px) allow more data per viewport, which is appropriate for expert users who have
+trained for the task (data analysts, financial operators). Comfortable rows (40–48px) allow
+the eye to identify the current row without active tracking, which is appropriate for
+general-purpose tables where the user's cursor is not always near the data they are reading.
+Default to comfortable; move to compact only when the reduction in scrolling genuinely
+improves the task.
+
+**Fixed columns unlock horizontal scrolling.** When a table has many columns and requires
+horizontal scrolling, the first column (the row identifier — name, ID, record title) should
+be fixed. Without it, the user scrolls right and loses the context that names what they
+are looking at. This is not a visual preference; it is the difference between a scannable
+table and one that requires memorising the row identity before scrolling.
+
+**Zebra striping vs hover highlighting.** Alternating row background colours (zebra
+striping) aid row tracking in wide tables by giving the eye a colour reference to follow
+across columns. Research at Software Usability Research Laboratory (Purdue University, 2008)
+found zebra striping reduced reading errors in wide tables by a measurable margin. In
+narrow tables (3–4 columns), striping adds visual noise without the benefit — the columns
+are close enough to track without colour assistance.
+
+---
+
+## Modals: the overuse problem and its alternatives
+
+A modal dialog interrupts the current task and requires the user to respond before
+continuing. This interrupt is the cost. The interrupt is only worth paying when the
+information requiring response is genuinely critical and cannot be presented in context.
+
+The overuse pattern: modals are used as the path of least resistance for any complex
+interaction that the designer does not want to solve in context — a settings form, a
+confirmation step, an extended detail view, a secondary workflow. The modal becomes a
+workaround for insufficient layout thinking.
+
+**The alternatives, by use case:**
+
+*Additional context about an existing item* — use **inline expansion** (a disclosure
+region below the row, or an accordion panel). The content appears in context; the user
+never leaves their current position; no overlay is required.
+
+*A secondary workflow that the user initiates deliberately* — use a **side panel / drawer**
+that slides in from the edge without replacing the current content. The primary view
+remains visible; the secondary workflow is spatially separated but contextually connected.
+
+*A transient action requiring quick input* — use a **popover** anchored to the trigger
+element. Small, non-blocking, dismissable. Appropriate for colour pickers, tag editors,
+date pickers, short confirmations.
+
+*Non-critical status communication* — use a **toast notification** that appears without
+interrupting the task and disappears after a short duration.
+
+Modals are legitimate for: destructive confirmation (deleting records, cancelling
+subscriptions), authentication gates (permission prompts, reauthentication), and complex
+forms that are explicitly task-isolated (a "create new project" form where no in-context
+alternative exists). Even in these cases, keep the modal content minimal — a modal with
+scrolling content has ceased to be a modal; it is a page that lacks a URL.
+
+Condition → choice → reason: before designing a modal, name the alternative and the reason
+it does not apply. "The modal was easier to implement" is not a reason; it is a cost
+transferred from the designer to the user.
+
+---
+
+## Toast notifications and alert hierarchy
+
+Feedback messages are not all the same weight. A toast that says "Changes saved" and a
+toast that says "Your account will be deleted in 24 hours" are using the same component
+for radically different situations. The hierarchy of feedback:
+
+**Inline validation errors**: adjacent to the field, persistent until corrected. The error
+stays visible because it needs to be referenced while the user corrects the input. A toast
+that vanishes after 3 seconds is wrong for this — the user may not have read it before it
+disappears.
+
+**Page-level alerts / banners**: a persistent strip above the content, requiring explicit
+dismissal or action. Used for: degraded service warnings, quota limits, required actions
+before proceeding. Appropriate when the condition affects the entire current task and needs
+to remain visible.
+
+**Toast / snackbar notifications**: transient, auto-dismiss after 3–5 seconds. Used for:
+confirmation of non-critical completed actions ("Saved," "Copied to clipboard," "Email
+sent"). Never use for errors that require action — a toast dismisses itself before the user
+can read and respond, leaving the user without context for what went wrong.
+
+**Modal alerts**: reserved for situations where the user must acknowledge before proceeding.
+True critical errors, destructive confirmations, blocking conditions. The interrupt is the
+point — the user cannot proceed without addressing this.
+
+The common failure is using toasts for errors. "Payment failed" as a toast is a critical
+error delivered in a transient container — it may vanish before the user notices it, and
+even if they see it, it disappears before they can read any detail about why it failed.
+Errors that require action belong in persistent, in-context containers.
+
+---
+
+## Search UI patterns
+
+Search is not a feature, it is an entire interaction model. The decision of how to surface
+search determines whether users who cannot navigate will find anything at all.
+
+**The search input placement.** The search input belongs where the content lives — in the
+page header for global search, above a list for list-specific search. A search icon that
+triggers an overlay or a page navigation to a search page adds a step between the user and
+the results. The step costs engagement, particularly for exploratory searches where the
+user is not certain what they are looking for.
+
+**Immediate vs submit-triggered results.** Typeahead (results updating on each keystroke)
+is the correct choice for any search over bounded data where the server can respond in under
+200ms. It removes the "submit and wait" loop and allows the user to steer the query
+toward what is actually available, which is more efficient than crafting a full query in
+advance. Submit-triggered search is appropriate for large unindexed datasets where
+typeahead would be too slow or too broad to be useful.
+
+**Empty search state vs zero-results state.** These are different screens with different
+jobs. The empty search state (the search input just received focus, no query typed) should
+show recent searches, popular items, or a helpful starting prompt — never a blank field
+with nothing to do. The zero-results state should explain why there are no results (common
+causes: typo, too-specific query, out-of-scope category) and offer a path forward (suggested
+queries, a broader search, a direct contact option). A zero-results page that says only
+"No results found" has told the user that their query failed without helping them succeed.
+
+---
+
+## Sources
+
+- Miller, "The Magical Number Seven, Plus or Minus Two" (1956, Psychological Review) —
+  working memory chunking; note the common misapplication to navigation counts
+- NN/g, "Hamburger Menus and Hidden Navigation Hurt UX Metrics" (2016) — bottom tab bar
+  vs hamburger menu engagement and discoverability comparison
+- Material Design 3, Button component — single primary-per-view, hierarchy specification
+- Carbon Design System (IBM), Button — danger/destructive semantic variant specification
+- Helios Design System (HashiCorp), Button Organisation — three-tier ceiling rationale
+- Baymard Institute, "Avoid Extensive Multi-column Layouts" (baymard.com) — inline
+  validation timing and abandonment rate research
+- Software Usability Research Laboratory (Purdue University, 2008) — zebra striping and
+  row-tracking error rates in wide tables
+- NN/g, "Website Forms Usability: Top 10 Recommendations" — validation timing, label
+  placement, single-column preference
+- Google Fonts Knowledge, "Understanding numerals" — tabular-nums for column alignment