The missing-sections Rule in DESIGN.md

What the rule checks#

The rule examines exactly two token maps: spacing and rounded. For each one, it asks:

1. Is the colors map non-empty? (If colors is empty, no finding fires for either section.)
2. Is this map empty?
3. Is the group not listed in the omitted key? (A listed group is skipped; see Skipping spacing or rounded on purpose.)

If all three conditions hold for a given section, the rule emits a finding for that section. The two sections are checked independently, so you can silence one without addressing the other.

The two messages, exactly as emitted:

{
  "severity": "info",
  "path": "spacing",
  "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
  "rule": "missing-sections"
}

{
  "severity": "info",
  "path": "rounded",
  "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults.",
  "rule": "missing-sections"
}

The rule does not check typography (that is covered by missing-typography, severity: warning) and does not check components or any other section.

Precondition: colors must be non-empty#

The rule is gated on state.colors.size > 0. A file with no colors entries at all (or with no YAML frontmatter) will produce no missing-sections findings even if spacing and rounded are also absent.

This design reflects that a completely empty or prose-only DESIGN.md has not yet expressed a design system. The rule only fires once the file demonstrates intent by defining at least one color.

What triggers it#

Example that trips both findings:

---
name: Blueprint UI
colors:
  primary: "#1D4ED8"
  on-primary: "#FFFFFF"
  surface: "#F1F5F9"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Colors

A blue-primary system with a light surface.

colors has three entries. spacing and rounded are both absent. The linter emits two findings (alongside others from different rules):

[
  {
    "severity": "info",
    "path": "spacing",
    "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
    "rule": "missing-sections"
  },
  {
    "severity": "info",
    "path": "rounded",
    "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults.",
    "rule": "missing-sections"
  }
]

How to read it, and when to act#

missing-sections is informational. The CLI exit code is 0 even when both findings fire, and no other rule blocks export because of this finding. You can ship a DESIGN.md without spacing or rounded and it will pass the linter.

The practical question is: how much control do you want over layout and shape?

When to leave it as-is

If you are working with a palette-and-type-only system early in a project, or if you are delegating layout decisions entirely to the consuming agent or design tool, you can ignore these findings. The agent will apply its own defaults for margins, padding, and corner radii.

When to act: defining spacing

Add a spacing section when you want to enforce a spacing scale across generated output. The spec accepts plain dimension values (px, rem, em):

spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 48px

Agents use the spacing tokens to populate padding and margin properties, and the export command includes them in the Tailwind and DTCG output.

When to act: defining rounded

Add a rounded section when your brand has a distinct shape language. Rounded values are also used by the rounded sub-token in component definitions:

rounded:
  none: 0
  sm: 4px
  md: 8px
  lg: 16px
  full: 9999px

The spec-recommended token names are none, sm, md, lg, xl, and full. Using canonical names lets the export and agent layers map them to Tailwind's built-in rounding scale without manual aliasing.

Skipping spacing or rounded on purpose#

If the design system has no spacing scale or no corner radius by design, say so with the omitted key instead of leaving the finding in place. List the group as a plain name, or as an object with a reason:

---
name: Blueprint UI
omitted:
  - spacing
  - section: rounded
    reason: "Square corners everywhere, per the brand book"
colors:
  primary: "#1D4ED8"
  on-primary: "#FFFFFF"
  surface: "#F1F5F9"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Colors

A blue-primary system with a light surface.

Both missing-sections findings are gone. In their place, the omitted-rules check reports each declared group as an info:

[
  {
    "severity": "info",
    "path": "omitted.spacing",
    "message": "spacing intentionally omitted \u2014 no spacing tokens will be validated",
    "rule": "declared-omission"
  },
  {
    "severity": "info",
    "path": "omitted.rounded",
    "message": "rounded intentionally omitted \u2014 no rounded tokens will be validated",
    "rule": "declared-omission"
  }
]

The info count stays the same, but the findings now record that the gap is intentional. The CLI prints an em dash in these messages; the JSON escape \u2014 above stands for it. Listing a group that does have tokens produces a redundant-omission warning, and a misspelled group name produces an unknown-omission warning and suppresses nothing. See the omitted key for the full syntax.

Interaction with components#

Once you define rounded tokens, components can reference them:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px

Using {rounded.md} instead of a literal 8px keeps your components aligned with the token scale. If you later change rounded.md from 8px to 6px, all components using the reference update automatically.

Suppressing infos in CI#

Both token-summary and missing-sections are info-severity. If your CI only needs to gate on warnings and errors:

npx @google/design.md lint DESIGN.md --format json \
  | jq '.summary | .errors == 0 and .warnings == 0'

This returns true when the file is clean of errors and warnings, ignoring all info-level findings.

Related rules#

• omitted-rules: the omitted key that marks a skipped group as intentional, and the findings that validate it.
• token-summary: info that reports the total count of defined tokens across all sections.
• orphaned-tokens: warning when a color token is defined but no component references it.
• missing-primary: warning when colors are defined but no primary key is present.
• CLI and Lint Rules Reference: full rules table and severity summary.

Try it in the tool