adam bien's blog

DESIGN.md stores a design system as YAML token blocks inside a markdown file. Agents and developers can read, review, and diff it like any other document.

zdmd is a Java port of the reference TypeScript CLI: a zero-dependency Java 25 application packaged as a single executable JAR. It lints, diffs, and exports DESIGN.md token files. One JAR replaces node_modules for anyone working with design systems on the JVM:

zdmd                    # convert DESIGN.md into all formats, write tokens.css + tokens.json
zdmd lint  [--format json|md]
zdmd diff   [--format json|md]
zdmd export  --format  [--prefix ]

The bare launch is built for agents: it reads DESIGN.md from the current directory, writes every supported format (tokens.css and tokens.json), and prints the written filenames. No flags to remember.

Only web-standard export formats are supported: CSS custom properties and W3C Design Tokens (DTCG) JSON. Tailwind is intentionally out of scope. lint exits with 1 on errors and diff exits with 1 on regressions, so both plug directly into CI pipelines.

Installation requires nothing but Java 25+:

curl -fLO https://raw.githubusercontent.com/AdamBien/zdmd/main/zdinstall
chmod +x zdinstall
./zdinstall

zdmd was built with the spec-driven BCE workflow (sbce.space): each capability lives in its own business component, and the spec in package-info.java is the boundary contract. It is part of z, a collection of zero-dependency Java projects.