How to Fix Missing Primary Color Warnings in design.md

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 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 or 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.

   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.

   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 demonstrates the required structure:

# 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, you can reference another color token:

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 demonstrates the expected behavior:

# 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 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 or 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 and 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.

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 for the expected successful output patterns.

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