Canonical Section Order in DESIGN.md: Rules, Violations, and CLI Enforcement

The canonical section order in DESIGN.md requires eight specific H2 sections—Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts—to appear in a fixed sequence, and violating this order triggers a "warning" severity finding from the CLI linter but does not halt processing.

The google-labs-code/design.md specification enforces a strict structural contract to ensure design system files remain machine-readable. Following the canonical section order in DESIGN.md allows the CLI linter, automated exporters, and downstream AI agents to reliably parse and interpret each design token.

Understanding the Canonical Section Order in DESIGN.md

The specification defines exactly eight mandatory sections, each declared as an H2 heading (##). According to docs/spec.md, the sequence is:

1. Overview (also labeled "Brand & Style")
2. Colors
3. Typography
4. Layout (or "Layout & Spacing")
5. Elevation & Depth (or "Elevation")
6. Shapes
7. Components
8. Do's and Don'ts

An optional top-level H1 (#) may precede these for the document title, but it is ignored for ordering validation.

How the CLI Enforces Section Order

The CLI tool validates document structure at runtime using two key source files.

The CANONICAL_ORDER Constant

In packages/cli/src/linter/spec-config.ts, the linter loads the canonical sequence into the CANONICAL_ORDER constant. This array is derived from the YAML spec configuration and provides the authoritative reference sequence against which all DESIGN.md files are compared.

The section-order Rule Implementation

The actual validation logic resides in packages/cli/src/linter/linter/rules/section-order.ts. When the linter parses a file, it compares the observed H2 sequence against the CANONICAL_ORDER array. If a section appears earlier than its predecessor in the canonical list, the rule triggers a finding.

What Happens When You Violate the Section Order

Violating the canonical section order in DESIGN.md does not stop the linter or break the build, but it produces a structured warning. The rule assigns severity "warning" to all ordering violations.

When detected, the linter emits a JSON finding containing the specific violation:

{
  "rule": "section-order",
  "severity": "warning",
  "message": "Section 'Components' appears before 'Colors', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts"
}

Downstream consumers—such as automated exporters and AI agents—depend on predictable section positions to extract design tokens. Out-of-order sections may cause these tools to misinterpret the design system or fail to locate required information.

DESIGN.md Section Order Examples

Correctly Ordered Sections

The following structure passes validation with no warnings:

## Overview

Brand principles and style guidelines.

## Colors

Primary and secondary palettes.

## Typography

Font stacks and scale.

## Layout

Spacing and grid systems.

## Elevation & Depth

Shadow and z-index definitions.

## Shapes

Border radius and corner treatments.

## Components

UI component specifications.

## Do's and Don'ts

Usage guidelines and anti-patterns.

Running the CLI produces no section-order findings:

npx @google/design.md lint examples/paws-and-paths/DESIGN.md

Out-of-Order Sections

Placing Components before Colors violates the canonical sequence:

## Overview

Brand principles.

## Components

Button specifications.

## Colors

Primary palette definitions.

This triggers the linter warning:

{
  "rule": "section-order",
  "severity": "warning",
  "message": "Section 'Components' appears before 'Colors', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts"
}

Summary

• The canonical section order in DESIGN.md mandates eight H2 sections in a fixed sequence: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.
• The constant CANONICAL_ORDER in packages/cli/src/linter/spec-config.ts defines this sequence at runtime.
• The section-order rule in packages/cli/src/linter/linter/rules/section-order.ts validates document structure.
• Violations emit "warning" severity findings but allow processing to continue.
• Following the canonical order ensures compatibility with the design.md CLI, exporters, and AI agents that consume design system files.

Frequently Asked Questions

What is the canonical section order in DESIGN.md?

The canonical order requires eight H2 sections in this exact sequence: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts. This sequence is defined in docs/spec.md and enforced by the CLI linter.

Does violating the section order break the build?

No. Violations generate a "warning" severity finding via the section-order rule, but the linter continues processing the document. However, downstream tools and AI agents may fail to correctly parse or export the design system if sections are out of order.

Where is the canonical order defined in the source code?

The canonical order is defined in the human-readable specification at docs/spec.md and exposed programmatically in packages/cli/src/linter/spec-config.ts through the CANONICAL_ORDER constant. The validation logic resides in packages/cli/src/linter/linter/rules/section-order.ts.

Can I add custom sections to a DESIGN.md file?

The analysis does not mention support for custom sections outside the canonical eight. The linter validates against the fixed CANONICAL_ORDER array, so adding non-standard H2 sections would likely trigger additional warnings or be ignored by downstream parsers.

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