# DESIGN.md Section Order Requirements: Canonical Structure Explained

> Understand DESIGN.md section order requirements and the canonical structure. Learn how linters enforce sequence rules and use the --fix flag for automatic reordering.

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

---

**DESIGN.md files must follow a strict canonical section order defined in the Design MD specification, with the linter enforcing sequence rules and a `--fix` flag available for automatic reordering.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository maintains a specification that governs how design documentation files must be structured. Understanding these **DESIGN.md section order requirements** ensures your documentation passes validation and remains compatible with the toolchain.

## The Canonical Section Order

The specification defines a mandatory sequence for sections. According to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) and generated from [`packages/cli/src/linter/spec-config.yaml`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.yaml), the **canonical order** is defined as 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 eight sections must appear in this exact sequence (when present):

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

### Optional Sections and Positioning Rules

While the eight sections above form the core structure, some sections like *Spacing* and *Rounded* are optional. However, if you include optional sections, they must appear in their designated canonical positions relative to the required sections. Missing optional sections trigger an informational lint (`missing-sections`), but out-of-order placement generates a **warning** (`section-order`).

## How Section Aliases Work

Section headings support alternate names through an alias resolution system. The mapping is defined in [`packages/cli/src/linter/spec-config.yaml`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.yaml) and resolved at runtime by the `resolveAlias` function 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).

For example, writing "Brand & Style" automatically resolves to "Overview", and "Layout & Spacing" resolves to "Layout". This allows flexibility in naming while maintaining strict ordering validation.

## Linter Enforcement and Validation

The repository includes a dedicated linter rule that validates section positioning. Located at [`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), this rule compares your document structure against the canonical order and reports violations.

When the linter detects a sequence error, it outputs:

```

warning: Section 'Colors' appears before 'Overview', which is out of order.

```

To check your file:

```bash

# In the repository root

bun run cli lint path/to/DESIGN.md

```

## Automatic Fixing with --fix

The toolchain provides automatic reordering through the fixer module in [`packages/cli/src/linter/fixer/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/fixer/handler.ts). When sections appear out of order, you can automatically rearrange them to match `CANONICAL_ORDER` without manual editing.

Run the fixer:

```bash
bun run cli lint path/to/DESIGN.md --fix

```

This command rewrites the file with sections positioned according to the canonical specification.

## Programmatic Validation

For custom workflows or CI/CD pipelines, you can programmatically validate section order using the internal API:

```typescript
import { loadSpecConfig } from './packages/cli/src/linter/spec-config.js';
import { sectionOrder } from './packages/cli/src/linter/linter/rules/section-order.js';
import { parseDesign } from './packages/cli/src/linter/model/parser.js';

const spec = loadSpecConfig();               // loads canonical order & aliases
const design = await parseDesign('path/to/DESIGN.md');
const findings = sectionOrder(design);

if (findings.length) {
  console.log('Ordering problems detected:');
  findings.forEach(f => console.log(f.message));
}

```

This approach loads the same configuration used by the CLI, ensuring consistent validation across custom tools.

## Summary

- **DESIGN.md section order requirements** mandate a specific sequence: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.
- Section aliases (like "Brand & Style" for Overview) are resolved automatically via `resolveAlias` in [`spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/spec-config.ts).
- Optional sections can be omitted, but if present must occupy their canonical positions.
- The linter rule in [`section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/section-order.ts) generates warnings for violations, while the `missing-sections` rule provides informational feedback for absent optional sections.
- Use `bun run cli lint path/to/DESIGN.md --fix` to automatically reorder sections according to the specification.

## Frequently Asked Questions

### What happens if I put sections in the wrong order?

The linter generates a warning with the message `Section '<current>' appears before '<next>', which is out of order`, specifying the expected sequence. Your file will still parse, but you lose tooling compatibility and consistent rendering guarantees.

### Can I use alternative names for sections?

Yes. The specification allows aliases defined in [`packages/cli/src/linter/spec-config.yaml`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.yaml). For instance, "Brand & Style" maps to "Overview", and "Elevation" maps to "Elevation & Depth". The `resolveAlias` function normalizes these before validation.

### Are all sections required in every DESIGN.md?

No. While the canonical order must be maintained for present sections, optional sections like *Spacing* and *Rounded* can be omitted. Missing optional sections trigger an informational lint rather than a warning, and the document remains valid.

### How do I automatically reorder sections?

Run the linter with the `--fix` flag: `bun run cli lint path/to/DESIGN.md --fix`. This invokes the fixer handler in [`packages/cli/src/linter/fixer/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/fixer/handler.ts) to rearrange sections into the canonical order defined by the `CANONICAL_ORDER` constant.