docs: Oryx design tokens

docs/scos/dev/front-end-development/202212.0/oryx/oryx-presets.md

@@ -43,7 +43,7 @@ For more information about feature sets, see [Feature sets](/docs/scos/dev/front
 
 ## Themes
 
-A *theme* represents the global visual appearance of an application, including typography, colors, and other specific design elements, such as the color of a form field's placeholder. Themes are built with design tokens, which are configurable values that are used in CSS properties. Configuring these design tokens lets you customize a theme and align the application and its components with your brand identity or specific design requirements.
+A _theme_ represents the global visual appearance of an application, including typography, colors, and other specific design elements, such as the color of a form field's placeholder. Themes are built with [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/styling/oryx-design-tokens.html), which are configurable values that are used in CSS properties. Configuring these design tokens lets you customize a theme and align the application and its components with your brand identity or specific design requirements.
 
 To apply a theme to your Oryx application, you can import it from the preset package and use it during the application setup:
 

docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-color-system.md

@@ -7,7 +7,7 @@ template: concept-topic-template
 
 An important part of the application user interface are the colors. Colors are used everywhere throughout components and are important for a good user experience. To ensure that you can adjust the colors to your needs throughout the application, a configurable color system is provided.
 
-The color system lets you set up the color values globally as well as override them per component. Components do not define _values_ for colors directly in their CSS but use _design tokens_. Design tokens are (CSS) variables that are provided by themes, which you can customize in your project.
+The color system lets you set up the color values globally as well as override them per component. Components do not define _values_ for colors directly in their CSS but use [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/styling/oryx-design-tokens.html). Design tokens are (CSS) variables that are provided by themes, which you can customize in your project.
 
 The color system comes with semantic color types and a consistent number of color steps. This results in a consistent naming system throughout all the components. The actual colors for those groups are not relevant for the color system and are part of the theme configuration. This lets you configure the colors in a global theme.
 
@@ -39,7 +39,7 @@ There are eight semantic color types used in Oryx components.
 | Secondary | Additional accent color that can be used for more color full experiences. Oryx components rarely use the secondary color.                                                                                                                       |
 | Neutral   | Also known as "grays". The neutrals are used for the layout—for example, as a divider color or background color. The Radix color system provides different neutrals that pair nicely with the color of choice, also known as "natural pairing". |
 | Highlight | The highlight color is used to highlight a sale.                                                                                                                                                                                                |
-| Success   | The success color is one of the `AlertType` colors that is used in components that are driven by `AlertType`—for example, notification.                                                                                                                |
+| Success   | The success color is one of the `AlertType` colors that is used in components that are driven by `AlertType`—for example, notification.                                                                                                         |
 | Info      | Similar to Success.                                                                                                                                                                                                                             |
 | Warning   | Similar to Success.                                                                                                                                                                                                                             |
 | Error     | Similar to Success.                                                                                                                                                                                                                             |
@@ -54,7 +54,6 @@ The Radix color system provides 15 color scales that are designed with a white f
 
 The color values can be of any supported color in the web platform, such as named colors ('red' or 'blue'), hex color, hcl, or rba. Oryx doesn't interfere with the provided colors but uses them as-is.
 
-
 ## Configure a color from the color palette
 
 To change the colors in an Oryx application, you can configure the colors using the color palette. This is convenient and the recommended approach to quickly try out the color system.
@@ -112,7 +111,7 @@ Providing both the light and dark mode is optional (but recommended), and is onl
 
 ## Color design tokens
 
-Each color type and its values are provided as a [design token. Design tokens are provided as CSS variables to the root of the application. The color design tokens follow a consistent naming pattern to improve the integration into your components:
+Each color type and its values are provided as a _design token_. [Design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/styling/oryx-design-tokens.html) are provided as CSS variables to the root of the application. The color design tokens follow a consistent naming pattern to improve the integration into your components:
 
 `--oryx-color-[type]-[step]`
 

docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-design-tokens.md

@@ -0,0 +1,39 @@
+---
+title: "Oryx: Design Tokens"
+description: Design tokens provide a centralized and consistent approach for styling components in Oryx applications.
+last_updated: July 24, 2023
+template: concept-topic-template
+---
+
+Design tokens are a fundamental aspect of the Oryx web framework, providing a powerful system for achieving consistent and customizable styles throughout the application. Design tokens are extensively used inside the [color system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/styling/oryx-colors-system.html), typography, icons and many more. Design tokens ensure a clean separation between styles and components, making it easier to manage and maintain the application's design system. This document focuses on the structure and usage of design tokens in Oryx.
+
+## CSS variables
+
+Design tokens are provided as CSS variables in the application code. The variables follow a structured naming convention to ensure consistency and avoid conflicts. The variables are prefixed with "oryx" to avoid naming conflicts with 3rd party variables and are written in kebab-case.
+
+The CSS variables are written in the root element of the application. This is the `oryx-app` component by default. CSS variables are inherited by all descendants of the root component. This makes is convenient to access the variables throughout the entire application. CSS variables can however be overridden at any element in te application.
+
+If you like to reuse the CSS variables outside the root element of the application, or if you are not using the `oryx-app` as the root, you can bootstrap the application using an alternative root:
+
+```ts
+import { appBuilder } from "@spryker-oryx/core";
+
+appBuilder().withAppOptions({ components: { root: "body" } });
+```
+
+## Usage of Design Tokens
+
+Design tokens are used extensively throughout Oryx components to achieve consistent and cohesive visual styles. Instead of hardcoding style values directly in component CSS, design tokens are used as CSS variables to define the styles. This way, developers can easily modify the visual appearance of the entire application by adjusting the corresponding design token values.
+
+### Example: Using Design Tokens in CSS
+
+```css
+.button {
+  background-color: var(--oryx-color-primary-9);
+  font-size: var(--oryx-typography-h1-size);
+}
+```
+
+## Themes
+
+Design tokens are organized in themes. This allows you to quickly switch from one theme to another as well as to create your own theme.