Understanding W3C Design Token Types

Discover the W3C standard types for design tokens and learn how to implement them effectively in Figma, CSS, and Penpot.

Jun 05, 2025

Hi there 👋

If you're building or maintaining a design system, you've probably encountered terms like “color”, “typography”, or “dimension” when working with design tokens.

But did you know these are now official value types in the W3C Design Tokens standard?

In this issue, we’ll break down all the value types defined by the spec and show how to apply them in Figma (via Tokens Studio) and your CSS codebase.

Supported `$type` values

The Design Tokens Format Module Level 1 by the W3C Design Tokens Community Group defines a set of value types, not naming rules or categories, but actual data types like color, dimension, number, and typography. These types ensure consistency, validation, and tool compatibility across platforms.

Here’s a rundown of the supported type values:

color

Any valid CSS color value. Examples: "#0066ff", "hsl(210 100% 56%)".

dimension

A number with a unit, like pixels or rems. Examples: "16px", "1rem".

number

A plain number without units. Examples: "1", "0.5".

`string`

Any plain string. Useful for values like easing keywords. Examples: "ease-in-out", "solid".

`boolean`

A true/false value. Examples: "true", "false".

`fontFamily`

A font family or stack. Example: "Arial, sans-serif".

`fontWeight`

Can be numeric or string. Examples: "400", "bold".

`duration`

A time value with a unit.
Examples: "300ms", "0.2s"

`cubicBezier`

An easing curve is represented as an array of four numbers.
Example: [0.4, 0.0, 0.2, 1]

`shadow`

An object with x, y, blur, and color.
Example: { x: "0px", y: "2px", blur: "4px", color: "#00000033" }

`gradient`

Describes linear or radial gradients, including stops and direction.
Example: { type: "linear", angle: "90deg", stops: [...] }

`border`

A composite value including width, style, and color.
Example: { width: "1px", style: "solid", color: "#ccc" }

`transition`

Combines duration, delay, and timing function.
Example: {duration: "300ms", delay: "0s", timingFunction: "ease-in-out"}

`typography`

A group of font-related styles in one token.
Example: { fontSize, lineHeight, fontWeight, fontFamily }

These types are used alongside $value and $alias and they enable smarter tooling and validation across platforms.

Structuring a Valid JSON Design Tokens File (W3C Format)

When working with design tokens as JSON, following the W3C format helps ensure consistency and machine-readable output across tools.

Here are some guidelines:

Root level is a flat or nested object where keys are token names or categories.
Each token is an object with at least a $value key representing the actual value.
Use the $type key to specify the token’s value type, helping tools interpret it correctly.
Optionally, $description can provide human-readable context.
Tokens can use $alias to reference other tokens by name, enabling semantic relationships.
Keep naming consistent and semantic, e.g. "spacing.sm", "color.brandPrimary".

Let’s see an example:

{
  "color": {
    "brandPrimary": {
      "$value": "#0066ff",
      "$type": "color",
      "$description": "Primary brand color"
    }
  },
  "spacing": {
    "sm": {
      "$value": "8px",
      "$type": "dimension"
    }
  },
  "typography": {
    "heading": {
      "$value": {
        "fontSize": "24px",
        "lineHeight": "32px",
        "fontWeight": "700",
        "fontFamily": "Arial, sans-serif"
      },
      "$type": "typography"
    }
  }
}

Benefits of this structure:

Clear distinction between token name, type, and value.
Supports complex types like “typography” and “shadow” as nested objects.
Enables aliasing and overrides for theming.
Facilitates validation and tooling interoperability.

Using types in design tools

Figma

Tokens Studio for Figma supports W3C-compatible token types. Here's how to use them effectively:

Assign “color” tokens to fills, text, and strokes.
Apply “dimension” tokens for spacing, radius, and sizes — always including units like px or rem.
Use composite “typography” tokens rather than splitting them into individual properties.
Apply semantic names (like “spacing.sm” or “brand.primary”) with the appropriate type for better clarity and tool compatibility.

Penpot

Penpot is gaining traction as an open-source alternative to Figma and it’s making moves toward native design token support (we’ve talked about it in the previous issue).

While Penpot doesn’t yet offer full support for the W3C token format, you can still apply a typed token strategy by:

Organizing tokens semantically in the "Assets → Styles" panel using naming conventions like “color.brand.primary” or “spacing.md”.
Using external tools like Tokens Studio or a custom JSON parser to convert W3C-compliant tokens into Penpot’s current format.
Preparing for the upcoming design tokens integration roadmap, which includes native support for theming and token references across components.

For now, the best way to manage tokens in Penpot is to:

Maintain a single source of truth in JSON (W3C-compliant).
Use CLI tools or scripts to generate Penpot-compatible styles.
Apply style names that reflect $type (e.g., font.size.heading for a dimension, or text.heading for typography).

Using types in code

Value types are essential not only in design tools but also in code, particularly when working with token compilers like Style Dictionary.

Here's how they map to CSS properties:

color → color, background-color, border-color
dimension → padding, margin, gap, font-size
typography → font-size, line-height, font-family, font-weight
shadow → box-shadow
transition → transition, animation
border → border, border-style, border-color, border-width

Using these types helps teams generate accurate platform-specific code, validate builds, and maintain clarity across the development process.

Takeaways

Typed tokens are more than just a spec — they’re the key to cross-tool consistency.

Use the correct $type in both design and code to ensure clarity and compatibility.
Stick to semantic naming, but don't confuse token names with types.
Export tokens in W3C format to prepare for future tooling and interoperability.

References

→ W3C Design Tokens Format Spec

Design Tokens Pills

Discussion about this post