Duplicating design facts in front matter and markdown body

Feedback

Thanks for sharing this. I’ve been experimenting with this pattern already. Implementation example

I like the goal of making DESIGN.md useful 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:

1. once in YAML for tools
2. again in markdown prose/tables for humans

For example:

• YAML says dark-muted: #858585
• prose says dark muted is #777777

At 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:

1. Make markdown the primary source of truth and parse structured markdown.
2. Generate YAML from markdown, and keep YAML external in a separate .yaml file.
3. Format YAML section in an md format, rather than yaml

If both layers remain, then the linter should either:

• discourage repeated facts across prose and tokens, or
• validate that repeated facts match

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.

Start by reading the DESIGN.md format specification and the YAML front matter and Markdown guidance it describes. Compare the proposed sources of truth, then review the issue discussion for a decided direction. Done is not defined yet: the issue asks for rationale and presents several alternatives rather than specifying a change.