# How DESIGN.md Handles Unknown Content: Parsing, Preservation, and Linting

> DESIGN.md preserves unknown content, surfacing warnings for typos and unparseable maps while ensuring safe export. Learn how DESIGN.md handles unrecognized YAML and markdown sections.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: internals
- Published: 2026-06-30

---

**DESIGN.md preserves unrecognized YAML keys and markdown sections while surfacing targeted warnings for potential typos or token-like maps that will be silently ignored during export.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) CLI employs a tolerant parsing strategy that accepts unknown content without failing, storing unrecognized keys for later linting analysis. This architecture separates the parsing phase from validation rules, allowing design systems to carry extra metadata while maintaining strict schema compliance where it matters.

## Parsing and Storing Unknown YAML Keys

When the CLI parses a DESIGN.md file, it constructs a `ParsedDesignSystem` object defined in [`packages/cli/src/linter/parser/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/spec.ts). While the `SCHEMA_KEYS` constant enumerates known top-level YAML keys—such as `version`, `name`, `colors`, and `typography`—the parser deliberately stores every entry, recognized or not, in the `rawValues` record.

During the conversion from `ParsedDesignSystem` to the runtime `DesignSystemState` model (defined in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts)), the handler in [`packages/cli/src/linter/model/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/handler.ts) populates two specific fields for unknown data:

- `unknownKeys`: An array of strings containing top-level keys not present in `SCHEMA_KEYS`
- `unknownKeyValues`: A record mapping those unknown keys to their raw YAML values

This preservation ensures that no data is lost during parsing, allowing subsequent lint rules to analyze the content and determine if it represents a typo, a valid extension, or a token map that will be dropped during export.

## Lint Rules for Unknown Content

The linter examines captured unknown keys through specialized rules that emit **warnings** rather than errors, ensuring that unrecognized content never blocks the build pipeline.

### Detecting Typographical Errors

The `unknown-key` rule, implemented in [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts), employs Levenshtein distance calculations to detect when an unknown key closely resembles a known schema key. When a potential typo is detected—such as `colours` instead of `colors`—the rule emits a warning with a suggested correction:

```json
{
  "severity": "warning",
  "path": "colours",
  "message": "Unknown key \"colours\" — did you mean \"colors\"?"
}

```

### Identifying Ignored Token Maps

The `token-like-ignored` rule in [`packages/cli/src/linter/linter/rules/token-like-ignored.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/token-like-ignored.ts) identifies unknown keys whose values resemble design-token maps—containing hex colors, CSS dimensions, or typography property names. This catches cases where users mistakenly use non-standard top-level keys for tokens that the export commands will silently ignore:

```json
{
  "severity": "warning",
  "path": "brandTokens",
  "message": "\"brandTokens\" looks like a design-token map but is not a recognized schema key (colors, typography, spacing, rounded, components). It will be silently ignored by export commands."
}

```

## Handling Unknown Markdown Sections

For markdown content, the parser stores all section headings in `state.sections` regardless of whether they match the canonical schema. The `section-order` rule in [`packages/cli/src/linter/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/section-order.ts) validates that known sections appear in the correct sequence based on `CANONICAL_ORDER` and `SECTION_ALIASES` definitions, but it never raises errors for unrecognized headings.

According to the consumer behavior documented in [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md), unknown section headings are **preserved** without error, while only duplicate headings trigger rejection. This allows documentation to contain supplementary sections—such as implementation notes or changelog entries—without breaking the linting process.

## CLI Output and Report Structure

When running `npx @google/design.md lint DESIGN.md`, the compiler aggregates findings into a JSON report. Each warning includes the severity level, the path to the unknown key, and a descriptive message:

```json
{
  "findings": [
    {
      "severity": "warning",
      "path": "colours",
      "message": "Unknown key \"colours\" — did you mean \"colors\"?"
    },
    {
      "severity": "warning",
      "path": "brandTokens",
      "message": "\"brandTokens\" looks like a design-token map but is not a recognized schema key..."
    }
  ],
  "summary": { "errors": 0, "warnings": 2, "info": 0 }
}

```

The `path` field corresponds directly to entries in `unknownKeys`, providing precise feedback on where unrecognized content appears in the YAML frontmatter.

## Practical Example

The following TypeScript example demonstrates how the programmatic API surfaces unknown content handling:

```typescript
import { lint } from '@google/design.md/linter';

const markdown = `
---
name: Demo
colours:               # typo of "colors"

  primary: "#112233"
brandTokens:           # token-like but unrecognized

  accent: "#ff00ff"
---

## Overview

A quick demo.

## Colours               # unknown heading (preserved)

Some description.
`;

const report = lint(markdown);

console.log(report.findings);
// Output includes warnings for 'colours' typo and 'brandTokens' being ignored

```

## Summary

- **Unknown YAML keys** are preserved in `unknownKeys` and `unknownKeyValues` fields during parsing in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts).
- The **`unknown-key`** rule detects potential typos using Levenshtein distance and suggests corrections.
- The **`token-like-ignored`** rule warns when unrecognized keys contain values that resemble design tokens but will be ignored by export commands.
- **Unknown markdown sections** are preserved; only ordering violations of known sections trigger warnings via the `section-order` rule.
- All unknown content handling produces **warnings**, never errors, allowing exports to proceed while informing authors of potential issues.

## Frequently Asked Questions

### Does DESIGN.md fail validation when it encounters unknown keys?

No. The parser in [`packages/cli/src/linter/parser/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/parser/spec.ts) stores unrecognized keys in `DesignSystemState.unknownKeys` and continues processing. Validation only produces warnings, not errors, ensuring that exports can complete even with extra metadata present.

### How does DESIGN.md distinguish between a typo and an intentional custom key?

The linter uses the `unknown-key` rule in [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts) to calculate Levenshtein distance between unrecognized keys and known schema keys. If the distance is small (indicating a likely typo), it suggests the correct spelling; otherwise, it treats the key as an intentional unknown and checks if it contains token-like data via the `token-like-ignored` rule.

### Will unknown sections in the markdown body be removed during export?

No. Unknown markdown sections are preserved in the document state. The `section-order` rule in [`packages/cli/src/linter/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/section-order.ts) only validates the sequence of known canonical sections, leaving supplementary headings intact for documentation purposes.

### What happens to design tokens defined under unknown keys?

Values under unknown keys that resemble token maps (hex colors, dimensions, or typography objects) trigger a `token-like-ignored` warning. These tokens are not exported to the final design system because the export commands only recognize keys defined in `SCHEMA_KEYS`, causing the data to be silently dropped while the build continues.