design.how vs DESIGN.md files

A DESIGN.md file describes a design as YAML tokens plus Markdown prose, in the format Google Stitch opened in April 2026. A design.how system brings that kind of description and the parts it describes: components to import, a skill the agent loads on its own, and a lint that fails on the code. A DESIGN.md tells an agent what the design should be; a design system gives it the parts and checks the result.

Text is context, not enforcement. Claude Code's own docs say it treats memory files "as context, not enforced configuration", and a DESIGN.md read through CLAUDE.md is the same. One reported failure is specific: the agent reads the tokens, then builds its own button from them instead of using the one in the component library. A Design Systems Collective post describes it under the title "I Gave My Agent CLAUDE.md and DESIGN.md. It Ignored My Entire Component Library."

A design.how system closes that gap in two places. Its skill tells the agent to use a component before writing custom markup, as rule quartz-components-first, and its lint fails when the agent restyles one:

"h-14" restyles the height of <Button>; use its variant and size props, and keep className for placement such as w-full, flex-1, self-start or mt-4.

• Keep a DESIGN.md as the brief for your brand: what it should feel like and why. It is easy to read and diff.
• If you have a brand DESIGN.md and no system yet, build-design-system can take it as the design source you choose and turn it into tokens, components and checks.
• shadcn's official skill added a DESIGN.md workflow in October 2026 that maps a DESIGN.md's tokens onto a shadcn/ui theme, if you build on shadcn/ui directly.