Valid Component Property Names in DESIGN.md: Complete Schema Reference

The DESIGN.md specification recognizes exactly eight official component property names: backgroundColor, textColor, typography, rounded, padding, size, height, and width.

The google-labs-code/design.md repository defines a strict schema for design tokens that restricts component properties to this specific whitelist. Understanding these valid component property names is essential for creating interoperable design systems that generate consistent CSS, Tailwind, and other styling artifacts without triggering parser warnings.

The Eight Official Component Property Tokens

According to the Component Property Tokens subsection in docs/spec.md, the schema supports only the following property names within any component definition:

Property	Expected Value Type
backgroundColor	<Color>
textColor	<Color>
typography	<Typography>
rounded	<Dimension>
padding	<Dimension>
size	<Dimension>
height	<Dimension>
width	<Dimension>

These tokens represent the only keys recognized by the DESIGN.md parser. Each property accepts either a literal value (such as "#ff0000" or "12px") or a token reference wrapped in curly braces (such as "{colors.primary}").

How the Schema Validates Property Names

The DESIGN.md specification treats the components section as a map<string, map<string, string>> structure. This type definition appears in the Design Tokens description within docs/spec.md around line 87. The inner map's keys are strictly limited to the eight tokens above to maintain format conciseness and cross-tool compatibility.

When parsing a component definition, the validator checks each property key against this whitelist. This restriction ensures that code generators can reliably map DESIGN.md properties to target platforms like CSS custom properties or Tailwind utility classes.

Handling Unknown Properties

If you include a property name not listed in the official eight—such as borderColor or margin—the parser will accept the component definition but emit a warning (see the "Unknown component property" rule around line 64 in docs/spec.md). While the file remains valid, tooling that relies on strict schema compliance may ignore these extra keys during code generation.

Practical Examples for Component Definitions

Basic Button Component

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px

Typography-Heavy Heading

components:
  heading-large:
    typography: "{typography.h1}"
    textColor: "{colors.primary}"

Fixed-Size Avatar

components:
  avatar:
    width: 48px
    height: 48px
    rounded: "{rounded.full}"

Complex Card Layout

components:
  card:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.lg}"
    padding: 24px
    width: 100%

Summary

• The DESIGN.md schema in google-labs-code/design.md restricts components to eight valid property names: backgroundColor, textColor, typography, rounded, padding, size, height, and width.
• These properties are defined in the Component Property Tokens section of docs/spec.md and support both literal values and curly-brace token references.
• The underlying schema structure is map<string, map<string, string>>, enforcing type safety across the component hierarchy.
• Unknown properties trigger parser warnings rather than hard errors, but may be ignored by downstream tooling.
• Property values can reference global design tokens using the "{token.name}" syntax or specify raw dimensions and colors directly.

Frequently Asked Questions

Can I use custom property names like borderColor or margin in components?

No, the schema does not recognize custom property names beyond the eight official tokens. If you add keys like borderColor, the parser will generate an "Unknown component property" warning according to the validation rules in docs/spec.md. While the file remains parseable, code generators and linters may skip these properties entirely.

Are component property names case-sensitive?

Yes, property names must match the exact casing defined in the specification: backgroundColor (camelCase), textColor, typography, rounded, padding, size, height, and width. Using backgroundcolor or BackgroundColor would trigger the unknown property warning.

What is the difference between size and width/height properties?

The size property is a shorthand <Dimension> token typically used for square elements or components where width and height should be equal, while width and height allow explicit dimensional control. All three accept dimension values (e.g., "48px", "{spacing.md}"), but size is often used for icons and avatars whereas width and height define rectangular boundaries.

How do component properties reference global design tokens?

Any component property value can reference a global token defined elsewhere in the DESIGN.md file by wrapping the token path in curly braces. For example, backgroundColor: "{colors.primary-60}" or rounded: "{rounded.full}". The parser resolves these references at build time, linking component properties to the centralized design token system.

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