Fixing section-order in DESIGN.md

The section-order rule fires with severity: warning when two or more recognized Markdown sections appear in a different order than the canonical sequence. Only the first out-of-order pair is reported per file. The warning is advisory; the file is accepted and can be exported.

Why section order matters#

The @google/design.md spec defines a canonical reading order for the eight Markdown sections in the body of a DESIGN.md file. That order follows the natural hierarchy of a design system: you define the brand overview, then the color palette, then typography, then layout constraints, then depth, then shapes, then assembled components, and finally usage guidance. When sections appear in a different order, agent tools that skim the prose in sequence may encounter components before understanding the color palette they reference, or encounter layout constraints without the typographic context they depend on.

The rule is advisory (warning, not error) because a DESIGN.md file with out-of-order sections is still structurally valid. Every section and token is parsed regardless of order. The warning is a signal that the prose narrative is out of sequence, which may reduce the quality of agent reasoning, not that the file is broken.

The canonical section order#

The linter recognizes eight canonical section names and enforces this sequence:

Overview (aliases: Brand & Style)
Colors
Typography
Layout (aliases: Layout & Spacing)
Elevation & Depth (aliases: Elevation)
Shapes
Components
Do's and Don'ts

Only sections whose headings match a canonical name or a recognized alias are checked. Custom sections (e.g., ## Motion or ## Iconography) are transparent to the rule and do not affect the order check.

You do not need to include all eight sections. The rule checks only the sections that are present. Two present sections are checked against each other; three sections are checked pairwise in sequence; and so on.

What triggers it#

The rule iterates through the list of recognized sections in the order they appear in the file. For each adjacent pair, it checks whether the first section's canonical position is after the second section's canonical position. If so, it emits a warning for that pair and stops (only one finding per file, regardless of how many additional pairs are out of order).

Example that trips the rule:

---
name: Cobalt Studio
colors:
  primary: "#1A2B6B"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Components

Button and card styles referencing Cobalt palette tokens.

## Colors

A deep cobalt blue as the primary with a warm neutral surface.

## Typography

Inter at 16 px for body text.

Components appears before Colors, which violates the canonical order. The linter emits:

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

Note: only the first violation is reported. If Typography also appeared before Colors, that would not produce a second finding in the same run.

How to fix#

Reorder the ## sections in the Markdown body to match the canonical sequence.

Step 1: Identify which recognized sections are present in your file. Custom sections can remain wherever they are.

Step 2: Move the recognized sections to match the canonical order. You only need to order the recognized ones; custom sections can sit between them without triggering the rule.

Step 3: Run npx @google/design.md lint DESIGN.md to confirm the warning is gone.

Corrected example:

---
name: Cobalt Studio
colors:
  primary: "#1A2B6B"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Colors

A deep cobalt blue as the primary with a warm neutral surface.

## Typography

Inter at 16 px for body text.

## Components

Button and card styles referencing Cobalt palette tokens.

The three recognized sections now appear in canonical order: Colors (position 2), Typography (position 3), Components (position 7). The rule passes.

Aliases and partial section names#

A section heading that exactly matches a recognized alias is treated as the canonical section for ordering purposes. For example, ## Brand & Style is treated as Overview (position 1), and ## Layout & Spacing is treated as Layout (position 4). The alias comparison is case-sensitive and must be an exact string match, not a substring.

A heading that does not match any canonical name or alias is ignored by the rule. It passes through without affecting the position check.

Automatic reordering via the JavaScript API#

The @google/design.md package exposes a fixSectionOrder utility in its JavaScript API. This function reads a DESIGN.md string, identifies the canonical sections, reorders them, and returns the corrected string with all prose content preserved. The CLI lint command reports the violation but does not reorder automatically.

missing-sections: info finding when spacing or rounded are absent.
unknown-key: warns when a top-level YAML key looks like a typo.
CLI and Lint Rules Reference: full rules table and command reference.

Try it in the tool

Was this page helpful?