← Back to work

design.md — specifying the system before pipelining it

An early experiment with Google's @google/design.md tooling — a single 264-line spec that lints, diffs, and exports to Tailwind / DTCG. Lab-notebook entry, not a shipped pipeline.

A Launchpad design specification excerpt shows color tokens, typography, and the scripts that check and export the spec.

Problem

Tokens-as-code is a strong default (see the design library case study) but it has a gap: the spec lives in TypeScript, which is great for consumers and bad for reviewers. A non-engineer can’t read tokens.ts and tell you whether the contrast ratios hold up, whether the type scale has a missing rung, or whether two components are quietly diverging from the system. The tokens-as-code lives in the codebase. The spec lives in designer’s heads.

@google/design.md (Google Labs, v0.1.1) is the candidate fix: a DESIGN.md file that’s half YAML front matter (machine-readable tokens) and half Markdown prose (rationale, contrast notes, do’s and don’ts). It lints. It diffs. It exports to Tailwind tokens or DTCG (Design Tokens Community Group). One artifact, two audiences.

Approach

I wired it into one project — cl-launchpad-protoapp-new — to see whether the spec format actually carries the weight I want it to carry. The DESIGN.md is 264 lines, ~3,600 words of prose, covering the whole K-12 launchpad surface:

  • Colors — 26 tokens (primary, accent, text hierarchy, semantic, status)
  • Typography — 7 roles (h1–h4 in Poppins, body variants in Open Sans, k2Body in Nunito for the K-2 mode)
  • Spacing — 8-point scale, 2px → 64px
  • Radii — seven steps, 4px → 20px + full pill
  • Components — 8 named tokens (Navbar, SearchBar, FolderCard, AppIcon, NotificationBadge, DashboardWidget, AppLibraryDrawer, UserAvatar) with source-code paths back to the Angular files
  • Prose sections — Overview, Colors with contrast compliance notes, Typography with the three-typeface strategy and the iOS zoom rule, Layout breakpoints, Elevation (six shadow tiers), Shapes, Components, and Do’s/Don’ts

A representative slice of the front matter:

version: "alpha"
name: ClassLink Launchpad Portals
description: K-12 SSO launchpad design system...
colors:
  primary: "#0a4d7f"
  primaryHover: "#083d66"
  accent: "#fbaf3e"
  accentOnLight: "#946200"
typography:
  h1:
    fontFamily: Poppins
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.2

Four npm scripts hang off it:

"design:lint":            "design.md lint DESIGN.md",
"design:diff":            "design.md diff",
"design:export:tailwind": "design.md export DESIGN.md --format tailwind",
"design:export:dtcg":     "design.md export DESIGN.md --format dtcg"

What I’m actually getting from it (today)

Honestly: a forcing function for spec-writing, not yet a token pipeline.

  • Lint catches structural mistakes before they propagate. If a typography role references a font family that isn’t declared, lint fails. If a contrast pair doesn’t meet WCAG, lint flags it.
  • Diff detects regressions between two versions of the spec — useful for “did this PR silently change a brand color?” reviews.
  • Exports are ephemeral. The Tailwind and DTCG exports run on demand; neither output is committed. The system of truth still lives in src/styles/_variables.scss — hand-maintained CSS custom properties, not generated from the spec.

That last point is the honest part of this case study. This isn’t a closed loop yet. The spec doesn’t generate the SCSS; it describes it. If the two drift, lint won’t catch the drift — only a human reading both will.

The unlock isn’t the export pipeline. It’s that I now have one file I can hand to a stakeholder, a contractor, or an audit, and they get the whole design system in 264 lines. The tokens-as-code remains. The DESIGN.md is the spec layer above it.

Why I’m publishing this as a case study even though it’s early

Because portfolios that only show the polished work hide the bet-placement step, and the bet-placement is the part of being an agentic designer that actually compounds. Adopting a new piece of tooling is itself an artifact — the decision to do it, the scope of the experiment, the honest read on what you got.

This entry exists so that future-me has a checkpoint: April 23, 2026, single project, single DESIGN.md, lint passes, no commits yet, no CI integration, no cross-project adoption. If a year from now this is everywhere and the SCSS files are auto-generated from the spec, I’ll know what to point at. If it dies, I’ll know that too.

What I’d do differently / what’s next

  • Commit the DESIGN.md. Right now it’s a working file in the repo, not pushed upstream. Until it’s tracked, the diff command has nothing to diff against.
  • Wire design:lint into CI. A failing lint should block a PR, the same way ESLint and TypeScript do. Otherwise the spec is just a Word doc that happens to live in git.
  • Pick the export and commit to it. Either DTCG → Style Dictionary → SCSS variables, or the spec just stays descriptive and SCSS stays the source of truth. Currently I get the worst of both: two systems, no enforced sync.
  • Try it on a second project. Single-project adoption isn’t a workflow; it’s a folder. If comp-design-library or my-files-react doesn’t get a DESIGN.md within the next quarter, the experiment failed quietly and I should retire it before pretending otherwise.
  • Generate a DESIGN.md from the existing tokens.ts. Reverse the flow. If the TypeScript tokens already exist, a small adapter could emit the YAML front matter. Closes the loop without rewriting either side.