Understanding missing-sections 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?

If both 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."
}

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

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."
  },
  {
    "severity": "info",
    "path": "rounded",
    "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults."
  }
]

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.

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#

• 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