Design tokens are standardized, reusable variables that store design decisions, such as colors, fonts, spacing, and other visual elements. These tokens help maintain consistency across a design system by ensuring that these elements are applied uniformly across different platforms and devices.
- Consistency: They ensure a cohesive visual identity by standardizing design elements across different components and platforms.
- Efficiency: They allow designers and developers to make updates quickly. Changing a token value, like a color or font size, will automatically update all instances where the token is used.
- Scalability: As projects grow, design tokens help manage complexity by centralizing design decisions, making it easier to maintain and evolve the design system.
- Collaboration: They bridge the gap between design and development, providing a common language and making it easier for teams to work together.
- Adaptability: Tokens can be adapted to different themes or modes (e.g., light and dark mode) without needing to redesign or recode elements from scratch.
Design tokens should have intuitive and descriptive names that clearly indicate their purpose. To ensure consistency and clarity, we follow these naming guidelines:
- Naming Structure: Use the format
{category}-{role}-{variant}-{modifier}. - Category: Always include a category, such as color, space, font, or button.
- Role: Define the role, such as background, size, or radius, using a consistent set of terms.
- Variant: Optionally include a variant, such as muted, inverse, or error. Omit this if not applicable.
- Modifier: Optionally include a state modifier, like hover, active, or focus. Omit if not needed.
- Avoid Redundancy: Keep names concise by avoiding repetitive terms.
- Multiple Modifiers: When multiple modifiers are required, arrange them logically and consistently.
By following these rules, we ensure that design tokens remain clear, scalable, and easy to maintain.
background-secondary-mutedfont-weight-boldbutton-border-hover
Not all design tokens will be necessary for every project, and you may need to introduce new ones. That's perfectly fine—just ensure that any additions adhere to the established naming conventions.
Primitive color tokens should correspond to either standard or brand colors. To enhance design flexibility, consider adding tints and shades, such as color-primary-light, color-primary-dark, and similar variants. Use HSL color values for these tokens.
color-primarycolor-secondarycolor-accentcolor-mutedcolor-inversecolor-errorcolor-warningcolor-dangercolor-successcolor-infocolor-disabled
CSS Example: --color-primary: hsl(46, 100%, 50%);
These colors are typically used in all projects and can be adjusted as needed. Use HSL color values for these tokens.
color-blackcolor-whitecolor-gray-100color-gray-200color-gray-300color-gray-400color-gray-500color-gray-600color-gray-700color-gray-800color-gray-900
CSS Example: --color-black: hsl(0, 0%, 0%);
Brand specific color tints and shades. Use HSL color values for these tokens.
color-redcolor-greencolor-bluecolor-yellow- ...
CSS Example: --color-yellow: hsl(60, 100%, 50%);
Pages, sections, elements and other background elements. Use HSL color values for these tokens when not referencing another color token.
backgroundbackground-mutedbackground-inversebackground-errorbackground-warningbackground-dangerbackground-successbackground-infobackground-disabledbackground-hoverbackground-activebackground-secondarybackground-secondary-mutedbackground-secondary-inversebackground-secondary-errorbackground-secondary-warningbackground-secondary-dangerbackground-secondary-successbackground-secondary-infobackground-secondary-disabledbackground-secondary-hoverbackground-secondary-active
CSS Example: --background: var(--color-black);
Text, borders, cards and other foreground elements. Use HSL color values for these tokens when not referencing another color token.
foregroundforeground-mutedforeground-inverseforeground-errorforeground-warningforeground-dangerforeground-successforeground-infoforeground-disabledforeground-hoverforeground-activeforeground-secondaryforeground-secondary-mutedforeground-secondary-inverseforeground-secondary-errorforeground-secondary-warningforeground-secondary-dangerforeground-secondary-successforeground-secondary-infoforeground-secondary-disabledforeground-secondary-hoverforeground-secondary-active
CSS Example: --foreground: var(--color-white);
link-colorlink-color-hoverlink-color-activelink-color-visitedlink-color-mutedlink-color-hover-mutedlink-color-active-mutedlink-color-visited-muted
CSS Example: --link-color: var(--color-blue);
button-backgroundbutton-textbutton-borderbutton-background-hoverbutton-text-hoverbutton-border-hoverbutton-background-activebutton-text-activebutton-border-activebutton-background-visitedbutton-text-visitedbutton-border-visitedbutton-background-mutedbutton-text-mutedbutton-border-mutedbutton-background-muted-hoverbutton-text-muted-hoverbutton-border-muted-hoverbutton-background-muted-activebutton-text-muted-activebutton-border-muted-activebutton-background-muted-visitedbutton-text-muted-visitedbutton-border-muted-visited
CSS Example: --button-background: var(--color-blue);
border-colorborder-color-mutedborder-color-inverseborder-color-errorborder-color-warningborder-color-dangerborder-color-successborder-color-infoborder-color-disabledborder-color-hoverborder-color-active
CSS Example: --border-color: var(--color-black);
focus-ring-colordivider-color
CSS Example: --focus-ring-color: var(--color-blue);
These are the font families that are available to use. The values should be the font family names.
font-family-sansfont-family-serif
body-fontbody-font-mutedheadings-fontheadings-font-muted
CSS Example: --body-font: var(--font-family-sans);
All fonts larger than 24px should be calculated using clamp() to ensure that they are responsive.
Font sizes are using default values.
--font-size--2: 0.75rem;12px--font-size--1: 0.875rem;14px--font-size-0: 1rem;16px--font-size-1: 1.125rem;18px--font-size-2: 1.25rem;20px--font-size-3: 1.5rem;24px--font-size-4: clamp(1.5rem, 1.375rem + 0.625vw, 1.875rem);24px > 30px--font-size-5: clamp(1.875rem, 1.75rem + 0.625vw, 2.25rem);30px > 36px--font-size-6: clamp(2.25rem, 2rem + 1.25vw, 3rem);36px > 48px--font-size-7: clamp(3rem, 2.75rem + 1.25vw, 3.75rem);48px > 60px--font-size-8: clamp(3.75rem, 3.5rem + 1.25vw, 4.5rem);60px > 72px
Font weights are using default values.
--font-weight-light: 300;--font-weight-normal: 400;--font-weight-medium: 500;--font-weight-bold: 700;--font-weight-extrabold: 800;--font-weight-black: 900;
Line heights are using default values.
--line-height-none: 1;--line-height-tight: 1.15;--line-height-snug: 1.375;--line-height-normal: 1.5;--line-height-relaxed: 1.75;--line-height-loose: 2;
Letter spacing is using default values.
--letter-spacing-tightest: -0.0625em;--letter-spacing-tighter: -0.03125em;--letter-spacing-tight: -0.015625em;--letter-spacing-normal: normal;--letter-spacing-wide: 0.02125em;--letter-spacing-wider: 0.0625em;--letter-spacing-widest: 0.09375em;
Font shorthand is a way to define a font size, line height, and font weight using a single token. (Reference)
text-body-smtext-body-md|text-bodytext-body-lgtext-title-smtext-title-md|text-titletext-title-lgtext-captiontext-button-smtext-button-md|text-buttontext-button-lg
All spacing larger than 24px should be calculated using clamp() to ensure that they are responsive.
Spacing values are using default values.
--space-2xs: 0.25rem;4px--space-xs: 0.5rem;8px--space-s: 0.75rem;12px--space-m: 1rem;16px--space-l: 1.5rem;24px--space-xl: clamp(2rem, 1.6667rem + 1.6667vw, 3rem);32px > 48px--space-2xl: clamp(3rem, 2rem + 5vw, 6rem);48px > 96px--space-3xl: clamp(6rem, 5.3333rem + 3.3333vw, 8rem);96px > 128px--space-4xl: clamp(8rem, 6.6667rem + 6.6667vw, 12rem);128px > 192px--space-5xl: clamp(12rem, 10.6667rem + 6.6667vw, 16rem);192px > 256px
Max width values are using default values.
--max-width-none: none;--max-width-auto: auto;--max-width-full: 100%;--max-width-container: 96rem;--max-width-content: 40rem;--max-width-breakout: 60rem;
Breakpoints are using default values.
--breakpoint-xs: 320px;--breakpoint-sm: 512px;--breakpoint-md: 768px;--breakpoint-lg: 1024px;--breakpoint-xl: 1280px;--breakpoint-2xl: 1536px;--breakpoint-3xl: 1782px;- ...
Ease values are using default values.
--ease-in: cubic-bezier(0.25, 0, 0.75, 0.25);--ease-out: cubic-bezier(0.25, 0.75, 0.75, 1);--ease-in-out: cubic-bezier(0.75, 0.25, 0.25, 0.75);--ease-out-back: cubic-bezier(0.175, 0.885, 0.32, 1.275);--ease-in-back: cubic-bezier(0.6, -0.28, 0.735, 0.045);--ease-in-out-back: cubic-bezier(0.68, -0.55, 0.265, 1.55);--ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);--ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);--ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);--ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);--ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);--ease-in-out-quint: cubic-bezier(0.87, 0, 0.13, 1);
Easing reference (Epiceasing.com).
Duration values are using default values.
--duration-immediate: 0s;--duration-faster: 0.15s;--duration-fast: 0.25s;--duration-slow: 0.35s;--duration-slower: 0.45s;--duration-slowest: 0.65s;
Border radius values are using default values.
--border-radius-none: 0;--border-radius-base: 0.25rem;--border-radius-pill: 9999px;--border-radius-circle: 50%;- ...
Border width values are using default values.
--border-width-none: 0px;--border-width-thin: 1px;--border-width-thick: 2px;- ...
Shadows are using default values.
--shadow-none: box-shadow: 0 0 #0000;--shadow-elevation-1:box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);--shadow-elevation-2: box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);--shadow-elevation-3: box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);--shadow-elevation-4: box-shadow: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);- ...