Feature: `omitted` key to declare intentional absence and suppress expected-missing warnings

[GenerationUX]

Problem

The spec states that sections "can be omitted if they're not relevant to your project." But the linter has no way of distinguishing a deliberate omission from an oversight. The result is that well-formed, intentionally scoped DESIGN.md files produce spurious warnings that degrade trust in the linter's signal.

The affected rules are missing-sections and missing-typography. Both fire when tokens are absent — but absence is often correct.

Example: a historical corporate identity

---
version: alpha
name: "Swiss Federal Railways — 1972 Signage System"
colors:
  primary: "#E30613"
  on-primary: "#FFFFFF"
  neutral: "#000000"
typography:
  body-md:
    fontFamily: Helvetica
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.4
---

## Overview

Hans-Rudolf Bosshard's 1972 signage system for SBB. Reduced palette;
no spacing scale and no component abstraction are defined because
neither concept existed in the source material.

Running lint against this file produces:

{
  "findings": [
    {
      "severity": "warning",
      "rule": "missing-sections",
      "message": "spacing and rounded sections absent when other tokens exist — agents will use defaults"
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 2 }
}

The warning is correct in the narrow sense — spacing and rounded are absent. But the file is not incomplete. The gaps are accurate. The linter has no way to know that, and neither does any downstream consumer reviewing the findings.

Context

We have been building a corpus of ~5,000 DESIGN.md files documenting historical design systems — print, broadcast, corporate identity, signage, publications — across roughly a century of output. A large proportion of files correctly omit spacing, rounded, and components because those abstractions do not exist in the source material. Linting across the corpus produces several hundred warnings of this type. All of them are accurate observations; none of them indicate an error in the file.

The problem is not that the warnings fire — it is that there is no mechanism to acknowledge them. There is no way for an author to say "I know this section is absent; that is correct" and have the linter confirm the acknowledgement rather than repeat the warning.

Proposal

Add an optional omitted top-level key to the YAML front matter. Its value is a list of section names that are intentionally absent. The linter suppresses missing-sections and missing-typography warnings for any section listed in omitted, and emits a single info finding per entry confirming the declaration was seen.

Schema addition

omitted:
  - <section-name>      # one of: colors, typography, spacing, rounded, components
  # ...

An optional reason field per entry provides human-readable context for why the section is absent:

omitted:
  - section: spacing
    reason: "No spacing scale defined in source material"
  - section: components
    reason: "Component abstraction not applicable to 1972 signage system"

Both forms (bare string and object with reason) should be accepted. reason is informational only — it has no effect on linter behaviour.

Linter behaviour change

Scenario	Current behaviour	Proposed behaviour
missing-sections warning for a section listed in omitted	warning emitted	warning suppressed; info emitted: "spacing intentionally omitted — declared in omitted key"
missing-typography warning when typography listed in omitted	warning emitted	warning suppressed; info emitted
Section listed in omitted but tokens are present	n/a	warning emitted: "spacing listed in omitted but spacing tokens are defined — omitted declaration has no effect"
Unknown section name in omitted	n/a	warning emitted: "unknown section name 'iconography' in omitted key"

New linting rule

Rule	Severity	What it checks
declared-omission	info	Section listed in omitted key; absence acknowledged and suppressed
redundant-omission	warning	Section listed in omitted but tokens for that section are present
unknown-omission	warning	Unrecognised section name in omitted key

Example output

{
  "findings": [
    {
      "severity": "info",
      "rule": "declared-omission",
      "path": "omitted.spacing",
      "message": "spacing intentionally omitted — no spacing tokens will be validated"
    },
    {
      "severity": "info",
      "rule": "declared-omission",
      "path": "omitted.components",
      "message": "components intentionally omitted — no component tokens will be validated"
    }
  ],
  "summary": { "errors": 0, "warnings": 0, "info": 4 }
}

What this does not change

• Files without an omitted key behave identically to today. This is purely additive.
• missing-primary is not suppressed by omitted. That rule concerns naming convention within a present colors section, not the absence of a section.
• broken-ref is not suppressed. If tokens reference absent sections, that remains an error.
• The export and diff commands are unaffected. omitted is a linter hint, not a schema constraint.

Version

@google/design.md 0.1.1

Happy to contribute a PR if the direction is accepted.