DESIGN.md Section Order Requirements: Canonical Structure Explained

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 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 and generated from 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.

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 and resolved at runtime by the resolveAlias function in 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, 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:

# 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. When sections appear out of order, you can automatically rearrange them to match CANONICAL_ORDER without manual editing.

Run the fixer:

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:

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.
• Optional sections can be omitted, but if present must occupy their canonical positions.
• The linter rule in 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. 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 to rearrange sections into the canonical order defined by the CANONICAL_ORDER constant.

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