Design Tokens
Understanding the C3 AI design system and design tokens
The C3 AI Design System implements a conceptual approach known as design tokens. To learn more about design tokens, go to Adobe's website.
Token Definitions
Tokens can be either: semantic tokens, alias tokens, or foundational tokens.
- Semantic tokens define a common naming convention that might be used across applications or platforms, and are mapped to alias tokens or foundational tokens.
- Alias tokens are just semantic tokens that might pointed to by other semantic tokens.
- Foundational tokens represent the actual color, spacing and other values that will be rendered in the end application.
Consider the differences between the token types:
| Semantic Tokens | Alias Tokens | Foundational Tokens |
|---|---|---|
| Map to foundational tokens | Are mapped from semantic tokens, and to foundational tokens or other alias tokens | Map directly to css values, such as hex or pixel values |
Are used directly in .scss files | May be used directly in .scss files | Are not used directly in .scss files |
| Are used by component and application developers | May be used by component and application developers, but defined by design team | Are only added and updated by the design team |
Example Semantic Token
The following is an example of a semantic token, fontColor, as mapped in metadata for C3 AI theme definitions. See Theming for more complete information.
{
// Dark mode
"fontColor": {
"value": "{color.core.gray.05.value}", // => "#F7F8FA"
"type": "color"
}
// Light mode
"fontColor": {
"value": "{color.core.gray.100.value}", // => "#111112"
"type": "color"
}
}At build time, the dot-delimited path that resolves to the token value, that is, color.core.gray.100.value, is converted to camel-case format, that is, colorCoreGray100 (value segment is removed), for easier integration in css declarations.
Example Alias Tokens
The following is an example of an alias tokens defined in a json format. The path color.font.base.value actually points to another foundational token at color.base.red.value.
{
"color": {
"font": {
"base" : { "value": "{color.base.red.value}" },
"secondary": { "value": "{color.base.green.value}" },
"tertiary" : { "value": "{color.base.gray.light.value}" }
}
}
}Example Foundational Tokens
The following is an example of foundational tokens defined in a json format.
{
"color": {
"core": {
"white": {
"value": "#FFFFFF"
},
"black": {
"value": "#000000"
},
"gray": {
"05" : { "value": "#F7F8FA" },
"10": { "value": "#EBEDF0" },
"20": { "value": "#DFE1E5" },
...
"100": { "value": "#111112" }
}
}
}
}Theming
Theming in C3 AI applications is achieved through metadata mappings from semantic token names to their associated foundational tokens. C3 AI defines themes based on color and density. The associated C3 base types are UiSdlThemeTemplate.c3typ and UiSdlDensityTemplate.c3typ respectively.
The fields in these types match the semantic tokens as defined in the C3 AI design system. The values represent css variable names that ultimately will resolve to the value of a foundational token when evaluated at runtime.
⚠️ Note that a semantic token might point to another semantic token. In this context, the semantic token being pointed to might be thought of as an "alias" token.
All foundational tokens are added in a root.css file as values in a :root pseudo-class. In this way, the css variable names are resolved to the correct foundational token value at runtime, based on the selected theme.
Example of the :root pseudo-class declarations:
--c3-style-colorCoreGray10: #EBEDF0;
--c3-style-colorCoreGray20: #DFE1E5;
--c3-style-colorCoreGray30: #C6C9CF;
--c3-style-colorCoreGray40: #AAAEB5;
--c3-style-colorCoreGray50: #8C919C;
...
--c3-style-size10: 3.5rem;
--c3-style-size11: 4rem;
--c3-style-size12: 5rem;
--c3-style-size13: 7.5rem;
...
--c3-style-fontSize01: 10px;
--c3-style-fontSize02: 11px;
--c3-style-fontSize03: 12px;
--c3-style-fontSize04: 14px;
...Theme example: in UiSdlDarkTheme.c3typ which extends UiSdlThemeTemplate.c3typ:
{
...
fontColor: ~= "--c3-style-colorCoreGray05"
formFieldBackgroundColor: ~= "--c3-style-colorCoreWhiteAlpha00"
formFieldBackgroundColorDisabled: ~= "--c3-style-colorCoreWhiteAlpha10"
formFieldBorderColor: ~= "--c3-style-componentBorderColor" // <= alias token
...
}Theme example: in UiSdlLightTheme.c3typ which extends UiSdlThemeTemplate.c3typ:
{
...
fontColor: ~= "--c3-style-colorCoreGray100"
formFieldBackgroundColor: ~= "--c3-style-colorCoreGrayAlpha00"
formFieldBackgroundColorDisabled: ~= "--c3-style-colorCoreGrayAlpha05"
formFieldBorderColor: ~= "--c3-style-componentBorderColor" // <= alias token
...
}At runtime, style properties that correspond to the above values (depending on the selected theme) are attached to the <html> tag. When a css value such as var(--c3-style-fontColor) is evaluated, it will continue to resolve until it reaches a leaf node (not a var declaration).
Creating a theme instance
Similar to other metadata types, an instance of a theme might be created by adding a json file in the metadata folder of the desired package. The json file should be added under a folder named either UiSdlThemeTemplate or UiSdlDensityTemplate.
metadata
└── UiSdlThemeTemplate
├── MyThemeInstance.jsonThe json file consists of key/value pairs. The keys match the field names of the corresponding base type. The values are either foundational tokens prefixed by --c3-style- or hard-coded values in the case of branded themes, that is, values that are not represented in the C3 AI foundational tokens.
Example theme instance:
{
"type": "UiSdlThemeTemplate",
"id": "MyThemeInstance",
"themeCategory": "Dark",
"accentColor": "--c3-style-colorCoreBlue50",
"accentFontColor": "--c3-style-colorCoreGray100",
"accentVariantColor": "--c3-style-colorCoreBlue60",
"borderColor": "--c3-style-colorCoreWhiteAlpha30",
"buttonControlBorderColor": "--c3-style-componentBorderColor"
...
}