Design Tokens

Token Levels

Not all tokens are equal; they have varying levels of specificity.

• Primitive Tokens - All contain raw values and do not alias other tokens
• Semantic Tokens - Give context to how the tokens should be used, often alias a primitive token
• Component Tokens - Tokens specific to a component, use semantic and primitive tokens

Naming

Semantic and component tokens are used to create themes; primitive tokens are only used in edge cases. Primitive tokens are aliased as values to each semantic or component token.

                                                        
                                                        
                                                            // Example Semantic CSS Variable
                                                        --co-feedback-danger-text: var(red-800);
                                                        
                                                            

Compound design tokens are structured to be self-explanatory. Tokens use intent and properties to build unique names.

Intent describes how to use a token, such as feedback, actions, or surfaces. Some intents include variants, such as feedback action.

Properties describe how the token is used. These include background and text.

Intents

• Base - Refers to the foundational styles for a specific theme and surface
• Invert - Each theme has an inverted surface; token categories are intended for these surfaces
• Cards - Specific tokens for styling containers like a card
• Inputs - Tokens for native or component form elements

Properties

• Bg - Refers to backgrounds
• Border - Border styles
• Surfaces - Refers to the background that other content sits upon
• Fill - Used for shapes and icons

React Native token structure

The React Native theme is based on Tailwind. Therefore, this generates a slightly different CSS token structure.

                                                        
                                                        
                                                            .text-feedback-danger
                                                        
                                                            

1. Property - Text, Background (BG), Fill, etc
2. Intent - Base, Success, Card
3. Variant - Primary, Secondary, Positive, Negative, etc
4. State - Default, Hove
5. Scale - Numerical or t-shirt sizes

Web token structure

The following structure generates each token's structure as a CSS class.

                                                        
                                                        
                                                            .co-color-feedback-danger
                                                        
                                                            

1. System Prefix - "co" for Compound Web library (not required for Compound React Native library)
2. Type - One of the Supernova types, e.g., Colour, Spacing, Radius
3. Intent or Item - Base, Success, Card
4. Property - Text, Background (BG), Fill etc
5. Variant - Primary, Secondary, Positive, Negative, etc
6. State - Default, Hover
7. Scale - Numerical or t-shirt sizes

Composite Tokens

Composite tokens combine multiple token types. Typography tokens include composite tokens, which combine primitive and semantic tokens into a single token.

W3C currently specifies six types of composite tokens.