The omitted Key in DESIGN.md

Why declare an omission#

Not every design system defines every token group. A print-first brand may have no corner radius at all; a component kit may take its fonts from the host app. Before 0.4.0 the linter could not tell a deliberate gap from a forgotten one, so both got the same missing-sections or missing-typography finding. The omitted key records the decision in the file itself, with an optional reason, and the linter stops reporting the gap as missing.

Syntax#

omitted is an optional top-level list. Each entry is either a plain group name or an object with a section name and an optional reason:

omitted:
  - spacing
  - section: rounded
    reason: "No rounded corners defined in brand book"

The upstream spec describes the key as "An array of sections that are intentionally omitted from the design system. This suppresses linter warnings for missing sections (e.g. colors, typography, spacing, rounded, components)." Despite the word "sections", the entries name token groups in the YAML frontmatter, not the ## sections of the Markdown body.

How the linter reads the list in 0.4.0:

• Names are compared without regard to case, so Spacing and ROUNDED work.
• omitted must be a list. A single string such as omitted: spacing is ignored: no omission is recorded, nothing explains why, and missing-sections still reports spacing.
• Object entries without a section string, and bare numbers, are dropped silently.
• The reason never appears in lint output. It is there for people and tools that read the file, including the viewer described below.
• A misspelled key such as omited: is not read as omitted. It gets an unknown-key warning suggesting omitted, and the list has no effect.

The five valid group names#

Each listed group that has no tokens also produces a declared-omission info, so the info count stays the same when an omission replaces a missing-sections finding. The finding now says the gap is intentional.

What omitted does not suppress#

omitted works on whole token groups. It cannot exempt a single token, so it does not affect missing-primary: that rule fires when colors exist without a primary key, and listing colors in a file that defines colors only adds a redundant-omission warning next to it. The other rules (broken-ref, contrast-ratio, orphaned-tokens, token-summary, section-order, unknown-key, token-like-ignored) ignore the list as well.

The findings omitted-rules reports#

The CLI's rules table lists this check as omitted-rules with severity info. Its findings, however, carry one of three rule ids of their own in the JSON rule field, and two of them are warnings.

Two of the messages contain an em dash between their halves. The JSON examples below write it as the escape \u2014, which decodes to the same character the CLI prints.

declared-omission (info)#

When: a valid group is listed and the file defines no tokens for it. Path: omitted.<group>. Message: <group> intentionally omitted, followed by an em dash and no <group> tokens will be validated.

Example:

---
name: Paper Ledger
omitted:
  - spacing
  - section: rounded
    reason: "No rounded corners defined in brand book"
colors:
  primary: "#1F2937"
  on-primary: "#FFFFFF"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
---

## Overview

A print-first system with square corners.

The complete output of npx @google/design.md lint DESIGN.md:

{
  "findings": [
    {
      "severity": "info",
      "message": "Design system defines 2 colors, 1 typography scale.",
      "rule": "token-summary"
    },
    {
      "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"
    }
  ],
  "summary": { "errors": 0, "warnings": 0, "infos": 3 }
}

Without the omitted key, the same file gets two missing-sections infos for spacing and rounded instead. No action is needed for this finding.

redundant-omission (warning)#

When: a group is listed, but the file defines tokens for it, so the entry has no effect. Path: omitted. Message: <group> listed in omitted but <group> tokens are defined, followed by an em dash and omitted declaration has no effect.

Example:

omitted:
  - spacing
spacing:
  md: 16px

{
  "severity": "warning",
  "path": "omitted",
  "message": "spacing listed in omitted but spacing tokens are defined \u2014 omitted declaration has no effect",
  "rule": "redundant-omission"
}

How to fix: remove the entry from omitted, or remove the tokens if the group really is meant to be absent. This happens when a group that was skipped at first gets tokens later.

unknown-omission (warning)#

When: an entry is not one of the five group names. Path: omitted. Message: unknown section name '<name>' in omitted key, with the name as written.

Example:

omitted:
  - spaceing
  - Overview

In a file that defines colors, typography, and rounded tokens but no spacing, 0.4.0 reports these findings next to token-summary:

[
  {
    "severity": "info",
    "path": "spacing",
    "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
    "rule": "missing-sections"
  },
  {
    "severity": "warning",
    "path": "omitted",
    "message": "unknown section name 'spaceing' in omitted key",
    "rule": "unknown-omission"
  },
  {
    "severity": "warning",
    "path": "omitted",
    "message": "unknown section name 'Overview' in omitted key",
    "rule": "unknown-omission"
  }
]

The misspelled spaceing suppresses nothing, so missing-sections still reports spacing. Overview is a Markdown section, not a token group; prose sections that do not apply can simply be left out of the body.

How to fix: correct the spelling to one of colors, typography, spacing, rounded, or components, and remove Markdown section names.

How the viewer shows omitted groups#

The viewer at /tool reads the same list. When a group is declared in omitted and has no tokens, its section shows a note that the tokens are intentionally omitted, followed by the reason when you gave one, instead of the usual empty state. The declared-omission, redundant-omission, and unknown-omission findings appear in the diagnostics with their rule ids and a link to this page.

Related rules#

• missing-sections: info when colors exist but spacing or rounded is absent and not listed in omitted.
• missing-typography: warning when colors exist but no typography tokens are defined and typography is not listed in omitted.
• missing-primary: warning that omitted does not affect.
• token-like-ignored: the other check added in 0.4.0, for token values under keys the schema ignores.
• CLI and Lint Rules Reference: full rules table and command reference.

Try it in the tool