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

> Discover the eight valid component property names in the DESIGN.md schema: backgroundColor, textColor, typography, rounded, padding, size, height, and width. Get the complete reference.

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

---

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

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

```

### Typography-Heavy Heading

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

```

### Fixed-Size Avatar

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

```

### Complex Card Layout

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

```

## Summary

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