lint should warn when frontmatter token-like fields are ignored by export

[NickAnthony]

Summary

design.md lint should warn when frontmatter contains token-like fields that will be ignored by exporters.

Right now, a DESIGN.md file can contain explicit design-token data, pass lint, and then export incomplete Tailwind output because the token-like fields are not part of the recognized schema.

Why this matters

My use case is to have an LLM generate a DESIGN.md file, then use design.md lint to tell the agent how to fix it before exporting tokens.

A successful lint plus successful export implies the exported Tailwind theme represents the DESIGN.md. In this case, export silently drops the color palette, so downstream agents or build tools may trust an incomplete Tailwind config.

Reproduction

Given a DESIGN.md file like:

---
brand_name: "Example"
base_colors:
  ink: "#0B0F14"
  paper: "#F6F7FA"
semantic_colors:
  background: "#F6F7FA"
  foreground: "#0B0F14"
typography:
  body:
    fontFamily: "Inter"
---

Run:

npx --yes @google/design.md@0.2.0 lint --format json DESIGN.md
npx --yes @google/design.md@0.2.0 export --format json-tailwind DESIGN.md

Observed export:

{
  "theme": {
    "extend": {
      "colors": {},
      "fontFamily": {
        "body": ["Inter"]
      }
    }
  }
}

Expected behavior

lint should warn that base_colors and semantic_colors are not recognized token fields and will not be exported.

More generally, lint should warn when unsupported frontmatter fields look like design tokens, such as:

• maps containing hex color values
• maps containing typography properties like fontFamily
• maps containing dimensions or spacing-like values
• DTCG-like token objects with $value / $type

Version

@google/design.md@0.2.0

[davideast]

Hey @NickAnthony! Congrats on being issue/PR 100!

This is a really good point.

My main question is, do you want these keys base_colors and semantic_colors in the export? Or are you saying this is something you want corrected with a lint?

I think we have a few options here. We can warn but we can make linting and exporting more extensible in general. We could set up a way to configure what rules you want to apply or ignore. We'd likely have to set up a whole rule plugin system but the current architecture isn't far from that. You could set up a plugin that processes any or specific parent token properties.

One interesting question I have, would you be interested in solving this problem with grouping?

---
colors:
  base:
    ink: "#0B0F14"
    paper: "#F6F7FA"
  semantic:
    background: "#F6F7FA"
    foreground: "#0B0F14"
---