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

> Discover the canonical section order in DESIGN.md: Overview, Colors, Typography, Layout, and more. Learn about CLI enforcement and violations in this essential guide for maintaining design consistency.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```json
{
  "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:

```markdown

## 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:

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

```

### Out-of-Order Sections

Placing `Components` before `Colors` violates the canonical sequence:

```markdown

## Overview

Brand principles.

## Components

Button specifications.

## Colors

Primary palette definitions.

```

This triggers the linter warning:

```json
{
  "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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and exposed programmatically in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.