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

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 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 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. 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 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 – Contains the rule implementation that checks for the presence of colors and absence of the primary token.
• 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 – Generates the design-system model consumed by agents, including logic for handling auto-generated primary colors.
• 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:

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:

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 and orchestrated through 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.

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.

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