saglitzdesign-mcp 0.3.1

package/knowledge/books/psychology-of-design.md

@@ -0,0 +1,152 @@
+---
+id: psychology-of-design
+title: "Design Psychology — Perception, Memory, Motivation (Weinschenk + Universal Principles)"
+category: book
+platform: both
+tags: [psychology, gestalt, attention, memory, motivation, decision-making]
+sources: ["100 Things Every Designer Needs to Know About People (Susan Weinschenk, 2011)", "Universal Principles of Design (Lidwell, Holden & Butler, 2003)"]
+updated: 2026-07-08
+---
+
+# Design Psychology — The ~25 Most Actionable Findings
+
+How people perceive, attend, remember, read, decide, err, and stay motivated — each finding stated as a rule an interface can obey. Grouped by cognitive function.
+
+## Perception (Gestalt, applied)
+
+**1. Proximity is your strongest free grouping tool.** Elements near each other are perceived as related — before borders, boxes, or color. Rule: encode relationships with spacing first (label near its input, actions near their object); reach for containers only when proximity is exhausted. Corollary: accidental proximity creates false relationships — a stray button near the wrong card will be read as belonging to it.
+
+**2. Similarity groups across distance.** Same color/shape/size = same kind of thing, even far apart. Rule: keep one visual treatment per role (all links alike, all destructive actions alike, all metadata alike) so users learn the system once. Never reuse a role's treatment for something unrelated.
+
+**3. Common region and connectedness override proximity.** A box or a connecting line beats spacing. Rule: use cards/containers to force grouping when layout constraints break proximity — and never draw a container around unrelated things.
+
+**4. Closure and continuity: people complete patterns.** A partially visible card implies scrollability; aligned elements imply a sequence. Rule: deliberately cut content at the fold/edge to signify "more"; keep alignment lines clean because users will follow them — a misaligned element reads as either broken or intentionally separate.
+
+**5. Figure/ground: people parse foreground vs. background instantly.** Rule: modals need a dimmed scrim to read as foreground; keep background decoration low-contrast so it never competes with content for figure status.
+
+**6. People see what they expect (and miss what they don't).** Perception is pattern-matching against experience. Rule: put things where conventions predict (logo top-left, search top-right, primary action bottom-right of a dialog on desktop). Users will also miss changes outside their focus (change blindness) — never update important state silently in a screen corner; bring the change to the point of attention.
+
+**7. Peripheral vision decides where to look next — and notices motion.** Rule: page-level "gist" is formed from the whole layout, not the part being read; keep peripheral areas calm. Use motion/animation only for the one thing that must attract attention; ambient animation (auto-carousels, looping banners) steals attention perpetually and gets banner-blindness in return.
+
+**8. Faces get looked at first, and gaze direction steers attention.** Rule: use faces sparingly and deliberately; if a photo's subject looks toward the CTA or key text, users look there too. A face looking off-page drags attention off-page.
+
+## Attention
+
+**9. Attention is selective and goal-filtered.** Users on a task filter out everything that doesn't look task-relevant — including your important notice, if it looks like an ad (banner blindness). Rule: critical information must appear in the task's path, styled like content, not like promotion.
+
+**10. Salience is zero-sum.** Every highlighted element reduces every other element's chance of being seen. Rule: budget one focal point per screen; audit by squinting/blurring — whatever survives the blur is what users will see first, and it had better be the right thing.
+
+**11. Sustained attention is short; interruptions are costly.** Rule: design flows resumable (autosave drafts, keep place in wizards); front-load the essential step; assume ~7–10 minutes of focus for any continuous task before minds wander.
+
+## Memory
+
+**12. Working memory holds ~3–4 chunks, briefly.** (The classic "7±2" overstates it; Weinschenk: design for 3–4.) Rules: never make users carry information between screens — repeat it (show the plan being paid for on the payment screen); chunk long strings (card numbers as 4-4-4-4, phone as 3-3-4); limit menus and option lists to scannable groups rather than one flat wall.
+
+**13. Recognition beats recall — always.** Rule: pickers over blank fields, recent/frequent items surfaced, autocomplete everywhere, previews instead of remembered names. Any UI that asks "what was it called?" should ask "is it one of these?" instead.
+
+**14. Memory is reconstructive and error-prone.** Users misremember what they did and what the app said. Rule: keep history visible (order history, activity logs, "last edited" stamps); never rely on users remembering a warning shown once.
+
+**15. People forget, so repeat and remind.** Rule: onboarding lessons decay in days — reinforce by contextual hints on Nth use, not a one-shot tour. Progressive disclosure beats a front-loaded manual: reveal complexity exactly when it becomes relevant (Universal Principles: "progressive disclosure").
+
+## Reading
+
+**16. Reading on screen is scanning in an F/zigzag pattern, driven by headings.** Rules: front-load keywords in headings, links, and list items; the first 2 words of a line carry most of the scan value; one idea per paragraph, meaningful subheads every few paragraphs.
+
+**17. Reading ability ≠ reading preference: keep it simple.** Even expert users prefer plain language. Rules: aim for ~grade 6–8 reading level in UI copy; active voice; verbs on buttons ("Save changes", not "OK"); avoid ALL CAPS for running text (it slows reading and reads as shouting — fine for short labels).
+
+**18. Legibility mechanics matter more than font aesthetics.** Rules: body text ≥16px on the web, adequate contrast (WCAG 4.5:1), line length 45–75 characters, real paragraphs spacing. Weinschenk: hard-to-read fonts make the *task itself* feel harder — perceived difficulty transfers from typography to product.
+
+## Decision-making
+
+**19. More choices = fewer decisions (choice overload).** People say they want more options and choose more readily from fewer. Rules: 3–5 options at any decision point; if the catalog is genuinely large, decide *for* the user first (defaults, "most popular" badge, a recommended tier) and let them override. Hick's Law (Universal Principles): decision time grows with number and complexity of options — split big decisions into sequenced small ones.
+
+**20. Defaults are decisions you make for the user — most users keep them.** Rules: default every field you responsibly can; make the default the safest and most common choice; never default users into hard-to-reverse or costly options (dark-pattern territory).
+
+**21. Most decisions are unconscious and feel-driven, then rationalized.** Social proof, scarcity, and framing move behavior more than specs. Rules (used ethically): show real usage evidence ("2,341 teams use this") near decisions; frame prices/values against an anchor (show the annual saving next to monthly price); only state true scarcity.
+
+**22. People are loss-averse and value what they own (endowment).** Rules: free trials work because leaving becomes a loss — show users what they've built/accumulated when they consider downgrading; frame preservation ("Keep your 14 projects") over acquisition. Never weaponize this into guilt ("confirm-shaming").
+
+## Errors and safety
+
+**23. People will make errors — design forgiveness, not blame (Universal Principles: "forgiveness").** Rules: undo > confirmation; confirmations reserved for the irreversible; preserve all user input through failures; constrain inputs so wrong entries are impossible (pickers, masks, live formatting). Error messages: say what happened, why, and the one next step — near the field, in plain language, without red-shouting the entire form.
+
+**24. When stressed, people tunnel.** Under time pressure or after an error, users see less of the screen and read less. Rules: error-state screens must be radically simpler than normal screens — one message, one action; put recovery controls exactly where the eye already is; never add promotional content to error/empty states.
+
+## Motivation and engagement
+
+**25. Progress is motivating; the closer the goal, the harder people work (goal-gradient).** Rules: show progress bars for multi-step flows; pre-fill some progress ("Profile 20% complete — you signed up!") because artificial head-starts measurably increase completion; break long journeys into visible stages with completion checkmarks.
+
+**26. Dopamine rewards seeking and anticipation, and variable rewards hook hardest.** Unpredictable rewards (new content, likes, surprises) drive checking behavior more than fixed ones. Rules: use ethically — celebrate genuine achievements (first project shipped) with small delightful moments; do NOT engineer compulsive variable-reward loops (endless feeds, streak anxiety) into productivity tools; give users natural stopping points.
+
+**27. Small commitments grow into big ones.** People act consistently with prior actions. Rules: ask for tiny first steps (one field, not a 12-field signup); defer heavy asks (full profile, payment details) until after the user has experienced value; sequence onboarding as an escalating ladder of micro-commitments.
+
+**28. Intrinsic beats extrinsic: mastery, autonomy, connection.** Rules: show users their own skill growth (stats, streaks-as-history not streaks-as-threat); let users customize and control their space (autonomy); make social features about genuine connection (collaboration, sharing) — leaderboards motivate the top 10% and demotivate the rest.
+
+**29. People are inherently lazy (least effort) — and that's fine.** Users satisfice and do the minimum needed. Rules: don't build for the thorough user who reads everything; make the lazy path the correct path (safe defaults, one-click common actions, smart suggestions). If the right behavior requires effort, redesign until it doesn't.
+
+**30. Aesthetic–usability effect (Universal Principles).** Attractive interfaces are perceived as easier to use and are forgiven more faults. Rule: visual polish is not vanity — it buys user patience and trust; but never use it to paper over a broken flow, because the effect delays complaints, not failures.
+
+## Cross-cutting Universal Principles worth enforcing
+
+- **Fitts's Law:** time-to-target depends on distance and size. Big, close targets for frequent actions; screen edges/corners are "infinite" targets on desktop; thumb-zone (bottom of screen) for primary mobile actions; tiny far-away targets only for actions you want to slow down (destructive).
+- **Performance load:** every bit of cognitive or physical work reduces completion. Audit each flow: remove a field, a step, a decision, a read — repeatedly.
+- **80/20:** 20% of features drive 80% of use. Give that 20% the prime placement and polish budget; move the rest behind progressive disclosure.
+- **Consistency (internal > external):** matching your own app's patterns matters most; matching platform conventions second; being novel is a cost you must justify.
+- **Confirmation + constraint pairing:** the safest systems combine constraints (can't do it wrong), good defaults (right without thinking), forgiveness (undo), and only then confirmation (last resort).
+
+## Applying the findings to common screens
+
+**Sign-up / onboarding:**
+- Minimize the first ask (#27): email + password or SSO only; everything else deferred until it gates a real feature.
+- Show a progress head start (#25) if setup has steps; celebrate the first real success (#26), not account creation.
+- Teach in context (#15): tooltips on first encounter with each feature, never a 6-slide upfront tour.
+
+**Forms:**
+- One column, top-aligned labels (scan pattern, #16); chunk long forms into titled sections of 3–5 fields (#12).
+- Constrain and format inputs live (#23); default everything defensible (#20).
+- Errors inline, adjacent, single-next-step; simplify the screen when errors appear (#24).
+
+**Pricing pages:**
+- 3 tiers, one visually recommended (#19, #20, #21); anchor with the highest tier positioned first or the saving framed against monthly (#21).
+- Social proof adjacent to the decision, specific and true (#21); trial framed so accumulated work is what users would lose by leaving (#22) — without guilt copy.
+
+**Dashboards:**
+- One focal metric per view (#10); peripheral areas static (#7); tables use recognition aids (icons, colors + labels, not color alone).
+- Respect 3–4 chunks (#12): group KPIs, don't line up twelve equal tiles.
+
+**Feeds / content apps:**
+- Variable reward dynamics apply whether you want them or not (#26) — add natural stopping points ("You're all caught up") in tools meant to respect time.
+- Faces in thumbnails capture attention (#8); use deliberately, budget salience (#10).
+
+**Error and empty states:**
+- Tunneled users (#24): one sentence, one button, recovery in the eye's current position.
+- Empty states are motivation moments (#25, #27): tiny first step, visible path, no dead ends.
+
+## Five more findings worth enforcing
+
+**31. People form mental models from the first exposure and resist updating them.** The first screen teaches users how the whole product works. Rule: make the first-run experience structurally representative of the real product — a wizard-style onboarding for a canvas-style tool teaches the wrong model.
+
+**32. Multitasking is a myth; task-switching is expensive.** Rule: one task per screen; never require users to consult another screen/app mid-flow (show the code, don't make them fetch it); minimize notifications during active flows.
+
+**33. People respond to computers socially.** Polite, human wording gets cooperation; machine-speak gets abandonment. Rule: write UI copy as a competent, brief human would speak ("We couldn't save that — try again?" not "Error 4092: operation failed"); reciprocity works — give value before asking (show the report preview before requesting the email).
+
+**34. Feedback timing shapes perceived speed.** Perceived wait, not actual wait, drives satisfaction; uncertain waits feel longer than known waits, and occupied time passes faster. Rule: skeleton screens over spinners; determinate progress over indeterminate whenever possible; do work optimistically and reconcile in the background.
+
+**35. Anecdote beats data; stories beat statistics.** People process narratives more deeply and remember them longer. Rule: lead with the concrete case ("Maria's team shipped 2× faster"), support with the number; structure onboarding and marketing pages as a story (situation → struggle → resolution) rather than a feature matrix.
+
+## Ethical line
+
+Weinschenk's findings describe how people work; several (scarcity, variable rewards, loss aversion, commitment escalation) power dark patterns when aimed at the business's goal instead of the user's. Rule of thumb: a technique is legitimate when it helps users do what they already came to do faster and with more confidence; it is a dark pattern when it manufactures a goal, hides a cost, or exploits a bias against the user's interest. An assistant applying this file should refuse the latter framing and propose the honest equivalent.
+
+## Quick audit checklist
+
+- [ ] Grouping by proximity/similarity is deliberate; no accidental groups; one treatment per role
+- [ ] One focal point per screen; passes the squint test; nothing important styled like an ad
+- [ ] No screen requires remembering anything from a previous screen; recognition over recall throughout
+- [ ] Headings/links front-loaded with keywords; UI copy ~grade 6–8; buttons are verbs
+- [ ] ≤5 options per decision; sensible safe defaults everywhere; big decisions split into small ones
+- [ ] Undo over confirm; inputs constrained; error states simplified and tunnel-vision-friendly
+- [ ] Progress visible with a head start; first asks tiny; lazy path = correct path
+- [ ] Frequent actions big and near (thumb zone / edges); rarely-needed complexity progressively disclosed
+- [ ] Waits made determinate/occupied (skeletons, progress); copy human and story-led
+- [ ] Every persuasion technique passes the ethics test: helps the user's existing goal, hides nothing

package/knowledge/books/refactoring-ui.md

@@ -0,0 +1,157 @@
+---
+id: refactoring-ui
+title: "Refactoring UI — Tactical Visual Design (Wathan & Schoger)"
+category: book
+platform: both
+tags: [visual-design, hierarchy, spacing, color, typography, polish]
+sources: ["Refactoring UI (Adam Wathan & Steve Schoger, 2018)"]
+updated: 2026-07-08
+---
+
+# Refactoring UI — Tactical Visual Design Tricks
+
+The book's thesis: you don't need innate artistic talent to make interfaces look professional — you need a bag of concrete, repeatable tactics. These are those tactics, stated as rules with before/after framing.
+
+## 1. Starting a design
+
+- **Start with a feature, not a layout.** Don't design the shell (navbar, sidebar, footer) first — design the actual thing the app does ("book a flight": two fields, date, button). The shell falls out of the features, never the reverse.
+- **Detail comes later.** Sketch at low fidelity (thick marker, grayscale wireframe) so you can't fuss over fonts and shadows before the flow works. Hold the color.
+- **Don't design too much.** Design a screen, build it, then design the next. Real data and real constraints will invalidate speculative screens ("work in cycles").
+- **Design the smallest useful version.** If a feature has an optional nice-to-have (comments with attachments), ship the core (comments) first; don't let the enhancement block the design.
+- **Choose a personality deliberately** and express it through consistent choices: font (serif = elegant/classic, rounded sans = playful, neutral sans = plain/professional), color (blue = safe, gold = premium, pink = playful), border radius (none = serious, large = friendly — pick one scale and never mix), and language tone. Personality drift (mixed radii, mixed tones) reads as amateur instantly.
+- **Limit your choices in advance.** Define systems — a type scale, a spacing scale, a color palette, a shadow scale — then pick from the system instead of the infinite continuum. Deciding among 8 font sizes is fast; deciding among 1–100px is paralysis. If you're ever nudging by 1px, you're missing a system.
+
+## 2. Hierarchy is everything
+
+The single highest-leverage idea: most UIs look bad because everything competes. **Deliberately de-emphasize most things so the few important things win.**
+
+- **Size is not the only (or best) lever.** Instead of huge primary text and tiny secondary text, use **weight and color**: dark high-contrast for primary content, medium grey for secondary, lighter grey for tertiary. Two or three text colors + two font weights (normal ~400/500, bold 600/700) cover almost everything. Before: 24px title / 12px meta. After: 18px semibold dark title / 14px regular grey meta — calmer and clearer.
+- **Never use grey text on colored backgrounds** by lowering opacity alone if it looks washed out; instead hand-pick a color with the same hue as the background, lighter and less saturated. On a blue button, "grey" text should be light blue.
+- **Emphasize by de-emphasizing.** If an element (e.g., active nav item) won't stand out, don't make it louder — make its siblings quieter (grey the inactive items). Competing-loudness is the default failure mode; subtraction is the fix.
+- **Labels are a last resort.** "Name: Erin Lindford / Phone: (555) 765-4321" wastes hierarchy on labels. Most data is self-evident from format (email, price, name) or context. When clarity needs help, fold the label into the value ("12 left in stock", "3 bedrooms") — and when labels are truly needed (dense data-heavy pages, settings), style them as secondary, not as the loud element.
+- **Semantics ≠ visual hierarchy.** An `<h1>` doesn't have to be huge; section titles often act as labels and should be small. Style by role in the visual hierarchy, not by HTML tag.
+- **Balance weight and contrast.** Icons are visually "heavy" next to text — soften them (lighter grey) to balance. Thin borders that feel too faint: don't darken them, thicken them; too-heavy bold text at small sizes: reduce contrast instead of weight.
+- **Actions have hierarchy too.** Per screen: one primary action (solid, high contrast), secondary actions (outline or soft background), tertiary (link-styled). **Destructive ≠ automatically big and red** — if delete isn't the primary action, make it a quiet secondary/tertiary control and save the big red button for the confirmation step.
+
+## 3. Layout and spacing
+
+- **Start with too much white space, then remove.** Dense-by-default reads cramped; generous-by-default reads designed. Only densify deliberately (dashboards, tables where overview is the point).
+- **Use a spacing/sizing scale** with multiplicative steps, e.g. 4, 8, 12, 16, 24, 32, 48, 64, 96, 128px. Adjacent values must differ by a clearly visible ratio (~≥25%); linear 2px steps create indistinguishable choices.
+- **You don't have to fill the whole screen.** A 600px-wide form on a 1400px canvas is correct — don't stretch content to the viewport. If a component needs to be small, design it small; spreading a simple form across the full width before: long input rows floating apart; after: narrow centered column, instantly scannable. Likewise, don't shrink the whole design to fit mobile — cut or stack, don't scale.
+- **Grids are useful, guides not gospel.** Fixed-width sidebars beat percentage columns (a sidebar shouldn't grow because the screen did). Max-widths beat fluid everything. Let content determine size ("give it what it needs"), then use the grid for alignment.
+- **Relative sizing doesn't scale.** Don't define everything in em-of-parent; large elements should shrink faster than small ones across breakpoints (a hero headline drops from 48 to 30px; body stays 16). Same for buttons: bigger buttons need proportionally more padding, small buttons proportionally less.
+- **Ambiguous spacing is a bug.** Groups must be closer to their own parts than to neighbors: a heading closer to the text below it than to the section above; a form label closer to its input than to the previous field; list-item spacing greater than intra-item line-height. If grouping is unclear, fix space before adding borders.
+
+## 4. Text
+
+- **Type scale:** hand-pick a fixed set (e.g. 12, 14, 16, 18, 20, 24, 30, 36, 48px) rather than a mathematical ratio that yields fractional sizes. Use px/rem, not em, so sizes don't compound.
+- **Font selection heuristics:** for UI, favor neutral sans-serifs with tall x-height; ≥5 weights available is a decent proxy for quality; when unsure, crib font choices from sites you admire; system font stack is a safe default.
+- **Line length: 45–75 characters** (~20–35em). Even inside a wide card, constrain paragraph width.
+- **Baseline-align mixed sizes** (a big number next to a small unit) rather than center-aligning.
+- **Line height is proportional to both size and width:** small text and wide columns need more (up to ~2.0 at 12–14px in wide layouts); large headlines need less (~1.1–1.3). Never one global line-height.
+- **Links in UI:** most UI "links" don't need blue+underline; use weight/color subtly, since half the interface is clickable anyway. Reserve loud link styling for links inside prose.
+- **Alignment:** left-align by default; right-align numbers in tables (compares magnitudes); center only short, independent blocks. Justify only with hyphenation enabled.
+- **Letter-spacing:** tighten slightly on large headlines (fonts are spaced for body sizes); widen for ALL-CAPS labels.
+
+## 5. Color
+
+- **Work in HSL**, not hex — hue/saturation/lightness map to how humans reason about color.
+- **You need more colors than you think:** ~8–10 shades of grey, 5–10 shades of the primary, and 5–10 shades of each accent/semantic color (red destructive, yellow warning, green positive) — defined up front, not improvised per screen.
+- **Build a shade scale:** pick the base (works as a button background) first, then the darkest (text) and lightest (tinted background) ends, then fill gaps to ~9 steps. Don't generate shades by lightness alone: **as a color lightens, reduce saturation compensation is needed; as it darkens or lightens away from base, increase saturation** to avoid washing out. For brighter perceived shades without white-wash, **rotate hue toward the nearest bright hue** (yellow, cyan, magenta); darker: rotate toward red, green, blue. Never rotate more than ~20–30°.
+- **Greys don't have to be grey:** cool greys = saturate with blue; warm greys = saturate with yellow/orange. Pick a temperature and use it everywhere.
+- **Accessible doesn't have to be ugly:** to hit 4.5:1 on colored backgrounds, flip the contrast — instead of white text on medium blue, use dark blue text on light blue background. Same for badges/alerts.
+- **Never rely on color alone** to convey meaning (colorblind users): pair with icons, text, or position; for positive/negative use contrast (grey vs. red) not just red/green.
+
+## 6. Depth: shadows, layers, borders
+
+- **Light comes from above.** Raised elements (buttons): subtle lighter top edge, small dark shadow below. Inset elements (wells, checked checkboxes, inputs): slightly darker top inner shadow.
+- **Define a shadow scale (~5 levels)** and map elevation to meaning: small tight shadows for buttons/cards, medium for dropdowns, large soft for modals. Shadows also serve interaction: increase shadow while dragging; a button pressing down loses its shadow.
+- **Two-part shadows look best:** one larger soft ambient shadow + one tighter darker direct shadow; the tight one fades first as elevation increases.
+- **Flat designs can still have depth:** lighter = closer, darker = recessed; short vertical offset solid shadows keep depth without gradients.
+- **Overlap elements to create layers:** cards straddling two background colors, avatars overlapping a stack (with a background-colored ring to fake a border), an image extending past its card. Overlap instantly reads as "designed."
+- **Fewer borders:** before reaching for a 1px line, try a box-shadow, different background colors between sections, or simply more spacing. Border-everything is the #1 cluttered-UI smell.
+
+## 7. Images
+
+- **Use good photos or none.** A mediocre phone snapshot destroys otherwise-good design; use professional stock or real professional photography, or design a no-photo layout.
+- **Text over images needs a treatment:** darken overlay, lower image contrast, colorize (desaturate + primary-color multiply), or a soft text-shadow "glow". Never raw white text on a raw photo.
+- **Everything has an intended size:** icons designed at 16–24px look chunky and amateur scaled to 3×; instead, keep the icon small inside a colored shape/container. Screenshots shrunk to fit look illegibly dense — take them at small viewport widths, crop to the relevant portion, or draw simplified representations. Favicons enlarged look terrible — recreate simple flat versions.
+- **User-generated content:** control the shape (center-crop into fixed containers) and prevent background bleed (a subtle inner shadow/ring instead of a border keeps white logos from disappearing on white cards).
+
+## 8. Finishing touches — cheap polish
+
+- **Supercharge the defaults:** replace list bullets with icons (checkmarks for features, arrows for links), style blockquotes as designed testimonial cards, make checkboxes/radios brand-colored custom controls, promote quotes' quotation marks into graphic elements.
+- **Add color with accent borders:** a 3–4px colored border on top of a card, left of an alert, under the active tab, or a full-width page top strip — big polish for zero artistic skill.
+- **Decorate backgrounds:** change background color per section, use a subtle gradient (two hues ≤30° apart), a low-contrast repeating pattern or texture, or a few simple geometric shapes anchored to corners — keeps long pages from feeling monotonous.
+- **Design empty states deliberately:** they're a first impression. Image/illustration + one-line explanation + prominent CTA; hide the unusable chrome (filters, tabs) until there's content to act on.
+- **Fewer borders** (again — it's the highest-frequency fix): spacing, background shifts, and shadows almost always beat lines.
+- **Think outside the "expected" component:** a dropdown can be a rich multi-column panel with icons and sections; a table can embed avatars, stacked primary/secondary text, and colored status pills instead of one string per column; radio buttons for plans can be selectable cards.
+
+## 9. Working method
+
+- **Steal deliberately:** when a screen feels off, find a well-designed product solving the same problem and identify *specifically* what they do differently (spacing, shade count, weight contrast).
+- **Iterate by subtraction first:** most "make it pop" problems are actually "everything else is too loud."
+- **Rebuild your systems as you go:** every one-off value (a 13px font, a #454A52 grey) is a future inconsistency; fold it into the scale or remove it.
+
+## 10. Before → after quick reference
+
+Concrete transformations to apply mechanically when reviewing a screen:
+
+- **Loud metadata:** Before — dates/IDs in the same dark 16px as titles. After — 14px, mid-grey; titles unchanged. The list suddenly has hierarchy.
+- **Label-heavy detail view:** Before — "Email: jane@x.com / Role: Admin". After — jane@x.com in dark text, "Admin" as a small tinted pill; labels deleted.
+- **Everything bordered:** Before — cards with borders inside a bordered panel with divider lines. After — borders removed, groups separated by background shade + spacing; one shadow on the outer card.
+- **Stretched form:** Before — full-width inputs across a 1200px page. After — 480–640px centered column; related short fields (city/postcode) share a row.
+- **Buried primary action:** Before — three identical grey buttons. After — one solid primary, one ghost secondary, "Delete" demoted to a red text link.
+- **Cramped card:** Before — 8px padding everywhere. After — 24px padding, 12px between internal elements; same content feels premium.
+- **Muddy hero text on photo:** Before — white text directly on image. After — image darkened 40% or brand-color multiply; text now readable and on-brand.
+- **Giant scaled icon:** Before — 24px icon scaled to 72px in a feature grid. After — 24px icon centered in a 48–64px tinted circle.
+- **Wall-of-text table:** Before — 8 plain text columns. After — key column gets two-line primary/secondary stacking, status becomes a colored badge, numbers right-aligned, low-value columns dropped.
+- **Timid headline:** Before — 20px grey heading over 16px grey body. After — 30px, weight 700, near-black heading; body stays 16px mid-grey. Contrast, not decoration.
+
+## 11. Component-level recipes
+
+**Buttons:**
+- Padding grows non-linearly with size: large CTA ≈ 16×32px padding; default ≈ 10×20; small ≈ 6×12 with a smaller font. Never one padding token for all sizes.
+- Hierarchy per screen: solid primary, soft/outline secondary, link tertiary; icon-only buttons get tooltips and generous hit areas.
+
+**Forms:**
+- Labels: small (13–14px), medium grey, 4–8px above the input — the input's content is the star, not the label.
+- Group related fields on one row only when they form one mental unit (first/last name, city/postcode).
+- Helper text below the field in caption style; error text replaces helper, same slot, red only for the message and border — don't repaint the whole field group.
+
+**Cards:**
+- Padding scales with card size (small card 16px, large 24–32px); internal hierarchy: image → title (semibold, dark) → metadata (small, grey) → action.
+- Prefer shadow + background over border; hover raises elevation one step.
+
+**Navigation:**
+- Active item: contrast (dark text, tinted background, or accent indicator bar) while siblings are mid-grey — de-emphasize to emphasize in its purest form.
+- Section labels in sidebars: 11–12px letterspaced caps, light grey — present but nearly silent.
+
+**Tables:**
+- Header row: caption-style (small, grey, medium weight, optionally caps) so data outweighs headers.
+- Row height ≥ 44–48px with 12–16px cell padding; zebra stripes or generous spacing, not both plus borders.
+- Emphasize one scan column (usually the first): darker and slightly heavier than the rest.
+
+**Modals:**
+- One job per modal; title (H3-scale), body (regular grey), actions right-aligned (desktop) with primary outermost; lg shadow, scrim at ~50% black; max-width ~480–560px for confirmations.
+
+## 12. Decision defaults (when unsure, pick these)
+
+- Body text 16px; secondary 14px; captions/labels 12–13px letterspaced caps or 13px grey.
+- Weights: 400/500 for body, 600/700 for emphasis and headings — skip anything lighter than 400 on screens.
+- Spacing: default gap between unrelated blocks 24–32px; related items 8–12px; card padding 16–24px.
+- Border radius: pick 4–6px (neutral-professional) or 10–16px (friendly) across the whole product.
+- Greys: slightly cool-tinted 9-step ramp; text uses steps ~900/700/500 on white.
+- Shadows: sm for interactive resting elements, md for popovers, lg for modals — nothing else.
+- One accent color doing the primary-action job everywhere; semantic red/yellow/green reserved for meaning.
+
+## Quick audit checklist
+
+- [ ] Systems exist and are obeyed: type scale, spacing scale, grey scale, shadow scale, color shades
+- [ ] Hierarchy via weight/color, not size alone; secondary content visibly quieter; one primary action per screen
+- [ ] Labels only where data isn't self-evident; labels styled quiet
+- [ ] Whitespace generous; grouping unambiguous (closer-within than between); content not stretched to fill
+- [ ] Line length 45–75ch; line-height varies with size; numbers right-aligned in tables
+- [ ] Colors in HSL with full shade ramps; no color-only meaning; contrast flipped (dark-on-light) where needed
+- [ ] Light-from-above depth; two-part shadows on a 5-step scale; borders replaced by space/shadow/background where possible
+- [ ] Empty states designed; accent borders/background sections used for cheap polish; no scaled-up icons or shrunken screenshots

package/knowledge/books/storybrand-copywriting.md

@@ -0,0 +1,194 @@
+---
+id: storybrand-copywriting
+title: "StoryBrand, Made to Stick & Ogilvy — Website Copywriting Playbook"
+category: book
+platform: both
+tags: [copywriting, storybrand, headlines, cta, messaging]
+sources: ["Building a StoryBrand (Donald Miller)", "Made to Stick (Chip Heath & Dan Heath)", "Ogilvy on Advertising / Confessions of an Advertising Man (David Ogilvy)"]
+updated: 2026-07-08
+---
+
+# Website Copywriting Playbook — StoryBrand + SUCCESs + Ogilvy
+
+Three frameworks, one division of labor:
+- **StoryBrand (SB7)** decides WHAT to say and in what ORDER (page architecture).
+- **Made to Stick (SUCCESs)** decides HOW each message is phrased so it lands and is remembered.
+- **Ogilvy** supplies the craft rules for headlines, long copy, and factual selling.
+
+**Prime directive (Miller):** The customer is the hero; the brand is the guide. Any sentence
+that makes the company the hero ("We're passionate about innovation") gets rewritten around
+the customer's transformation. **Second directive:** Clear beats clever, always. If the reader
+must burn calories to decode it, they leave.
+
+---
+
+## Part 1 — The SB7 Framework as Page Architecture
+
+Every effective story: a CHARACTER with a PROBLEM meets a GUIDE who gives them a PLAN and
+CALLS them to ACTION that ends in SUCCESS and avoids FAILURE. Map it to a page top-to-bottom:
+
+### 1. Character (the customer) — Hero section
+Define what the customer WANTS in one sentence, related to their survival/thriving (save money,
+save time, gain status, reduce anxiety, belong). The hero headline states that want or its fulfillment.
+- Rule: one desire per page. Multiple desires = multiple pages.
+- The "grunt test": within 5 seconds a stranger must answer — What do you offer? How does it
+  make my life better? How do I get it? (headline / subline / button).
+
+### 2. Problem — first section below hero
+Three levels; copy should touch all three:
+- **External** (the tangible problem): "Invoices go unpaid for months."
+- **Internal** (how it makes them feel — this is what people actually buy solutions to):
+  "You feel awkward chasing clients for money you earned."
+- **Philosophical** (why it's just wrong): "Freelancers shouldn't have to be debt collectors."
+- Optional villain: personify the problem (chaos, busywork, the blank page) — one villain, not a cast.
+- Template: "Most [segment] struggle with [external]. It leaves you [internal feeling]. We think [philosophical stance]."
+
+### 3. Guide (the brand) — trust section
+The guide shows exactly two things, in this order:
+- **Empathy**: "We know what it's like to [pain]" — one authentic sentence, not a paragraph.
+- **Authority/competence**: logos, counts, years, results, testimonials — enough to be trusted,
+  brief enough to keep the spotlight on the customer.
+- Rule: empathy before authority. Competence without empathy reads cold; empathy without competence reads weak.
+
+### 4. Plan — "How it works" section
+Reduce perceived risk with a named 3-step process plan: "1. Connect your account 2. Set your
+rules 3. Get paid on time." Three steps always — even complex products compress to three; more
+steps re-introduce the fear of effort. Optionally add an agreement plan (risk reversals: free
+trial, money-back guarantee, no lock-in) near the CTA.
+
+### 5. Call to Action — repeated throughout
+- **Direct CTA**: the purchase-path action ("Start free trial," "Book a demo"). One per page,
+  visually dominant, verb-first, repeated hero + after each major section + page end.
+- **Transitional CTA**: the low-commitment alternative for not-ready visitors ("Download the
+  pricing guide," "Watch 2-min demo") — visually secondary, adjacent to the direct CTA.
+- Never make the visitor guess the next step; passive buttons ("Learn more" as primary) signal
+  the brand itself isn't sure.
+
+### 6. Failure stakes — woven in, one section or less
+What it costs to do nothing: "Every month without [product], you lose [quantified cost]."
+A pinch of salt, not a horror movie — fear copy beyond one clear stake reads manipulative and
+triggers avoidance.
+
+### 7. Success — the vision section + closing
+Paint the after-state concretely: status gained, problem gone, identity transformed ("Become the
+freelancer who never chases an invoice"). Show it visually — smiling humans with the result, the
+clean dashboard, the zero-inbox. This is the aspirational identity: from [current self] to [desired self].
+
+### Canonical landing-page section order (SB7 default)
+1. Hero: outcome headline + clarifying subline + direct CTA + transitional CTA + success imagery
+2. Social proof strip (guide authority, minimal)
+3. Problem (external → internal → philosophical, villain named)
+4. Guide (empathy + authority, testimonials)
+5. Plan (3 steps)
+6. Value/feature sections (each tied to success or averted failure)
+7. Stakes (brief) + risk reversal
+8. Final CTA block: repeat headline promise + direct CTA + transitional CTA
+
+### One-liner formula (elevator pitch, meta descriptions, bios)
+`[Problem] + [Solution] + [Result]`: "Most freelancers waste hours chasing unpaid invoices.
+[Product] chases them automatically, so you get paid on time without awkward emails."
+
+---
+
+## Part 2 — Made to Stick: The SUCCESs Filter
+
+Run every headline, section, and CTA through six checks. Sticky = understood, remembered, acted on.
+
+**S — Simple.** Find the core, compact it. One idea per message; lead with it (inverted pyramid).
+"If you say three things, you say nothing." Use existing schemas: "Uber for X" transfers a whole
+model in three words — then differentiate.
+
+**U — Unexpected.** Break a pattern to earn attention; open a curiosity gap to hold it.
+- Counterintuitive stat or claim in the hero or section leads: "Your best customers churn first."
+- Gap headlines: pose the question the section answers. Never clickbait — the payoff must satisfy
+  the curiosity you opened, or trust dies.
+
+**C — Concrete.** Abstractions slide off; sensory, specific language sticks.
+- Replace "streamline workflows" → "turn a 3-hour report into a 10-minute one."
+- Numbers, objects, named actions. Test: can the reader picture it? If not, rewrite.
+- Feature pages: every abstract capability gets a concrete miniature scenario.
+
+**C — Credible.** Belief needs a source:
+- External: authorities, press, certifications.
+- Internal: vivid details (detail = truthiness), statistics HUMANIZED ("processes 1M rows —
+  that's every customer you'll ever have, in one screen").
+- Testable credentials — let them verify themselves: free trial, live demo, calculator,
+  "try it with your own data." The strongest credibility on the web is a try-before-believe widget.
+
+**E — Emotional.** People act for individuals and identities, not aggregates.
+- One named customer's story beats "10,000 companies."
+- Appeal to self-interest ("you get…") and to identity ("people like you do things like this").
+- WIIFY rule: the reader's benefit appears in the first line of every section.
+
+**S — Stories.** Stories are flight simulators — readers rehearse acting.
+- Case studies as narrative: struggle → discovery → result (not "Challenge/Solution/Results" boilerplate prose).
+- Three sticky plots: **Challenge** (underdog wins — inspires), **Connection** (bridging a gap —
+  belonging), **Creativity** (clever breakthrough — innovation). Pick one per case study.
+- Beware the **Curse of Knowledge**: experts write in abstractions because they can't remember
+  not knowing. Antidote: use customers' verbatim words from reviews/support tickets; read copy
+  aloud to a newcomer.
+
+---
+
+## Part 3 — Ogilvy's Craft Rules
+
+**Headlines (Ogilvy: ~5x more people read the headline than the body — if the headline doesn't
+sell, ~80% of spend is wasted):**
+1. Promise a benefit or deliver news; self-interest headlines outperform cleverness.
+2. Include the words that qualify the buyer (product category, audience name) — flag your prospect.
+3. Specific outperforms general; add the number, the timeframe, the place.
+4. Never run a headline that requires the body copy to make sense.
+5. Avoid negatives, puns, and blind headlines; don't be clever at the cost of clear.
+6. Long headlines that say something beat short ones that say nothing (10+ word headlines sold
+   more in his tests) — but every word must earn its place.
+
+**Body copy:**
+- Write to one person, second person, conversational: "as if answering a letter from an intelligent friend."
+- Facts sell. "The consumer isn't a moron" — respect intelligence; give specifics, not adjectives ("very," "world-class" = filler).
+- Long copy outsells short WHEN interest is high and the copy stays factual — pricing pages,
+  product pages, and case studies can and should be thorough; landing pages for cold traffic stay lean.
+- Captions under images are read more than body text: every image gets a selling caption.
+- First paragraph ≤ ~11 words of momentum; short sentences, short paragraphs, subheads every
+  2-3 paragraphs (web: every section scannable by subheads alone).
+- Kill "we" openings; convert to "you" (audit: your/you should outnumber we/our ~2:1 on any page).
+
+**Layout & typography (Ogilvy's print rules, still valid on web):**
+- Image → caption → headline → copy is the natural eye path; don't fight reading gravity.
+- Serif-vs-sans matters less than: dark text on light background, generous size, real paragraphs.
+  Never body text over busy imagery; avoid all-caps and reversed-out long text.
+- One dominant visual with a story appeal ("story appeal" images — the intriguing detail that
+  pulls the eye) beats collages.
+
+---
+
+## Part 4 — Ready-to-Use Templates
+
+**Hero headline formulas (pick by situation):**
+1. Outcome promise: `[Achieve desired result] without [pain/objection]` — "Get paid on time without chasing clients."
+2. Identity transformation: `Become [aspirational identity]` — "Become the agency clients never leave."
+3. Qualified category claim: `The [category] for [audience]` + benefit subline.
+4. Unexpected/stat lead: `[Counterintuitive fact]. [Product] fixes it.`
+5. Question gap: `Still [painful old way]?` + subline with new way.
+6. Concrete before/after: `From [bad state] to [good state] in [timeframe].`
+
+**Subline formula:** what it is + who it's for + how it delivers the headline's promise, ≤ 20 words.
+
+**CTA button rules:** verb-first, outcome-flavored, 2-4 words: "Start saving time," "Get my plan,"
+"Book a demo." Never "Submit," "Learn more" (as primary), or "Sign up" without a value word.
+First person ("Get MY plan") often lifts; test it. Repeat the same primary CTA text on every
+instance on the page — one action, one label.
+
+**Section copy pattern (every feature/value section):**
+Subhead = benefit claim (SUCCESs-filtered) → 1-2 sentence concrete scenario → proof element
+(stat, quote, or screenshot with caption) → optional micro-CTA.
+
+**Microcopy near CTAs (objection killers):** "No credit card required · Cancel anytime ·
+Set up in 5 minutes" — pick the top 2-3 real objections and answer them in ≤ 8 words each.
+
+**Full-page rewrite procedure:**
+1. Extract the customer's want, 3-level problem, and success state (interviews/reviews).
+2. Draft the SB7 section order with placeholder claims.
+3. Write 5+ hero headline candidates from the formulas; SUCCESs-filter; pick the clearest.
+4. Write sections with the section copy pattern; enforce you:we ratio.
+5. Ogilvy pass: cut adjectives, add facts/numbers, caption every image, tighten first lines.
+6. Grunt test with a stranger; ship; A/B the hero headline first (highest-leverage element).

package/knowledge/components/buttons.md

@@ -0,0 +1,90 @@
+---
+id: buttons
+title: "Buttons — Complete Design Guide"
+category: component
+platform: both
+tags: [buttons, cta, interaction, touch-targets, states]
+sources: ["https://m3.material.io/components/buttons", "https://developer.apple.com/design/human-interface-guidelines/buttons", "https://www.nngroup.com/articles/button-states-communicate-interaction/"]
+updated: 2026-07-08
+---
+
+# Buttons — Complete Design Guide
+
+Buttons are the single highest-leverage component in any interface. Get hierarchy, sizing, states, and labels right and most flows fix themselves.
+
+## Button hierarchy (use exactly one primary per view)
+
+| Level | Use | Visual treatment |
+|---|---|---|
+| Primary (filled) | The one main action of the screen | Solid brand/accent fill, highest contrast |
+| Secondary (tonal/outlined) | Alternative or supporting action | Tonal fill or 1–1.5px outline, no fill |
+| Tertiary (text/ghost) | Low-emphasis actions, cancel, links | Text only, accent color |
+| Destructive | Delete/remove/irreversible | Red/danger color; confirm irreversible actions |
+
+Rules:
+- **One primary button per screen/section.** Two side-by-side filled buttons destroy hierarchy.
+- Never style "Cancel" as prominently as the confirm action; make it text/ghost.
+- In dialogs: primary action on the right (iOS/web convention), destructive action colored red even when primary.
+- Don't use disabled primary buttons as form gatekeepers when avoidable — prefer enabled button + inline validation on submit. If you must disable, explain why nearby.
+
+## Sizing & touch targets
+
+- **Minimum touch target: 44×44pt (iOS), 48×48dp (Android/Material), 24×24px CSS minimum (WCAG 2.2 AA), 44px recommended for web.**
+- Comfortable mobile button height: 48–56px full-width primary CTA; desktop web: 40–48px.
+- Horizontal padding: ≥16–24px; text never touches edges.
+- Full-width primary buttons on mobile below ~480px viewport; intrinsic-width buttons on desktop.
+- Spacing between adjacent tappable buttons: ≥8px (Material recommends 8dp; more if targets are small).
+- Bottom-fixed mobile CTAs: respect safe-area insets (`env(safe-area-inset-bottom)`), add a subtle top gradient/border to separate from scrolling content.
+
+## Shape & radius
+
+- Radius communicates brand: 4–8px = neutral/enterprise, 10–16px = friendly product default, fully rounded (pill) = consumer/mobile-first (current dominant trend in iOS apps and modern SaaS).
+- Be consistent: one radius scale across all buttons; pill buttons pair with pill inputs.
+- Material 3 default: fully rounded (pill); Material 3 Expressive allows shape-morph on press (round → slightly squarer).
+- iOS/Liquid Glass: capsule buttons, translucent materials for controls overlaying content.
+
+## States (all are mandatory)
+
+1. **Default** — resting.
+2. **Hover** (web/desktop) — darken/lighten fill ~4–8%, or elevate slightly. Cursor: pointer.
+3. **Focus-visible** — 2px outline offset 2px, high-contrast ring. Never remove focus outlines; style them.
+4. **Active/pressed** — darken ~10–12% and/or scale to 0.97–0.98 (100–150ms). Mobile: pressed state must be visible under the finger (ripple on Android, opacity/scale on iOS).
+5. **Disabled** — reduced opacity (~38–50%) or gray fill; keep text readable (don't drop below 3:1 if the label must be read). `cursor: not-allowed` is optional; never keep hover effects.
+6. **Loading** — replace label with spinner OR keep label + inline spinner; **keep button width fixed** (reserve space) to avoid layout shift; disable further clicks; announce via `aria-busy`.
+
+## Labels & microcopy
+
+- **Verb-first, specific:** "Create account", "Save changes", "Start free trial" — never "Submit", "OK", "Yes/No" alone.
+- Match the label to the outcome: button says what happens next.
+- 1–3 words ideal; sentence case (Material, most modern products) — avoid ALL CAPS (worse readability; dated).
+- Destructive confirms: repeat the object — "Delete 3 files", not "Confirm".
+- Icons: leading icon only when it adds meaning (e.g., ⬇ Download). Icon-only buttons require `aria-label` and a tooltip on web.
+
+## Color & contrast
+
+- Label-to-fill contrast: **≥4.5:1** (WCAG AA normal text; ≥3:1 for ≥18.66px bold/24px).
+- Button fill vs background: ≥3:1 for the button to read as a control (WCAG non-text contrast).
+- Don't rely on color alone for destructive vs primary — differentiate with label + placement.
+- Dark mode: desaturate/darken brand fills slightly; avoid pure-saturated fills that vibrate on dark backgrounds.
+
+## Placement conventions
+
+- Mobile: primary CTA bottom of screen (thumb zone); avoid top corners for frequent actions.
+- Forms (web): primary aligned with the form fields' left edge (single-column forms) or right-aligned in modals/wizards; "Back" left, "Next/Submit" right.
+- Sticky CTAs: use when the form/page is long; ensure they never cover inputs being edited (keyboard-aware on mobile).
+
+## Motion
+
+- Press feedback: 100ms in, 150–200ms out; ease-out on release.
+- Never animate layout-affecting properties on press (use transform/opacity).
+- Respect `prefers-reduced-motion`: replace scale/ripple with opacity change.
+
+## Anti-patterns (reject in reviews)
+
+- Two or more filled primary buttons competing on one view.
+- "Click here" / "Submit" / "OK" labels.
+- Ghost buttons as the sole CTA on imagery (low contrast, low affordance).
+- Buttons that look like links and links that look like buttons used interchangeably — navigation = link (`<a>`), action = button (`<button>`).
+- Tiny (<40px) touch targets packed together in mobile toolbars.
+- Loading state that swaps to a different-width element (layout jump).
+- Disabled button with no explanation of what's missing.