# Design GL

**Design GL (Design GuideLines) — a lightning-fast, evidence-based design and UI auditor for AI coding agents, served as an MCP server and API.**

> **Status: pre-release.** This repository holds the open client pieces that exist today: the wire
> contract and the privacy-preserving collector core. The CLI, the MCP bridge, the agent plugins and
> the hosted audit service are not released yet. Nothing here audits a page on its own.

[Русская версия](README.ru.md)

## Why

Coding agents ship interfaces that pass tests and still look wrong: spacing drifts off the scale,
icons sit a few pixels off the text they label, hover and focus states are missing, motion stutters,
and the same fonts and decorations appear on every project. Prose guidelines don't stop it, and vision models miss most of it: on the DiffSpot benchmark
(arXiv 2605.29615, May 2026) the best of 13 models finds 40.7 % of real visual changes. Design GL measures the rendered page instead and returns short,
fixable findings.

## How it works

- **Your browser measures, our server judges.** The open client renders your page locally with
  Playwright at six widths and in its interactive states, and measures geometry, computed styles,
  glyph metrics, contrast and motion.
- **Measurements leave your machine, not your page.** What travels is numbers, enumerated values
  and keyed hashes under a closed schema: no page text; element ids are dropped; class names
  outside a design vocabulary of 379 words (such as `btn` or `col-md-6`) are hashed with your project's
  key; URLs keep the origin and a hashed path, the query is dropped. Your design-token names and
  the browser's user-agent string are sent as they are.
- **Rules are evidence-tiered.** Every rule states whether it rests on a standard (WCAG), on
  published research, on design-system consensus, or on craft judgement. Only rules of the first
  three kinds may block an agent, and only where the rule is no stricter than its source; craft
  rules are advice.
- **Your project's own scale, not one house style.** Findings are expressed in your tokens.

## What is in this repository

| Path | What |
| --- | --- |
| `packages/schema` (`@designgl/schema`) | The wire contract: the measurement payload, findings, the rule-id format and the DTCG token input, as strict zod schemas that run without code generation in Cloudflare Workers. |
| `packages/collector` | The client-side sanitizer and payload builder: hashing, the byte budget, DTCG normalisation. |
| `tools/` | Repository guards (closed paths and ids, commit trailers, secrets) with self-tests, and the mutation run for the sanitizer. |

Development: Node ≥ 22.12, pnpm; `pnpm install`, then `pnpm -s check` (typecheck, lint, tests with
100 % coverage).

## Privacy

The payload schema is closed: unknown fields are rejected. A test fixture full of personal data
(names, emails, labels, placeholders, token descriptions) must produce a payload with none of it,
and a mutation run checks that the sanitizer's defences are each covered by a failing test.

## Sources & thanks

Design GL would not exist without the people who taught generations of designers to see. We are
deeply grateful to Don Norman; Josef Albers, Yale University Press and the Josef & Anni Albers
Foundation; Josef Müller-Brockmann and Verlag Niggli; Robert Bringhurst; Ellen Lupton and Princeton
Architectural Press; Adam Wathan and Steve Schoger; Adham Dannaway; Steve Krug; Jenifer Tidwell,
Charles Brewer and Aynne Valencia; Rudolf Arnheim and the University of California Press; Colin Ware;
Edward R. Tufte and Graphics Press; Ilya Birman; Artemy Lebedev and Art. Lebedev Studio; Kirill Egerev;
Jon Yablonski; Artem Gorbunov and Bureau Gorbunov; Jakob Nielsen and the Nielsen Norman Group; Massimo
Vignelli and the Vignelli Center for Design Studies at RIT; Heydon Pickering and Andy Bell; the W3C Web Accessibility
Initiative; the teams behind Apple's Human Interface Guidelines, Material Design, Fluent, Carbon,
Spectrum, Atlassian, Polaris, Primer, Geist, Radix, Ant Design, SLDS, Paste, GOV.UK, USWDS, Pajamas,
Base Web and Orbit; and the researchers whose studies we rely on.

We read their work, learned from it and wrote every rule in our own words: nothing is quoted, and no
figures, examples or chapter structure are reproduced. None of these authors or publishers has
reviewed or endorsed Design GL.

## License

Apache-2.0. Design GL is not affiliated with or endorsed by Anthropic, OpenAI or Anysphere.