Living Design System

Sources#

• How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development
• I tested Meta's "agent-ready" design system Astryx. Here's the results.

Summary#

Thariq Shihipar's third HTML-first workflow: maintain a design_system.html file — an artifact that is both human- and machine-readable — as a portable source of truth for your application's visual language. Unlike a static style-guide document, it renders: color palette, typography scales, spacing rules, and interactive examples of core components (buttons, inputs, cards) all displayed live on the page. You hand this one file to Claude as context whenever you start new work, and everything it builds comes out on-brand.

This is the HTML as the New Markdown move applied to the persistent problem of design-system adherence: the same artifact a human can eyeball is the artifact the model reads to stay consistent.

How it's built#

1. Extract the design DNA. Point Claude at a project folder — or multiple GitHub repositories at once (e.g. the marketing site and the app) — and ask it to extract the design system. It analyzes the CSS, components, and styling to infer the visual language.
2. Generate the design_system.html artifact. Claude renders the extracted system as a single HTML file that visually displays palette, type scale, spacing, and interactive component examples — not a description of the components, the components themselves.
3. Explore variations and share. With tools like Claude Design, build component playgrounds with interactive knobs and sliders ("what would this button look like with more padding? a different border?") to explore variations in real time.

Why it's "living"#

A conventional style guide drifts: the doc says one thing, the code does another. A design_system.html extracted from the code and rendered as real components is harder to falsify — what you see is what the components actually do. And because it's a single portable file, it travels: give it to a new project, a new feature, or a teammate, and it becomes the reference that keeps output consistent. It is a durable allocation of compute — generated once, reused as context indefinitely — in contrast to the throwaway micro-apps.

Bridging engineering and the rest of the company#

The artifact's biggest payoff is organizational. A rendered component page lets non-technical stakeholders — marketers, PMMs, anyone making decks or videos — go to one page, see every component in its various states, and grab high-fidelity mockups "without bugging an engineer." Claire Vo reports doing exactly this with her own component-visualization page. The design system thus bridges not just human↔AI but engineering↔the rest of the company — the same human-facing-legibility payoff HTML as the New Markdown claims for plans.

Tested: on-brand output is coverage-gated, not prompt-gated#

The first hands-on test of the core premise — does handing a model a rendered, structured design system actually produce on-brand output? — comes from Evangeline's trial of Astryx, Meta's open-source "agent-ready" design system, driven against a real consumer brand (Salt & Straw) with real shopping flows (case-study, single practitioner, n=1, unmeasured).

Result 1 — the artifact is the input, not the prompt. Early runs came out generic and off-brand (no purchase buttons at all). The author's initial read was that Astryx was at fault; the actual cause was missing design artifacts:

"The gap between generic AI output and on-brand output is not a prompting problem. It's the missing design artifacts like tokens.json design.md etc. AI can't reproduce choices and designs I didn't provide."

After extracting the brand into a DESIGN.md plus layered token files (primitives / semantic / component) — capturing not just values (coral #F0483E, Bebas Neue display / Inter body, 8px base, 10/30/70 radii, flat/no-shadow depth) but the reasoning behind them — the agent produced a full working product surface: shop finder with map and wait times, order history with tracking timeline, cart, flavors page with real photography and buy buttons, loyalty page, both desktop and mobile. "Give it real decisions and real images, and it produces genuinely brand-specific work." This is direct support for the page's thesis, and it sharpens it: the win is not that the artifact renders, it is that the artifact records decisions the model would otherwise have to invent. The author's own diagnosis of every failure: "Every time my output looked generic, it was writing down a decision I'd left implicit."

Result 2 — the brand stops exactly where the system's customization slots stop. Astryx exposes deep customization for four components only — buttons, cards, text inputs, links. Everything else can only be nudged through theming. The output split cleanly along that line: correct coral, candy-stripe, flat cards everywhere the slots existed; the rewards progress bar rendered blue (#0074E2) and shop-finder wait-time bars blue-and-yellow, because no slot existed. A segmented control also picked up a shadow in violation of DESIGN.md rule #2 ("Flat depth model — no shadows, ever"). The failure is not stochastic taste drift — it is a coverage boundary: outside the mapped surface the system substitutes its own defaults, silently.

The tell that this is a fallback rather than a mis-read: the author re-ran with Blue Bottle, whose blue sits near Astryx's default, and the progress bar looked correct. Same code path, same silent fallback, only now indistinguishable from success. A design system whose defaults resemble your brand hides its own coverage gaps.

"The system can display a brand well, but it can't fully ingest one. For anything Astryx doesn't have a slot for, the brand identity ends up living outside the system, or, rendering in the wrong color."

Result 3 — the customization model matters more than the token format. Run the same brand and screens through shadcn/ui and the progress bar comes out coral. The difference is ownership, not artifact quality: shadcn copies components into your project (user-owned files, editable as ordinary code), Astryx keeps components in the system and styles them through a theme layer, where "layered tokens get flattened" and there is no escape hatch — "when the progress bar came out the wrong color, I couldn't correct it through the theme on the path I used." The tradeoff is the ordinary one: shadcn's owner maintains every component as the brand grows; Astryx's owner maintains less and lives inside the constraints. "Agent-ready" as a label describes readability by the agent; it says nothing about whether the system can absorb a brand.

What this adds to the page. A design_system.html that renders is a legibility win, but legibility is not coverage. Two distinct properties are in play, and only the first is what this page originally claimed:

1. Decisions recorded — does the artifact state the choice? (Astryx test: yes, and it works.)
2. Slots to apply it — does every component the product needs have a place for that decision to land? (Astryx test: 4 components, and everything else regresses.)

An extraction-based artifact like design_system.html is stronger on (2) than a vendored system is, precisely because it is derived from components you already own — but the same gap appears in a different place: the artifact documents whatever the extractor found, and anything the product later needs but the artifact never covered gets the model's priors, not yours. The maintenance obligation this page's open questions raise is therefore not just staying in sync but staying complete.

Connections#

• Design by Selection — the same move productized: upload brand files, logos, decks and typography specs to Claude Design and it generates the design system every later artifact starts from — the first-party answer to the model's default aesthetic. The Astryx test above puts a boundary on that answer: context defeats the default aesthetic exactly where a customization slot exists, and nowhere else
• Why AI Lags at Design — reason 4 (the design↔code abstraction layer) is the design-system problem: semantics between components, not their pixels
• Agent-Native Infrastructure — design_system.html is agent-native infrastructure for the design layer
• Systems Thinking Over Specialization — the enterprise-scale practice: Netflix's design org shifts hiring toward design-systems thinkers who encode "what great design looks like" as templates so non-designers ship coherently without "shipping Frankensteins"
• Thariq Shihipar — originator of the design_system.html workflow
• Claude Code — extracts the design DNA from repos and renders design_system.html; Claude Design powers the component playgrounds
• HTML as the New Markdown — the parent thesis; design system is the HTML-first move applied to design
• Compute Allocator — a durable compute allocation (generate once, reuse as context)
• Disposable Micro-Apps — the throwaway counterpart; design system is the keep-it counterpart
• Claire Vo — runs a parallel component-visualization practice for non-technical stakeholders
• Engineer PM Convergence — an artifact that lets non-engineers self-serve high-fidelity assets is the tooling side of roles blurring across the org
• The HTML Artifact Lifecycle: Where Plan History Lives, and When Disposable Becomes Durable — names this page as the durable exemplar: an artifact earns keep-it status via recurrence, sync pressure, and audience, and pays for it in the maintenance obligations this page's open questions enumerate

Open Questions#

• How does the design_system.html stay in sync as the codebase evolves — re-extract on a cadence, or wire it into CI? And is completeness (does every component the product needs have a slot?) the binding constraint rather than freshness — the Astryx test suggests uncovered components fail silently, which staleness checks wouldn't catch.
• Does a rendered, model-readable design system measurably improve on-brand output vs. a plain CSS/token file, or is the win mostly human legibility? #oq/source Partially answered: I tested Meta's "agent-ready" design system Astryx. Here's the results. shows structured artifacts (DESIGN.md + layered tokens) flip output from generic to on-brand, so the artifact clearly beats no artifact — but it does not isolate the variable this question actually asks about, since the artifacts used were plain files, not a rendered page. Rendered-vs-plain remains untested.
• At what project size does maintaining the artifact cost more than the consistency it buys?

Sources#

• How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development
• I tested Meta's "agent-ready" design system Astryx. Here's the results. — Evangeline, Substack, July 2026 (case-study, n=1): Meta's Astryx driven against Salt & Straw; structured artifacts produce on-brand output, but only across the four components with real customization slots, with a shadcn/ui comparison isolating component ownership as the difference