Shapes

Shape tokens live under the rounded key in YAML frontmatter, not under shapes. Each token maps a scale name to a Dimension value (px, em, rem). The section heading in the Markdown body should be ## Shapes. Recommended scale names are none, sm, md, lg, xl, and full. Components reference shape tokens with {rounded.token-name}.

The Shapes / `rounded` name mismatch#

The canonical Markdown heading for this section is ## Shapes. The tool's engine recognizes ## Shapes and several aliases (## Rounded, ## Corner Radius, ## Radii) and classifies them all as section kind shapes.

However, the YAML frontmatter key that holds the actual tokens is rounded, not shapes. This mirrors the Layout / spacing relationship: the heading names the design concept (shapes, corner radius), while the YAML key names the token data (rounded corners). When you write a DESIGN.md file, use rounded:

rounded:
  none: 0px
  sm: 4px
  md: 8px
  lg: 12px
  xl: 24px
  full: 9999px

A top-level key named shapes or radius in frontmatter is not recognized by the parser and will appear in unknownKeys.

Token shape#

Each token in rounded maps a scale name to a Dimension: a number followed by px, em, or rem.

Token name	Typical value	Common use
`none`	`0px`	Sharp corners; strictly architectural or editorial designs
`sm`	`4px`	Subtle rounding; inputs, chips, tags
`md`	`8px`	Cards, panels, dialog containers
`lg`	`12px`	Prominent UI surfaces, hero cards
`xl`	`24px`	Large rounded containers, pill-shaped UI
`full`	`9999px`	Fully circular or pill shapes; avatars, badges, toggles

These names are recommended in the spec-config but are not required. Any descriptive key is valid.

Component references#

A component references a rounded token using {rounded.token-name}:

rounded:
  sm: 4px
  md: 8px
  full: 9999px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px
  avatar:
    rounded: "{rounded.full}"
    size: 40px

A reference to a rounded token that does not exist triggers a broken-ref error.

Accepted heading aliases#

The engine accepts all of the following headings and maps them to the shapes section kind:

## Shapes (canonical)
## Rounded
## Corner Radius
## Radii

German equivalents: ## Formen, ## Ecken, ## Radien

Full DESIGN.md example: Shapes section#

---
name: Soft Geometry
colors:
  primary: "#1B4FD8"
  on-primary: "#FFFFFF"
  tertiary: "#B8422E"
rounded:
  none: 0px
  sm: 4px
  md: 8px
  lg: 16px
  xl: 32px
  full: 9999px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.lg}"
    padding: 14px
  badge:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.full}"
    padding: 4px
---

## Shapes

The shape language is **consistently rounded** at medium and large scales.
Sharp corners are reserved for decorative rule lines only.

- **Buttons and interactive elements**: `rounded.lg` (16px) for primary
  actions; keeps the feel approachable without being cartoonish.
- **Cards and panels**: `rounded.md` (8px) for content containers.
- **Badges and counts**: `rounded.full` (9999px) for fully circular labels.
- **Never mix sharp and soft**: do not combine `rounded.none` and
  `rounded.lg` on adjacent elements in the same view.

Try it in the tool

Was this page helpful?