Repository navigation
Duplicating design facts in front matter and markdown body #16
Description
Activity
- changed the title
[-]# Duplicating design facts in front matter and markdown body[/-][+]Duplicating design facts in front matter and markdown body[/+]on Apr 22, 2026 Hey @torbenanderson. This is a good idea and I've been thinking about it a lot too. I'm drafting up a few ideas I have and I'll share them here over the next day or so.
Reacted by Michael GregoireReacted by Mr. TorbenAwesome - happy to collaborate as needed @davideast :-)
- added a commit that references this issue
on May 10, 2026 The root cause is that the spec doesn't say what prose must never do.
The concern here is real and well-observed. Working with design.md at scale (we've been building a corpus of ~5,000 files for a design history project), we ran into this same tension and found a resolution that required no format change.
The spec currently says "tokens are normative, prose provides context" — but it doesn't say prose must never restate token values. That one unspoken rule is what causes drift. When an author writes #858585 in prose because "that's what the token is", they're treating prose as a second token store. The fix isn't to collapse the layers; it's to be explicit that prose should interpret tokens by name and register, never by value.
The practical rule: prose references tokens by name or describes their perceptual register — it never contains their literal value. You write "the dark-muted tone creates separation without contrast" — not #858585. The YAML is the record; the prose is the reading. If the spec states this clearly, drift becomes structurally impossible without any format change.
The linter enforcement is straightforward: flag any literal token-shaped value (6-digit hex, px/rem dimension) appearing in the markdown body outside of code blocks. That's a single rule that catches the failure mode before it ships — and it fits cleanly alongside the existing broken-ref and contrast-ratio rules.
On the case for markdown-primary: for a single-team workflow this might work well. But the diff and export commands depend on machine-parseable tokens in a predictable location. Once you're querying across multiple files, the YAML layer is what makes the format queryable, not just readable. Collapsing it would remove the capability the format is most distinctively useful for.
Proposed spec addition (something like):
The markdown body must describe design intent, context, and aesthetic rationale. It must not contain literal token values — no hex colors, no px/rem dimensions, no numeric font sizes. These belong exclusively in YAML front matter. Prose references tokens by name (e.g. "the primary color", "body-md type scale") or describes their perceptual register. Code blocks showing usage examples are exempt from this rule.And a proposed linter rule: prose-token-leak / warning / Flags literal token values (hex, dimension) found in markdown body text or tables.
Happy to draft spec language or a linter implementation if that would help move this forward.
Reacted by maxtamAQ and Zach ShallbetterFirst of all, thanks for building this! This is such an important piece of the future of design!
A couple of unstructured thoughts on building a DESIGN.md for a greenfield new SaaS app:
- "DESIGN.md gives agents a persistent, structured understanding of a design system" implies DESIGN.md is not the design system. It's more like an instruction manual for the agent to use the design system.
- Yet the YAML front matter captures machine-readable design tokens.
- But design systems change.
- So we immediately hit a drift problem: two sources of truth.
- DESIGN.md is really an understanding of a snapshot of a design system.
- That makes "token values serve as context, not rendering instructions" (in PHILOSOPHY.md) feel contradictory — that's not the nature of machine-readable tokens. We give a token to an agent, they will use it (unless we put a bunch of extra prompts on top, which defeats the purpose of design.md). This becomes more problematic with component tokens.
- Of course there are usage logic and taste associated to how component tokens should be used, which is useful to be captured in the prose. But now the line between DESIGN.md and design systems becomes quite blurry.
- The CLI
specandexportfeatures points to a reverse workflow: DESIGN.md as source of truth, driving agentic development. But that's counterintuitive if a human is still in the loop, since a human would just tweak the visual output directly.
So I think it is trying to be two things at once right now - a stable contract/guide for agents, and a live reflection of a design system that changes. Those pull in opposite directions.
Based on my tinkering so far and workflow, I favor the proposal above by @GenerationUX .
Thanks again!
Reacted by Zach ShallbetterI opened a PR to address this here: #167.
Sorry about the push spam on the thread, I was rebasing to keep the commit history clean.
The implementation adds a
prose-token-leakwarning rule. It flags literal hexes, rgb/hsl colors, and dimensions inside markdown text, while ignoring code blocks, inline code, and brace references. I also updated the spec file and project readme to document the policy.Let me know what you think!
Feedback
Thanks for sharing this. I’ve been experimenting with this pattern already. Implementation example
I like the goal of making
DESIGN.mduseful to both humans and tools, but I think the current format creates drift risk. Appreciate that this is already documented as alpha, but I thought I'd lay out the concern anyway.As I understand it, YAML front matter contains the normative design-token values, while the markdown body provides human-readable guidance. In practice though, many of the same facts will likely appear twice:
For example:
dark-muted: #858585#777777At that point the document still looks authoritative, but now contains two versions of the truth.
Markdown should already be structured enough for many design-system facts through headings, tables, lists, and code blocks. Repeating exact values in YAML creates a second source of truth inside the same file.
It also changes the reading experience a bit, particularly in markdown editors.
Suggestion
A few possible directions:
.yamlfile.If both layers remain, then the linter should either:
Personally, I’m mostly in favor of markdown being the one canonical source without YAML, or if YAML remains but in markdown format. But I could be missing key context.
Question
What was the reasoning behind putting design-token data in YAML front matter instead of making the markdown body the source of truth?
Happy to contribute a PR if useful, especially since this is still in alpha, happy to support where I can.