You can define your tokens as part of the createStyled
configuration. There are 14 token types available.
export const { styled, css } = createStyled({
tokens: {
colors: {
$gray500: 'hsl(206,10%,76%)',
$blue500: 'hsl(206,100%,50%)',
$purple500: 'hsl(252,78%,60%)',
$green500: 'hsl(148,60%,60%)',
$red500: 'hsl(352,100%,62%)',
},
space: {
$1: '5px',
$2: '10px',
$3: '15px',
},
fontSizes: {
$1: '12px',
$2: '13px',
$3: '15px',
},
fonts: {
$untitled: 'Untitled Sans, apple-system, sans-serif',
$mono: 'Söhne Mono, menlo, monospace',
},
fontWeights: {},
lineHeights: {},
letterSpacings: {},
sizes: {},
borderWidths: {},
borderStyles: {},
radii: {},
shadows: {},
zIndices: {},
transitions: {},
},
});
This is based on the System UI Theme Specification by Brent Jackson.
We highly recommend prefixing each token with $
, @
or some other symbol.
Since many devs use a numeric scale for token names, and numeric values like 5
convert to 5px
, non-prefixed tokens can cause confusion.
Prefixing all tokens ensures an accurate TypeScript autocomplete experience.
However, token prefixes are optional. They still work, but numeric scale tokens will autocomplete to numeric values, which will convert to px
.
After your tokens are defined, you can use them to style components.
const Button = styled('button', {
backgroundColor: '$blue500',
borderRadius: '$pill',
color: '$loContrast',
fontSize: '$3',
lineHeight: '1',
fontWeight: 500,
height: '$6',
paddingLeft: '$4',
paddingRight: '$4',
border: '0',
});
render(<Button>Button</Button>);
Tokens also work inside the css
prop.
const Button = styled('button', {
backgroundColor: '$blue500',
borderRadius: '$pill',
color: '$loContrast',
lineHeight: '1',
fontWeight: 500,
border: '0',
});
render(
<Button
css={{
fontSize: '$4',
height: '$7',
paddingLeft: '$5',
paddingRight: '$5',
}}
>
Button
</Button>
);
Tokens even work with shorthand CSS properties.
const Button = styled('button', {
backgroundColor: 'white',
borderRadius: '$pill',
color: '$blue600',
fontSize: '$3',
lineHeight: '1',
fontWeight: 500,
height: '$6',
paddingLeft: '$4',
paddingRight: '$4',
// tokens in shorthand properties
border: '1px solid $blue400',
boxShadow: '0 5px 15px $blue300',
});
render(<Button>Button</Button>);
Token types are automatically mapped to CSS Properties for an improved developer experience.
Token | Properties |
---|---|
colors | backgroundColor color borderColor borderRightColor borderBottomColor borderLeftColor caretColor columnRuleColor outlineColor fill stroke |
fonts | fontFamily |
fontSizes | fontSize |
fontWeights | fontWeight |
lineHeights | lineHeight |
letterSpacings | letterSpacing |
radii | borderRadius borderTopLeftRadius borderTopRightRadius borderBottomRightRadius borderBottomLeftRadius |
sizes | blockSize minBlockSize maxBlockSize inlineSize minInlineSize maxInlineSize width minWidth maxWidth height minHeight maxHeight flexBasis |
space | gap gridGap columnGap rowGap gridRowGap inset insetBlock insetBlockEnd insetBlockStart insetInline insetInlineEnd insetInlineStart margin marginTop marginRight marginBottom marginLeft marginBlock marginBlockEnd marginBlockStart marginInline marginInlineEnd marginInlineStart padding paddingTop paddingRight paddingBottom paddingLeft paddingBlock paddingBlockEnd paddingBlockStart paddingInline paddingInlineEnd paddingInlineStart top right bottom left |
zIndices | zIndex |