E03_Specific_References_Beat_Adjectives

Why "Lecture Handout" Beats "Modern and Clean"

The strongest DESIGN.md files are the ones whose Do's and Don'ts sections are the shortest. This sounds backwards. It is not. The reason is the format's load-bearing idea, and once you see it, the entire format snaps into focus.

Key Takeaways

• A specific reference — "a 1970s graduate lecture handout" — is a compressed specification the model already knows how to expand. An adjective list — "modern, clean, trustworthy" — is a region the model has to average over.
• The negative constraints in a design arrive for free when the reference is specific enough. The Do's and Don'ts section is a belt-and-suspenders for weakly-described designs, not a separate specification layer.
• The motion example in PHILOSOPHY.md shows the format's stance on extensibility: motion tokens are added without a spec change, because the spec is the prose, not the token vocabulary.
• This is why the YAML schema is small. A small schema forces the prose to do the heavy lifting, and the prose is the layer the model is actually good at.

The Sentence That Starts Everything

There is one sentence in PHILOSOPHY.md that I have been circling back to since I first read the repository. It is buried in the second section, after the framing. The repository's authors do not call it out as the load-bearing claim, but the rest of the file is consistent with it, and the three example DESIGN.md files all behave as if it were true.

"A design that references 'A 1970s graduate lecture handout in the tradition of an old and established university' evokes a complete world: the one color of ink, the generous margins, the serif set at a reading size, and the absence of decoration. That single sentence carries more useful information than a dozen metric values. It carries the reasoning behind the values."

That is the entire argument. I want to dwell on it for a moment, because the sentence is doing a lot of work, and it is the kind of sentence that reads as obvious in retrospect and as completely non-obvious the first time you encounter it.

What A Specific Reference Does

A specific reference is a name. "A 1970s graduate lecture handout" is a name. The model has seen many such handouts in its training data, and it knows what they look like: a single color of ink, generous margins, a serif at a reading size, no decoration. The model also knows what a handout is not: it is not a magazine cover, it is not a webpage with rounded corners and a hero moment, it is not a Substack post with an italic standfirst. The model knows this. The reference names it.

The model, given the reference, will produce a design that matches the reference. The design will be consistent with other designs produced from the same reference, because the reference is a single point in design space. The design will carry the implicit constraints of the reference — no glow, no gradient, no italic standfirst — without the prose having to list them. The list is redundant. The reference is the list.

The adjective list is the opposite. "Modern, clean, trustworthy, premium" is not a name. It is a region. The region contains many designs: a Material You card, an iOS settings panel, a Stripe landing page, a Linear modal. The model has to pick a point in the region. It will pick differently every time. The constraints the user wanted — the *specific* design language, the specific composition — are not in the list, because the list is a list, not a name.

I started this analysis expecting the prose philosophy to be aesthetic preference, a "write beautifully" suggestion. It is not. It is load-bearing engineering advice. The format's authors are telling you, in the form of a writing recommendation, that the model needs a name to render consistently. Adjectives do not give the model a name. References do.

graph LR
    subgraph REGION[Adjective Region: "modern, clean, trustworthy"]
        A1[Material You card]
        A2[iOS settings panel]
        A3[Stripe landing]
        A4[Linear modal]
    end
    subgraph POINT[Specific Reference: "1970s lecture handout"]
        B1[Serif at reading size<br/>Generous margins<br/>One ink<br/>No decoration]
    end
    REGION -.model averages.-> X[Underspecified design<br/>Drifts between sessions]
    POINT -.model expands.-> Y[Specified design<br/>Consistent across sessions]
    style REGION fill:#fef3c7,color:#78350f
    style POINT fill:#1A1C1E,color:#F7F5F2
    style X fill:#fecaca,color:#7f1d1d
    style Y fill:#d1fae5,color:#065f46

The two starting points. The model has to make a choice from the region. The model only has to render the point.

The Do's And Don'ts Section Is A Diagnostic

The Do's and Don'ts section in the spec is the eighth canonical section. It is where a design system is supposed to list its prohibitions. The README's example is the standard "use primary color only for the single most important action; don't mix rounded and sharp corners; maintain WCAG AA contrast; don't use more than two font weights on a single screen" content. The PHILOSOPHY.md file includes a worked example from a fictional "Technical Handout" design system, and that example is the most useful thing in the entire repository. The example's Do's and Don'ts list is fourteen lines long. The list includes things like "Don't add a hero moment to the title page," "Don't reach for an italic standfirst," "Don't use Bold. Anywhere," "Don't introduce dark mode, gradients, glows, glass surfaces, drop shadows, or rounded corners."

Read that list. The list is a *negative specification*. The list is the prohibitions that, if removed from the design, the design is no longer a lecture handout. The list is what the design has to *not be* in order to *be* the reference.

The repository makes a strong claim about this. The claim is that a specific reference carries its restrictions *automatically*. A model that knows what a lecture handout is already knows it does not have a hero moment, does not have a standfirst, does not use bold, does not have dark mode. The model does not need to be told. The list, then, is *redundant* for a well-described design.

This is the paradox I flagged in the chapter's hook: the strongest DESIGN.md files are the ones whose Do's and Don'ts sections are the *shortest*. A short list is a signal that the reference did the work. A long list is a signal that the reference did not, and the prohibitions are picking up the slack.

You are reviewing a teammate's DESIGN.md. The Brand & Style section reads "modern, clean, trustworthy." You scroll to Do's and Don'ts. It is fourteen lines long. You are about to have a problem. The reference is vague; the list is doing the work; the model will average over the adjectives and ignore the prohibitions it can. The result will be the same drift problem from Chapter 0, but now with a longer document.

The Motion Example Is The Deepest Argument In The File

PHILOSOPHY.md includes a worked example of how to add motion tokens to a DESIGN.md without changing the spec:

## Motion

motion: feedback: 120ms content: 250ms easing: 'cubic-bezier(0.2, 0, 0, 1)'

Transitions are quick and mechanical. Nothing bounces, nothing overshoots, nothing lingers. State changes should feel like a light switch, not a door closing.

- Interactive feedback (hover, press, toggle): {motion.feedback}, always {motion.easing}.
- Content transitions (page, panel, modal): {motion.content}, same curve.
- Nothing in the UI animates longer than 300ms. If something takes longer, cut it.
- Respect `prefers-reduced-motion`: all durations collapse to 0ms.

The example is striking because the motion key is *not* in the schema. The five-group schema is colors, typography, rounded, spacing, components. There is no motion group. The example still works. The linter will accept the unknown top-level key (because the consumer-behavior table in the spec says "Unknown section heading: preserve; do not error"). The prose describes the tokens, the model can use them, and the design system has motion.

The example is the format's stance on extensibility, made concrete. The format does not standardize motion. It does not standardize iconography, or elevation, or text casing, or paragraph measure. It does not standardize the things where one team's design system is structurally different from another team's. The format standardizes the five groups, the section order, the reference syntax, and the linter. Everything else is up to the prose.

This is the format's deepest design choice, and it is the one that makes the smallness of the schema coherent. The schema is small because the schema is the minimum. The prose is the rest.

The Counter-Intuitive Conclusion

I went into this chapter expecting to argue that the prose philosophy was a stylistic preference. I came out arguing that it is the *only* reason the format is shaped the way it is.

The smallness of the schema (Chapter 2) is not a constraint imposed on the format by the maintainers' taste. It is a *consequence* of the prose philosophy. If the schema had a hundred groups, the prose would not have to work. If the prose did not have to work, the references would not have to be specific. If the references did not have to be specific, the Do's and Don'ts section would be doing the work. If the Do's and Don'ts section is doing the work, the format is just a less-good version of a Tailwind config.

The five groups, the reference syntax, the depth limits — they exist *because* the format bets on prose. The bet is that the model is good at expanding a reference and bad at expanding a list. The format's shape follows from that bet.

The repository's own PHILOSOPHY.md says, in a single sentence near the top, almost as an aside:

"DESIGN.md captures how a design looks, feels, and behaves. The prose is where the design lives. Everything else in the document exists to support it."

That sentence, plus the lecture-handout paragraph, is the entire argument. The format is a wrapper for a piece of writing. The wrapper is small on purpose.

Where This Leaves Us

We have a two-layer document (Chapter 1), with a small token schema (Chapter 2), built around a prose-first philosophy that asks the design system author to write references, not adjective lists. The format is shaped, end to end, around a single bet: that the model is good at expanding names and bad at expanding regions.

The next chapter closes the loop. The CLI is what operationalizes the bet. The linter is what enforces the parts of the format that the model cannot enforce itself. The exporters are what make the format useful in the ecosystems teams already use. And the alpha status is the open question: the bet is in the file, but the file is alpha, and the most interesting question is not what is shipped but what is not.

---

References:

• PHILOSOPHY.md — full text
• docs/spec.md — Do's and Don'ts section, consumer behavior table
• examples/atmospheric-glass/DESIGN.md — a specific-reference design system
• examples/paws-and-paths/DESIGN.md — a different specific-reference design system
• examples/totality-festival/DESIGN.md — a third specific-reference design system

---

A small schema, a small resolver, a prose-first philosophy. The next chapter is the proof: a CLI that turns all of it into something an agent can run.