design-taste

What this skill does

# Design Taste Skill

## What this skill is

This skill is the visual quality bar for every build. It owns both the *taste* layer (foundations, archetypes, recipes, anti-patterns) and the *mechanics* layer (template contract, brand theming, BrandMark, light-mode mandate, header right cluster).

This skill is read by:
- **mitb-initial-agent** on the first task, after the agent has stated its vision and design tokens. design-taste is the implementation contract that turns the vision into a coherent app.
- **mitb-agent-prototype** and **mitb-agent-full-access** on subsequent tasks. The vision is already in the codebase by then; design-taste guides additions to match the existing visual language.

The first task is special — it sets the design language. Every task after that respects it. Both modes use design-taste; only the first build uses it to *establish* the system, and every later build uses it to *extend* the system.

## Reading order — fully read these before writing any tokens or components

The reference files are short and necessary. Do not skim, do not partial-read with `head`, do not skip:

1. `references/archetypes.md` — full archetype catalog, token sets, reference apps, typography pairings
2. `references/components.md` — exact recipes for every common component
3. `references/anti-patterns.md` — failure modes to scan for during and before completion
4. `references/mechanics.md` — template contract, brand theming, BrandMark, light-mode mandate, header rules

If any of these is unread when you start writing tokens, your output will drift from the system. The previous build (dental scheduler, April 2026) only read SKILL.md and partial archetypes.md and produced generic-dashboard output. Read all four references in full.

---

## A. Foundations — what good design feels like

These principles describe the qualities the build should have. They're abstract on their own; the system, patterns, and recipes that follow are how each principle gets implemented.

### 1. Visual balance

Most app screens are NOT centered hero pages. Content aligns left, scans top-to-bottom, with the focal element occupying the upper third or upper-left of the main content area. Asymmetric balance — a heavy element offset by a lighter cluster of supporting elements — reads as more sophisticated than centered symmetry, which is reserved for empty states, error pages, and onboarding.

A balanced layout has:
- **One focal point per screen.** The primary score, the day's plan, the active document, the highlighted record. One — not three.
- **Supporting elements that orbit, don't compete.** Secondary information sits to the side or below at lower visual weight (smaller, lighter, less color).
- **Negative space as a design element.** Empty space isn't unfilled — it's part of what makes the focal point feel focal.

### 2. Hierarchy

Hierarchy is how the user knows what to look at first, second, third. It's built from four levers — size, weight, color, spacing — and the rule is to use ONE, occasionally two, never four at once.

- **Size hierarchy:** primary number 32px, title 20px, supporting label 14px, metadata 12px. Four sizes total. A fifth means you're trying to differentiate something that doesn't deserve differentiation.
- **Weight hierarchy:** semibold (600) for primary numbers and headings, medium (500) for titles and emphasized labels, regular (400) for body. Three weights, used systematically.
- **Color hierarchy:** foreground (primary text), muted (secondary), subtle (tertiary). Three text colors. The brand color is reserved for action, not for hierarchy.
- **Spacing hierarchy:** larger gaps (32-40px) separate major sections; medium gaps (16-24px) separate cards within a section; small gaps (8-12px) separate elements within a card.

When two elements need to feel different in importance, change ONE lever — usually size or weight. Don't change all four. Visual noise comes from over-differentiation.

### 3. Restraint

Restraint is the signature of premium design. AI defaults toward the opposite — using brand colors everywhere, adding gradients, layering shadows, multiplying decorative elements. Each individually feels like "more polish"; together they feel like a discount template.

The single most important restraint rule: **the brand or accent color appears in roughly 8-10% of pixels — no more.** Primary buttons, the active state border, the score badge fill, maybe one or two focal accents. Body text is foreground. Icons are foreground or muted. Most surfaces are neutral.

Other restraint rules:
- **No more than one primary action per screen.** Two if absolutely necessary, with one clearly subordinate.
- **No more than one focal element per screen.** Other elements are supporting context.
- **No more than 2-3 colors in any chart.** Multi-colored bars and lines are noise.
- **No more than 4 type sizes total in the entire app.** Hard ceiling.
- **No drop shadows for elevation.** Use 1px borders. Shadows immediately read as bargain-template.

Restraint produces calm. Calm is what makes the user trust the app.

### 4. Rhythm

Rhythm is the consistent spacing and sizing pattern that makes the app feel like one designer made it. It comes from using a defined scale — radius scale, spacing scale, type scale — and never improvising values.

- **8px grid for spacing.** All spacing values are multiples of 4 (4, 8, 12, 16, 20, 24, 32, 40). Invisible to the user but felt in the regularity of the layout.
- **Generous default.** When in doubt about whether a gap should be 12px or 16px, choose 16px. AI defaults to dense layouts; override the default. Premium aesthetics breathe.
- **Consistent radius by hierarchy.** Cards use one radius, chips use another, badges use another. Same hierarchy = same radius. Don't mix.
- **Aligned baselines.** Text in the same row aligns vertically. Headings align with the icons next to them. Card content has consistent padding all around.

Rhythm is invisible when present and obvious when absent. It's what separates "looks fine" from "feels right."

### 5. Inline-first composition

This is the principle most often violated by AI builds. Cards are not the default layout primitive. They are an *exception* used when content needs emphasis, separation, repetition, or framing.

Default to inline content in the page body:
- A page title sits as text, not inside a card with a title bar
- A primary number sits as a large display element on the page, not inside a "metric card"
- A list of items can be a styled list with rows, not a grid of card tiles
- A form is field rows on the page, not a "Form" card

Use cards only when:
- **Emphasis** — this one element is the focal point and needs visual lift from its surroundings
- **Separation** — multiple unrelated content blocks need to be visually distinct
- **Repetition** — a list of equivalent things benefits from each one being self-contained
- **Framing** — a detail panel, modal, or overlay frames content for focused attention

A page that stacks one card after another for no reason — KPI card, today card, list card, secondary list card — is the dashboard reflex, and it's almost always wrong. Real apps inline most content and reserve cards for moments that actually need framing.

---

## B. System — how to encode visual language

The principles in Section A describe what the build should feel like. This section describes the mechanics.

### Core mandate: token-first, then archetype, then components

Every build follows this order:

1. **Pick or derive an archetype** based on the app's purpose, customer, and feeling
2. **Declare the complete token set** in `app.css` — colors, typography, radius, borders, elevation, spacing
3. **Build every component as a consumer of those tokens** — no hardcoded hex values, no improvised type sizes, no ad-hoc radii

This single ordering eliminates the most common AI design failures: invented colors, mixed radii, accidental new type sizes, ad-hoc status colors. The constraint pro