Does DESIGN.md Define Spacing Systems and Component Styling? A Technical Guide

Question

Discover if DESIGN.md defines spacing systems and component styling. This guide details the machine-readable design token system within VoltAgent/awesome-design-md, including spacing scales and styling.

Accepted Answer

Yes, every DESIGN.md file in the VoltAgent/awesome-design-md repository defines a complete, machine-readable design token system that includes hierarchical spacing scales and explicit component styling specifications.

The VoltAgent/awesome-design-md repository collects Google Stitch DESIGN.md specification files that encode visual design as declarative tokens. These files treat spacing systems and component styling as structured data rather than static documentation, enabling AI agents and build tools to generate pixel-perfect interfaces automatically.

Spacing Tokens and Scale Hierarchy

Named Spacing Units

Each DESIGN.md file contains a complete spacing token table that maps semantic names to concrete pixel values. In design-md/zapier/DESIGN.md, the system defines a base unit of 4 px and establishes a hierarchical scale from {spacing.xxs} to {spacing.4xl}.

According to line 371 of the Zapier file, the tokens resolve as follows:

{spacing.xxs} = 2 px
{spacing.xs} = 4 px
{spacing.sm} = 8 px
{spacing.md} = 12 px
{spacing.lg} = 16 px
{spacing.xl} = 24 px
{spacing.4xl} = 64 px

The x.ai design at line 322 repeats this identical token table, ensuring consistency across different brand implementations. These spacing tokens appear throughout layout specifications, such as the section band padding defined at line 373 which uses {spacing.4xl} (64 px) for vertical rhythm.

Component Style Specifications

Button Components

Component definitions reference these spacing tokens alongside color, typography, and shape values. The primary button in design-md/zapier/DESIGN.md (line 222) demonstrates the complete token binding:


button-primary — the orange CTA
- Background {colors.primary}, text {colors.on-primary}
- Label {typography.button-md}, padding {spacing.md} {spacing.xl}
- Shape {rounded.md} (12 px)

The x.ai variant at line 69 adjusts the pattern using {spacing.xs} {spacing.md} for padding and {rounded.pill} for shape, illustrating how the same token system supports brand-specific styling while maintaining structural consistency.

Additional Components

Beyond buttons, each DESIGN.md defines cards, inputs, navigation bars, and footers using the same token syntax. Every component specifies padding, margins, corner radius, and typography through curly-brace notation that tools can parse and resolve to CSS values.

Machine-Readable Implementation

The token system is machine-readable by design. References like {spacing.xl} and {colors.primary} follow a consistent {category.name} format that AI agents and design-system generators can consume directly. This declarative approach allows automated tools to render interfaces without manual CSS authoring.

Practical Code Examples

Using Spacing Tokens in Markdown Templates

You can reference DESIGN.md tokens directly in HTML attributes for rapid prototyping:

<!-- Hero band -->
<div class="hero-band" style="
  background:{colors.canvas};
  color:{colors.ink};
  padding:{spacing.4xl} {spacing.xl};
">
  <h1 style="font:{typography.display-xl}">Welcome</h1>
</div>

<!-- Primary button -->
<button class="button-primary"
        style="
          background:{colors.primary};
          color:{colors.on-primary};
          padding:{spacing.md} {spacing.xl};
          border-radius:{rounded.md};
        ">
  Get Started
</button>

Defining Custom Components in YAML

For design-system libraries, you can extend the token system to define new components:

components:
  card-banner:
    background: "{colors.canvas-soft}"
    text: "{colors.ink}"
    padding: "{spacing.xl}"
    radius: "{rounded.md}"
    typography: "{typography.body-md}"

When rendered, this component inherits the 24 px padding from {spacing.xl} and 12 px radius from {rounded.md} as defined in the underlying token table.

Consuming Tokens in JavaScript

Export spacing values for React or Vue applications:

import tokens from './design-tokens.json';

export const spacing = {
  xxs: `${tokens.spacing.xxs}px`, // 2px
  xs:  `${tokens.spacing.xs}px`,  // 4px
  sm:  `${tokens.spacing.sm}px`,  // 8px
  md:  `${tokens.spacing.md}px`,  // 12px
  lg:  `${tokens.spacing.lg}px`,  // 16px
  xl:  `${tokens.spacing.xl}px`,  // 24px
};

Source File Reference

The following files in the VoltAgent/awesome-design-md repository demonstrate these patterns:

design-md/zapier/DESIGN.md (line 371): Complete spacing token table and button component definitions (line 222)
design-md/x.ai/DESIGN.md (line 322): Alternative component styles using the same spacing scale (line 69)
design-md/wise/DESIGN.md: Additional implementation examples across different brand contexts

Summary

DESIGN.md files define hierarchical spacing tokens from {spacing.xxs} (2 px) to {spacing.4xl} (64 px) based on a 4 px base unit.
Component styling is tokenized using syntax like {colors.primary}, {spacing.md}, and {rounded.md} for machine-readable specifications.
Spacing and component definitions are machine-readable and can be consumed by AI agents to generate consistent UI automatically.
Multiple brand implementations (Zapier, x.ai, Wise) share the same token structure while allowing variant values.

Frequently Asked Questions

What spacing values are defined in DESIGN.md?

DESIGN.md files define a semantic spacing scale based on a 4 px base unit. The standard set includes {spacing.xxs} (2 px), {spacing.xs} (4 px), {spacing.sm} (8 px), {spacing.md} (12 px), {spacing.lg} (16 px), {spacing.xl} (24 px), and {spacing.4xl} (64 px), as documented in design-md/zapier/DESIGN.md at line 371.

How are components styled in DESIGN.md?

Components are styled using token references that combine spacing, color, typography, and shape values. For example, a primary button uses {colors.primary} for background, {spacing.md} and {spacing.xl} for horizontal and vertical padding, and {rounded.md} (12 px) for corner radius, as seen in the Zapier file at line 222.

Can DESIGN.md tokens be used in JavaScript projects?

Yes, you can export DESIGN.md tokens as JSON and import them into JavaScript applications. This allows you to reference tokens.spacing.xl (24 px) directly in your component code, ensuring perfect alignment with the design specification across your entire codebase.

Where can I find examples of DESIGN.md files?

The VoltAgent/awesome-design-md repository contains working examples in the design-md/ directory, including implementations for Zapier (design-md/zapier/DESIGN.md), x.ai (design-md/x.ai/DESIGN.md), and Wise (design-md/wise/DESIGN.md), each demonstrating spacing systems and component styling in real-world contexts.