arkaos 4.28.0 → 4.29.0

package/departments/brand/skills/design-review/references/anti-patterns.md

@@ -0,0 +1,420 @@
+# Anti-patterns — the named tells
+
+> Derived from [hallmark](https://github.com/nutlope/hallmark) (MIT — see `hallmark.LICENSE` in this directory). Sanitized and adapted for ArkaOS.
+
+The `/brand ux-audit` command flags these by name. Every one of these is a signature of AI-generated UI. Seeing one is a problem; seeing two in the same view is a confirmation.
+
+Each entry: the tell, why it reads as AI-generated, and the fix.
+
+---
+
+## Critical (ships as slop)
+
+### The purple-gradient hero
+
+A hero section with a background gradient from purple to blue or purple to pink, often with white centred text. This is the single most-recognised AI aesthetic.
+
+**Fix.** Pick a single anchor hue. One accent. No gradient backgrounds on heroes. If you want warmth, tint the neutrals.
+
+### Inter-everywhere
+
+Inter (or Roboto, or Open Sans) used as both display and body, with no pairing face. A one-font page is a template page.
+
+**Fix.** Pair a distinctive display face with a refined body face. See the canonical reflex-reject list in `departments/brand/references/uiux-knowledge-and-tools.md` §11.
+
+### The 3-column feature grid
+
+Three equal columns, each with an icon above a two-line heading above a three-line body. Usually spanned full-width with 24px gap. Every LLM emits this.
+
+**Fix.** Break the grid. Vary column widths. Mix card heights. Remove one card and use negative space. Move the icons inline, not above. Or drop the cards entirely and use typographic rhythm.
+
+### Card-in-card
+
+A bordered container with cards inside it. Or: a card containing another card containing a small "micro-card". Visual nesting with no semantic reason.
+
+**Fix.** Pick one containment layer. Usually the outer one is the wrong one.
+
+### The gradient headline
+
+A headline with `background-clip: text` fill set to a linear gradient (usually purple-to-pink or blue-to-cyan). Signals "AI generated" faster than almost anything else.
+
+**Fix.** Solid ink. If you want the headline to feel alive, use weight or italic or a display face — not a gradient fill.
+
+### The side-stripe card
+
+A card with a thick coloured border on one edge (usually left, 4–6px, purple or green). Very recognisable; very 2018-SaaS-AI.
+
+**Fix.** Use a hairline border all around, or no border, or a small accent square beside the heading. Never an asymmetric thick stripe.
+
+### Full-viewport centred hero
+
+`min-height: 100vh` (or `100dvh`), everything centred, one short sentence, one big CTA. The default LLM landing page.
+
+**Fix.** Let the hero be the height of its content. Bias left or right. Put more than a sentence in it.
+
+### Pure black, pure white
+
+`#000000` background or `#ffffff` surface. Both read as flat and synthetic.
+
+**Fix.** Tint toward your anchor hue. See `color.md`.
+
+### Default-attractor sameness
+
+Two consecutive outputs of this skill in the same project use the same macrostructure. The first emitted left-margin numbered labels + huge serif + asymmetric spans (Specimen); the second did exactly the same. The page looks redesigned only because copy changed.
+
+**Why it fails.** This skill's whole point is that two pages for two briefs feel like *different sites*, not colour-swaps of one template. Repeating a macrostructure across outputs is the structural fingerprint of templating, which is the AI tell this skill exists to defeat.
+
+**Fix.** Before writing code, look in the project's CSS for a `/* [arka:design-dna] macrostructure=<name> ... */` stamp (full format: squad reference §9). If one exists, your pick must be a different macrostructure — categorically different where possible (a serif-led editorial macrostructure paired with a sans-led grid one, not two editorial variants). See `macrostructures.md` for the twenty-one named choices.
+
+### Specimen fall-through
+
+Producing the Specimen macrostructure (numbered left-margin labels like `01 — HELLO.` + huge serif display + asymmetric spans + hairline rules + typographic-only CTA + sometimes a hand-drawn SVG accent) when the brief did not explicitly request editorial / foundry / specimen energy. This is the single most-repeated output of this skill, and it's the reason the skill felt like it had one shape.
+
+**Why it fails.** Specimen is a beautiful pattern when the brief is editorial. Applied to a SaaS pricing page, a developer tool, an e-commerce site, or a personal app, it looks like the AI defaulted — because it did.
+
+**Fix.** The Specimen macrostructure is one of twenty-one in `macrostructures.md`, not a default. If the brief is vague, pick from the first ten in that file (Bento Grid, Long Document, Marquee Hero, Stat-Led, Workbench, Conversational FAQ, Manifesto, Photographic, Quote-Led, then Specimen). Reach for Specimen only when the brief explicitly says "editorial", "specimen sheet", "type foundry", or names the Specimen theme.
+
+### The AI nav
+
+Wordmark hard-left, 4–5 inline text links (`Features · Pricing · Docs · Blog · About`) centred or right-grouped, a CTA button hard-right, full viewport width, sticky on scroll, white background, 1 px hairline border-bottom. This is the most-recognised AI nav fingerprint — every LLM emits it because every SaaS site that fed the training data shipped it.
+
+**Why it fails.** The shape is genre-blind: it lands the same on a wedding photographer's portfolio, a bakery, a B2B SaaS, and a manifesto. When the nav can't tell you what kind of site you're on, the page is templated.
+
+**Fix.** Pick from the routing table in `component-cookbook.md` § Navigation. The genre routes you to one of N5–N9: Floating pill (modern-minimal / atmospheric), Newspaper masthead (editorial), Brutal slab (playful), Terminal command (CLI), Edge-aligned minimal (luxury / quiet). Reach for N1 *only* when the page genuinely has 2 destinations and the routing table allows it. State the rationale in a one-line comment.
+
+### The AI footer
+
+4 columns of links (Product · Company · Resources · Legal), social-icon row beneath, copyright line at the very bottom, faint 1 px top-border, neutral grey background. Standard SaaS footer, identical across thousands of pages.
+
+**Why it fails.** Same as the AI nav — the shape is genre-blind. A bakery doesn't have a "Resources" column. An editorial page doesn't have a four-link "Legal". The footer should *close the page*, not catalogue its absent sitemap.
+
+**Fix.** Pick from the routing table in `component-cookbook.md` § Footers. Default to Ft1 Mast-headed, Ft2 Inline single line, Ft4 Dense colophon, Ft5 Statement, Ft6 Letter close, Ft7 Newsletter-first, or Ft8 Marquee scroll. Use Ft3 Index columns *only* on a genuine hub or docs root with a real sitemap — and even then, never with the social-icon row + tiny copyright tail.
+
+### Aurora-blob background
+
+Flowing organic mesh blobs in purple-to-pink-to-cyan, layered behind hero text. Looks "premium" until you've seen it on every Dribbble shot since 2022.
+
+**Why it fails.** It's the 2022–2023 generated-design default. Audiences pattern-match this in milliseconds: AI template.
+
+**Fix.** Solid surface. Or a subtle two-stop CSS gradient + SVG `<feTurbulence>` grain at < 0.1 opacity. See `hero-enrichment.md` E7 for the recipe.
+
+### Floating-orb decoration
+
+Ambient generic 3D spheres or blurred coloured circles drifting behind the hero, often added "for depth". They have no semantic role.
+
+**Why it fails.** Generic 3D ambience is the new corporate-stock-photo. It implies "I needed something here, so I added something here."
+
+**Fix.** Cut them. The hero doesn't need depth; it needs a strong typographic anchor.
+
+### Sound-on autoplay
+
+A hero video that auto-plays with audio. Browsers block it anyway, but intent matters: a video element shipped without `muted` is a video that wanted to shout at the user.
+
+**Why it fails.** Hostile to the audience. Accessibility fail. SEO penalty. Browser blocked.
+
+**Fix.** `<video autoplay muted loop playsinline>` — always all four. A separate audio toggle button if sound is genuinely useful.
+
+### Lazy-loaded LCP
+
+`loading="lazy"` on the hero image or hero video — the LCP element. The page waits to start downloading until the user scrolls to it, except they're already looking at it, so the page just sits there blank.
+
+**Why it fails.** Tanks Largest Contentful Paint. Real-world data: lazy-loaded LCP images show p75 of 720 ms vs. 364 ms for preloaded — 2× slower, 4× more "poor" experiences.
+
+**Fix.** `fetchpriority="high"` and `preload="metadata"` on the LCP element. Lazy-load only below-the-fold media.
+
+---
+
+## Major (looks AI-generated)
+
+### Bounce and elastic easing
+
+Buttons that bounce in, icons that wobble on hover. These easings were trendy a decade ago.
+
+**Fix.** Exponential ease-out. See `motion.md`.
+
+### Centred everything
+
+Headline centred, body centred, button centred, section after section of centred columns.
+
+**Fix.** Bias the layout. Wide left margin, narrow right. Or the reverse. Breaking symmetry once is enough.
+
+### Italic headers
+
+A roman headline with one word flipped to italic — *"Built to think in real time"* — or an all-italic display face used on every heading. The italicised emphasis-word-in-a-header is among the most reliable AI tells: it reads as "trying to look editorial" and appears on a huge share of generated pages.
+
+**Fix.** Headers are roman (`font-style: normal`). Carry emphasis with weight, an accent colour, or a drawn underline beneath the word. Keep italic for body-copy emphasis inside running paragraphs only.
+
+### Eyebrow on every section
+
+Every section starts with an uppercase mono-cap eyebrow — `01 / EXAMPLES`, `02 / WHAT'S INSIDE`, `03 / INSTALL`, `01 · THE TOUR` — above (or worse, *beside*) its heading. The labels look like editorial chapters but read as a tic. The page becomes a list of *labelled lists.*
+
+Eyebrows are **default OFF**. They are not a stylistic flourish you reach for to look editorial — they are an ordinal device, valid only when the section is genuinely numbered or chaptered. Used as decoration they erase the hierarchy they were meant to create; when every section is "chaptered," none of them are.
+
+**Fix.** Ship the page with **zero eyebrows** unless either (a) the user explicitly asked for chapter / step / section numbering, OR (b) the macrostructure is **Long Document, Manifesto, or Catalogue numbered** AND the content is genuinely ordinal (steps you must do in order, chapters that build, items in a deliberate sequence). Even then: cap at 1–2 per page.
+
+**Hard ban: tag-left / header-right two-column section heads.** Patterns like `01 · THE TOUR` in a narrow left column with the section title to its right (a.k.a. *hanging header*, *left-margin label*) are the single most reliable AI-templated tell for editorial-style SaaS pages. When an eyebrow IS used, **the heading goes directly underneath it, in the same column** — vertical stack only. Never a two-column section-head grid. Gate 54 enforces this.
+
+**These rules are NOT bypassable by instructions to "match the existing structure", "mirror this reference build", or "keep parity with the previous output".** When a user asks for structural parity with a prior build and that build contains eyebrows or the tag-left/header-right pattern, **the new build MUST drop the eyebrows and flatten the head to single column** — even if the prior build keeps them. Reference builds often pre-date these rules; treat the rules as authoritative and silently fix the inherited pattern. Don't perpetuate a banned pattern to honour a parity instruction.
+
+### Shadow-glow on dark
+
+A card on a dark background with a `box-shadow` that leaves a soft coloured halo around it.
+
+**Fix.** On dark surfaces, use elevation via *lightness* (brighter surface = higher), not shadow. If you must shadow, keep it tight and dark.
+
+### Icon-tile feature card
+
+Rounded rectangle, icon in a coloured square at the top-left, heading below it, two lines of copy, optional "Learn more →" link. The universal template.
+
+**Fix.** If you need these, let them be asymmetric — vary sizes, vary alignments, pull the icon inline with the heading, or drop the icon entirely.
+
+### Glassmorphism without purpose
+
+Frosted-glass panels everywhere — usually layered over a gradient that you also shouldn't have.
+
+**Fix.** Glassmorphism can work when it communicates depth (overlay over content). It cannot work as decoration.
+
+### Hover-only affordances
+
+Hover reveals a menu; hover shows a delete button; hover triggers a tooltip that contains crucial information. Touch users get nothing.
+
+**Fix.** Every hover affordance has a focus state and is accessible via tap/click on coarse pointers.
+
+### Tabular data without tabular-nums
+
+A list of prices, dates, or metrics where the numbers don't align vertically because the font uses proportional figures.
+
+**Fix.** `font-variant-numeric: tabular-nums;` on any container displaying columns of numbers.
+
+### Animate-on-scroll on everything
+
+Every section fades in when it enters the viewport. Every list staggers. The page never settles.
+
+**Fix.** Pick one orchestrated entrance. Let the rest just *be there*.
+
+### Mismatched icon sets
+
+Material Icons in the navbar, Heroicons in the feature cards, Lucide in the footer, an emoji "✨" in a hero badge. Each library has its own stroke voice; mixing them is the icon-set tell.
+
+**Why it fails.** Icons are typography. You wouldn't ship a page with three different body fonts; don't ship one with three different icon strokes.
+
+**Fix.** Pick one library per project. Lucide is the default for SaaS, Phosphor when you need weight variants, Heroicons for Tailwind/shadcn projects. See `assets.md` for the canon.
+
+### AI-illustration look
+
+Smooth-mesh-blob characters with no joint articulation, mid-2010s "modern flat" stock poses, unmistakably-Midjourney compositions with the symmetric default lighting. Hand-drawn SVG humans (the "doodle person with one eye larger than the other") fall under this — corporate-doodle is the late-2010s Slack/Figma marketing template, and the audience reads it as AI immediately.
+
+**Why it fails.** It reads as AI in milliseconds. The 2026 audience pattern-matches this faster than any other tell.
+
+**Fix.** Hand-build the illustration in pure CSS or SVG (Tier A or B in `hero-enrichment.md`). If you must generate, use the ArkaOS image pipeline (`/brand image-create`, ComfyUI) with reference images, asymmetric crop, and grain post-processing — never raw output. See `custom-craft.md` Tier E.
+
+### Invented metrics
+
+A stat-led layout, comparison row, or proof bar carrying numbers the user never supplied — "10× faster", "saves 5 hours per week", "trusted by 50,000+ teams", "99.9 % uptime", "+47 % conversion". The model reached for a stat to fill a stat slot and made one up.
+
+**Why it fails.** Audiences read invented stats as fast as they read invented testimonials. A page that lies on its proof bar can't be trusted on its claims either, and the AI tell is unmistakable: every fabricated number reads "this was generated, not written".
+
+**Fix.** Three options, in order of preference: (1) replace the number with `—` and a labelled grey block ("metric to confirm" or "stat pending"); (2) ask the user for the real number and pause the run; (3) rebuild the section without the proof slot — a stat-led macrostructure with no real stats is the wrong macrostructure. The number-shaped hole is honest; the fabricated number is slop. *(Slop-test gate 46.)*
+
+### Generic emoji as feature icon
+
+A feature card, value prop, step number, or pricing tier with `✨` `🚀` `⚡` `🔥` `🎯` `✅` rendered as the primary icon. The "sparkle hero" badge with a `✨` glyph beside the eyebrow. Emoji standing in for an icon library because the model didn't pick one.
+
+**Why it fails.** Emoji are typography of a sort, but they are not part of the page's typographic system — they're rendered by the OS and look different on every device, they break the icon's stroke voice (you've now mixed a Phosphor-style line icon with a Twemoji blob), and the choice is recognisably the AI default. Sparkle-emoji-as-AI-shortcut is the cliché of the 2024–2025 era.
+
+**Fix.** Pick a single icon library and ship it (`assets.md` names the canon). Or build a custom SVG mark. Or omit the icon entirely and lead with typography — most feature lists don't need icons. *(Slop-test gate 30.)*
+
+### Re-drawn UI chrome
+
+A fake browser bar (URL pill + traffic-light dots) wrapping a screenshot. A fake phone frame (rounded rectangle + notch + speaker slit) around a mobile mockup. A fake code-block window (mock title bar + close/minimise dots) wrapping a `<pre>`. A fake IDE chrome (file tabs + activity bar) around an editor screenshot. All hand-built in HTML/CSS or SVG.
+
+**Why it fails.** The user already has the chrome — their browser, their phone, their IDE all *are* chrome. Redrawing it in a page is like printing a photograph of a picture frame inside a real picture frame. The fakery is also bad: the URL is wrong, the dots aren't macOS dots, the notch is the wrong shape. Audiences pattern-match re-drawn chrome as "AI invented a UI that already exists" within a glance.
+
+**Fix.** Use a real screenshot wrapped in `<figure>` (with a hairline border at most). For phone mockups, use a transparent-PNG device frame from a vendor or a real product photograph — never a CSS-drawn one. For code blocks, use the system `<pre>` with a typographic frame (top rule + label + bottom rule), not a faked window-chrome. The page's job is to show content, not to imitate the OS. *(Slop-test gate 47.)*
+
+### Mid-render token improvisation
+
+A theme is selected at the top of the run, but the artifact contains inline colour values (`#5b6cff`, `oklch(74% 0.18 245)`, `rgb(...)`) or `font-family` declarations that aren't drawn from the token block. Or: the artifact ships with the theme's token set *plus* one extra hex tucked into a hover state, a focus ring, or a single border. The model picked the theme, then drifted.
+
+**Why it fails.** Token discipline is the difference between a system and a freestyle. Once a theme is locked, every colour and every font in the file must reference a named token (`var(--color-accent)`, `font-family: var(--font-display)`). Inline values are how cohesion erodes — by the third edit pass, the page has eight colours instead of three, and the editorial restraint that made the theme work is gone. Audiences don't see the inline value, but they feel the looseness.
+
+**Fix.** Every colour and every font in the artifact must come through `var(--token-name)`. If you need a value that doesn't exist as a token, add it to the token block first (`--color-accent-warm: oklch(...)`) and then reference it. Inline OKLCH or one-off hex values mid-render are not allowed. *(Slop-test gate 48. See also `departments/brand/references/uiux-knowledge-and-tools.md` §3, Design Tokens.)*
+
+### Wrap-to-two-lines clickable text
+
+A button label, nav link, footer link, breadcrumb, or CTA reads on two lines because the viewport got narrow and the label was long. Visually, the affordance now looks broken — readers can't tell whether the line break is intentional. Worst case: the second line is one word ("free", "more", "started"), which reads as a styling error.
+
+**Why it fails.** Clickable affordances are one-line objects. The reader scans the label, decides whether to click, moves on. A two-line label slows the scan, breaks the row's vertical rhythm (button height grows, sibling buttons stay the same), and signals "this page wasn't tested at this width". It's a responsive-discipline tell.
+
+**Fix.** In order of preference: (1) shorten the label — *"Get started free" → "Start free"*; *"Read the documentation" → "Read docs"*. Most CTA labels are too long. (2) Set `white-space: nowrap` on the affordance and let the parent flex container reflow. (3) Drop a non-essential nav item at narrow widths via `hidden=until-found` or `display: none`. (4) Collapse the nav into a sheet/menu under a threshold. *Never* let a primary CTA or nav link wrap. *(Slop-test gate 49. See `responsive.md` § Clickable text — never wraps.)*
+
+### Lottie shortcut
+
+Reaching for a LottieFiles community animation — the spinning logo, the checkmark draw, the loading spinner, the "loading dots" loop — when pure CSS or hand-built SVG would have produced it stronger and lighter.
+
+**Why it fails.** Lottie pulls were an AI-tool shortcut throughout 2023–2024; the audience now reads them as one. The 50–500 KB JSON file plus the runtime cost is a tax on a job CSS does in zero bytes.
+
+**Fix.** Build it custom. Spinning logo → CSS `@keyframes rotate`. Checkmark → SVG `stroke-dasharray` animated. Loading dots → CSS `@property` + `animation-delay`. Lottie is Tier F in the enrichment hierarchy — last resort, only for genuinely articulated character motion.
+
+### Three.js for a still object
+
+A WebGL hero where the 3D doesn't earn its place by being interactive. A stationary spinning thing the user can't touch, can't reorient, can't customise — just a model rotating because someone wanted "3D".
+
+**Why it fails.** The 100–300 KB Three.js bundle, the model, the textures, the GPU work — all for a thing that could be a static photograph or an SVG.
+
+**Fix.** If the user can't manipulate it, it doesn't justify Three.js. Use a still photograph or a hand-built SVG.
+
+---
+
+## Microinteraction tells
+
+These are the named tells of AI-generated *motion*. See `microinteractions.md` for the full catalogue and recipes.
+
+### `transition-all`
+
+Every property animating, including ones that should be instant (visibility, focus rings).
+
+**Fix.** Specify the properties. `transition: background-color var(--dur-short) var(--ease-out), transform 100ms var(--ease-out)`.
+
+### Universal `hover:scale-105`
+
+Every card lifts on hover, with no shadow change, no easing specified, no purpose.
+
+**Fix.** Pick one signal per element. A 1px translate, or a colour shift, or an underline thickening — never all four.
+
+### Bouncy overshoot easings on UI
+
+`cubic-bezier(0.34, 1.56, 0.64, 1)` and friends on buttons, modals, tooltips. Tasteless throwback.
+
+**Fix.** Reserve overshoots for genuine physical interactions (drag-and-drop release). For UI state, use `--ease-out` from `motion.md`.
+
+### Animated hover gradients
+
+Background gradient slides through colour space on hover.
+
+**Fix.** Cut. Or pick one colour shift, instant.
+
+### Cursor follower dots
+
+A trailing dot that lags behind the pointer.
+
+**Fix.** Cut.
+
+### Auto-rotating carousels with no pause
+
+WCAG 2.2.2 failure.
+
+**Fix.** Manual advance only, or pause-on-hover-and-focus, or autoplay disabled by default.
+
+### Celebratory success toasts
+
+"Done!" when the user just saved a thing they can see was saved.
+
+**Fix.** Silent success. Toasts only for failures, async actions whose effect isn't visible, and explicit confirmations the user will need.
+
+### Confirmation dialogs for reversible actions
+
+"Are you sure you want to delete this?" before a one-row delete.
+
+**Fix.** Optimistic delete + 5–10s Undo toast. Reserve the modal for irreversible destructive actions, and even then, type-the-name confirmation, not click-OK.
+
+### Tooltips with the same delay on hover and focus
+
+Both delay 800ms.
+
+**Fix.** Hover delay 800–1000ms. Focus delay 0ms. Different intents, different timing.
+
+### Focus rings that animate in
+
+The ring fades in over 200ms — keyboard users have no indicator at the start of the transition.
+
+**Fix.** Focus rings appear instantly. Always. Don't transition `outline` or `box-shadow` when the element gains focus.
+
+### Toasts that shift layout
+
+New toast pushes content down; dismissed toast lets it spring back.
+
+**Fix.** Stack at a viewport corner, fixed positioning. Existing toasts don't move when a new one arrives.
+
+### Universal scroll-triggered fade-up
+
+Every section fades in on intersection. The page never settles.
+
+**Fix.** One orchestrated entrance on first load. After that, content is just there.
+
+### Spinners that flash
+
+A spinner appears for 50ms while a fast action completes.
+
+**Fix.** Either delay-show the spinner (150ms before showing) or enforce a minimum visible duration (300ms once shown). Skeletons over spinners when the layout is known.
+
+---
+
+## Minor (small taste issues)
+
+### Straight quotes
+
+`"Hello"` and `'word'` in rendered text. A sign nothing was proof-read.
+
+**Fix.** Curly quotes: `"Hello"`, `'word'`.
+
+### Double-hyphen dashes
+
+`--` in body copy where an em-dash belongs.
+
+**Fix.** `—` (U+2014).
+
+### Three periods instead of ellipsis
+
+`...` in body copy.
+
+**Fix.** `…` (U+2026).
+
+### Placeholder names
+
+"Jane Doe", "John Smith", "Example User".
+
+**Fix.** Plausible placeholder names reflecting the audience, or pull from a seeded faker. "Maya Okonkwo", "Sam Tan", "Elena Ruiz".
+
+### Startup-cliché product names
+
+"Acme", "Nexus", "Pulse", "Unleash", "Seamless", "Supercharge".
+
+**Fix.** Name the thing concretely. If it's a demo, use a domain-specific placeholder — "Maple Weekly", "Ridgeline Inventory" — not abstract startup bingo.
+
+### `z-index: 9999`
+
+Arbitrary large z-values.
+
+**Fix.** Use the six-level named scale. See `layout-and-space.md`.
+
+### Every section padded the same
+
+Top padding, bottom padding, horizontal padding — all equal across every section.
+
+**Fix.** Vary. Tighten one, expand another.
+
+### 100vw widths
+
+`width: 100vw` on anything. Breaks on scrollbar-visible desktops.
+
+**Fix.** `width: 100%` with container padding.
+
+---
+
+## How `/brand ux-audit` should report
+
+For each finding:
+
+```
+[severity] Tell name — file:line
+  why it's a tell (one line)
+  → fix (one line)
+```
+
+Then:
+
+```
+Summary — N critical · M major · K minor
+Verdict — [ships as slop | reads as AI-generated | close, fix the minors]
+```

package/departments/brand/skills/design-review/references/critique-protocol.md

@@ -0,0 +1,169 @@
+# Critique Protocol — Isolated Dual-Review Design Critique
+
+> Derived from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0 — see `impeccable.LICENSE` and `impeccable.NOTICE` in this directory). Distilled and adapted for ArkaOS; changes from upstream are substantial (orchestration kept, CLI plumbing removed).
+
+## Purpose
+
+Resolve one stable target (a source file path over a dev-server URL — ports drift, paths do not), run two independent assessments, and synthesize a design critique the way a design director would deliver it. The chat report is the deliverable.
+
+## Hard Invariants
+
+- Assessment A (LLM design review) and Assessment B (deterministic detector + browser evidence) are BOTH required.
+- A and B MUST run as two isolated subagents whenever dispatch is available. Running them inline is "possible" but NOT permitted — it is a degraded run. Inline is allowed only when no subagent dispatch exists.
+- If you degrade for any reason, the report's FIRST line must be the banner: `⚠️ DEGRADED: single-context (<reason>)`. A silent degraded critique is a failed critique.
+- Assessment A must finish before detector findings enter the synthesis context. Detector output is deterministic, but it still anchors judgment.
+- A skipped detector is a failed critique run unless the detector is genuinely missing or crashes after a real attempt.
+- Viewable targets require browser inspection when browser automation is available.
+- Never claim a user-visible overlay or visual evidence exists unless the browser step actually produced it.
+
+## Orchestration — Two Isolated Subagents
+
+Dispatch two isolated review subagents (quality dispatches are exempt from subagent-discipline caps — independent review context is a correctness requirement). They MUST NOT see each other's output; do not show findings to the user until synthesis.
+
+- **Sub-agent A — Design review.** Reads relevant source files and visually inspects the live page when browser automation is available. Blind to detector output.
+- **Sub-agent B — Deterministic evidence.** Runs the deterministic design-slop detector (QG check `design-slop`, Wave 3) plus browser evidence. Blind to A's judgment.
+
+Rules of engagement:
+
+- Spawn A and B in parallel whenever dispatch is available. "Unavailable" means exactly one thing: no subagent dispatch is exposed in this session. It does not mean inconvenient, and never "faster inline".
+- If and only if dispatch is unavailable, fall back sequentially: finish and record Assessment A, then run Assessment B, then synthesize — and emit the degraded banner.
+- Whichever path was taken, declare it in the report header (see provenance below). Skipping isolation without the banner is the most common failure of this protocol.
+- If browser automation is available, each assessment opens its own fresh tab. Never reuse an existing tab, even if it is already at the right URL.
+
+## Assessment A: Design Review
+
+Think like a design director. Evaluate:
+
+- **AI slop** — would someone believe "AI made this" immediately? Apply the anti-slop doctrine and the register-specific slop tests (see `design-registers.md`).
+- **Holistic design** — hierarchy, IA, emotional fit, discoverability, composition, typography, color, accessibility, states, copy, edge cases.
+- **Cognitive load** — apply the working-memory rule and the 8-item checklist below; report checklist failures and any decision point with >4 visible options.
+- **Emotional journey** — peak-end rule, emotional valleys, reassurance at high-stakes moments.
+- **Nielsen heuristics** — score all 10 heuristics 0–4. Score against Nielsen's 10 heuristics — the squad's canonical source is [[Area 02 - Design]] and the ui-ux-pro-max plugin.
+
+Return contract: AI slop verdict, heuristic scores, cognitive load result, emotional journey notes, 2–3 strengths, 3–5 priority issues, persona red flags, minor observations, provocative questions.
+
+## Assessment B: Detector + Browser Evidence
+
+Run the deterministic design-slop detector (QG check `design-slop`, Wave 3) against the target markup, and gather browser evidence when the target is viewable and automation is available (fresh tab, screenshot, console/state observations on 3–5 representative pages for multi-view targets).
+
+Return contract: detector findings with counts, rule names, and file locations; browser observations if applicable; suspected false positives; skipped or failed steps with concrete reasons. Reuse B's detector findings in synthesis — do not rerun the detector in the parent unless B failed, was truncated, or omitted counts, rule names, or locations.
+
+## Synthesis — Combined Critique Report
+
+Synthesize both assessments into a single report. Do NOT concatenate. Weave the findings: note where the LLM review and the detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Present the full structured critique in chat — never a summary plus a link.
+
+### Report header provenance
+
+The report's first line MUST declare how the assessments ran, so a degraded run is never silent:
+
+- Dual-agent: `Method: dual-agent (A: <agent-id> · B: <agent-id>)`
+- Degraded: `⚠️ DEGRADED: single-context (<reason, e.g. no subagent dispatch exposed>)`
+
+### Design Health Score
+
+Present the Nielsen scores as a table (canonical heuristics source: [[Area 02 - Design]] + ui-ux-pro-max):
+
+| # | Heuristic | Score | Key Issue |
+|---|-----------|-------|-----------|
+| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] |
+| 2 | Match System / Real World | ? | |
+| 3 | User Control and Freedom | ? | |
+| 4 | Consistency and Standards | ? | |
+| 5 | Error Prevention | ? | |
+| 6 | Recognition Rather Than Recall | ? | |
+| 7 | Flexibility and Efficiency | ? | |
+| 8 | Aesthetic and Minimalist Design | ? | |
+| 9 | Error Recovery | ? | |
+| 10 | Help and Documentation | ? | |
+| **Total** | | **??/40** | **[Rating band]** |
+
+### Report sections, in order
+
+1. **Anti-Patterns Verdict** — start here. Does this look AI-generated? Give the LLM assessment (aesthetic feel, layout sameness, generic composition, missed personality) AND the deterministic scan summary (counts, locations, false positives flagged).
+2. **Overall Impression** — gut reaction: what works, what doesn't, the single biggest opportunity.
+3. **What's Working** — 2–3 things done well, specific about why.
+4. **Priority Issues** — the 3–5 most impactful problems, ordered. Each tagged `[P0–P3]` with: **What** (name it), **Why it matters** (user/goal impact), **Fix** (concrete).
+5. **Persona Red Flags** — 2–3 personas from the selection table below; name the exact elements and interactions that fail each persona, never generic descriptions.
+6. **Minor Observations** — quick notes on smaller issues.
+7. **Questions to Consider** — provocative unlocks: "What if the primary action were more prominent?" "Does this need to feel this complex?" "What would a confident version of this look like?"
+
+## Scoring Mechanics (0–4)
+
+Each heuristic scores 0–4: **0** = broken/absent, **1** = rare/mostly failing, **2** = partial with major gaps, **3** = good with minor gaps, **4** = genuinely excellent. Total out of 40:
+
+| Score Range | Rating | What It Means |
+|-------------|--------|---------------|
+| 36–40 | Excellent | Minor polish only; ship it |
+| 28–35 | Good | Address weak areas, solid foundation |
+| 20–27 | Acceptable | Significant improvements needed before users are happy |
+| 12–19 | Poor | Major UX overhaul required; core experience broken |
+| 0–11 | Critical | Redesign needed; unusable in current state |
+
+## Honesty Rubric
+
+- Be honest with scores. A 4 means genuinely excellent, not "good enough". Most real interfaces score 20–32.
+- Be direct. Vague feedback wastes everyone's time.
+- Be specific. "The submit button," not "some elements."
+- Say what's wrong AND why it matters to users.
+- Give concrete suggestions. Cut "consider exploring..." entirely.
+- Prioritize ruthlessly. If everything is important, nothing is.
+- Don't soften criticism. Builders need honest feedback to ship great design.
+
+## Issue Severity (P0–P3)
+
+| Priority | Name | Description | Action |
+|----------|------|-------------|--------|
+| **P0** | Blocking | Prevents task completion entirely | Fix immediately; showstopper |
+| **P1** | Major | Causes significant difficulty or confusion | Fix before release |
+| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass |
+| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits |
+
+Tie-breaker: "Would a user contact support about this?" If yes, it's at least P1.
+
+## Cognitive Load — Working Memory Rule + Checklist
+
+**Humans hold ≤4 items in working memory at once** (Miller's Law, revised by Cowan 2001). At any decision point, count distinct options/actions/facts the user must hold simultaneously: ≤4 manageable · 5–7 pushing the boundary (group or disclose progressively) · 8+ overloaded (users skip, misclick, abandon). Practical caps: ≤5 top-level nav items, ≤4 form fields per visual group, 1 primary + 1–2 secondary actions, ≤4 dashboard metrics without scrolling, ≤3 pricing tiers.
+
+Checklist — evaluate all 8:
+
+- [ ] **Single focus**: can the user complete the primary task without competing elements?
+- [ ] **Chunking**: information in digestible groups (≤4 items per group)?
+- [ ] **Grouping**: related items visually grouped (proximity, borders, shared background)?
+- [ ] **Visual hierarchy**: immediately clear what's most important?
+- [ ] **One thing at a time**: single decision at a time before moving on?
+- [ ] **Minimal choices**: ≤4 visible options at any decision point?
+- [ ] **Working memory**: no remembering info from a previous screen to act on this one?
+- [ ] **Progressive disclosure**: complexity revealed only when needed?
+
+Scoring: count failures. 0–1 = low load (good) · 2–3 = moderate (address soon) · 4+ = high (critical fix).
+
+## Persona-Based Design Testing
+
+Test through 2–3 archetypes; each exposes failure modes a single design-director lens misses. Walk the primary user action as each persona and report specific red flags — exact elements, not generic concerns.
+
+**1. Alex — Impatient Power User.** Expert with similar products; skips onboarding, hunts keyboard shortcuts, tries bulk/batch actions, abandons anything slow or patronizing. Red flags: forced tutorials or unskippable onboarding · no keyboard navigation for primary actions · slow unskippable animations · one-item-at-a-time workflows where batch would be natural · redundant confirmations for low-risk actions.
+
+**2. Jordan — Confused First-Timer.** Never used this product type; reads everything, hesitates before unfamiliar clicks, takes labels literally, abandons rather than figures it out. Red flags: icon-only navigation with no labels · technical jargon without explanation · no visible help or guidance · ambiguous next steps after an action · no confirmation that an action succeeded.
+
+**3. Sam — Accessibility-Dependent User.** Screen reader (VoiceOver/NVDA), keyboard-only, may use 200% zoom; needs 4.5:1 contrast, ARIA labels, heading structure, announced state changes. Red flags: click-only interactions with no keyboard alternative · missing or invisible focus indicators · meaning conveyed by color alone · unlabeled form fields or buttons · time-limited actions without extension · custom components that break screen-reader flow.
+
+**4. Riley — Deliberate Stress Tester.** Pushes past the happy path: empty states, long strings, emoji/RTL input, refresh mid-flow, multiple tabs; documents gaps between what the UI promises and what happens. Red flags: features that appear to work but silently fail · error handling that exposes technical detail or bricks the UI · empty states with no guidance · workflows that lose data on refresh or navigation · inconsistent behavior between similar interactions.
+
+**5. Casey — Distracted Mobile User.** One thumb, on the go, interrupted mid-flow, possibly on 3G; taps over typing, expects state preserved on return. Red flags: primary actions at the top of the screen (out of thumb zone) · no state persistence across interruptions · large text inputs where selection would work · heavy assets with no lazy loading · tiny or crowded tap targets (<44×44pt).
+
+### Persona selection table
+
+| Interface Type | Primary Personas | Why |
+|---------------|-----------------|-----|
+| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile |
+| Dashboard / admin | Alex, Sam | Power users, accessibility |
+| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity |
+| Onboarding flow | Jordan, Casey | Confusion, interruption |
+| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav |
+| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile |
+
+When the project carries real audience/brand context (project design system, brand descriptor), derive 1–2 project-specific personas from it — profile, behaviors, red flags. Never invent audience details; without real context, use only the 5 predefined personas.
+
+## After the Report
+
+Ask 2–4 targeted questions grounded in actual findings (priority direction among the found issue categories, design intent on tonal mismatches, scope: top-3 vs all, off-limits areas). Never ask generic "who is your audience?" questions; offer concrete options. If findings are trivial (1–2 clear issues), skip questions and go straight to a prioritized action list mapped to the issues, ordered by the user's stated priorities, then impact.