# How to Fix Missing Primary Color Warnings in design.md

> Resolve missing primary color warnings in design.md by adding a primary key with a valid hex color to your colors block. Fix the linter error efficiently.

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

---

**Add a `primary` key with a valid hex color to the `colors` block of your design specification file to eliminate the linter warning.**

The missing primary color warning is emitted by the `design-cli` linter when a design specification lacks a valid `primary` entry in its color palette. This rule is enforced 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 ensures that Material Design 3 (MD-3) token families can be generated correctly. When you encounter this warning in the google-labs-code/design.md repository, it indicates that downstream generators for Tailwind, component exporters, or token summaries may fail to produce complete color systems.

## Why the Warning Appears

The linter rule explicitly checks for the presence of `colors.primary` in parsed design system files such as [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) or [`design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/design_tokens.json). If the key is absent, misspelled, or resolves to an invalid value, the linter emits a warning.

- **No `primary` key defined**: The `colors` block lacks the literal `primary` entry.
- **Incorrect key spelling**: Using `Primary`, `primary-color`, or `brand.primary` instead of the exact lower-case `primary` key.
- **Invalid token resolution**: A token reference like `{colors.brand}` that resolves to a non-color value or invalid hex.

## How to Fix Missing Primary Color Warnings

1. **Add the `primary` entry** directly under the `colors` block in your design file.

   ```yaml
   colors:
     primary: "#647D66"          # Your brand's primary hue

     on-primary: "#FFFFFF"
     primary-container: "#1B3026"
   ```

2. **Use valid hex values or resolvable token references**. The rule validates that the final resolved value is a proper hex color.

   ```yaml
   colors:
     brand: "#006B5A"
     primary: "{colors.brand}"   # Resolves to "#006B5A"

     on-primary: "#FFFFFF"
   ```

3. **Save the file and re-run the linter**. The warning disappears when `colors.primary` is present and valid.

## Common Pitfalls and Solutions

| Pitfall | Solution |
|---------|----------|
| Nesting `primary` inside a `brand` object like `brand: { primary: ... }` | Move `primary` directly under the `colors` root level. |
| Using uppercase `Primary` or hyphenated `primary-color` | Rename to exactly `primary` (lower-case). |
| Providing CSS variables like `var(--my-primary)` | Convert to a hex value `#RRGGBB` or use a token reference `{colors.existing-token}`. |
| Forgetting to commit the updated design file | Ensure the file is saved and the linter points to the latest version. |

## Code Examples

### Minimal Valid Design File

This example from [`examples/totality-festival/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) demonstrates the required structure:

```yaml

# examples/totality-festival/DESIGN.md

colors:
  primary: "#FFF6DF"
  on-primary: "#3A3000"
  primary-container: "#FFD700"
  on-primary-container: "#705E00"
  inverse-primary: "#705D00"

```

### Using Token References

As shown in [`packages/cli/src/linter/spec-gen/spec-helpers.test.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-gen/spec-helpers.test.ts), you can reference another color token:

```yaml
colors:
  brand: "#006B5A"
  primary: "{colors.brand}"   # resolves to "#006B5A"

  on-primary: "#FFFFFF"

```

### CLI Output Before and After

The test file [`packages/cli/src/linter/linter/runner.test.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/runner.test.ts) demonstrates the expected behavior:

```sh

# Before adding primary

design-cli lint examples/paws-and-paths/DESIGN.md

# → Warning: missing primary color

# After adding primary

design-cli lint examples/paws-and-paths/DESIGN.md

# → No missing-primary warnings; summary info printed.

```

## Summary

- The **missing primary color** warning originates from [`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 triggers when `colors.primary` is absent or invalid.
- **Fix by adding** a `primary` key with a hex value directly under the `colors` block in your [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) or [`design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/design_tokens.json) file.
- **Token references** like `{colors.brand}` are valid only if they resolve to valid hex colors.
- **Downstream tooling** including Tailwind generators and component exporters require this entry to build the complete MD-3 primary color family.

## Frequently Asked Questions

### What file does the missing primary color rule check?

The rule checks [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) and [`design_tokens.json`](https://github.com/google-labs-code/design.md/blob/main/design_tokens.json) files parsed by the CLI linter. Specifically, it validates the `colors` object for the presence of a `primary` key 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).

### Can I use a CSS variable for the primary color?

No. The linter requires either a literal hex color (e.g., `#647D66`) or a token reference that resolves to a valid hex value. CSS variables like `var(--my-primary)` are not supported and will trigger the warning.

### Why does the linter require a primary color?

The `primary` color is the foundation of the Material Design 3 color system. Downstream generators use this value to compute related tokens such as `on-primary`, `primary-container`, and `inverse-primary`. Without it, tools that generate Tailwind configurations or component CSS cannot produce complete color families.

### How do I verify the fix worked?

Run `design-cli lint` against your design file. If the configuration is correct, the warning will no longer appear in the output, and the linter will print summary information without the "missing primary color" entry. You can also check [`packages/cli/src/linter/linter/runner.test.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/runner.test.ts) for the expected successful output patterns.