What Happens If a DESIGN.md File Is Missing Primary Color or Typography Tokens?

When a DESIGN.md file lacks primary color or typography tokens, the Design-MD linter emits warnings (not errors), allowing the build to succeed while alerting authors that agents will auto-generate colors and default fonts.

The google-labs-code/design.md repository provides a markdown-based specification for declaring design system tokens. If your DESIGN.md file is missing primary color or typography tokens, the CLI linter flags these omissions as warnings rather than fatal errors. This ensures the design system remains parseable while clearly notifying authors that they are relinquishing deterministic control over core visual elements.

How the Design-MD Linter Detects Missing Tokens

The linter implements specific rules to audit token completeness. These rules run during the linting process and surface guidance without halting execution.

Missing Primary Color Detection

The missing-primary rule, implemented in [packages/cli/src/linter/linter/rules/missing-primary.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-primary.ts), verifies that the colors map contains a primary entry. When the map is non-empty but lacks primary, the linter returns a warning with the message:

“No ‘primary’ color defined. The agent will auto‑generate key colors, reducing your control over the palette.”

Missing Typography Tokens Detection

The missing-typography rule, located in [packages/cli/src/linter/linter/rules/missing-typography.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-typography.ts), checks that at least one typography token exists when colors are present. If the typography map is empty, the linter produces the warning:

“No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity.”

Consequences for Downstream Agents and Tools

When these warnings are present, consuming agents fall back to automated defaults rather than authored specifications.

• Auto-generated colors: Agents generate derived values like primary-fixed and primary-dim algorithmically rather than using defined palette values.
• Default system fonts: Without typography tokens, agents resort to system default fonts rather than specified font families.
• Continued parsing: Because the severity is warning (not error), the linting process exits with code 0 and the DESIGN.md file remains valid for consumption.

Specification Requirements vs. Runtime Behavior

According to the DESIGN.md specification in [docs/spec.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), the Colors section mandates that “at least the primary color palette must be defined.” Similarly, the specification expects a Typography section for complete design systems.

However, the linter enforces these requirements leniently at runtime. The distinction between specification ideals and linter behavior allows incomplete design systems to be prototyped and parsed, though the warnings encourage authors to comply with the full specification for production use.

Code Examples

Linting a DESIGN.md Without Primary Color

Consider a DESIGN.md file that defines secondary colors but omits the primary palette:

---
name: Example System
colors:
  secondary: "#ff8800"
typography:
  body:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
---

Running the CLI linter produces a JSON report with the warning:

bun run cli lint examples/invalid/DESIGN.md --format json

{
  "findings": [
    {
      "path": "colors",
      "message": "No 'primary' color defined. The agent will auto‑generate key colors, reducing your control over the palette.",
      "severity": "warning"
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 0 }
}

Linting a DESIGN.md Without Typography

When typography tokens are absent, the linter surfaces the missing-typography warning:

---
name: Example System
colors:
  primary: "#1a1c1e"
  secondary: "#6c7278"
---

The resulting output:

{
  "findings": [
    {
      "path": "typography",
      "message": "No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity.",
      "severity": "warning"
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 0 }
}

Programmatic Linting via JavaScript API

You can invoke the same rule set programmatically using the @design-md/cli package:

import { lint } from '@design-md/cli';

const content = `---
name: Example
colors:
  secondary: "#ff8800"
---`;

const report = lint(content);
console.log(report.summary.warnings); // → 1 (missing primary)

The lint function processes the content through the same rules defined in missing-primary.ts and missing-typography.ts, returning a report object identical to the CLI output.

Summary

• Missing primary color or typography tokens in DESIGN.md triggers warnings from the missing-primary and missing-typography linter rules, not fatal errors.
• The linter implementation resides in packages/cli/src/linter/linter/rules/missing-primary.ts and packages/cli/src/linter/linter/rules/missing-typography.ts.
• Agents auto-generate color values and fallback to system fonts when tokens are absent, reducing author control over the visual identity.
• Builds succeed (exit code 0) despite warnings, allowing iterative development while encouraging compliance with the DESIGN.md specification.

Frequently Asked Questions

Does missing primary color break the build?

No. Missing primary color triggers a warning with severity level warning, not error. The linting process completes with exit code 0, and the DESIGN.md file remains parseable. However, the warning indicates that agents will auto-generate key colors, reducing your control over the palette.

What auto-generated colors do agents use when primary is missing?

When the primary color is undefined, agents algorithmically generate derived tokens such as primary-fixed and primary-dim. These are computed automatically rather than sourced from your declared palette, which may result in colors that do not match your intended brand identity.

Is typography strictly required by the DESIGN.md specification?

While the DESIGN.md specification expects a Typography section for complete design systems, the linter treats missing typography as a warning rather than a hard requirement. The missing-typography rule specifically checks for typography tokens only when colors are present, ensuring that color-only systems can still be linted.

How do I check for these warnings programmatically?

Import the lint function from @design-md/cli and pass your DESIGN.md content as a string. The function returns a report object containing a findings array where you can filter by severity === 'warning' and check the path property for colors or typography to detect missing tokens.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}