Canonical Section Order in DESIGN.md: Structure, Rules, and Validation

DESIGN.md files must follow a strict eight-section sequence so that automated tools and AI agents can reliably parse design system documentation, with violations triggering linter warnings but not blocking execution.

The canonical section order in DESIGN.md is a core requirement of the google-labs-code/design.md specification. This ordering ensures that CLI tools, exporters, and downstream automation can locate specific design tokens and guidelines without heuristic parsing. When authoring or maintaining design system documentation, understanding this sequence is essential for compliance and tool compatibility.

The Eight-Section Canonical Order

DESIGN.md files must organize content using exactly eight <h2> headings in this specific sequence:

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

This sequence is defined in the human-readable specification at [docs/spec.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and exposed programmatically through the constant CANONICAL_ORDER in packages/cli/src/linter/spec-config.ts. An optional top-level <h1> title may precede these sections but is ignored for validation purposes.

How the Linter Validates Section Order

The CLI linter enforces this structure through the section-order rule implemented in [packages/cli/src/linter/linter/rules/section-order.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/section-order.ts). When the linter scans a DESIGN.md file, it compares the actual heading sequence against the CANONICAL_ORDER array defined in the spec configuration.

If a later canonical section appears before an earlier one, the rule emits a finding with "warning" severity. The linter continues processing the remainder of the document; it does not halt execution or treat the violation as an error.

What Happens When Sections Are Out of Order

Violating the canonical section order produces a specific diagnostic message that identifies the misplaced section and the expected sequence. While the linter continues to process the file, downstream consumers—particularly automated agents and export tools that rely on positional parsing—may fail to locate required information or misinterpret the design system structure.

Practical Examples

Correctly Ordered Sections

The following structure produces no section-order warnings:

## Overview

Brand guidelines and design principles...

## Colors

Primary and secondary palettes...

## Typography

Font families and scale...

## Layout

Grid systems and spacing...

## Elevation & Depth

Shadow values and z-index...

## Shapes

Corner radius and forms...

## Components

Button, card, and input specifications...

## Do's and Don'ts

Usage guidelines and anti-patterns...

Running the validation:

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

This execution completes with no findings related to section order.

Incorrect Section Order

Placing Components before Colors triggers a warning:

## Overview

...

## Components

Button specifications...

## Colors

Primary palette...

Validation output:

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

{
  "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

• Canonical sequence: DESIGN.md requires eight specific sections in a fixed order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.
• Source of truth: The order is defined in docs/spec.md and implemented via the CANONICAL_ORDER constant in packages/cli/src/linter/spec-config.ts.
• Validation: The section-order rule in packages/cli/src/linter/linter/rules/section-order.ts checks compliance and emits warnings for violations.
• Impact: Out-of-order sections generate warnings but do not stop processing; however, they may break compatibility with automated tools and AI agents consuming the document.

Frequently Asked Questions

What is the exact canonical section order for DESIGN.md?

The exact order is: Overview, Colors, Typography, Layout (or Layout & Spacing), Elevation & Depth (or Elevation), Shapes, Components, and Do's and Don'ts. All must use <h2> markdown headings (##). This sequence is hardcoded in the CANONICAL_ORDER constant and documented in the specification.

Does the DESIGN.md linter stop execution when sections are out of order?

No. The linter assigns "warning" severity to section-order violations and continues processing the document. This allows authors to view multiple issues in a single run, though the warnings indicate that automated consumers may misinterpret the file structure.

Where is the canonical order defined in the source code?

The canonical order is defined in two locations: the human-readable specification at [docs/spec.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and the runtime configuration at [packages/cli/src/linter/spec-config.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts), which exports the CANONICAL_ORDER array used by the linter and other tools.

Can I use an H1 title in my DESIGN.md file?

Yes. An optional top-level <h1> heading (#) may be used for the document title, but it is ignored for section-order validation. Only the eight canonical <h2> sections are validated against the required sequence.

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