Astro Design Tokens

What are Design Tokens?

Design Tokens empower designer and developer workflows by providing answers to common questions like "what color should I use for XYZ?" They enable you to make consistent design decisions that define the UI elements of a Design System and are your single source of truth. They can describe everything from color to border radii to typography and follow a consistent naming convention. Most importantly, they are platform-agnostic.

Types of Design Tokens

Astro Design Tokens are broken down into three tiers based on their usage:

Reference > System > Component

Reference Tokens

color.palette.brightblue.500

Reference Tokens represent the complete palette and include all possible values that are available to use. They do not convey any intent or meaning.

You should avoid creating your own colors or values if you want to be Astro-compliant. Our color values are very carefully chosen to meet WCAG accessibility compliance standards among others.

System Tokens (Preferred)

color.background.interactive

Reference Tokens help enforce consistency; however, the sheer number of them can be overwhelming. To help determine which tokens to use, Astro recommends System Tokens to better convey intent, usage, patterns and concepts (like `interactive` or `surface`). All System Tokens refer to our Reference Tokens.

Component Tokens

status-symbol-color-fill-critical

Component Tokens describe all the properties of individual components. They should only be used in scenarios where you are rebuilding existing Astro components, such as:

1. If you are unable to use our Figma and Web Component libraries. For example, developing a native Windows application, designing in Adobe XD, etc.
2. If you are theming an existing component library or design system. For example, Bootstrap or Material.

Component Tokens are scoped to individual components and should not be used outside of the component. Instead, use the token that is being referenced directly. For example, in a list component, don't use button-color-background-hover instead, note that button-color-background-hover references color.background.interactive.default and use the System Token instead. Note that Component Tokens may change in upcoming releases and may break the visual design of your custom component if you use them.

Common Use Cases

I'm a designer creating a new component or piece of UI
System (Preferred) Reference

Start with System Tokens wherever possible. If you can't find what you're looking for, drop down and use the Reference Tokens.

If you find yourself wanting to copy an existing Component's Token value for your new component, look up what that component token is referencing and use that instead.

I'm a designer working in something that isn't Figma
Component

Since you won't have access to our Figma component library, you'll need to create your own Astro components. You can do this using just our Component Tokens: button-color-background, button-color-text.

I'm a single developer working on some new UI
System (Preferred) Reference

Start with System Tokens wherever possible. If you can't find what you're looking for, drop down and use the Reference Tokens.

If you find yourself wanting to copy an existing component's token value for your new component, look up what that Component Token is referencing and use that instead.

I'm a developer who can't use Astro Web Components
Component

Since you won't have access to our web component library, you'll need to create your own Astro components. You can do this using just our Component Tokens: button-color-background, button-color-text.

Naming Convention

Our design tokens follow a consistent naming convention:

1. Group
2. Component
3. Element
4. Category
5. Property
6. Concept
7. Variant
8. State
9. Scale

• Group
  • Represents concepts that span across multiple components
  • Example: forms
• Component
  • Component-specific values that can override other token values
  • Example: our global status bar uses the same colors for both light and dark themes
• Element
  • Sometimes components need to override other components or elements within them
  • Example: notification-banner-icon-fill-critical Notification Banner overrides the icon fill color
• Category
  • The backbone of all tokens. Describes what kind of value it is
  • Example: color, size, radii, opacity
• Property
  • Describes a particular type of category
  • Example: background(color), text(color), border(color), inner(shadow), outer(shadow)
• Concept
  • Describes a general, related idea
  • Example: surface, status
• Variant
  • Describes different variants of a value
  • Example: (button) secondary
• State
  • Describes a particular state
  • Example: hover, focus, selected
• Scale
  • Describes a hierarchy between values
  • Example: (color)100-900, (fontSize)sm-lg

A token may have only some of these levels and do not need to include all of them.

Astro components offer off the shelf solutions for common UI patterns, but they do not encompass the whole picture. While it is possible to build an application using nothing but Astro components, you will still need Design Tokens for things like spacing between the components themselves. In most cases, you will also need to create your own custom components. Design Tokens can help there as well.