# Canonical Section Order in DESIGN.md: Structure, Rules, and Validation > Learn the canonical section order for DESIGN.md files. Discover the 8 required sections and how violations trigger linter warnings. Ensure reliable parsing for your design system documentation. - Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md) - Tags: deep-dive - Published: 2026-07-03 --- **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`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) is a core requirement of the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files must organize content using exactly eight `

` 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)](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and exposed programmatically through the constant [`CANONICAL_ORDER`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts) 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). An optional top-level `

` 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)](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`](https://github.com/google-labs-code/design.md/blob/main/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: ```markdown ## 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: ```bash 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: ```markdown ## Overview ... ## Components Button specifications... ## Colors Primary palette... ``` Validation output: ```bash npx @google/design.md lint examples/paws-and-paths/DESIGN.md ``` ```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 - **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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and implemented via 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). - **Validation**: 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) 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 `

` 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)](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)](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 `

` heading (#) may be used for the document title, but it is ignored for section-order validation. Only the eight canonical `

` sections are validated against the required sequence.