Valid Component Properties in DESIGN.md: The Complete 8-Property Schema

Design.md recognizes exactly eight canonical component properties—backgroundColor, textColor, typography, rounded, padding, size, height, and width—that define the visual contract for UI components.

The google-labs-code/design.md repository uses a declarative YAML format to define design tokens and component specifications. Understanding the valid component properties in DESIGN.md files is essential for building compatible tooling and ensuring consistent design system integration.

The Eight Canonical Component Properties

According to the specification, a DESIGN.md components map accepts only these eight officially supported properties. Any consumer of DESIGN.md files must recognize these specific keys as valid, while other properties trigger warnings but are technically accepted.

The valid component properties are:

• backgroundColor – A color token that fills the component’s background
• textColor – A color token used for the component’s foreground text
• typography – A reference to a typography token defining font family, size, weight, and line height
• rounded – A dimension token that controls corner radius
• padding – A spacing token that sets internal padding
• size – A dimension token defining generic size, often used for icons or avatars
• height – A dimension token that forces a specific height
• width – A dimension token that forces a specific width

These properties establish the strict schema that linting tools and renderers expect when parsing component definitions.

Source of Truth in the Repository

The specification for valid component properties appears in two authoritative locations within the repository.

According to the README.md “Component Tokens” section, the eight properties above constitute the complete list of valid component properties. This documentation provides the primary reference for designers and developers.

The docs/spec.md file contains a “Component Property Tokens” subsection that repeats the same enumeration, formalizing it as part of the official specification. This redundancy ensures the schema contract is clear across both user documentation and technical specification.

Practical Implementation Examples

Basic Component Definition

A complete component definition utilizes all eight valid properties to define a fully specified UI element:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.sm}"
    padding: 12px
    width: 120px
    height: 40px
    size: 24px

Variant States and Overrides

Component variants, such as hover states, only need to declare properties that differ from the base definition:

components:
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"
    textColor: "{colors.on-tertiary}"

Referencing Custom Dimension Tokens

Define reusable tokens in the top-level collections, then reference them within components:

rounded:
  sm: 4px
  md: 8px
  lg: 16px

components:
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: 24px

Invalid Property Handling

Using non-canonical properties results in validation warnings. The linter accepts the value but flags it as non-standard:

components:
  badge:
    backgroundColor: "{colors.error}"
    borderColor: "{colors.on-error}"   # Not a valid property; triggers warning

Validation and Tooling

The repository includes validation logic in packages/cli/src/linter/fixtures/ that tests how the linter handles valid and invalid component properties. These fixtures ensure strict adherence to the eight-property schema.

Real-world usage examples appear in examples/totality-festival/DESIGN.md, demonstrating how production design systems implement the canonical properties in complex component hierarchies.

Summary

• Design.md recognizes exactly eight valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, and width
• The schema is documented in both README.md (Component Tokens section) and docs/spec.md (Component Property Tokens subsection)
• Invalid properties trigger warnings but do not prevent file parsing
• Tooling validation exists in packages/cli/src/linter/fixtures/ to enforce schema compliance
• Production examples are available in the examples/totality-festival/DESIGN.md file

Frequently Asked Questions

What happens if I use a property not in the canonical list?

The DESIGN.md parser will accept the property value but emit a warning indicating it is not part of the canonical schema. For example, using borderColor will function but flag a validation warning, as only the eight specified properties are considered officially supported.

Can I use dimension values directly or must I reference tokens?

Both approaches are valid. You can reference tokens using the {category.token} syntax, such as {rounded.md}, or provide literal values like 12px, 24px, or 100%. The specification supports direct values and token references interchangeably for dimension and spacing properties.

Are all eight properties required for every component?

No. Components only need to declare the properties relevant to their visual appearance. A text-only component might specify only textColor and typography, while a container component might omit typography and textColor in favor of backgroundColor and padding.

Where is the formal specification for component properties documented?

The formal specification resides in docs/spec.md under the “Component Property Tokens” subsection. The user-facing documentation in README.md also lists the valid properties in the “Component Tokens” section, providing both technical specification and practical implementation guidance.

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