# How DESIGN.md Integrates with Coding Agents for UI Generation: A Technical Deep Dive

> Discover how DESIGN.md seamlessly integrates with coding agents for UI generation. Learn how it converts YAML to JSON specs, enabling the Ink renderer to build user interfaces.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-06-27

---

**DESIGN.md bridges human-readable design documentation and machine-executable UI generation by parsing YAML front-matter tokens into structured JSON specifications that coding agents render via the Ink renderer.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository establishes a declarative framework where design systems are expressed as markdown documents with embedded machine-readable tokens. This architecture enables coding agents to consume DESIGN.md files as the single source of truth for generating interactive terminal UIs. By coupling YAML front-matter with prose rationale, the system creates a tight feedback loop between design intent and rendered output.

## The Three-Stage Integration Pipeline

Coding agents process DESIGN.md through a deterministic pipeline that transforms declarative design into executable interface components.

### Stage 1: Parsing and Validation with the CLI Linter

The integration begins with the CLI’s linter, which validates the token schema and emits a **structured JSON representation** of the design system. Located in [`packages/cli/src/linter/spec-gen/generate.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/generate.ts), the linter enforces rules such as `missing-primary` and `contrast-ratio` to guarantee safe downstream generation.

Validation ensures that token values (e.g., `colors.primary`) are semantically correct before agents attempt to render them. The linter outputs a JSON-compatible design state that serves as the canonical intermediate representation.

### Stage 2: Spec Generation to JSON

Once validated, the design transforms into a **UI specification** conforming to the `@json-render/ink` schema. The `spec` command in [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts) invokes the `getSpecContent` helper to produce a **flat element map** with a root key of `main` plus a list of UI elements capturing layout, typography, colors, and interactive behavior.

This generated spec is JSON-compatible and streamable, allowing agents to consume design changes in real-time without manual code updates.

### Stage 3: Rendering via the Ink Skill

Agents load the JSON spec into the **Ink renderer** (`@json-render/ink`), consuming the skill definition documented in [`.agents/skills/ink/SKILL.md`](https://github.com/google-labs-code/design.md/blob/main/.agents/skills/ink/SKILL.md). This skill supplies a full catalog of terminal components including `Box`, `Heading`, and `Tabs`, together with state-binding and event-handling primitives.

By wrapping the renderer with `JSONUIProvider`, an agent drives a fully interactive terminal UI directly from the design description. The rendering layer interprets the spec's element map and binds it to React Ink components.

## End-to-End Implementation Examples

### Validating and Converting DESIGN.md

First, lint the file to ensure token integrity and generate a structured report:

```bash
npx @google/design.md lint DESIGN.md --format json > lint-report.json

```

Next, generate the UI specification that agents will consume:

```bash
npx @google/design.md spec DESIGN.md > ui-spec.json

```

### Rendering the Spec in a Terminal Agent

The following TypeScript implementation loads the generated spec and renders it using the Ink component library:

```tsx
import { createRenderer, standardComponents } from "@json-render/ink";
import { JSONUIProvider } from "@json-render/ink";
import { createStateStore } from "@json-render/ink";
import type { StateStore } from "@json-render/ink";
import fs from "fs";

// Load the spec generated from DESIGN.md
const spec = JSON.parse(fs.readFileSync("ui-spec.json", "utf-8"));

// Initialize external state store for interactive components
const store: StateStore = createStateStore({ activeTab: "overview" });

const InkRenderer = createRenderer(
  // The catalog is auto-generated by the CLI; reuse the standard set
  { components: {}, actions: {} },
  { ...standardComponents }
);

function App() {
  return (
    <JSONUIProvider store={store}>
      <InkRenderer spec={spec} />
    </JSONUIProvider>
  );
}

// Render the app (e.g., with `render(App())` in a script)

```

### Streaming Specs for Dynamic Generation

For agents that generate designs on-the-fly, stream the spec directly from an API endpoint:

```tsx
import { useUIStream } from "@json-render/ink";

function LiveApp() {
  const { spec, isStreaming } = useUIStream({ api: "/api/generate-design" });

  if (isStreaming) return <Text>Generating UI…</Text>;
  return <InkRenderer spec={spec} />;
}

```

## Why This Matters for Agent Workflows

The DESIGN.md architecture delivers three critical capabilities for coding agents:

- **Consistent branding** – Token values defined in YAML front-matter propagate identically across lint warnings, prose documentation, and rendered UI components.
- **Agent-first ergonomics** – Agents query the JSON spec for component properties, apply conditional visibility logic, and emit actions that feed back into the design system state.
- **Cross-format export** – The CLI’s `export` command emits Tailwind, CSS, or W3C Design Tokens formats, allowing agents to embed the same design language into web, native, or terminal targets without duplication.

## Summary

- DESIGN.md combines YAML front-matter tokens with markdown prose to create a machine-readable design source of truth.
- The CLI linter in [`packages/cli/src/linter/spec-gen/generate.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/generate.ts) validates tokens and emits JSON design states.
- The `spec` command transforms validated designs into `@json-render/ink` compatible specifications via [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts).
- Agents render interactive terminal UIs by wrapping the Ink renderer with `JSONUIProvider` and consuming the generated spec.
- Changes to DESIGN.md propagate automatically to generated UIs, eliminating manual synchronization between design docs and code.

## Frequently Asked Questions

### How does DESIGN.md differ from standard design token files?

DESIGN.md embeds machine-readable YAML front-matter within human-readable markdown prose, creating a single document that serves both documentation and code generation purposes. Unlike standalone JSON token files, it preserves design rationale alongside the values, enabling agents to understand context while parsing tokens.

### Can agents modify the UI specification after generation?

Yes. The JSON spec output is mutable, and agents can programmatically adjust component properties, visibility rules, or state bindings before passing the spec to the Ink renderer. The `JSONUIProvider` accepts external state stores, allowing agents to inject dynamic data or user interactions into the rendered interface.

### What validation rules ensure the generated UI is accessible?

The CLI linter enforces rules such as `contrast-ratio` and `missing-primary` defined in [`packages/cli/src/linter/spec-gen/generate.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/generate.ts). These guarantees ensure that color combinations meet accessibility standards and that required design tokens are present before the agent attempts to render the interface.

### Where is the formal specification for the DESIGN.md format documented?

The complete token schema and format specification reside in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) within the repository. This document defines the relationship between YAML front-matter keys, markdown structure, and the expected JSON output consumed by the `@json-render/ink` renderer.