# How to Extend DESIGN.md with Custom YAML Keys: A Complete Guide

> Learn how to extend DESIGN.md with custom YAML keys in this complete guide. Preserve your custom data for downstream tools and keep your files clean.

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

---

**You can add any top-level YAML key to DESIGN.md as a custom extension, and the linter will ignore keys that are not close matches to schema fields while preserving them for downstream tools.**

The google-labs-code/design.md repository defines a token schema that is intentionally extensible. While the specification governs standard keys like `colors` and `typography`, the parser and linter accept arbitrary top-level YAML keys without breaking validation. This architecture allows design systems to store metadata, branding guidelines, or integration-specific data alongside official design tokens.

## How Custom YAML Keys Work in DESIGN.md

The extension mechanism relies on three core components that distinguish between schema violations and intentional custom data.

### Permissive YAML Parsing

In [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts), the front-matter loader uses a permissive YAML parser that produces a plain JavaScript object. Unlike strict schemas that reject unknown properties, this parser accepts any syntactically valid YAML key as a top-level property, loading the entire front matter into a generic object that preserves custom extensions.

### The Unknown-Key Lint Rule

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) implements intelligent typo detection using **Levenshtein distance** calculations. When the linter encounters a key not defined in the official schema, it computes the edit distance between the unknown key and all known schema keys. If the distance falls below a configurable threshold, the linter warns of a probable typo. Keys with distances above the threshold are treated as custom extensions and generate no findings.

### Consumer Behavior for Unknown Content

According to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), the **Consumer Behavior for Unknown Content** section mandates that tools must accept unknown keys provided their values are syntactically valid. When consuming DESIGN.md files, the CLI and other tools copy these custom keys through unchanged, enabling round-tripping and allowing specialized agents to read the additional data.

## Adding Custom YAML Keys to Your DESIGN.md

To extend your design tokens with custom metadata, add any valid YAML key at the top level of your front matter. Choose names that are distinct from standard schema keys to avoid typo warnings.

```yaml
---
name: Aurora
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem

# Custom extension - preserved but ignored by standard linting

branding:
  logo: "./assets/logo.svg"
  tagline: "Bright ideas, bold design"
---

```

The `branding` key above is not part of the official DESIGN.md schema, but it remains valid. The linter will not flag it because "branding" is sufficiently different from known keys like `colors` or `name`.

## Accessing Custom Keys Programmatically

When parsing DESIGN.md files in your own tools, the custom keys appear in the parsed front matter object alongside standard properties.

```typescript
import { parseDesignMd } from '@google/design.md/parser';

const markdown = await Deno.readTextFile('DESIGN.md');
const { frontMatter } = parseDesignMd(markdown);

// Access custom extension data
console.log(frontMatter.branding?.logo);   // → "./assets/logo.svg"
console.log(frontMatter.branding?.tagline); // → "Bright ideas, bold design"

```

Because the parser in [`spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/spec-config.ts) loads the YAML into a generic object without filtering unknown properties, your custom data remains accessible throughout the pipeline.

## Validating DESIGN.md Files with Custom Extensions

Run the linter to verify that your custom keys do not trigger warnings:

```bash
npx @google/design.md lint DESIGN.md

# Exits with code 0 - no warnings for custom keys

```

If you accidentally use a key close to a standard one, such as `colours` instead of `colors`, the `unknown-key` rule will emit a warning suggesting the correction. To silence this, either correct the spelling or choose a more distinct custom key name like `brandColors` or `customColours`.

## Summary

- **Add any top-level key** to DESIGN.md front matter to store custom metadata alongside design tokens.
- The **permissive parser** in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts) loads all YAML keys into a generic object without filtering.
- The **unknown-key rule** uses Levenshtein distance to distinguish between typos and intentional custom extensions.
- **Consumer behavior** mandates that unknown keys are preserved during export and round-tripping, making them available to downstream tools.
- **Choose distinct names** for custom keys to avoid triggering typo warnings from the linter.

## Frequently Asked Questions

### Will custom YAML keys break the DESIGN.md linter?

No. The linter explicitly tolerates unknown keys that are not close matches to schema fields. As 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), the rule only warns when an unknown key appears to be a misspelling of a known property. Truly custom keys with distinct names pass validation silently.

### How do I prevent the linter from flagging my custom key as a typo?

Ensure your custom key name has a Levenshtein distance greater than the configurable threshold from all standard schema keys. For example, use `brandMetadata` instead of `color` or `colour`. If the linter suggests a correction, your key name is too similar to an existing schema field.

### Are custom keys preserved when exporting design tokens?

Yes. According to the consumer behavior specification in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), tools must copy unknown keys through unchanged during export operations. This guarantees round-tripping and allows external pipelines to access custom metadata stored in the DESIGN.md file.

### Can I add custom keys at nested levels within standard schema objects?

The extension mechanism primarily targets top-level keys. While the permissive YAML parser may preserve nested unknown properties, the `unknown-key` rule and consumer behavior guarantees focus on top-level extensions. For maximum compatibility with DESIGN.md tooling, place custom keys at the root level of your YAML front matter.