Reports

The state of machine-readable design.

Two conventions settled in under two years: a context file at the project root, and a protocol for serving context on demand. Design has not caught up to either.

The context file became a convention

A markdown file at the project root, read automatically on entry, is now how coding agents receive project context. AGENTS.md is the cross-tool form, and every major editor reads something shaped like it. The convention arrived faster than most standards do because it required no coordination: one file, plain text, no schema to ratify.

What lands in those files is overwhelmingly engineering context. Build commands, directory maps, test invocations, conventions. Design context is either absent or reduced to a sentence asking the agent to match the existing style.

Serving beat shipping

MCP moved context from something you copy into something you query. That matters more for design than for code, because code is already in the repository the agent can read. Design decisions are not. They live in a design tool, a documentation site, and the heads of two or three people.

A protocol for asking a question mid-task is the right shape for that problem. The gap is not the transport. It is that most design systems have nothing structured to serve.

What is still missing

• Usage rules alongside values. Most token exports carry the what and drop the when.
• State coverage as data. Empty, loading, error, and disabled are documented in prose, if at all.
• The reasoning. Agents inherit decisions without the constraint that produced them, so they cannot tell which ones are safe to break.
• A contract that survives a version bump, so a pinned project keeps resolving.

What we expect next

The design system stops being a site people visit and becomes a service tools query. The documentation stays, because humans still edit the thing. The center of gravity moves to the served form, and the question a team asks about a design system shifts from whether it is adopted to whether it is readable.

Method

This is a read of public conventions and tool documentation as of August 2026, not a survey. It reports what the conventions look like, not how many teams follow them. When we run a survey with real sample sizes, the numbers land here and this note gets replaced.