ESLint plugin

The essential plugin for use with the Atlassian Design System.

no-unsafe-design-token-usage

Using design tokens in an unsafe way risks the health of the system and will affect how fast your codebase can migrate between versions.

Examples

This rule will mark design token usage that is not statically and locally analyzable, as well as design tokens that are considered deleted.

Incorrect

const textColor = 'red';

css({ color: textColor });
             ^^^^^^^^^ must be a string literal

css({ boxShadow: '0px 1px 1px var(--ds-accent-subtleBlue)' });
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^ must use the token() function

Correct

import { token } from '@atlaskit/tokens';

css({ boxShadow: token('elevation.shadow.card') });

css`
    color: ${(token('color.text.highemphasis'), N20)};
`;

Token names in xcss

The rule also checks experimental and deleted token names used directly in object literals passed to xcss() from @atlaskit/primitives, including nested pseudo selectors and media queries. Aliased imports and namespace imports are supported.

import { xcss } from '@atlaskit/primitives/xcss';

// Incorrect: experimental token
xcss({ gap: 'space.gap.medium' });

// Correct: active token; no token() wrapper is needed
xcss({ gap: 'space.100' });

Fixes replace the string with its replacement token name. Raw CSS replacements are reported without a fix because token-valued xcss properties may not accept them. This check covers literal property values in the xcss object, rather than values supplied through variables or object spreads.

Primitive component props

The rule also reports experimental and deleted tokens selected by explicit string props on @atlaskit/primitives components. This includes:

Box: backgroundColor and all padding props.
Inline: space and rowSpace; Stack: space.
Flex and Grid: gap, rowGap, and columnGap.
Text: color, size, and weight; MetricText: size.
Bleed: all, inline, and block, resolved to negative spacing tokens.
Standard Anchor and Pressable: backgroundColor and all padding props. Their compiled versions do not expose these props.

Named, aliased, namespace, and supported default imports are recognized, including component subpaths and /compiled imports. Local bindings that shadow imports are ignored.

import { Stack } from '@atlaskit/primitives/compiled/stack';

// Incorrect: experimental token
<Stack space="space.gap.medium" />;

// Correct
<Stack space="space.100" />;

Both space="..." and space={'...'} are checked. Semantic values are resolved to their actual tokens: for example, Text size="small" selects font.body.small, and Bleed all="space.100" selects space.negative.100. Fixes preserve the prop's value format and are only offered when the replacement is a token the prop supports. Raw CSS replacements and incompatible token families are reported without a fix.

This check does not resolve variables, expressions, prop spreads, omitted defaults, or implicit surface-derived text colors. It does not require token() wrappers or fallbacks for primitive props. Deprecated tokens are checked by no-deprecated-design-token-usage, allowing its warning severity to remain independently configurable.

Options

This rule comes with options to aid in migrating to design tokens.

fallbackUsage

forced: Fallback values must always be provided
none: Fallback values must never be provided. (Fixer will remove if provided)
optional: Fallbacks are optional

shouldEnforceFallbacks (deprecated)

When true the rule will mark token function usage as violations when fallbacks aren't defined. When false the rule will mark token function usage as violations when fallbacks are defined.

Was this page helpful?

We use this feedback to improve our documentation.