Canonical Order of Sections in a DESIGN.md File: The 7-Section Standard

A DESIGN.md file follows a strict top-to-bottom sequence of seven sections: Brand & Style, Colors, Typography, Layout & Spacing, Elevation & Depth, Shapes, and Components.

The google-labs-code/design.md repository establishes a consistent document structure that progresses from high-level brand narrative to concrete UI implementation. This canonical ordering appears across every example design system in the repository, ensuring teams can locate design tokens and component specifications predictably. Mastering this sequence allows you to create design documentation that mirrors the logical flow from why a system looks a certain way to how it is built.

The Seven-Section Hierarchy

The canonical order follows a deliberate progression from conceptual foundations to concrete building blocks. This structure appears in examples/totality-festival/DESIGN.md, examples/paws-and-paths/DESIGN.md, and examples/atmospheric-glass/DESIGN.md.

1. Brand & Style

This opening section establishes the visual personality, mood, and overall aesthetic narrative. It answers why the design system exists before diving into implementation details.

2. Colors

The palette definitions follow next, including primary, secondary, surface, and semantic color tokens. These are foundational design tokens that subsequent sections reference.

3. Typography

Type-scale definitions, font families, and typographic hierarchy tokens appear here. This section specifies the textual voice of the system through measurable tokens.

4. Layout & Spacing

Grid systems, margin conventions, container sizes, and spacing units define the structural rhythm of the interface. This section bridges visual identity with spatial organization.

5. Elevation & Depth

Rules for shadows, glass-morphism effects, and layer hierarchy establish the z-axis logic of the system. This section often includes depth scales and shadow tokens.

6. Shapes

Corner-radius conventions and shape language tokens (borders, pill shapes, etc.) appear here, completing the foundational token set.

7. Components

The final section catalogs reusable UI components (buttons, cards, inputs) that reference the tokens defined in all preceding sections. This is the concrete UI layer where abstract tokens become interface elements.

Evidence from the Repository

The consistency of this ordering is observable across the repository's example design systems.

In examples/totality-festival/DESIGN.md, the seven headings appear in exactly this sequence between lines 148 and 194, establishing the visual language before enumerating any specific components. Similarly, examples/atmospheric-glass/DESIGN.md repeats the same heading sequence from lines 44 to 96, confirming that even radically different aesthetic systems (festival branding versus glass-morphism) adhere to the same document architecture.

The examples/paws-and-paths/DESIGN.md file also follows this pattern, demonstrating that the canonical order applies regardless of the specific design domain or visual style.

Implementing the Canonical Order

When creating a new DESIGN.md file, you should structure both the YAML frontmatter and markdown sections to respect this hierarchy. Below is a minimal skeleton that follows the repository conventions:

---
name: Your Design System
colors:
  primary: "#ff0000"
  on-primary: "#ffffff"
  secondary: "#00ff00"
typography:
  headline-lg:
    fontFamily: Inter
    fontSize: 32px
    fontWeight: "600"
    lineHeight: 40px
    letterSpacing: -0.02em
rounded:
  sm: 0.125rem
  md: 0.375rem
spacing:
  unit: 8px
  container-max: 1280px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.headline-lg}"
    rounded: "{rounded.md}"
    padding: 12px
---

Following the YAML frontmatter, the markdown body should use these exact H2 headings in order:

## Brand & Style

Describe the visual language, tone, and overall feel.

## Colors

Explain the palette, usage rules, and intent.

## Typography

Detail the type-scale, font families, and hierarchy.

## Layout & Spacing

Specify grids, margins, container sizes, and base unit.

## Elevation & Depth

Define shadow, glass-morphism, and depth strategies.

## Shapes

State corner-radius conventions and shape language.

## Components

List reusable UI components, referencing the tokens above.

Summary

• Design.md files use a strict 7-section sequence observed across all examples in the google-labs-code/design.md repository.
• The order progresses from abstract to concrete: Brand & Style → Colors → Typography → Layout & Spacing → Elevation & Depth → Shapes → Components.
• File evidence confirms this pattern in examples/totality-festival/DESIGN.md (lines 148-194), examples/atmospheric-glass/DESIGN.md (lines 44-96), and examples/paws-and-paths/DESIGN.md.
• Implementation requires both YAML frontmatter tokens and markdown sections following the same conceptual-to-concrete flow.

Frequently Asked Questions

Why must Colors come before Typography in the canonical order?

Colors and Typography are both foundational token layers, but Colors establishes the visual identity first, allowing Typography to potentially reference color tokens for text hierarchies (such as accent-colored headings). According to the repository examples, this ordering ensures that when readers reach the Components section, they have encountered all prerequisite token definitions (color, type, space, depth, shape) needed to understand component specifications.

Is the YAML frontmatter required to follow the same section order?

Yes, the YAML frontmatter should mirror the markdown section hierarchy. In examples/totality-festival/DESIGN.md and others, the YAML tokens are organized with colors, typography, spacing, and rounded (shapes) appearing before the components mapping. This alignment ensures that token references in the components section resolve logically within the document structure.

Can I add custom sections between the canonical seven?

The repository examples suggest maintaining the seven core sections as top-level headings to ensure compatibility with tooling expecting this structure. While you can nest additional subsections (H3) within the canonical seven, inserting new top-level sections between them (for example, between Layout & Spacing and Elevation & Depth) would break the established pattern that teams and parsers rely on for scanning design documentation.

Where is this canonical order documented in the source code?

The canonical order is not explicitly documented in a single configuration file; rather, it is enforced through the example files themselves. By analyzing examples/totality-festival/DESIGN.md, examples/paws-and-paths/DESIGN.md, and examples/atmospheric-glass/DESIGN.md, you can observe that all three files use identical heading sequences despite describing entirely different design systems, establishing the pattern as a repository-wide convention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}