Design Intelligence

---
model_tier: inherit
name: design-intelligence
description: "Grounded design brief from the adopted corpus — style, WCAG-checked color tokens, typography, layout pattern, anti-patterns. Use on ui-design-brief or any which-style/palette/font/chart decision."
domain: engineering
personas:
  - frontend-engineer
workspaces:
  - engineering
packs:
  - frontend-design
token_budget_class: rich
trust:
  level: professional
install:
  removable: true
scope:
  write: []
  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
execution:
  type: manual
---

# design-intelligence

> The grounded source for frontend design decisions (ADR-061; first
> consumer of [`corpus-grounding`](../corpus-grounding/SKILL.md)). When the
> UI directive set's `design` step emits `@agent-directive: ui-design-brief`,
> consult this corpus FIRST and pre-fill the brief candidates — then the
> human confirms (`design_confirmed`). Corpus output is a **constraint
> set**, never final microcopy; the placeholder lock in
> `directives/ui/design.ts` is unaffected.
>
> **Boundary (council-locked):** `design.ts` stays a pure orchestration
> gate and never imports the engine — the corpus call lives HERE, in the
> skill layer, keeping the engine an optional dependency.

Corpus: 11 tabular CSVs under [`data/`](data/) (161-row `ui-reasoning`
decision map, WCAG-adjusted color token sets, 84 styles, 73 font
pairings, 25 chart rules, UX/react/mobile guidelines) + 16 prose
design-language specs ([`references/design-languages.md`](references/design-languages.md))
+ the 10-category pre-delivery checklist
([`references/design-rules-checklist.md`](references/design-rules-checklist.md)).
Provenance + licenses: [`ATTRIBUTION.md`](ATTRIBUTION.md); manifest:
[`data/manifest.json`](data/manifest.json).

## When to use

- The UI directive set emits `@agent-directive: ui-design-brief` (the
  design step found `state.ui_design` empty).
- Any pre-build selection question: which style / palette / font pairing /
  layout pattern / chart type / icon system fits this product.
- Stack-idiom lookup before writing UI code (`--stack` axis).

## Section index — load on demand

Load the reference file whose sections the task needs — never all of them by default:

- [`references/context-and-registers.md`](references/context-and-registers.md) — Cross-task design memory — read DESIGN.md / PRODUCT.md first · Register — brand vs product · Design Read — articulate intent before generating
- [`references/integration-mapping.md`](references/integration-mapping.md) — `MASTER.md` + page overrides ↔ `state.ui_design` (mapping) · Grounding the review/polish a11y gate (charts + contrast) · Stack guidance (`--stack` axis) · Diagram-type routing — route on the verb · Interplay (who owns what)

## Honesty / real-system grounding

When the brief maps to an official design system (Material Design, Fluent,
Carbon, Polaris, GOV.UK, shadcn, Tailwind UI, Radix, etc.):

0. **Canon grounding first.** If the brief names a system OR
   `components.json`/deps signal one (`@mui/material`, `antd`, `@fluentui/*`,
   `@carbon/*`, `@atlaskit/*`), pull
   [`docs/guidelines/design-canon.md`](../../../docs/guidelines/design-canon.md),
   surface the matching one-line summary, and **offer to fetch the live spec**
   before committing to the system's conventions — rather than improvising.
   The canon index is thin + lazy: do not load it for a generic, unnamed brief.
1. **Install the real package** — do not hand-recreate its CSS or components.
   Surface the install command for the project's package manager (the
   system's official package, e.g. the shadcn CLI or the `@mui/material`
   distribution) and link the canonical documentation URL.
2. **Never label an approximation as the official system.** If generating
   approximate CSS for a system the project does not yet depend on, label it
   explicitly: *"Approximation of Material Design elevation — not the official
   `@mui/material` package; install the package for production use."*
3. **If no official system is relevant:** pick a deliberate creative direction
   (see Design Read above); never fall back to an unnamed generic aesthetic
   (per `source-discovery-gate`: real source before guessing).

**Grounding precedence** (consistent with `brand-source-of-truth`): consumer
brand tokens > confirmed session decisions > named canon
([`design-canon.md`](../../../docs/guidelines/design-canon.md)) > generated
corpus. Canon is a gap-filler, never an override of a registered brand value.

## Procedure: Produce a grounded design brief (`ui-design-brief` rebound)

1. **Ground** (one call — engine runs the manifest's plan
   product → style → color → landing → typography with decision rules):

   ```bash
   ./scripts-run <skills-root>/corpus-grounding/scripts/ground ground \
     --manifest <skills-root>/design-intelligence/data/manifest.json \
     "<product type + mood + platform>" --json
   ```

2. **Translate selections into the brief** for `state.ui_design`:
   - `layout` ← landing/pattern selection (`Section Order`, CTA placement)
     + the reasoning rule's `Recommended_Pattern`;
   - `components` ← audit reuse first (`existing-ui-audit` inventory wins
     over corpus suggestions — never propose a new component the audit
     already has);
   - `states` ← required five (`empty/loading/error/success/disabled`),
     styled per the selected design language;
   - `microcopy` ← **agent-written, final strings** — the corpus never
     supplies microcopy;
   - `a11y` ← color selection's contrast-adjusted token set + the
     checklist's CRITICAL rows + `accessibility-auditor` method;
   - style/typography/effects/anti-patterns ← the grounded selections
     verbatim, with alternatives listed.
3. **Always surface** the grounded output's `confidence` + `evidence_gap`
   lines in the brief summary — the user signs off on what the corpus
   could NOT support, not only on what it could.
4. On `design_confirmed: true` the directive engine advances; revisions
   loop back here.

### Font delivery columns — which one is the answer

`font-pairings-reference.csv` carries three delivery-adjacent columns and they
are **not** interchangeable. This is the arbitration between them, so the file
and its sibling `data/stacks/nextjs.csv` (row 22: a font-CDN `<link>` sits in
that row's **Don't** column) no longer read as opposite instructions:

| Column | What it answers | Status |
|---|---|---|
| `Google Fonts URL` | *where do I find / verify this font?* | discovery + availability check |
| `Self-Hosted Route` | *how does it get onto the page?* | **the default answer** — `@fontsource/*` package ids derived from the row's own Google-Fonts families; two rows name a foundry file instead (Fontshare pairs with a Google alternative) |
| `CSS Import` | the third-party CDN `@import` | **opt-in only** — emitting it transmits the visitor's IP to the third party; policy owner is [`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md) § Asset & imagery discipline ([`ADR-205`](../../../docs/decisions/ADR-205-webfont-delivery-ownership.md)) |

Per-stack route resolution (Next / bundler / asset-pipeline / plain) lives in
[`typography-system`](../typography-system/SKILL.md) § Delivery — one table, not
two.

### Font fallback (no google-fonts index — by design)

The 745 KB Google-Fonts index was rejected (ADR-061 §8): it duplicates a
public API. When a requested font is outside `font-pairings-reference.csv`'s 73
pairings: query `https://fonts.google.com/specimen/<Family>` (or the
`webfonts` API) for metadata, OR propose the nearest curated pairing and
say why. Never invent pairing metadata.

## Output format

1. Grounded brief candidates per `state.ui_design` slot (layout,
   components, states, microcopy placeholder-free, a11y) — selections
   cited per corpus row.
2. The grounded output's `confidence` label + every `evidence_gap` line,
   verbatim, in the brief summary.
3. Alternatives list per domain so the human can swap before
   `design_confirmed`.

## Do NOT

- Do NOT let the corpus write microcopy — it supplies constraint sets;
  final strings are agent-written (placeholder lock stays in force).
- Do NOT import the engine into `directives/ui/design.ts` — council
  boundary; the corpus call lives in this skill layer.
- Do NOT propose a new component the `existing-ui-audit` inventory
  already covers — audit findings outrank corpus suggestions.
- Do NOT hide low confidence — the user signs off on the gaps too.

## Gotchas

- Corpus grounds **pre-action selection** — do not use it as mid-task
  reference (open `references/` instead) or as a validator (rules own that).
- Empty result ≠ error: surface the evidence gap and proceed on priors.
- Keep queries product-shaped ("fintech dashboard", "luxury e-commerce
  mobile") — the detect map routes generic words to `style`.

## Anti-slop discipline

Before finalizing any design brief, cross-check against
[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
— especially the Color (C1–C5), Typography (T7–T8), and Layout (L1–L2) sections.
If the grounded corpus selection lands on a pattern in the catalog, either invoke
the override condition or adjust the selection.
For typography this is **a field, not a memory test**: a
`font-pairings-reference.csv` row whose heading or body font is a T7 overused-AI
default carries it in its `AI-Default Flag` column (`T7:<font>`; 15 of 73 rows) —
read the field. An empty flag means the row carries no T7 font, so a pairing is
never "flagged by association" (Poppins + Open Sans, the example most often
cited as flagged, carries none). T8 (single typeface for everything) needs no
column: it is `Heading Font == Body Font` on the row. A flag is a visible
conflict to resolve, never a ban — the catalog's override condition still
applies. Run the AI-slop originality
self-test (catalog § "The AI-slop originality self-test") on the chosen aesthetic
direction before emitting `design_confirmed`.

## Why this skill is rich

This skill carries 11 tabular CSVs (161-row UI-reasoning decision map,
WCAG-adjusted color token sets, 84 styles, 73 font pairings, 25 chart rules, UX/
react/mobile guidelines) plus 16 prose design-language specs and a 10-category
pre-delivery checklist. Agents need to see the full corpus to make grounded
selections — condensing to a summary destroys the evidence trail ("corpus
row 47 justifies the palette choice") that the skill's output contract requires.
Compressing the 16 design-language specs into fragments makes the style
selection unreproducible and audit-unfriendly.

## Policies

- Upstream MIT + Apache-2.0 obligations: [`ATTRIBUTION.md`](ATTRIBUTION.md).
- Refresh: quarterly per the manifest; bump `upstream.last_checked` on
  every refresh (ADR-061 §6).