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

> Discover the eight valid component properties in DESIGN.md including backgroundColor, textColor, and typography. Master UI component visual contracts for better design system management. Learn more!

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: api-reference
- Published: 2026-06-26

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/README.md) (Component Tokens section) and [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) under the “Component Property Tokens” subsection. The user-facing documentation in [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) also lists the valid properties in the “Component Tokens” section, providing both technical specification and practical implementation guidance.