Grammar v2 — the design taste specification

§Abstract

Grammar v2 is an open specification that decomposes brand design taste into 30 named axes across surface, palette, typography, emphasis, whitespace, voice, motion, and imagery.

It exists so that arguments about design — usually subjective, frequently circular — can be grounded in a shared vocabulary that machines and humans both speak. Every axis has an enumerated value set, a scoring scale (ordinal or nominal), and a documented extraction method. A brand, a generated webpage, or an LLM‑authored mockup can each be expressed as a vector over these 30 axes and compared point‑by‑point.

The intended audience is threefold: agents and LLMs that need a stable target schema for design output; design tools (linters, generators, brand systems) that want to declare conformance; and brand teams that need a portable, version‑pinned definition of their visual identity. If OpenAPI describes the shape of HTTP, Grammar v2 describes the shape of taste.

§Status & versioning

This document specifies grammar-v2.0.0, released 2026-05-17. The canonical machine-readable form lives at /schema/grammar-v2.json.

Semver policy

• MAJOR — an axis is removed, renamed, or its value set changes in a breaking way. Existing vectors require migration.
• MINOR — a new axis is added, or a new allowed value is appended to an existing axis. Existing vectors remain valid.
• PATCH — clarifications to rubrics, descriptions, or example sets. No effect on validation.

Implementations must pin to a specific major.minor in audit blocks. Computed weights and per-axis convergence priors are versioned separately in /api/weights.json.

§Conformance levels

A tool, brand, or service may declare conformance at one of four levels. Higher levels include everything from the levels below.

0. L0
   Declarative

   Tool or brand references Grammar v2 by URL. No machine-checkable claim about output — just a stated commitment to the vocabulary.
1. L1
   Producer

   Emits axis vectors that pass JSON Schema validation against grammar-v2.json. Values are syntactically valid; semantic accuracy not yet verified.
2. L2
   Producer + Validated

   Vectors are verified against a hand-graded reference set (the Golden Set). Inter-axis agreement above the published threshold.
3. L3
   Reference tier

   Hand-graded by maintainers. Anchors the calibration chain — all L2 implementations are evaluated against L3 vectors.

§The 30 axes

Each axis is identified by a dotted key (category.name), an enumerated value set, and a scale type. Distance scoring for ordinal axes uses c = clip(1 − |b − o| / (max − 1), 0, 1); nominal axes use binary match until a proximity matrix is published. Every row below is individually addressable via #axis-<key>.

§JSON shape

Every brand entry under /api/styles/<brand>.json includes a grammar field — a complete 30-axis vector keyed by category. Below is the verbatim shape from Stripe’s entry (an L3 reference-tier brand).

"grammar": {
  "surface": {
    "ground":    "white",
    "radius":    "4-6px",
    "borders":   "hairline",
    "shadows":   "subtle",
    "texture":   "mesh",
    "dark_mode": "none"
  },
  "palette": {
    "strategy":   "full-spectrum",
    "saturation": "balanced",
    "warmth":     "mixed",
    "accent_use": "pervasive",
    "contrast":   "high"
  },
  "type": {
    "pairing":        "sans/sans",
    "heading_weight": "medium",
    "body_size":      "regular",
    "display_scale":  "balanced",
    "tracking":       "normal"
  },
  "emphasis": {
    "mechanism":       "color",
    "cta_treatment":   "filled-gradient",
    "density_signals": "grouping-cards"
  },
  "whitespace": {
    "discipline":  "medium",
    "section_gap": "balanced",
    "element_gap": "medium"
  },
  "voice": {
    "archetype":       "engineer",
    "formality":       "conversational",
    "hedging":         "low",
    "sentence_length": "balanced"
  },
  "motion": {
    "budget":    "pervasive",
    "character": "smooth",
    "trigger":   "autonomous"
  },
  "imagery": {
    "strategy": "abstract"
  }
}

Live: /api/styles/stripe.json · Validation schema: brand-style-v2.json

§“Speak Grammar v2” badge

If your tool, brand site, or LLM output emits valid Grammar v2 vectors, you may display this badge. It is a single inline SVG with no external dependencies.

[![Speaks Grammar v2.0](
  https://tastehq.dev/badge/grammar-v2.svg
)](https://tastehq.dev/spec)

<a href="https://tastehq.dev/spec">
  <img src="https://tastehq.dev/badge/grammar-v2.svg"
       alt="Speaks Grammar v2.0" height="28">
</a>

§Implementations

Reference implementations maintained alongside the spec. All speak Grammar v2 natively.

• /eval The calibration surface. Compares judge outputs to the Golden Set and computes inter-axis agreement.
• /api/score Judge endpoint. Accepts a brief + URL, emits a scored vector with verdict, strongest and weakest axes.
• /scorer Browser UI for the judge endpoint. Paste a brief and a URL, get a scored Grammar v2 vector back.
• cli/ Python and Node CLIs. Local extraction, batch scoring, CI-ready exit codes.
• mcp/ Model Context Protocol server. Lets Claude, ChatGPT, and other agents query the catalog and spec.
• RFC-001 The motivating RFC. Why a grammar exists at all, what it replaces, and how it’s calibrated.