# How the missing-primary Warning Affects Agent Behavior in DESIGN.md

> Learn how the missing-primary warning in DESIGN.md triggers auto-generated primary colors, impacting agent behavior and designer control over UI components. Understand the consequences and solutions.

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

---

**The missing-primary warning triggers when a DESIGN.md file defines color tokens but lacks a primary color definition, causing downstream agents to auto-generate a primary color that ensures UI components render correctly while reducing designer control over the final palette.**

The `missing-primary` rule is part of the DESIGN.md linter in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository. This validation ensures design systems remain functional even when designers omit explicit primary color tokens, though it comes with trade-offs in design precision.

## What Triggers the missing-primary Warning

The linter evaluates two conditions 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) before emitting the warning:

1. **Presence of a color palette** – The rule checks if `state.colors.size > 0`, confirming that color tokens exist in the DESIGN.md file.
2. **Absence of primary token** – The rule verifies that no token named `primary` is defined in the color set.

When both conditions are met, the linter emits a warning with `severity: "warning"` and the message: *"No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."* According to the README table (lines 13-15), this warning explicitly states that *"agents will auto-generate one"* if the primary token is missing.

## How Agents Handle the Missing Primary Token

When the warning is triggered, downstream agents consuming the DESIGN.md token set implement automatic fallback behavior to maintain system usability.

### Auto-Generation Logic

Agents synthesize a primary color by selecting a hue from the available palette defined in [`packages/cli/src/linter/spec-gen/compiler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/compiler.ts). This auto-generated value populates the `design.autoGeneratedPrimary` property, which agents reference when the explicit `primary` key is absent. The linter runner in [`packages/cli/src/linter/linter/runner.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/runner.ts) orchestrates this process by invoking the `missing-primary` rule during the validation phase.

### Impact on Design Control

The auto-generation mechanism creates two distinct outcomes:

- **Reduced designer control** – The agent selects the primary color algorithmically from available tokens, which may not align with the intended brand emphasis or accessibility requirements.
- **Ensured system functionality** – Components expecting a primary color (such as button backgrounds or active states) receive a usable value rather than falling back to undefined or default browser styles.

## Implementation Files

The warning logic spans four key files in the repository:

- **[`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)** – Contains the rule implementation that checks for the presence of colors and absence of the primary token.
- **[`packages/cli/src/linter/linter/runner.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/runner.ts)** – The linter entry point that executes all rules, including the `missing-primary` check.
- **[`packages/cli/src/linter/spec-gen/compiler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/compiler.ts)** – Generates the design-system model consumed by agents, including logic for handling auto-generated primary colors.
- **[`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md)** (lines 13-15) – Documents the warning description and its implication for agent behavior.

## Code Examples

### Detecting the Warning

The following TypeScript example demonstrates how the linter identifies a missing primary token in a DESIGN.md file:

```ts
import { lint } from '@google/design.md/linter';
import { missingPrimaryRule } from '@google/design.md/linter/rules/missing-primary';

// A minimal DESIGN.md snippet without a primary token
const markdown = `
colors:
  secondary: "#ff5722"
  accent: "#00bcd4"
`;

const report = lint(markdown);
console.log(report.findings);
/* Output:
[
  {
    path: 'colors',
    message: "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
  }
]
*/

```

### Agent Fallback Behavior

When rendering components, agents check for the auto-generated primary value as a fallback:

```ts
import { parseDesignSystem } from '@google/design.md/linter';
import { renderButton } from './agent/button';

const design = parseDesignSystem(markdown);
const btn = renderButton({
  backgroundColor: design.colors.get('primary') ?? design.autoGeneratedPrimary,
});

```

If the `primary` key is absent from the color map, `design.autoGeneratedPrimary` supplies the synthesized color value, ensuring the button renders with a valid background color.

## Summary

- The **missing-primary warning** activates when color tokens exist but no primary token is defined in DESIGN.md.
- Agents **auto-generate a primary color** from the available palette to maintain UI functionality.
- This behavior is 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) and orchestrated through [`packages/cli/src/linter/linter/runner.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/runner.ts).
- The warning serves as both a **designer notification** and a **safety mechanism** for maintaining usable design systems.

## Frequently Asked Questions

### What severity level does the missing-primary warning use?

The `missing-primary` rule emits a warning with `severity: "warning"` rather than an error, allowing the design system to compile while alerting designers to the potential loss of color control.

### Can agents override the auto-generated primary color?

No, agents cannot override the auto-generated primary color with custom logic unless the designer explicitly defines a `primary` token in the DESIGN.md file. The auto-generation only occurs when the token is missing, and agents use the synthesized value directly from `design.autoGeneratedPrimary`.

### How does the linter check for the primary token?

The linter checks `state.colors.size` to confirm colors exist, then searches for a token named `primary` in the color set. If the palette exists but lacks this specific token, the rule triggers the warning as 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).

### Why do agents need a primary color if my design doesn't use one?

Many UI components (buttons, links, active states) expect a primary color value for rendering. Rather than failing or rendering with undefined styles, agents generate a primary color from your existing palette to ensure visual consistency and functional components across the design system.