saglitzdesign-mcp 0.3.1

package/knowledge/seo/seo-for-designers.md

@@ -0,0 +1,159 @@
+---
+id: seo-for-designers
+title: "SEO for Designers 2026"
+category: seo
+platform: web
+tags: [core-web-vitals, layout-shift, font-loading, image-optimization, mobile-first, accessibility]
+sources: ["https://web.dev/articles/vitals", "https://web.dev/articles/optimize-cls", "https://web.dev/articles/font-best-practices", "https://developers.google.com/search/docs/crawling-indexing/mobile/mobile-sites-mobile-first-indexing", "https://www.uxpin.com/studio/blog/web-design-seo-key-principles/", "https://www.uxpin.com/studio/blog/ux-seo-guide/", "https://www.modernwebseo.com/en/blog/seo-friendly-web-design-guide/", "https://www.elegantthemes.com/blog/design/web-design-and-seo"]
+updated: 2026-07-08
+---
+
+# SEO for Designers 2026
+
+Every design decision — hero media, font choice, navigation pattern, animation — becomes a Core Web Vitals number, a crawlability property, or an accessibility signal. This file maps design choices to their SEO consequences with hard rules. Thresholds referenced: LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1 at the 75th percentile of real users (see technical-seo.md).
+
+## 1. Layout Stability (CLS) — Design Rules
+
+CLS ≤ 0.1 means the page visually budges almost not at all after first paint. Shifts are caused by *designed* elements arriving late.
+
+**Rules:**
+- **Reserve space for everything that loads late.** Images, videos, iframes, embeds, ad slots, testimonial carousels: fixed `aspect-ratio` or explicit `width`/`height` in the design spec, always.
+```css
+.hero-media { aspect-ratio: 16 / 9; width: 100%; }
+img { max-width: 100%; height: auto; } /* with width/height attrs in HTML */
+```
+- **Cookie banners and promo bars:** design them as `position: fixed` overlays (bottom sheet) or reserve their height in the layout. Never let them push the page down on arrival.
+- **No content injected above the fold after load** — late-loading announcement bars are the single most common CLS failure.
+- **Skeleton screens must match final content dimensions exactly** — a skeleton that's shorter than the loaded card causes the shift it was meant to prevent.
+- **Carousels/accordions/tabs:** size the container to the tallest state, or animate `transform` (compositor-only) rather than `height`/`top`. `transform`/`opacity` animations never count toward CLS; layout-property animations do.
+- **Buttons/badges with dynamic text** ("3 items"): min-width so digits changing doesn't reflow neighbors.
+- Design review gate: load the page on throttled 4G and watch — anything that visibly jumps fails the design, not just the build.
+
+## 2. Font Loading — Typography Without the SEO Tax
+
+Web fonts are a top cause of both CLS (swap reflow) and slow LCP (text is often the LCP element).
+
+**Rules:**
+- **Max 2 font families, ≤ 4 total weights/styles.** Every weight is a network file. Prefer a variable font when you need > 2 weights of one family.
+- **Self-host WOFF2.** Third-party font CDNs add a connection; Google Fonts via CSS link is slower than self-hosting and has privacy implications in the EU.
+- **Preload the primary text font:**
+```html
+<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
+```
+- **`font-display: swap`** so text is never invisible (FOIT kills LCP). Then neutralize the swap-reflow with fallback metric matching:
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/inter-var.woff2") format("woff2");
+  font-display: swap;
+}
+@font-face {
+  font-family: "Inter Fallback";
+  src: local("Arial");
+  size-adjust: 107%;
+  ascent-override: 90%;
+  descent-override: 22%;
+}
+body { font-family: "Inter", "Inter Fallback", sans-serif; }
+```
+  (`size-adjust`/`ascent-override` tuned so the fallback occupies identical space → zero font-swap CLS. Tools: Fontaine, next/font does this automatically.)
+- **Subset fonts** to used character sets (latin) — often 70%+ smaller.
+- Decorative display fonts used once in the hero: consider an SVG wordmark or accept system-font fallback on slow connections.
+- **Don't** load icon fonts (Font Awesome as font) — use inline SVG icons; icon fonts are a render-blocking request and an accessibility problem.
+
+## 3. Images & Media — The LCP Discipline
+
+The hero image is usually the LCP element; the design decision about it *is* the performance decision.
+
+**Rules:**
+- **Formats:** AVIF first, WebP fallback, via `<picture>` or content negotiation. JPEG only as last resort; PNG only for UI screenshots needing lossless; SVG for logos/icons/illustrations.
+- **Hero/LCP image:** `fetchpriority="high"`, never `loading="lazy"`, preloaded if it's a CSS background. Target ≤ 200 KB for a full-bleed hero (AVIF makes this achievable at 1920 px).
+- **Everything below the fold:** `loading="lazy" decoding="async"`.
+- **Responsive sizing:** export/serve multiple widths with `srcset` + `sizes`; never ship a 2400 px image into a 400 px slot:
+```html
+<img src="/work/case-800.avif"
+     srcset="/work/case-400.avif 400w, /work/case-800.avif 800w, /work/case-1600.avif 1600w"
+     sizes="(max-width: 768px) 100vw, 50vw"
+     width="1600" height="1000"
+     alt="Redesigned checkout flow for Acme, mobile and desktop views"
+     loading="lazy" decoding="async">
+```
+- **Alt text on every meaningful image:** describe content and function, include keywords only when natural. Decorative images: `alt=""` (empty, not missing).
+- **Descriptive filenames:** `bakery-website-redesign-hero.avif`, not `IMG_4021-final-v3.png`.
+- **Background video heroes:** muted, `preload="none"` or poster-first, compressed ≤ 2–3 MB, with a static image fallback on mobile/reduced-data. Autoplaying video must never be the LCP bottleneck — the poster image can be the LCP element instead.
+- Text as text, never baked into images — invisible to search, AI engines, and translation.
+
+## 4. Mobile-First Indexing — Parity Is Non-Negotiable
+
+Google indexes and ranks from the **mobile rendering** of your site. Whatever the mobile design hides, SEO loses.
+
+**Rules:**
+- **Content parity:** the mobile design must contain the same content, headings, structured data, and internal links as desktop. "Simplified" mobile pages that drop sections drop rankings.
+- Content in accordions/tabs on mobile is fine and fully indexed — as long as it's in the DOM (HTML present, visually collapsed), not fetched on click.
+- **Tap targets ≥ 48×48 px** with ≥ 8 px spacing; body text ≥ 16 px without zooming; no horizontal scroll at 360 px width.
+- `<meta name="viewport" content="width=device-width, initial-scale=1">` — absence makes the page "not mobile friendly" outright.
+- No intrusive interstitials on mobile entry (full-screen popups before content) — explicitly penalized. Design email-capture as inline sections, exit-intent (desktop), or small dismissible banners.
+- Design mobile-first in Figma: the 375–414 px frame is the canonical design, desktop is the enhancement.
+- Hamburger menus are fine for crawling (links must be in HTML), but every strategic page should also have contextual in-body links (see on-page-seo.md §4).
+
+## 5. Accessibility ↔ SEO Overlap
+
+Accessibility work is SEO work — the same semantics feed screen readers, Googlebot, and LLM crawlers:
+
+| Accessibility practice | SEO effect |
+|---|---|
+| Semantic landmarks (`<header> <nav> <main> <footer> <article>`) | Cleaner content extraction, better AI parsing |
+| Correct heading outline | Section-level ranking & AI Overview citation |
+| Alt text | Image search + image context for page relevance |
+| Descriptive link text | Anchor-text relevance signals |
+| Color contrast ≥ 4.5:1, visible focus states | Engagement/UX quality, lower pogo-sticking |
+| Captions/transcripts for video | Indexable text for otherwise opaque media |
+| `prefers-reduced-motion` respected | Lower INP/CLS risk from heavy animation |
+
+- Buttons for actions, links (`<a href>`) for navigation — misuse breaks both keyboard users and crawlers.
+- One page language declared: `<html lang="en-GB">` — feeds translation, screen readers, and international targeting.
+
+## 6. Design Patterns That Hurt SEO (Avoid / Replace)
+
+| Anti-pattern | Why it hurts | Replace with |
+|---|---|---|
+| Full-page preloader/splash animation | Delays LCP by its full duration | Instant content, subtle entrance animation |
+| Text embedded in hero images | Invisible to search/AI | Real text over image (`<h1>` + CSS) |
+| Infinite scroll only | Deep items never crawled | Infinite scroll + paginated URLs (`/work/page/2/`) |
+| Mega "app-like" SPA portfolio with client-only routes | Empty HTML to AI crawlers, delayed Google indexing | SSG/SSR (Astro, Next) |
+| Hover-only content reveals | No tap equivalent, content risk on mobile index | Click-to-expand with content in DOM |
+| Carousel as sole home for key messages | Slides 2+ barely seen or crawled | Stacked sections; carousel for gallery only |
+| Scroll-jacking / heavy parallax libraries | Main-thread cost → INP failures | CSS scroll-driven animations, `transform`-only effects |
+| PDF for service/pricing info | Poor mobile UX, weak indexing | HTML page (PDF as secondary download) |
+| Thin "gallery-only" portfolio pages | No text = nothing to rank | Case studies: problem → process → measurable result |
+| Custom cursors/heavy WebGL on every page | JS weight, INP, battery | Reserve for one showcase page, not sitewide |
+
+## 7. Design-Phase SEO Checklist (before handoff)
+
+- [ ] Every image/media block in the mockup has defined aspect ratio + max file-size budget noted
+- [ ] Hero: LCP element identified; image ≤ 200 KB AVIF plan; no text baked in
+- [ ] Fonts: ≤ 2 families, weights listed, variable font considered, fallback metrics planned
+- [ ] Heading levels annotated in the design (H1/H2/H3), one H1 per page
+- [ ] Mobile frames designed first; content parity with desktop confirmed
+- [ ] Tap targets ≥ 48 px; body ≥ 16 px; contrast ≥ 4.5:1
+- [ ] Cookie/promo banners designed as non-shifting overlays
+- [ ] Nav + footer link map matches the site's internal-linking plan
+- [ ] No intrusive mobile interstitials in the flow
+- [ ] Animations specified as `transform`/`opacity`; reduced-motion variant defined
+- [ ] Empty/loading states sized identically to loaded states
+- [ ] Each template's target query + H1 + title documented alongside the mockup
+
+## 8. Performance Budget (per page template, 2026 defaults)
+
+| Budget item | Target |
+|---|---|
+| HTML document | ≤ 50 KB |
+| Total CSS | ≤ 100 KB (critical CSS inlined ≤ 15 KB) |
+| JS shipped to client | ≤ 200 KB compressed (marketing pages ≤ 100 KB) |
+| Hero image | ≤ 200 KB AVIF |
+| Total page weight (first load) | ≤ 1.5 MB mobile |
+| Web fonts | ≤ 2 files, ≤ 120 KB total |
+| Third-party scripts | ≤ 3, all deferred |
+| Field LCP / INP / CLS | ≤ 2.0 s / ≤ 150 ms / ≤ 0.05 (buffer under official 2.5 s / 200 ms / 0.1) |
+
+Budgets are design constraints, not engineering afterthoughts: if the concept needs 4 fonts and a 4 MB video, the concept fails the budget review.

package/knowledge/seo/technical-seo.md

@@ -0,0 +1,194 @@
+---
+id: technical-seo
+title: "Technical SEO 2026"
+category: seo
+platform: web
+tags: [core-web-vitals, structured-data, crawling, javascript-seo, hreflang, sitemaps]
+sources: ["https://web.dev/articles/vitals", "https://developers.google.com/search/docs/appearance/core-web-vitals", "https://developers.google.com/search/updates", "https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites", "https://www.debugbear.com/blog/technical-seo-checklist", "https://www.stackmatix.com/blog/javascript-rendering-seo-best-practices", "https://seomator.com/blog/crawl-to-refer-ratio-ai-crawlers-llm-bots", "https://www.linkgraph.com/blog/hreflang-implementation-guide/"]
+updated: 2026-07-08
+---
+
+# Technical SEO 2026
+
+Technical SEO in 2026 has two audiences: Google's crawler/renderer **and** AI crawlers (GPTBot, ClaudeBot, PerplexityBot) that now account for roughly half of all crawler traffic and **do not execute JavaScript**. Everything below assumes both.
+
+## 1. Core Web Vitals — Current Official Thresholds
+
+Google evaluates each metric at the **75th percentile** of real-user (CrUX field) data, segmented by mobile and desktop. All three must be "Good" for the page to pass.
+
+| Metric | Good | Needs Improvement | Poor |
+|---|---|---|---|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
+| **INP** (Interaction to Next Paint) | ≤ 200 ms | 200–500 ms | > 500 ms |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+- INP replaced FID in March 2024. FID is dead — ignore any guidance referencing it.
+- **Myth check (verified July 2026):** several SEO blogs claim Google lowered the LCP "Good" threshold to 2.0 s in a "March 2026 update." Google's official docs (web.dev and Search Central, last updated Dec 2025) still state **2.5 s**. Treat 2.5 s as the pass line, but target ≤ 2.0 s LCP and ≤ 150 ms INP as a competitive buffer — thresholds are graded on field data you don't fully control (slow devices, slow networks).
+- CWV is a ranking signal, but a modest tiebreaker — it will not rescue thin content, and great content ranks despite mediocre vitals. Fix vitals for UX and conversion first, rankings second.
+
+### LCP quick wins
+- The LCP element is usually the hero image or H1. Serve it from your own origin, in AVIF/WebP, **never lazy-loaded**, with `fetchpriority="high"`.
+- `<link rel="preload" as="image" href="/hero.avif" fetchpriority="high">` for CSS background heroes.
+- TTFB budget: ≤ 800 ms. Use CDN + edge caching; LCP can't be good if the HTML is slow.
+- Inline critical CSS; defer non-critical CSS and all non-essential JS.
+
+### INP quick wins
+- Break long tasks (> 50 ms) with `scheduler.yield()` / `setTimeout` chunking.
+- Minimize third-party scripts; load tag managers and chat widgets after interaction or with `defer`.
+- Give instant visual feedback on tap (CSS `:active` states) even if work continues async.
+- Avoid re-rendering huge DOM trees on input; keep DOM under ~1,400 nodes where possible.
+
+### CLS quick wins
+- Explicit `width`/`height` (or `aspect-ratio`) on ALL images, videos, iframes, embeds, ads.
+- Reserve space for ads/banners with `min-height` placeholders.
+- Never inject content above existing content (cookie bars: use `position: fixed`, or reserve space).
+- Fonts: see the font-loading rules in `seo-for-designers.md`.
+
+## 2. Crawlability & Indexing
+
+### Checklist
+- [ ] `robots.txt` at root; blocks only genuinely private paths. Never block CSS/JS — Google must render the page.
+- [ ] One canonical protocol+host: force HTTPS and one of www/non-www via 301.
+- [ ] Every important page reachable within **3 clicks** of the homepage.
+- [ ] No orphan pages (pages with zero internal links).
+- [ ] Return proper status codes: 404/410 for gone, 301 for moved, no "soft 404s" (200 with empty content).
+- [ ] Redirect chains ≤ 1 hop; no redirect loops.
+- [ ] Paginated archives: self-canonical each page, plain `<a href>` links between pages (`rel=prev/next` is ignored by Google but harmless).
+- [ ] Faceted/filter URLs: `noindex` or canonicalize to the base category; block crawl-trap parameter combinations in robots.txt.
+- [ ] Monitor Search Console → Pages report monthly for "Crawled – currently not indexed" spikes (usually a quality/duplication signal, not technical).
+
+### Do / Don't
+- **Do** use real `<a href="/path">` anchors for all navigation. Buttons with click handlers and router `pushState` links are invisible to crawlers.
+- **Do** keep URL structure flat, lowercase, hyphen-separated: `/services/web-design`, not `/index.php?cat=2&id=17`.
+- **Don't** put indexable content behind login, infinite scroll without paginated URLs, or hover/tap-only reveals with no HTML fallback.
+- **Don't** use meta refresh or JS redirects; use HTTP 301/302.
+
+## 3. JavaScript Rendering
+
+Google renders JS in a second wave (delayed, resource-limited). AI crawlers **read initial HTML only**. Rule of thumb for 2026:
+
+> **If content matters for search or AI citation, it must exist in the server-rendered HTML response.**
+
+- **Preferred:** SSG (static) or SSR (Next.js, Nuxt, Astro, SvelteKit) for all indexable routes. Hydrate for interactivity.
+- **Acceptable:** hybrid/ISR — static shell with server-rendered content, client-side enhancement.
+- **Avoid:** pure client-side rendering (CRA-style SPA) for anything you want ranked or cited. Dynamic rendering (serving bots a prerendered version) is officially deprecated as a long-term approach — treat as a temporary patch only.
+- Metadata (title, meta description, canonical, structured data) must be server-rendered. Client-injected JSON-LD works for Google *if* rendering succeeds, but fails for AI crawlers — inject server-side.
+- Test: `curl -s https://example.com/page | grep -i "your key phrase"` — if it's not in the raw HTML, AI engines can't see it.
+
+## 4. Structured Data (Schema.org)
+
+Use **JSON-LD in the `<head>` or body, server-rendered**. Validate with Google's Rich Results Test and Schema.org validator.
+
+### Still-supported, high-value types (2026)
+`Organization`, `LocalBusiness`, `Product` (+ `Offer`, `AggregateRating`), `Article`/`BlogPosting`, `BreadcrumbList`, `Person`, `WebSite`, `Event`, `JobPosting`, `Recipe`, `VideoObject`, `Review`.
+
+### Deprecated — do NOT promise clients rich results from these
+- `HowTo` rich results: removed 2023–2024.
+- `FAQPage` rich results: restricted in 2023, fully retired for visual snippets by 2026.
+- June 2025 removals: Course Info, Claim Review, Estimated Salary, Learning Video, Special Announcement, Vehicle Listing (Book Actions was later reinstated).
+- The markup itself is still valid schema.org and can aid entity understanding / AI comprehension — it just earns no SERP visual. Keep FAQPage markup if cheap; don't build strategy on it.
+
+### Example: LocalBusiness + WebSite (design-agency baseline)
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "ProfessionalService",
+  "@id": "https://example.com/#business",
+  "name": "Saglitz Design",
+  "url": "https://example.com/",
+  "logo": "https://example.com/logo.png",
+  "image": "https://example.com/studio.jpg",
+  "telephone": "+44-20-0000-0000",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "1 Example St",
+    "addressLocality": "London",
+    "postalCode": "EC1A 1AA",
+    "addressCountry": "GB"
+  },
+  "sameAs": [
+    "https://www.linkedin.com/company/example",
+    "https://www.instagram.com/example"
+  ]
+}
+</script>
+```
+
+### Example: Article with author entity (E-E-A-T support)
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "How Layout Shift Kills Conversions",
+  "datePublished": "2026-06-01",
+  "dateModified": "2026-07-01",
+  "author": {
+    "@type": "Person",
+    "name": "Jane Doe",
+    "url": "https://example.com/about/jane-doe",
+    "jobTitle": "Founder & Designer",
+    "sameAs": ["https://www.linkedin.com/in/example"]
+  },
+  "publisher": { "@id": "https://example.com/#business" }
+}
+</script>
+```
+
+## 5. Canonicals
+
+- Every indexable page carries a **self-referencing** canonical: `<link rel="canonical" href="https://example.com/page/">`.
+- Absolute URLs only, matching final protocol/host/trailing-slash exactly.
+- One canonical tag per page — duplicates or conflicts cause Google to ignore all of them.
+- Canonical is a *hint*, not a directive. Reinforce with matching internal links, sitemap URLs, and redirects.
+- Don't canonicalize paginated page 2+ to page 1 (hides deep content); self-canonicalize each.
+- Parameter variants (`?utm=`, sort, filter) → canonical to the clean URL.
+
+## 6. Hreflang (International SEO)
+
+~75% of international sites have hreflang errors. The three non-negotiables:
+
+1. **Self-reference:** each page lists itself in its own hreflang set.
+2. **Reciprocity (return tags):** if A points to B, B must point back to A. One-way tags are ignored.
+3. **Valid codes:** ISO 639-1 language + optional ISO 3166-1 Alpha-2 region. `en-GB` ✓, `en-UK` ✗, `gb` alone ✗.
+
+```html
+<link rel="alternate" hreflang="en-gb" href="https://example.com/en-gb/" />
+<link rel="alternate" hreflang="en-us" href="https://example.com/en-us/" />
+<link rel="alternate" hreflang="de"    href="https://example.com/de/" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/" />
+```
+
+- Always include `x-default` (global/language-picker fallback).
+- hreflang targets must be indexable, 200-status, self-canonical URLs — never redirect or noindexed pages.
+- Implementation options: HTML `<head>` tags (small sites), XML sitemap (large sites — easier to maintain), HTTP headers (PDFs).
+- URL structure: subdirectories (`/de/`) are the default recommendation — consolidate authority on one domain. ccTLDs (`example.de`) give the strongest geo signal but split link equity. Avoid parameters (`?lang=de`).
+- **Don't** auto-redirect users by IP to a locale version — Googlebot crawls mostly from the US and will never see other versions. Offer a banner/suggestion instead.
+- Translate content properly; don't hreflang two identical English pages to `en-us`/`en-gb` unless there's genuine localization (currency, spelling, offers).
+
+## 7. XML Sitemaps
+
+- Include **only** canonical, indexable, 200-status URLs. No redirects, no noindexed pages, no parameter dupes.
+- Max 50,000 URLs / 50 MB uncompressed per file; use a sitemap index for more.
+- `<lastmod>` must be truthful (Google uses it; fake dates get ignored). Skip `changefreq`/`priority` — ignored.
+- Reference it in robots.txt: `Sitemap: https://example.com/sitemap.xml` and submit in Search Console.
+- Split by type (`sitemap-pages.xml`, `sitemap-posts.xml`, `sitemap-images.xml`) to isolate indexing problems per section.
+- Image/video sitemaps (or `<image:image>` extensions) for media-heavy portfolio sites.
+
+## 8. AI Crawlers & GEO (Generative Engine Optimization)
+
+- AI/LLM crawlers now exceed traditional search crawlers in volume (~52% vs ~34% of crawler traffic, 2026 data).
+- **Default: allow them.** Blocking GPTBot/ClaudeBot/PerplexityBot removes you from AI answers and citations. Block only for genuine licensing/competitive reasons.
+- They read raw HTML only → SSR everything (see §3), keep clean heading hierarchy, use semantic HTML.
+- `llms.txt` (a curated markdown index of key pages at `/llms.txt`): no confirmed ranking/citation effect yet, but zero-risk and ~30 minutes to create. Optional, low priority.
+- Rate-limit abusive crawlers at CDN level rather than blanket robots.txt bans if server load is the concern.
+
+## 9. Technical SEO Audit — Minimum Monthly Checks
+
+1. Search Console: Pages (indexing), Core Web Vitals, and Crawl Stats reports.
+2. Field CWV via CrUX (PageSpeed Insights) on top 10 templates — field data, not just Lighthouse lab scores.
+3. Crawl the site (Screaming Frog/Sitebulb): broken links, redirect chains, missing/duplicate titles & canonicals, orphan pages.
+4. Validate structured data on each template type.
+5. `curl` key pages to confirm content + JSON-LD present in raw HTML.
+6. Confirm sitemap URL count ≈ indexable URL count (large gaps = index bloat or coverage loss).

package/knowledge/ux/accessibility.md

@@ -0,0 +1,68 @@
+---
+id: accessibility
+title: "Accessibility (WCAG 2.2) — Practical Guide"
+category: ux
+platform: both
+tags: [a11y, wcag, contrast, keyboard, screen-readers, aria]
+sources: ["https://www.w3.org/WAI/WCAG22/quickref/", "https://webaim.org/resources/contrastchecker/"]
+updated: 2026-07-08
+---
+
+# Accessibility — Practical Guide (WCAG 2.2 AA baseline)
+
+Accessibility is a design constraint, not a QA pass. Target WCAG 2.2 AA.
+
+## Contrast (memorize these)
+
+- Normal text: **≥4.5:1** against background.
+- Large text (≥24px, or ≥18.66px bold): **≥3:1**.
+- Non-text UI (borders of inputs, icons, focus rings, button fills vs page): **≥3:1**.
+- Placeholder text, disabled elements: exempt, but keep placeholders ~4.5:1 anyway if they carry format info.
+- Don't put text on busy imagery without a scrim/overlay (40–60% black or gradient).
+
+## Color independence
+
+Never encode meaning in color alone: pair with icon, label, or pattern (error = red + icon + message; chart series = color + shape/label; links in body text = underline, not just color).
+
+## Keyboard (web) — hard requirements
+
+- Everything operable by keyboard; logical tab order following visual order.
+- `:focus-visible` ring on every interactive element: ≥2px, ≥3:1 contrast, offset from element.
+- Skip-to-content link first in tab order. Escape closes overlays. Arrow keys within composite widgets (menus, tabs, radio groups).
+- No keyboard traps; focus never lands on invisible elements.
+- WCAG 2.2 additions: focus not fully obscured by sticky headers/footers; dragging operations need a click alternative.
+
+## Touch & pointer
+
+- Targets ≥24×24 CSS px absolute minimum (WCAG 2.2), 44–48px recommended.
+- Gesture-only functions (swipe, pinch, long-press) need visible single-tap alternatives.
+
+## Semantics & ARIA
+
+- Native elements first: `<button>`, `<a>`, `<nav>`, `<main>`, `<label>` — ARIA is a repair tool, not a replacement ("No ARIA is better than bad ARIA").
+- One `<h1>` per page; heading levels never skip; headings describe structure, not styling.
+- Images: meaningful → descriptive `alt`; decorative → `alt=""`.
+- Icon-only buttons: `aria-label`. Live updates (toasts, validation, cart count): `aria-live="polite"`.
+- Forms: programmatic label association; errors referenced via `aria-describedby`; `aria-invalid` on failed fields.
+
+## Motion & media
+
+- Respect `prefers-reduced-motion`: disable parallax, large movement, auto-playing animation; keep opacity/color transitions.
+- No flashing >3 times/second. Auto-playing carousels/video need pause controls (or better: don't autoplay).
+- Video: captions; audio: transcripts.
+
+## Text & zoom
+
+- Base body ≥16px; support 200% zoom / iOS-Android Dynamic Type without loss of content or horizontal scroll.
+- Use relative units (rem) for font sizes on web; test at 320px-wide viewport equivalent.
+- Line length 45–75 characters; line-height ≥1.5 body text.
+
+## Quick audit checklist
+
+1. Tab through the page — reachable, visible focus, sane order?
+2. Grayscale screenshot — does meaning survive?
+3. Contrast-check text, buttons, inputs, focus rings.
+4. Screen reader pass (VoiceOver/NVDA) on the core flow.
+5. 200% zoom + 320px viewport — usable, no horizontal scroll?
+6. Forms: labels, error announcement, keyboard submit.
+7. `prefers-reduced-motion` honored?

package/knowledge/ux/color-systems.md

@@ -0,0 +1,58 @@
+---
+id: color-systems
+title: "Color Systems — Palettes, Semantics, Dark Mode"
+category: ux
+platform: both
+tags: [color, palette, dark-mode, semantic-tokens, contrast]
+sources: ["https://m3.material.io/styles/color/system", "https://developer.apple.com/design/human-interface-guidelines/color"]
+updated: 2026-07-08
+---
+
+# Color Systems — Palettes, Semantics, Dark Mode
+
+## Building a product palette
+
+- **60-30-10**: ~60% neutral surfaces, ~30% secondary/structural, ~10% accent. Accent is scarce by design — that scarcity is what makes CTAs pop.
+- One brand/accent hue + full neutral ramp + 4 semantic hues (success green, warning amber, danger red, info blue).
+- Build ramps of 10–12 steps per hue (50→950). Generate in a perceptual space (OKLCH) so steps are visually even; keep hue slightly shifting across the ramp (warmer lights, cooler darks) to avoid dead grays.
+- Neutrals: tint them toward the brand hue 1–3% saturation — pure gray reads lifeless next to a colored accent.
+- Test every pairing you actually use: accent-on-surface, text-on-accent, border-on-surface at 3:1/4.5:1.
+
+## Semantic tokens (never hardcode hex in components)
+
+Two layers:
+1. **Primitives**: `blue-600`, `gray-100` … (raw ramps)
+2. **Semantic roles**: `bg/surface`, `bg/surface-raised`, `bg/accent`, `text/primary`, `text/secondary`, `text/on-accent`, `border/default`, `border/focus`, `state/success|warning|danger`
+
+Components consume only semantic roles → dark mode and theming become a token swap, not a redesign.
+
+## Dark mode (rules, not inversion)
+
+- Surfaces: dark gray (#0A0A0B–#1C1C1E range), **never pure black** behind text (halation); elevation = lighter surface, not shadow.
+- Desaturate accents ~10–20% and lighten them; saturated brights vibrate on dark.
+- Text: white at 87–92% opacity primary, 60% secondary — pure #FFF body text is harsh.
+- Shadows barely work — use borders (`+6–8%` white overlay) to separate raised surfaces.
+- Semantic colors need dark-mode variants (lighter red/green for 4.5:1 on dark surfaces).
+- Images/illustrations: dim slightly (~90% opacity) or provide dark variants.
+- Respect the OS setting (`prefers-color-scheme`) and offer a manual override that persists.
+
+## Psychology & context (use lightly)
+
+- Blue = trust/finance-tech default (also the most overused); green = growth/health/money; red = urgency/danger — reserve for destructive & errors in-product; purple = premium/creative; orange/yellow = energy/attention, weak for text.
+- Cultural check for global products (white/red/gold meanings vary).
+- Category convention beats psychology: fintech ≈ blue/green + dark premium; health ≈ calm greens/blues; food ≈ warm reds/oranges.
+
+## Practical rules
+
+- Red/danger only ever means destructive or error in-product. Don't use it for badges/accents.
+- Links: one link color, underline in body prose.
+- Charts: 6-hue max categorical palette, colorblind-safe (test deuteranopia), consistent series colors across the product.
+- Gradients: same-hue or adjacent-hue only (blue→violet fine, blue→orange muddy); subtle in UI, bolder allowed in marketing heroes.
+- White space is a color: default to more surface, less ink.
+
+## Anti-patterns
+
+- Accent color used for 30% of the screen (nothing pops).
+- Text on gradients/images without scrim.
+- Dark mode as naive inversion (pure black + neon saturated accents).
+- Six different blues drifting across a product because values were hardcoded per-component.

package/knowledge/ux/conversion-ux.md

@@ -0,0 +1,78 @@
+---
+id: conversion-ux
+title: "Conversion UX — Landing Pages, CRO, Trust"
+category: ux
+platform: web
+tags: [conversion, cro, landing-page, cta, social-proof, pricing]
+sources: ["https://www.nngroup.com/articles/conversion-rate/", "https://cxl.com/blog/"]
+updated: 2026-07-08
+---
+
+# Conversion UX — Landing Pages, CRO, Trust
+
+## The above-the-fold contract
+
+Within 5 seconds a visitor must be able to answer: **What is this? Who is it for? Why should I care? What do I do next?**
+
+- Headline: outcome-focused, specific, ≤10 words ("Ship your app in days, not months" — not "Welcome to X" or vague "Empower your workflow").
+- Subheadline: 1–2 lines expanding the how/who.
+- One primary CTA above the fold; optional low-commitment secondary ("See demo").
+- Real product visual (screenshot/video) beats abstract illustration for SaaS.
+- Social-proof strip (logos / rating / user count) immediately under the hero.
+
+## Page narrative (proven order)
+
+1. Hero (promise + CTA + proof strip)
+2. Problem/agitation or "how it works" (3 steps)
+3. Feature/benefit sections — benefit-led headings; features as evidence
+4. Deep social proof (testimonials with names, faces, companies, specific results)
+5. Pricing (if self-serve) 
+6. Objection handling / FAQ
+7. Final CTA section (restate promise)
+8. Footer
+
+Repeat the CTA every 1.5–2 viewport heights. All CTAs on one page → same action (one conversion goal per page).
+
+## CTA optimization
+
+- First-person, value-forward labels test well: "Start my free trial", "Get the template" > "Submit", "Learn more".
+- Reduce perceived risk beside the CTA: "Free 14-day trial · No credit card required · Cancel anytime".
+- Contrast: CTA should be the highest-contrast element in its viewport; if you screenshot and squint, the CTA must be the first thing you see.
+
+## Forms & signup friction
+
+- Every field costs conversion: signup = email + password (or SSO only). Ask for the rest later (progressive profiling).
+- Multi-step beats single long form; start with the easy/engaging question (commitment escalation).
+- Show value before the wall: interactive demo, free tier, sample output.
+
+## Trust & credibility (Stanford guidelines, operationalized)
+
+- Specificity sells: "12,483 teams" > "thousands of teams"; "reduced churn 23%" > "improves retention".
+- Testimonials: full name + photo + role/company + concrete result. Anonymous quotes are worse than none.
+- Security/compliance badges near payment and signup (SOC2, GDPR, Stripe).
+- Visible humans, physical address, responsive support links; polished 404s and error states — sloppy edges leak distrust.
+- Price transparency: hiding pricing behind "Contact us" for a self-serve-priced product kills qualified traffic.
+
+## Pricing page patterns
+
+- 3 tiers, middle highlighted ("Most popular") — anchor high tier first on enterprise-leaning products.
+- Per-tier CTA; feature comparison collapsed below the cards; annual/monthly toggle with savings label ("Save 20%").
+- Answer the top 5 objections in FAQ on the pricing page itself (refunds, cancellation, limits, security, migration).
+
+## Urgency & ethics
+
+Real scarcity/deadlines only. Fake countdowns, hidden costs at checkout, confirm-shaming ("No thanks, I hate saving money"), forced continuity, and roach-motel cancellations are dark patterns — they convert once, destroy LTV and brand, and increasingly are illegal (FTC/EU).
+
+## Measurement
+
+- One primary conversion metric per page; instrument scroll depth, CTA clicks, form-field drop-off.
+- A/B test one variable at a time; headline and hero tests move numbers more than button-color tests.
+- Speed is CRO: every second of load costs ~5–10% conversions; mobile experience is the majority experience.
+
+## Anti-patterns
+
+- Carousel heroes (message dilution; slide 2+ is never seen); auto-playing sound.
+- Multiple competing CTAs ("Sign up" + "Contact" + "Download" equally weighted).
+- Wall-of-features tables with no benefits framing; jargon headlines ("Synergize your workflows").
+- Newsletter modal before the visitor reads a single paragraph.
+- Stock photos of handshakes/headsets standing in for a real product.

package/knowledge/ux/mobile-ux.md

@@ -0,0 +1,69 @@
+---
+id: mobile-ux
+title: "Mobile App UX — Platform Rules & Ergonomics"
+category: ux
+platform: mobile
+tags: [mobile, thumb-zone, gestures, ios, android, onboarding]
+sources: ["https://developer.apple.com/design/human-interface-guidelines/", "https://m3.material.io/", "https://www.nngroup.com/articles/mobile-ux/"]
+updated: 2026-07-08
+---
+
+# Mobile App UX — Platform Rules & Ergonomics
+
+## Thumb-zone design
+
+- Bottom third of the screen = easy reach; top corners = hardest. On 6.1–6.9" phones, one-handed use dominates.
+- Primary actions, tab bars, key CTAs → bottom. Destructive actions → out of accidental-tap zones.
+- Top of screen: titles, status, search (with pull-down or bottom-sheet alternatives in reach-heavy apps).
+- FABs: bottom-right (Material); avoid covering list content actions.
+
+## Platform respect (don't ship one design to both)
+
+| Concern | iOS | Android |
+|---|---|---|
+| Back | Top-left back + edge-swipe | System back gesture/button — must always work correctly |
+| Nav bar | Tab bar 49pt + safe area | Navigation bar 80dp |
+| Typography | SF Pro, Dynamic Type | Roboto/brand, sp units |
+| Sheets | Detent sheets, capsule buttons | Bottom sheets, M3 shapes |
+| Settings | Grouped inset lists | Preference lists |
+| Share/context | Share sheet, context menus (long-press preview) | Share sheet, ⋮ menus |
+
+Core brand and layout can match; navigation, gestures, pickers, and system integrations must be native-correct.
+
+## Gestures
+
+- Every gesture needs a visible alternative (swipe-to-delete → edit mode / ⋯ menu).
+- Standard gestures only: swipe back, pull-to-refresh, long-press context, pinch zoom on media. Custom gestures need onboarding and rarely stick.
+- Don't fight system gestures: keep interactive elements out of edge-swipe zones and the home-indicator area.
+
+## Onboarding & first-run
+
+- Time-to-value is the metric: get users to the core "aha" in <60 seconds. Defer signup until value is shown when possible.
+- Skip intro carousels or cap at 3 screens with Skip; contextual education (tooltips at first encounter) beats upfront tours.
+- Personalization questions: only if answers visibly change the experience; show progress; ≤5 steps.
+- Permissions: ask in context with a pre-permission explainer screen (notifications after user does something worth notifying about — never on cold start). Each cold-start permission dialog costs conversions.
+- Sign-in: offer Apple/Google SSO first (one-tap), email fallback; passkeys are the 2026 default recommendation.
+
+## Performance = UX
+
+- Cold start <2s to interactive content; show branded splash → skeleton, never splash → blank.
+- 60fps scrolling is non-negotiable; janky lists read as "cheap app".
+- Offline: cache last content, queue writes, explicit offline banner + retry. Airplane-mode test every core flow.
+- Images progressive/lazy; interactions respond <100ms (optimistic UI for likes/saves).
+
+## Mobile-specific patterns
+
+- Keyboard management: scroll focused input above keyboard; "Done/Next" return-key flow through forms; dismiss on scroll or tap-out.
+- Notifications: transactional > promotional; batch digests; deep-link every notification to its exact content.
+- App Store touchpoints: request review only after a success moment, cap frequency; never interrupt a task.
+- Haptics: light impact for selections/toggles, success/error notification haptics — subtle, never on scroll.
+- Text: minimum tap targets 44pt; body 16–17pt; support Dynamic Type up to accessibility sizes without truncation.
+
+## Anti-patterns
+
+- Web-view wrappers that ignore platform navigation.
+- Login wall before demonstrating any value (unless product truly requires it).
+- Interstitial ads/paywalls mid-task; notification permission dialog at first launch.
+- Hiding core actions behind long-press with no hint.
+- Splash screens >2s; forced app tours; blocking "rate us" dialogs.
+- Bottom sheets/keyboards covering the input being edited.