Gesso

A brand-neutral design grammar for coding agents. Drop it into any project so an agent produces coherent, intentional UI instead of the generic, interchangeable default it converges on.

Gesso ships as a DESIGN.md — the emerging open convention for giving agents persistent visual context, the way AGENTS.md gives them code conventions.

The idea: two layers, never fused

Most design tools ship one locked look, so every app built on them looks the same (the shadcn fate). Gesso separates the two things that get mistakenly fused:

• Grammar — how good design behaves. Brand-neutral, universal rules: spacing scale, radius steps, type hierarchy built from size + weight (not color), border/shadow discipline, motion, and explicit anti-patterns. The versatile base — it must work for a marketing page, a dense dashboard, and a consumer app alike. → grammar/

• Skin — who a project is. A project-specific identity (palette, personality, accent, typeface, imagery, voice) that sits on top of the grammar and overrides its values. Different every project. One ships as a polished, ready-to-use reference. → skins/default/

You can run the grammar alone (neutral, correct, a little plain) or pair it with a skin (personality). Writing your own skin is the point — see docs/writing-a-skin.md.

Quick start

# Drop grammar + the default skin into your project:
npx gesso-design init --target ./my-app

# Or pick a skin / write your own first:
npx gesso-design init --skin default --target ./my-app
npx gesso-design list

This writes two files into the target and points the agent at them:

• DESIGN.md — grammar + skin merged into one spec the agent reads before building any UI.
• design.tokens.css — the matching CSS custom properties for colors, type, spacing, radius, motion. Grammar defaults first, skin overrides after (the CSS cascade does the merge).

It also appends an idempotent pointer block to the target's AGENTS.md / CLAUDE.md so the agent consults DESIGN.md every time. Re-running is safe.

Validate

Gesso wires up Google's official DESIGN.md linter rather than reinventing it:

npx --yes @google/design.md lint DESIGN.md   # token refs, WCAG AA contrast, structure → JSON

npm run lint validates the grammar and the bundled skin; exit code 1 on errors, ready for CI.

Repo layout

gesso/
├─ grammar/              # Layer 1 — brand-neutral universal rules
│  ├─ DESIGN.md          #   spec-valid: tokens (front matter) + rules (prose)
│  └─ tokens.css         #   neutral primitives + the accent slot + gap slots
├─ skins/
│  ├─ default/           # Layer 2 — the reference skin (warm, accent-less)
│  └─ _template/         # copy this to start your own skin
├─ install/bin/gesso.mjs # the install command (merge + point the agent)
├─ examples/             # static showcase of grammar + default skin
├─ docs/
│  ├─ writing-a-skin.md
│  └─ gaps.md            # the 3 new capabilities, with open design work flagged
├─ package.json          # `gesso` bin + lint scripts wiring Google's validator
└─ LICENSE               # Apache-2.0 (matches the DESIGN.md spec)

See the live showcase: open examples/index.html in a browser.

What's new vs. the source reference

The grammar adds three capabilities the seed aesthetic lacked. The slots exist; some design semantics are intentionally left open (flagged, not silently invented) in docs/gaps.md:

1. Data-viz / chart palette — a categorical series set so charts read as one family (sequential/diverging ramps + color-blind safety: open).
2. Dense table mode — density tokens for data-heavy surfaces (reference component: open).
3. Accent slot — the grammar permits one hero color; the source brand forbade any. A skin may claim it or opt out (spend-the-accent rulebook: open).

Roadmap

This repo is the foundation: grammar + one reference skin + install path + validator wiring. Two larger pieces are explicitly v1, not here yet:

• Skin-derivation engine — auto-derive a skin from a short brief, instead of hand-authoring tokens.css.
• Visual self-verify loop — render the UI, compare against the DESIGN.md, and correct drift automatically.

How we work / contributing

• Two lanes. Design/content (skins, the open gaps in docs/gaps.md, prose rules) and backend/tooling (the gesso CLI, validator wiring, merge logic).
• Small, clearly-labelled commits. Discuss load-bearing changes before making them — especially anything that touches the grammar, which all skins inherit.

License

Apache-2.0. The bundled default skin's values were distilled from a real product aesthetic and generalized into a brand-neutral default; fonts are free analogs (Inter, Instrument Serif). Swap freely — that's what a skin is for.