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

> Discover what happens when your DESIGN.md file misses primary color or typography tokens. The linter warns, allowing builds to succeed while auto-generating defaults.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-07-03

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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)](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)](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)](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:

```markdown
---
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:

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

```

```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:

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

```

The resulting output:

```json
{
  "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:

```typescript
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`](https://github.com/google-labs-code/design.md/blob/main/missing-primary.ts) and [`missing-typography.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-primary.ts) and [`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).
- 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.