ui-ux-master 1.2.1 → 1.5.0

package/references/landing-page-patterns.md

@@ -0,0 +1,327 @@
+# Landing Page Patterns & Chart Type Guide
+
+Load this file when designing landing pages, marketing pages, or choosing data visualizations for dashboards.
+
+---
+
+## Part 1 — Landing Page Conversion Patterns
+
+Each pattern describes a proven page structure. Match the pattern to the product type and conversion goal. Use the section order as a scaffold — apply brand tokens, copy, and components on top.
+
+---
+
+### Pattern 1 — Hero-Centric
+
+**Conversion goal:** Create immediate desire and push to a single CTA.
+**Best for:** Consumer products, SaaS, mobile apps, simple single-offer products.
+
+**Structure:**
+1. **Hero** — Bold headline (outcome, not feature). Subheadline. Primary CTA. Hero visual (product screenshot, lifestyle image, or animated demo).
+2. **Social proof bar** — Logos or "X,000 users" (real numbers only).
+3. **Core features** — 3 features, icon + title + 1-line description.
+4. **Product showcase** — Screenshot or demo walkthrough.
+5. **Testimonials** — 2–3 quotes with name, role, company.
+6. **Pricing** — Clear, transparent, 2–3 tiers.
+7. **Final CTA** — Repeat primary CTA with a secondary backup.
+
+**Copy rule:** Hero headline must state an outcome ("Ship 10× faster"), not a category ("A development platform").
+
+---
+
+### Pattern 2 — Feature-Led
+
+**Conversion goal:** Educate first, convert second. For considered purchases.
+**Best for:** B2B SaaS, developer tools, complex products.
+
+**Structure:**
+1. **Hero** — Clear product category + differentiator. CTA to demo or trial.
+2. **Logo bar** — Enterprise or recognizable customer logos.
+3. **Feature deep-dives** — 4–6 features, each with a screenshot and 3-line description. Alternating left/right layout.
+4. **How it works** — 3-step process diagram.
+5. **Integration list** — "Works with your stack" logos.
+6. **Social proof** — Case study card with company + metric.
+7. **Pricing** — Feature comparison table.
+8. **CTA** — Demo booking or free trial.
+
+---
+
+### Pattern 3 — Social Proof First
+
+**Conversion goal:** Build trust before making any product claim.
+**Best for:** New brands, high-skepticism categories (health, finance, legal).
+
+**Structure:**
+1. **Hero** — Modest headline. Social proof count ("Trusted by 12,000 professionals — real number").
+2. **Customer logos** — Immediately below hero.
+3. **Testimonial carousel or grid** — Above the fold-ish, prominent.
+4. **Product features** — Now that trust is established.
+5. **More testimonials / case studies** — With metrics.
+6. **Security/compliance badges** (if relevant).
+7. **CTA** — "Join them."
+
+---
+
+### Pattern 4 — Problem-Solution
+
+**Conversion goal:** Identify the pain, then position the product as the only logical answer.
+**Best for:** Products solving a specific painful problem. Especially effective for productivity, operations, and workflow tools.
+
+**Structure:**
+1. **Problem hook** — "Does this sound familiar?" or "Tired of [pain]?"
+2. **Agitate** — List 3 symptoms of the problem. Make it feel recognized.
+3. **Solution reveal** — "There's a better way." Introduce product.
+4. **How it solves it** — Feature-to-problem mapping.
+5. **Proof** — Testimonials from people who had the same problem.
+6. **CTA** — "Stop [problem]. Start [solution]."
+
+---
+
+### Pattern 5 — Product Demo First
+
+**Conversion goal:** Show, don't tell. Let the product speak.
+**Best for:** AI tools, creative apps, anything with a compelling interactive demo.
+
+**Structure:**
+1. **Hero with live/embedded demo** — The product working in the hero itself.
+2. **"Here's what you just saw" explainer** — Brief description of the demo.
+3. **Key capabilities** — What else it can do.
+4. **Use case tabs** — "For designers", "For developers", "For product managers."
+5. **Testimonials from each persona**.
+6. **Pricing or trial CTA**.
+
+---
+
+### Pattern 6 — Storytelling / Narrative
+
+**Conversion goal:** Emotional connection before conversion.
+**Best for:** Consumer brands, luxury, wellness, food, lifestyle, mission-driven companies.
+
+**Structure:**
+1. **Opening visual** — Lifestyle or brand-world hero. Minimal text.
+2. **Brand story** — 3–4 paragraphs of genuine origin/mission.
+3. **Product/offer introduced** — Natural transition from story.
+4. **Product details** — Materials, process, sourcing (whatever is meaningful).
+5. **Community/people** — Behind the brand or customers.
+6. **CTA** — Invitation, not pressure.
+
+---
+
+### Pattern 7 — Comparison / Competitive
+
+**Conversion goal:** Position against the alternative (usually the status quo or a named competitor).
+**Best for:** Switching products, disruptors, "X but better" positioning.
+
+**Structure:**
+1. **Hero** — "Finally, a [category] that doesn't [competitor's problem]."
+2. **Comparison table** — You vs. them. Be fair — only list real advantages.
+3. **Deep feature sections** — Where you win.
+4. **Testimonials from switchers** — "I switched from X because…"
+5. **Migration offer** — Import, free migration, etc.
+6. **CTA** — "Make the switch."
+
+**Rule:** Never make false claims in comparison tables. Only list features you genuinely have. Users will verify.
+
+---
+
+### Pattern 8 — Waitlist / Coming Soon
+
+**Conversion goal:** Capture interest before launch. Build anticipation.
+**Best for:** Pre-launch products, exclusive launches, limited access.
+
+**Structure:**
+1. **Hero with countdown or "Coming [date]"** — Single focus.
+2. **Teaser of what's coming** — Just enough to create desire.
+3. **Email capture** — Primary action. Keep form to email only.
+4. **Early access benefits** — What waitlist members get.
+5. **Social proof** — "X people already on the waitlist" (if real).
+
+---
+
+### Pattern 9 — Pricing Page
+
+**Conversion goal:** Help the user choose the right tier and commit.
+**Best for:** SaaS, subscription products, membership products.
+
+**Structure:**
+1. **Headline** — "Simple, transparent pricing." No tricks promise.
+2. **Toggle** — Monthly / Annual (annual should show savings).
+3. **Pricing tiers** — 2–4 tiers. Highlight the recommended tier.
+4. **Feature comparison table** — Below tiers for detail-oriented buyers.
+5. **FAQ** — "What happens after my trial?" "Can I cancel anytime?"
+6. **Enterprise CTA** — "Need more? Talk to us."
+7. **Guarantee / Trust signal** — "Cancel anytime. No credit card required."
+
+**Rules:**
+- Never hide the price. If you can't show it, say "Custom pricing — contact sales" clearly.
+- Always show what's included, not just what's different from tier to tier.
+- Annual savings: show in % and in $ amount.
+
+---
+
+### Pattern 10 — Documentation / Developer Home
+
+**Conversion goal:** Get developers into the docs and first integration fast.
+**Best for:** APIs, SDKs, developer platforms.
+
+**Structure:**
+1. **Hero** — Product in one sentence. "Get started in 5 minutes." Code snippet.
+2. **Quickstart** — Inline code block. Real runnable example.
+3. **Key capabilities** — What you can build.
+4. **Integration ecosystem** — "Works with X, Y, Z."
+5. **Community / GitHub** — Stars, contributors, Discord.
+6. **CTA** — "Read the docs." Never "Sign up" as the primary.
+
+---
+
+### Pattern 11 — Portfolio / Case Study
+
+**Conversion goal:** Build credibility through demonstrated work.
+**Best for:** Agencies, consultants, freelancers, service businesses.
+
+**Structure:**
+1. **Hero** — Name/studio + specialty. Best work preview.
+2. **Work grid** — Projects with title, category, thumbnail.
+3. **Case study detail** — Challenge → Process → Outcome (with metrics).
+4. **About** — Brief, human, specific.
+5. **Client logos** — Social proof.
+6. **CTA** — "Start a project" or "Get in touch."
+
+---
+
+### Pattern 12 — E-commerce Category Page
+
+**Conversion goal:** Help users discover and filter to the right product.
+**Best for:** Retail, D2C, marketplace.
+
+**Structure:**
+1. **Category hero** — Seasonal or collection-led visual.
+2. **Filter bar** — Sort, filter by attributes. Sticky on scroll.
+3. **Product grid** — Cards with image, name, price, quick-add.
+4. **Pagination or infinite scroll** — Clear affordance.
+5. **Upsell section** — "Complete the look" or "Frequently bought together."
+
+---
+
+## Part 2 — Chart & Data Visualization Type Guide
+
+Load this section when designing dashboards, analytics pages, or any data-heavy screen.
+
+---
+
+### Chart Selection Decision Tree
+
+```
+What is the user trying to understand?
+
+COMPARISON
+  ├── Between a few items (≤7)     → Bar Chart (vertical)
+  ├── Between many items           → Horizontal Bar Chart
+  ├── Over time                    → Line Chart
+  └── Part of a whole              → Pie Chart (≤5 segments) / Donut Chart
+
+TREND OVER TIME
+  ├── Single metric                → Line Chart
+  ├── Multiple metrics             → Multi-line Chart
+  ├── Cumulative / stacked         → Stacked Area Chart
+  └── Volume over time             → Bar Chart (time axis)
+
+DISTRIBUTION
+  ├── Spread of values             → Histogram
+  ├── Statistical summary          → Box Plot
+  └── Individual data points       → Scatter Plot
+
+RELATIONSHIP / CORRELATION
+  ├── Two variables                → Scatter Plot
+  ├── Three variables              → Bubble Chart
+  └── Categories vs. metric        → Heatmap
+
+COMPOSITION (part of whole)
+  ├── Static snapshot              → Pie / Donut (≤5 segments only)
+  ├── Over time                    → Stacked Bar / Stacked Area
+  └── Hierarchical                 → Treemap / Sunburst
+
+FLOW / PROCESS
+  ├── Sequential steps             → Funnel Chart
+  ├── Flow between categories      → Sankey Diagram
+  └── Network relationships        → Force-directed graph
+
+GEOGRAPHIC
+  └── Location-based data          → Choropleth Map / Dot Map
+
+KPI / SINGLE METRIC
+  └── Current value + context      → Metric Card with sparkline / Gauge
+```
+
+---
+
+### Chart Type Specs
+
+| Chart | Use when | Avoid when | Max data points |
+|---|---|---|---|
+| **Line** | Trends over time, continuous data | Comparing unrelated categories | 5–7 lines max |
+| **Bar (vertical)** | Comparing categories, discrete data | More than 12 bars (use horizontal) | 12 bars |
+| **Bar (horizontal)** | Long category names, ranked lists | Showing trends over time | 20 items |
+| **Pie** | Part-of-whole, 3–5 categories only | More than 5 slices, comparing sizes | 5 segments |
+| **Donut** | Same as pie + center metric | Same as pie | 5 segments |
+| **Area** | Volume over time, cumulative data | Overlapping areas that obscure data | 3 series |
+| **Stacked bar** | Part-of-whole over categories | Too many stack layers (>5) | 5 stack layers |
+| **Scatter** | Correlation between two variables | Showing trends over time | 500 points |
+| **Bubble** | 3-variable relationship | When bubble size differences are subtle | 50 bubbles |
+| **Heatmap** | Density, frequency, correlation matrix | When exact values matter more than pattern | 100×100 cells |
+| **Funnel** | Conversion pipeline, drop-off analysis | Anything not a sequential conversion | 7 stages |
+| **Treemap** | Hierarchical part-of-whole | When exact sizes matter | 50 tiles |
+| **Histogram** | Distribution of a single variable | Comparing multiple variables | 1 variable |
+| **Metric card** | Single KPI + change + context | When the metric needs breakdown | 1 value |
+| **Sparkline** | Trend at a glance, inline in table | When full axis detail is needed | Simple trend |
+| **Gauge** | Current value vs. target/range | When absolute values matter more | 1 value |
+
+---
+
+### Dashboard Layout Rules
+
+**Grid and density:**
+- Cards: consistent padding (24px inner), consistent border-radius, consistent shadow.
+- Spacing between cards: 16–24px.
+- KPI metrics row: 4 cards across at desktop (2 at mobile).
+- Charts: primary charts span 2/3 width; secondary charts span 1/3.
+
+**Data typography:**
+- Metric value: `--text-3xl` to `--text-4xl`, `font-weight: 700`, monospace optional.
+- Metric label: `--text-sm`, `--color-text-secondary`.
+- Chart labels: `--text-xs`, `--color-text-muted`.
+- Table: `--text-sm`, `--text-base` for headings.
+
+**Color in charts:**
+- Use a consistent, accessible color sequence (not rainbow):
+  1. Brand primary (--color-accent)
+  2. Brand secondary (shifted hue)
+  3. Neutral dark
+  4. Semantic: success green, warning amber, error red
+- Never use red/green as the only indicator in the same chart (colorblindness).
+- Provide pattern + color differentiation for multi-series charts.
+
+**Empty and loading states:**
+- Skeleton: same size/shape as the chart it will replace.
+- Empty: explain why it's empty + offer an action ("No data for this period — try adjusting the date range").
+- Error: state what failed + offer retry ("Failed to load — Retry").
+
+**Interaction patterns:**
+- Tooltips on hover: show exact values, category label, date.
+- Click-through on chart elements: drill down to detail view.
+- Date range picker: always show current range prominently.
+- Export: CSV and PNG download options for any chart.
+
+---
+
+### Anti-Patterns in Data Visualization
+
+| Pattern | Why it's wrong | Fix |
+|---|---|---|
+| Truncated Y-axis (doesn't start at 0) | Exaggerates differences | Always start bar charts at 0 |
+| Pie chart with >5 slices | Impossible to compare small slices | Use horizontal bar chart |
+| 3D charts | Distorts visual perception of values | Never use 3D — always flat |
+| Dual Y-axes with different scales | Implies false correlation | Use separate charts or normalize |
+| Animations on every data update | Distracts, slows perception | Animate once on load only |
+| Red/green only for success/failure | Colorblind users cannot distinguish | Add icon or pattern indicator |
+| Showing raw numbers without context | Users can't judge if good or bad | Add target, average, or prior period comparison |
+| Auto-refreshing without user control | Disorienting, loses user's place | Show "last updated" + manual refresh option |

package/references/output-quality-gates.md

@@ -0,0 +1,246 @@
+# Output Quality Gates
+
+Load this file before emitting any design output. Apply the 5-dimensional self-critique, pass P0 hard gates, then check the anti-slop blacklist. Only emit output after all three pass.
+
+This is not optional. A design output that skips these gates has not been reviewed and should not be considered complete.
+
+---
+
+## Part 1 — 5-Dimensional Self-Critique
+
+Before producing final visual output (mockup, spec, component, landing page, design system), silently score your output on these five dimensions. Do not show the scoring to the user unless they ask. Fix and rescore until all dimensions are ≥ 3.
+
+| Dimension | What it measures | Score 1 | Score 3 | Score 5 |
+|---|---|---|---|---|
+| **Philosophy** | Does the design have a clear, defensible visual identity? | Generic. Could be any product in any category. | Has a point of view but it's diluted or inconsistent. | Every layout decision, color choice, and type scale serves a single coherent visual thesis. |
+| **Hierarchy** | Is the most important element unambiguously dominant? | Multiple elements compete for attention equally. | A primary element exists but is undermined by noise. | The user's eye lands exactly where it should, in the right sequence, without effort. |
+| **Execution** | Are spacing, alignment, type scale, and color application precise? | Arbitrary spacing, misaligned elements, inconsistent sizing. | Generally consistent but has visible irregularities. | Every value is intentional. Spacing is from a system. Nothing looks accidental. |
+| **Specificity** | Is content real and specific, or generic and placeholder? | All text is lorem ipsum or generic ("Title here", "10× faster"). | Some real content, some placeholder. | Every piece of visible copy is real, specific, and contextually correct. |
+| **Restraint** | Are there elements that should be removed? | Visually noisy. Too many competing colors, sizes, or effects. | A few unnecessary elements but the core is clean. | Nothing could be removed without losing meaning. Every element earns its place. |
+
+### Scoring Rules
+
+- Score each dimension 1–5 honestly.
+- If any dimension scores below 3: identify the cause, fix it, rescore.
+- Two fix-and-rescore passes is normal and expected.
+- If you cannot get a dimension above 2 with the constraints given, flag it explicitly: "Constraint note: [dimension] is limited by [reason]. Recommended fix: [suggestion]."
+- Do not emit output with any score below 3 without an explicit constraint note.
+
+### Scoring Shorthand (use internally)
+
+```
+Philosophy: [1-5]  Hierarchy: [1-5]  Execution: [1-5]  Specificity: [1-5]  Restraint: [1-5]
+→ [PASS / NEEDS FIX]
+```
+
+---
+
+## Part 2 — P0 Hard Gates
+
+These are non-negotiable checks. Any P0 failure blocks output entirely until fixed.
+
+### P0 — Critical (output blocked until resolved)
+
+- [ ] **No fake metrics.** Output contains no invented numbers presented as facts ("10× faster", "used by 50,000 teams", "99.9% uptime") unless the user provided those numbers. Replace with `—` or a clearly labelled placeholder (see Part 3 — Honest Placeholders).
+- [ ] **No inaccessible text contrast.** All text has at least 4.5:1 contrast against its background. All large text (18px+ or 14px+ bold) has at least 3:1. Checked, not assumed.
+- [ ] **No missing interactive states.** Every interactive element (button, link, input, toggle, card) has at minimum: default, hover, focus, disabled states defined.
+- [ ] **No orphaned CTAs.** Every call-to-action has: a label (not icon-only), a destination or action, and an accessible name.
+- [ ] **No overflowing or clipped content at 375px mobile.** Layout tested at the smallest target breakpoint.
+
+### P1 — Important (flag to user if not fixed)
+
+- [ ] All images have alt text described (not just `alt="image"`).
+- [ ] Color is not the only differentiator for any meaning (status, error, category).
+- [ ] Heading hierarchy is logical (H1 → H2 → H3, no skipped levels).
+- [ ] Focus order follows visual reading order.
+- [ ] Error messages identify the field and state a recovery action.
+
+### P2 — Recommended (note in handoff)
+
+- [ ] Dark mode tokens specified if the product targets dark-mode users.
+- [ ] RTL layout checked if product targets Arabic, Hebrew, or Persian markets.
+- [ ] Loading / skeleton states defined for all data-dependent components.
+- [ ] Empty states defined for all lists, grids, and dashboards.
+- [ ] i18n: all visible copy fits in typical translation expansions (German/French can expand 30–40%).
+
+---
+
+## Part 3 — Anti-AI-Slop Blacklist
+
+These patterns are explicitly forbidden. If any appear in your output, remove them before emitting.
+
+### Visual Patterns — Never Use
+
+| Forbidden pattern | Why it's slop | What to use instead |
+|---|---|---|
+| Aggressive purple-to-blue gradient as a hero background | Overused in AI/SaaS projects to the point of meaninglessness | Solid brand color, OKLch-calibrated tint ramp, or image-driven hero |
+| Rounded card with a thick left-border accent color | Generic "dashboard widget" pattern that communicates nothing | Use elevation (shadow), contained background, or inline icon for status |
+| Generic emoji icons as product icons (🚀🎯💡✅) | AI defaults, no brand identity, looks auto-generated | SVG icons (Lucide, Heroicons, Phosphor, or custom), or no icon at all |
+| Hand-drawn SVG humans / people illustrations with bold outlines | Overused "friendly tech" cliché | Photography, abstract illustration, or no illustration |
+| Inter as a display/headline face | Beautiful for body text, but AI always defaults to it | Pair Inter body with a display face (Sohne, DM Sans, Fraunces, etc.) or use brand-specified type |
+| Stock "team" photos (diverse group smiling at laptop) | Instantly recognizable as AI/stock filler | Real product screenshots, abstract visuals, or explicitly labelled placeholders |
+| "Confetti" or celebration lottie on every positive action | Loses meaning through overuse | Reserve confetti-style animation for truly significant milestones (account created, first payment) |
+| Pastel blue + white + a single rounded button — nothing else | The "minimum viable SaaS" look, signals no design thinking | Commit to a visual direction with actual identity |
+| Neon glow effects on dark backgrounds | AI "cyberpunk" default | Use brand accent sparingly, without glow, on dark surfaces |
+| Multiple competing gradient backgrounds on the same page | Visual noise, no hierarchy | One gradient maximum, used structurally |
+
+### Copy Patterns — Never Use
+
+| Forbidden copy pattern | Why it's slop | What to use instead |
+|---|---|---|
+| `"10× faster"` without a source | Invented metric, erodes trust | `"—"` or `"[insert benchmark result]"` |
+| `"Trusted by 10,000+ teams"` without a source | Same | `"[insert real user count]"` or remove |
+| `"The future of [category]"` | Meaningless, overused | Specific outcome: what the user achieves |
+| `"Seamlessly"`, `"Effortlessly"`, `"Powerful yet simple"` | Filler adjectives that all AI copy uses | Describe the specific mechanic or outcome |
+| `"All-in-one platform"` | Tells the user nothing | Name the specific things it does |
+| Lorem ipsum in high-fidelity output | Breaks specificity; users cannot evaluate if copy is right | Write real placeholder copy that fits the context |
+| `"Click here"` as link text | Not descriptive, fails accessibility | "View pricing", "Download the report", "Start free trial" |
+| Generic testimonial: `"This product changed my life. — John D."` | AI filler | Leave blank with `[real customer quote, role, company]` |
+
+### Structure Patterns — Never Use
+
+| Forbidden structure | Why | Alternative |
+|---|---|---|
+| Full-page loading spinner with no progress feedback | Dead UX; users don't know if anything is happening | Skeleton screens + progress indication |
+| Carousel/slider in the hero | Reduces engagement, bad on mobile, poor accessibility | Single strong hero message |
+| "5 features, each with an icon, title, and one-line description" as the entire homepage | The generic SaaS landing page formula | Differentiate: use proof, specificity, demos |
+| Accordion-everything on mobile | Not discoverable, feels lazy | Prioritize content; accordion only for genuinely secondary info |
+| Hiding price until a "Contact Sales" wall | Dark pattern, destroys trust | Show pricing or at minimum a pricing range |
+
+---
+
+## Part 4 — Honest Placeholder Protocol
+
+When you do not have real content, use structured, honest placeholders. Never invent facts.
+
+### Numbers and Metrics
+
+```
+Invented:  "10× faster inference"
+Correct:   "[Performance benchmark — to be added after testing]"
+Short form: —
+```
+
+```
+Invented:  "Trusted by 50,000 teams"
+Correct:   "[User count — to be verified]"
+Short form: —
+```
+
+### Images
+
+```
+Invented:  Describe a stock photo of people smiling
+Correct:   [Product screenshot] or [Photography: team in office] or [Illustration: abstract]
+```
+
+### Quotes and Testimonials
+
+```
+Invented:  "This saved us 10 hours a week. — Sarah K., Head of Product"
+Correct:   [Customer quote — name, title, company to be added]
+```
+
+### Dates and Stats
+
+```
+Invented:  "Since 2019, serving 120 countries"
+Correct:   [Founded: year] [Markets: regions]
+```
+
+### Rule
+
+If a piece of content is a placeholder, it must **look** like a placeholder. Use `[square brackets]`, grey fill blocks, or `—`. Never make a placeholder look like real content.
+
+---
+
+## Part 5 — Code-Level AI Audit Error Codes
+
+When auditing or reviewing generated UI code (HTML, JSX, TSX, Vue, Svelte, etc.), flag issues using these standardized codes. Output one line per issue in format: `[severity] L[line] [CODE] [description]`.
+
+**Severity levels:** 🔴 Critical (blocks delivery) · 🟡 Warning (must fix before release) · 🔵 Info (best practice)
+
+### Tailwind / CSS Errors
+
+| Code | Severity | Pattern | Description |
+|------|----------|---------|-------------|
+| `AI001` | 🔴 | `bg-[${variable}]` | Tailwind class interpolation — purged at build, will not render |
+| `AI002` | 🔴 | `text-shadow-*` | Hallucinated Tailwind utility — no native text-shadow in core Tailwind |
+| `AI003` | 🔴 | `bg-gradient-[...]` with arbitrary | Arbitrary gradient shorthand not supported in all Tailwind versions |
+| `AI004` | 🟡 | `h-screen` | Causes layout shift on mobile with dynamic viewport — use `min-h-dvh` |
+| `AI005` | 🟡 | `drop-shadow-[...]` on text | Intended for elements, not text — use `text-shadow` via plugin |
+| `AI006` | 🟡 | `opacity-[val]` on parent with absolute children | Creates stacking context issues |
+| `AI007` | 🟡 | `overflow-hidden` on scroll container | Clips sticky children unintentionally |
+| `AI008` | 🟡 | Low-contrast semi-transparent text | `text-white/50` on white bg — passes visual but fails WCAG |
+| `AI009` | 🔵 | Missing `dark:` variant | Interactive element has no dark mode override |
+| `AI010` | 🔵 | `transition-all` | Too broad — prefer `transition-colors`, `transition-opacity` |
+
+### Accessibility Errors
+
+| Code | Severity | Pattern | Description |
+|------|----------|---------|-------------|
+| `AI011` | 🔴 | `<div onClick>` without `role` + `tabIndex` | Non-interactive element used as button — not keyboard accessible |
+| `AI012` | 🔴 | `<img>` missing `alt` | Images without alt text fail WCAG 1.1.1 |
+| `AI013` | 🔴 | `outline: none` / `outline: 0` without replacement | Removes focus visibility — keyboard navigation broken |
+| `AI014` | 🟡 | Icon-only button without `aria-label` | Screen readers announce nothing meaningful |
+| `AI015` | 🟡 | `target="_blank"` without `rel="noopener noreferrer"` | Security vulnerability + missing screen reader warning |
+| `AI016` | 🟡 | Form `<input>` without associated `<label>` | Not announced correctly by screen readers |
+| `AI017` | 🟡 | Color-only status indicator | Red/green badge without icon or text label |
+| `AI018` | 🔵 | Missing `lang` attribute on `<html>` | Screen readers default to wrong language |
+| `AI019` | 🔵 | Heading levels skipped (H1 → H3) | Broken document outline |
+
+### React / Framework Errors
+
+| Code | Severity | Pattern | Description |
+|------|----------|---------|-------------|
+| `AI020` | 🔴 | `key={index}` on dynamic list | Index as key causes reconciliation bugs on reorder/insert |
+| `AI021` | 🔴 | Direct state mutation `state.push(x)` | Bypasses React reactivity — UI won't update |
+| `AI022` | 🟡 | `useEffect` with empty dep array fetching data | Stale closure — deps should include all referenced values |
+| `AI023` | 🟡 | `useState` for server data | Use React Query / SWR / server state pattern |
+| `AI024` | 🟡 | Large component with 300+ lines | Split into smaller, focused components |
+| `AI025` | 🔵 | Missing `displayName` on forwardRef components | Debugger shows anonymous component |
+
+### Content / Copy Errors
+
+| Code | Severity | Pattern | Description |
+|------|----------|---------|-------------|
+| `AI026` | 🔴 | Invented metric without source | "10× faster", "99.9% uptime" without data — see Honest Placeholder Protocol |
+| `AI027` | 🔴 | Lorem ipsum in high-fidelity output | Placeholder in final deliverable |
+| `AI028` | 🟡 | "Click here" as link text | Not descriptive — fails WCAG 2.4.6 |
+| `AI029` | 🟡 | Error message without recovery action | "Invalid input" with no guidance on how to fix |
+| `AI030` | 🔵 | Generic CTA copy "Submit" / "Click" | Replace with action-outcome copy: "Create account", "Save changes" |
+
+### Audit Output Format
+
+```
+🔴 L5  [AI001] Tailwind class interpolation detected — bg-[${primaryColor}] will be purged
+🟡 L9  [AI005] Hallucinated utility class — "text-shadow-lg" does not exist in Tailwind core
+🟡 L12 [AI008] Low contrast pseudo-transparency — text-white/50 on white background
+🟡 L18 [AI004] h-screen causes layout shift on mobile — use min-h-dvh
+🟡 L21 [AI015] target="_blank" missing rel="noopener noreferrer" — security + accessibility
+🔵 L44 [AI009] Button has no dark: color variant defined
+
+SUMMARY: 1 critical, 4 warnings, 1 info
+→ Fix all 🔴 before delivery. Fix 🟡 before release.
+```
+
+---
+
+## Quick Checklist (use before every emit)
+
+```
+5-DIM CRITIQUE
+Philosophy ≥3? [ ]  Hierarchy ≥3? [ ]  Execution ≥3? [ ]
+Specificity ≥3? [ ]  Restraint ≥3? [ ]
+
+P0 GATES
+No fake metrics? [ ]  Contrast passes? [ ]  States defined? [ ]
+CTAs labeled? [ ]  375px OK? [ ]
+
+ANTI-SLOP
+No purple gradient hero? [ ]  No generic emojis? [ ]  No left-border accent card? [ ]
+No hand-drawn humans? [ ]  No Inter-as-hero? [ ]  No Lorem ipsum in high-fi? [ ]
+No invented numbers? [ ]  No "10× faster" without source? [ ]
+
+→ EMIT [ ] / NEEDS FIX [ ]
+```