Design system concepts for AI-built interfaces
The building blocks behind a good AI-built brand: a DESIGN.md the agent follows, and the semantic color tokens that make light and dark modes coherent.
60 guides in this topic.
How to generate a DESIGN.md (and what it is)
A DESIGN.md is the written design brief your AI coding agent follows so it stops building generic UI. Here is what belongs in one, and how to generate a complete, exportable DESIGN.md from a real design system.
Updated 2026-08-04
Semantic color tokens explained
Semantic color tokens use role names like background, primary, muted, and border instead of hue names. See all 28 roles in a live light and dark example.
Updated 2026-08-03
Interface guidelines an AI agent can actually follow
Packaging Apple's HIG, Material, or your own house rules as agent-readable guidance: what survives the translation from human design doc to agent instruction, what doesn't, and why platform guidelines alone still produce generic UI.
Updated 2026-07-27
Font pairings for SaaS: what a product typeface has to do
Every SaaS font list recommends the same faces. Here is why, what a typeface actually has to survive in a dense product UI (tabular numerals, real weight separation, small-size legibility) and when a second family earns its place.
Updated 2026-07-27
Atomic design in the agent era: which parts still hold
Atomic design solved a 2013 problem: giving humans a shared vocabulary for interface parts. An agent already has the vocabulary and lacks the judgement. Which parts of the methodology survive that, and which were always scaffolding.
Updated 2026-07-27
Design system vs component library: the difference that costs money
A component library is code you can install. A design system is the set of decisions that made that code look the way it does. Confusing them is why teams install shadcn, ship a generic product, and cannot work out what went wrong.
Updated 2026-07-27
Design token naming: the three-tier system, and where it breaks
Primitive, semantic, component. The three-tier convention is close to universal and most teams still end up with tokens nobody uses. Why that happens, how to name each tier, and the test that tells you a name is wrong before it ships.
Updated 2026-07-27
Design system governance when most commits are not human
Governance models were designed around the assumption that a person requests a change and a person reviews it. When an agent writes forty screens between reviews, contribution processes stop being the bottleneck and enforcement becomes the whole job.
Updated 2026-07-27
Figma to code: why the output is visually right and structurally wrong
Design-to-code tools reproduce what a frame looks like. They cannot reproduce what it means, because a Figma frame does not contain that. What actually transfers, what does not, and the naming decision that closes most of the gap.
Updated 2026-07-27
Avenir font pairings that hold up, with free stand-ins you can ship
What actually pairs with Avenir, rendered live instead of screenshotted. Plus the Google Fonts that stand in for it when the license doesn't travel, and complete systems built on those pairings.
Updated 2026-08-03
Caslon font pairings: what works with the original workhorse serif
The sans-serifs and monos that pair with Caslon, rendered live in free Caslon revivals you can actually ship. When in doubt, use Caslon; when pairing it, read this first.
Updated 2026-08-03
Proxima Nova font pairings, and what to ship when you can't license it
The serifs and monos that pair with Proxima Nova, rendered live with the free faces that stand in for it. The internet's default font deserves a partner that isn't a default.
Updated 2026-08-03
Gilroy font pairings that work, with the free faces that stand in
What pairs with Gilroy's rounded geometry, rendered live with free Google Fonts stand-ins. Plus which of the free weights you can actually build a product on.
Updated 2026-08-03
Brand guidelines examples worth stealing from (and what they all miss)
Eight public brand guidelines that actually teach you something, what separates a working document from a pretty PDF, and why the next generation of guidelines has to be executable by machines, not just read by designers.
Updated 2026-08-04
Shadcn design system generators compared
Compare shadcn theme generators, broader design systems, and coding-agent handoffs by inspecting their documented outputs and exported artifacts.
Updated 2026-08-03
AI UI review checklist
A pre-ship checklist for AI-generated UI: observable acceptance criteria, realistic states, issue routing, and a copyable review record.
Updated 2026-08-03
Google Stitch design system handoff
Assign rule authority in Google Stitch, diagnose inconsistent screens, test one controlled change, and verify the DESIGN.md and code handoff.
Updated 2026-08-03
Brand kit for web developers
How to turn brand assets into a handoff a developer can implement: ownership boundaries, an intake record, a public kit example, and acceptance checks.
Updated 2026-08-03
Webflow design system: who owns what
Map authority across Webflow variables, classes, components, and breakpoints, then verify one controlled change the way you would review a pull request.
Updated 2026-08-03
Shadcn typography: who owns the font
Where each shadcn typography decision lives: font packages, theme aliases, roles, component code, or DESIGN.md, with a real font swap traced through.
Updated 2026-08-03
Storybook design system documentation
Document a design system in Storybook without letting stories become policy: an authority map, a story coverage matrix, and one controlled change.
Updated 2026-08-03
Design token deprecation strategy
Deprecate design tokens without breaking consumers: map dependencies, pick the replacement shape, migrate layer by layer, remove behind a hard gate.
Updated 2026-08-03
FlutterFlow design system: theme to export
Give every FlutterFlow design decision one home, from theme values through components to exported Flutter code, and verify app and export separately.
Updated 2026-08-03
Design system contribution guidelines
Size design system reviews by reach, not diff length: classify the change, name what must move and what must not, and record the decision.
Updated 2026-08-03
Shadcn design tokens: :root to bg-primary
Trace a shadcn token from :root through @theme inline to bg-primary, then see what apply --preset really rewrites, with tested diffs and partial apply.
Updated 2026-08-03
How to validate DTCG design tokens: what a validator pass proves
Validate DTCG design tokens with a reproducible process that covers the published specification target, validator scope, controlled fixtures, generated artifacts, named consumers, and a bounded approval decision.
Updated 2026-09-06
Font fallback stack for product UI: choose by role, script, and failure mode
Choose and test product UI fallback fonts by role, script, and environment. Includes a requirements matrix, valid CSS examples, controlled failure tests, and accept, revise, or block criteria.
Updated 2026-09-07
Component tokens vs semantic tokens: when to add a component layer
Decide whether a component token creates a useful contract or needless maintenance. Compare scopes, trace an alias path, run a two-change propagation test, and record the boundary.
Updated 2026-09-07
CSS light-dark() with design tokens: preserve semantic roles and theme control
Use CSS light-dark() with semantic design tokens while preserving system preference, explicit app choice, nested theme scopes, fallbacks, and testable control.
Updated 2026-09-08
Tailwind CSS v4 design tokens: map external semantic roles to @theme
Map external semantic design tokens into Tailwind CSS v4 without duplicating raw values. Includes valid @theme examples, runtime dependencies, mode checks, an ownership worksheet, and an acceptance record.
Updated 2026-09-09
Penpot design tokens: what is native, what is shared, and what still needs verification
A practical Penpot token adoption guide that separates native capability from project evidence, maps ownership across six layers, and provides intake and controlled-change records with clear acceptance criteria.
Updated 2026-09-09
Style Dictionary with DTCG tokens: verify what gets converted and emitted
Use Style Dictionary 5 to ingest tokens written with documented DTCG properties, convert a complete legacy fixture, generate CSS, and verify one token from source to consumer.
Updated 2026-09-10
Minimum viable design system for startups: what to standardize first
Build the smallest useful startup design system with a copyable admission register, evidence-based deferrals, a bounded kit example, and a reproducible acceptance check.
Updated 2026-09-11
DTCG design token aliases: write, resolve, and verify references
Write DTCG aliases against the 2025.10 Format report, diagnose direct and chained reference failures, and verify what a downstream consumer actually received.
Updated 2026-09-12
Design system accessibility checklist: test the system, then retest the product
A practical design system accessibility checklist with a responsibility matrix, two-pass testing, a copyable evidence register, retest triggers, and explicit release decisions.
Updated 2026-09-14
Design system release checklist: verify artifacts, consumers, and rollback
A practical design system release checklist for tracing approved changes through generated artifacts, distribution, documentation, representative consumers, exceptions, and rollback.
Updated 2026-09-16
OKLCH gamut mapping in CSS: detect, map, and verify token colors
A practical workflow for detecting out-of-gamut OKLCH colors, separating CSS fallbacks from mapping, emitting controlled sRGB output, and verifying semantic token pairs.
Updated 2026-09-18
DTCG border tokens: author, transform, and verify composite borders
Author a DTCG border composite, choose the right token boundary, define expected CSS output, and verify the result in a named interface consumer without confusing source validity with runtime evidence.
Updated 2026-09-19
Design token handoff checklist: prove the path from source to consumer
Use this copyable design token handoff checklist to record source authority, artifact provenance, project mappings, consumers, observations, exceptions, owners, and the final accept, revise, or block decision.
Updated 2026-09-23
Design tokens in Shadow DOM: define, override, and verify the styling contract
Map semantic design tokens into Shadow DOM through a defined styling API. Use a contract matrix, an escaped Web Component fixture, precedence tests, computed-value checks, and an acceptance record to verify each layer.
Updated 2026-09-23
Brand guidelines to Tailwind CSS: map rules into code without losing context
Classify brand rules before implementation, place each one in Tailwind v4, CSS, components, assets, or DESIGN.md, and verify the path from source to consumer.
Updated 2026-09-24
Brand guidelines for SaaS product UI: map brand rules into states and components
Turn SaaS brand guidelines into an operational product UI contract. Place each rule in the right artifact, cover representative surfaces and states, and verify the result with a source-to-consumer acceptance record.
Updated 2026-09-25
Design tokens for responsive spacing: choose fixed, stepped, fluid, or container-scoped rules
Choose fixed, breakpoint-stepped, fluid, or container-scoped spacing, place each rule in the right layer, and verify the result in named consumers.
Updated 2026-10-01
Design tokens for focus indicators: define the contract and verify every state
Decide which focus-indicator rules belong in tokens, components, or CSS, then verify buttons, links, inputs, checkboxes, and composite controls across modes, surfaces, and forced colors.
Updated 2026-10-02
Design token taxonomy template: define layers, scope, and change rules
Copy a repository-ready design token taxonomy template, use a six-outcome matrix to route disputed values, and record migration evidence from governing source to named consumers.
Updated 2026-10-02
Design tokens for status colors: define roles, map modes, and verify states
Route status colors to the token layer that owns them, map one named consumer across light and dark modes, and use an evidence record to accept, revise, or block the result.
Updated 2026-10-03
Z-index design tokens: define layer roles and debug stacking failures
Decide when z-index belongs in a shared semantic token, a component contract, or an exception. Includes a layer contract, verification cases, and a first-divergence debugging procedure.
Updated 2026-10-03
Rebranding a SaaS product checklist: plan the cutover across every surface
Use this operational SaaS rebranding checklist to map the current brand to its replacement, inventory product states, plan rollout waves, set rollback triggers, and record an accept, revise, or block decision.
Updated 2026-10-04
Design system for AI chat apps: define states, actions, and recovery
Build an AI chat design system around explicit lifecycle states, permitted actions, persistence, approvals, interruption, recovery, and bounded acceptance evidence.
Updated 2026-10-05
Design system component inventory template: map design, code, usage, and decisions
Build a versioned component inventory that connects design assets, code packages, documentation, product usage, owners, exceptions, duplicates, and lifecycle decisions.
Updated 2026-10-05
Brand identity package for SaaS: what to include before you approve it
Compare SaaS brand identity packages with a scope matrix, evidence boundaries, a copyable acceptance record, and clear accept, revise, or block rules.
Updated 2026-10-06
Design system decision record template: capture authority, impact, and evidence
Copy a design system decision record that connects rationale and authority to affected tokens, artifacts, components, consumers, owners, evidence, review triggers, and supersession.
Updated 2026-10-07
Vercel design system: what Geist exposes and how to adapt it
A dated map of Vercel's public Geist resources, their acquisition boundaries, and a practical method for adapting one principle without mistaking documentation for implementation.
Updated 2026-10-09
Plus Jakarta Sans and JetBrains Mono pairing for product UI
Decide how to pair Plus Jakarta Sans with JetBrains Mono, assign each family to suitable product UI roles, load only the weights you need, and verify the result across prose, controls, code, logs, identifiers, and numeric data.
Updated 2026-10-13
Command palette design system: define commands, states, and safety
Design a reusable command palette with clear ownership, a copyable command record, consequence-aware states, alternate routes, and evidence from a named product consumer.
Updated 2026-10-15
AI tool call UI patterns: states, consequences, and recovery
Design evidence-backed AI tool-call UIs with a portable lifecycle, consequence matrices, parent-child invocation records, recovery controls, and a copyable acceptance record.
Updated 2026-10-16
Generative UI design system: constrain components, states, and runtime evidence
Build a governed generative UI design system with a versioned component catalog, explicit authority boundaries, deterministic fallbacks, and evidence-based acceptance.
Updated 2026-10-18
Design system migration checklist: plan a source-to-screen cutover
Use this vendor-neutral checklist to inventory migration units, map old contracts to a selected design system, choose a rollout route, govern coexistence, verify adoption, and close each wave with evidence and rollback criteria.
Updated 2026-10-22
Brand guidelines to shadcn theme: map decisions to tokens and DESIGN.md
Turn approved brand guidelines into a shadcn theme without inventing missing decisions. Use a source-to-target crosswalk, route rules to the right artifacts, and verify named components in light and dark modes.
Updated 2026-10-23
DTCG typography tokens: model composites and verify the CSS result
Learn how to model DTCG typography tokens, choose atomic or composite structures, emit CSS, and trace font problems from source data to rendered text.
Updated 2026-10-24