# Outlex Design Precedence v3.1

Version **v3.1**, dated **14 September 2026**. This file states one thing: which instruction wins when two design sources disagree, what each layer is and is not allowed to override, the brief every substantial design request needs before any composition starts, how planning, building, and review are separated, and what a machine check can block versus what needs a human look. The same text (condensed) opens `brand/agents-v3.html` as a new Section 00, so an agent following the fetch-routing table sees it before anything else.

---

## 1. The order

**Current founder correction, then live canon (`design.outlex.ai`), then project adapter (the consuming repo's own design rules), then surface-specific skill.**

1. **Current founder correction.** A correction Guilherme states in the current conversation, or the most recent dated entry in `brand/founder-corrections.md`, outranks everything else, including a numbered rule in `tokens/PRINCIPLES-v3.md` that has not yet caught up to it. If it contradicts a published rule, follow the correction and log the conflict; do not silently apply the old rule.
2. **Live canon.** Everything served from `design.outlex.ai`: `brand-v3.md`, `GRAMMAR.md`, `GRAMMAR-v3.md`, `tokens-v2.css`, `tokens-v3-gravity.css`, `tokens/PRINCIPLES-v3.md`, `brand/compositions-v3.md`, `brand/imagery-v3.md`, `brand/taste-v3.md`, this file. This is the second-highest authority: it wins over a project's own local design docs whenever they conflict, because it is the one place every project is supposed to converge on.
3. **Project adapter.** A consuming repo's own design instructions (for example `mvp2/CLAUDE.md`'s Design Hard Stops, `DESIGN_DIRECTION.md`, a repo's migration-state notes) exist to say *where a specific surface currently stands* (migrated or not, V7 versus foundation versus Gravity). They never invent a new visual rule the live canon doesn't have; they only say which of the canon's layers currently applies to which surface.
4. **Surface-specific skill.** A skill covering one output format (email, slides, product screenshots, video) translates the canon's rules into that format's mechanics. A skill's own formatting convention never overrides a canon rule; if a skill and the canon conflict on substance (not just mechanics), the canon wins and the skill needs a fix.

## 2. What each layer may and may not override

| Layer | May override | May never override |
|---|---|---|
| Current founder correction | anything below it, for its stated surface and date | nothing, it is the top of the stack |
| Live canon | project adapter, surface skill | a current, dated founder correction; the hard nos in `tokens/PRINCIPLES-v3.md` § Hard nos and `brand-v3.md` §19 |
| Project adapter | surface skill, within its own repo | live canon on substance; it may only narrow (say which migrated surface uses which layer), never widen or contradict |
| Surface-specific skill | its own format's mechanics | any rule from a layer above it |

A migration-state note ("this surface is still V7") is not a licence to introduce new V7-only visual rules; it only says which existing, already-canonical layer (V7 legacy, foundation, or Gravity) governs that surface today.

## 3. The mandatory structured brief

Every substantial design request, a new page, a new hero, a new campaign asset, a redesign of an existing surface, starts with a structured brief before any composition work begins. Use `grilling` or an equivalent structured interview to fill these fields; do not start laying out a page from a one-line request.

| Field | What it answers |
|---|---|
| Audience | Who sees this, specifically (not "startups"; "a Series-A COO closing a data-room request") |
| Pain | The real moment of friction this addresses today |
| Desired action | What the viewer does next, concretely |
| Promise | The one claim this surface makes, that it can back up |
| Story | The one buyer story running through the whole composition |
| Product proof | Which real product moment, screenshot, or photograph proves the promise |
| Emotional tone | What the viewer should feel, in plain words |
| Baseline | The live surface (or nearest comparable) this has to beat, side by side |
| Reference mechanics | The one or two mechanics borrowed from `brand/taste-v3.md`'s great wall, named explicitly |
| Required assets | Photography, product crops, icons, and their registration/rights status |
| Motion opportunity | Where motion earns its place, or "none" |
| Constraints | Brand hard stops, accessibility, locale, technical limits |
| Success test | How the founder (or a calibrated reviewer) will judge this before ship |

A request missing these fields is incomplete, not merely terse; fill them before composing, not after.

## 4. Planner, builder, reviewer: separated roles

Design work here has three distinct roles, and they do not collapse into one pass by the same untracked reasoning:

1. **Creative planner**: fills the structured brief (§3), defines story, composition, interaction, imagery, and the borrowed mechanics, before any code or pixels exist.
2. **Builder** (frontend builder, product-screenshot specialist, image producer, email designer, slide designer, per surface): builds exactly the approved direction from the planner's brief. A builder does not re-plan mid-build; a material change in direction goes back to the planner.
3. **Independent visual reviewer** (visual critic, accessibility reviewer, performance reviewer): compares the rendered result against the live baseline and the approved reference wall, and reports a score, not a fix. The reviewer did not write the plan or the code, so its comparison is not correlated with the builder's own judgment of its work.

Full agent roster, model, inputs, authority, and handoff per role is tracked separately in the design-skill consolidation (plan §14 step 7); this file states the separation of duties, and that work states the concrete agent definitions.

## 5. What CI can block versus what needs a human score

**CI blocks automatically** (a check that fails the build or the PR, no judgment call): contrast ratios below WCAG AA, an image used without a registry entry, a prohibited treatment (pure black, banned gradient use, sparkle-on-AI, amber-as-AI, `transition: all`, a hardcoded hex where a token exists), a known accessibility defect (missing alt text, no reduced-motion fallback, sub-44px touch target), and token drift (a value that doesn't match the canon's token files).

**Needs rendered comparison and a calibrated human score, never a machine check**: originality (does this look like a template, or like other AI-made sites), composition (fewer elements, each placed with intent), emotional impact (does it read as a real moment, not a staged concept), product storytelling (does the product proof land without extra explanation), and overall polish (craft details at the level the live site sets). These five are the categories the founder has actually scored candidates on (`brand/taste-v3.md` §3); an agent's self-score on them is not evidence of founder acceptance (`confirmed-design-learning.md` § All Outlex visual surfaces: "agent scores, clean scans and source checks do not establish founder acceptance").

Rule of thumb: if the answer is a fixed number or a boolean, it is a CI check. If the answer requires putting two renders side by side and deciding which one feels better, it is a reviewer's job, and ultimately the founder's.