docs: Oryx design tokens

_data/sidebars/scos_dev_sidebar.yml

@@ -3437,16 +3437,18 @@ entries:
             - title: Integration of backend APIs
               url: /docs/scos/dev/front-end-development/oryx/reactivity/oryx-integration-of-backend-apis.html
             - title: Signals
-              url: /docs/scos/dev/front-end-development/oryx/reactivity/signals.html              
+              url: /docs/scos/dev/front-end-development/oryx/reactivity/signals.html
         - title: Styling
           include_versions:
           - "202212.0"
           - "202307.0"
           nested:
-          - title: "Color system"
+          - title: Color system
             url: /docs/scos/dev/front-end-development/oryx/styling/oryx-color-system.html
+          - title: Design tokens
+            url: /docs/scos/dev/front-end-development/oryx/styling/oryx-design-tokens.html
           - title: Typography
-            url: /docs/scos/dev/front-end-development/oryx/styling/typography.html
+            url: /docs/scos/dev/front-end-development/oryx/styling/oryx-typography.html
 
     - title: Marketplace
       include_versions:

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,9 +7,9 @@ template: concept-topic-template
 
 Colors are used everywhere throughout UI components and are important for a good user experience. To enable you to adjust colors throughout the application to your needs, Oryx provides a configurable color system.
 
-The color system lets you set up color values globally and override them per component. Components don't 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.>>>>>>> master
 
-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.
+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 to the color system and are part of the theme configuration. This lets you configure the colors in a global theme.
 
 ## Color palette
 
@@ -31,16 +31,16 @@ Colors can be provided for both light and dark modes. The dark mode is another i
 
 There are eight semantic color types used in Oryx components:
 
-| TYPE      | DESCRIPTION                                                                                                                                                                                                                                     |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Primary   | Typically represents the brand color of a website. This color is used as the call-to-action color in many components.                                                                                                                              |
-| Secondary | Additional accent color that can be used for more color-full experiences. Oryx components rarely use the secondary color.                                                                                                                       |
+| TYPE      | DESCRIPTION         |
+| --------- | ------- |     
+| Primary   | Typically represents the brand color of a website. This color is used as the call-to-action color in many 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 or background color. The Radix color system provides different neutrals that pair nicely with the color of choice, also known as "natural pairing". |
-| Highlight | Used to highlight a sale.                                                                                                                                                                                                |
-| Success   | 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.                                                                                                                                                                                                                             |
+| Highlight | Used to highlight a sale.                                 |
+| Success   | 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.         |
 
 ## Color steps
 
@@ -52,9 +52,9 @@ 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 like `red` or `blue`, hex color, HCL, or RBA. Oryx doesn't interfere with the provided colors but uses them as-is.
 
-
 ## Configure colors 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.
 
 ```ts
@@ -110,7 +110,9 @@ Even though it's optional, we recommend providing both the light and dark mode c
 
 ## 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]`
 
@@ -127,4 +129,4 @@ button:hover {
 }
 ```
 
-The example shows the usage of design tokens in CSS. The primary color is defined for the default state of the the button background color. When the user hovers over the button, the 400 color shade is used. It works consistently with all colors. The buttons have a white foreground color on a colorful background. In case the background color is bright, the foreground color becomes black.
+The example shows the usage of design tokens in CSS. The primary color is defined for the default state of the the button background color. When the user hovers over the button, the 400 color shade is used. It works consistently with all colors. The buttons have a white foreground color on a colorful background. In case the background color is bright, the foreground color becomes black.

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

@@ -0,0 +1,49 @@
+---
+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 provide a powerful system for achieving consistent and customizable styles throughout an Oryx application. They are extensively used inside the [color system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/styling/oryx-color-system.html), typography, icons, and many more. Ensuring a clean separation between styles and components, design tokens make 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. To avoid naming conflicts with third-party variables, they are prefixed with `oryx` and are written in kebab-case.
+
+The variables are written in the root element of the application, the `oryx-app` component by default. The variables are inherited by all descendants of the root component. This makes it convenient to access the variables throughout the entire application. At the same time, they can be overridden at any element in the application.
+
+If you like to reuse the 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 a consistent and cohesive visual experience. Instead of hardcoding style values directly in component CSS, design tokens are used as CSS variables to define the styles. This way, you can easily change the visual appearance of the entire application by adjusting the corresponding design token values.
+
+The following example shows how to avoid hardcoded style values by using design tokens:
+
+```css
+.button {
+  background-color: var(--oryx-color-primary-9);
+  font-size: var(--oryx-typography-h1-size);
+}
+```
+
+The CSS variables are inherited throughout all descendants, but you can override the value anywhere in the DOM tree. The following example shows how to override a design token anywhere in the DOM.
+
+```html
+<div style="--oryx-color-primary-9: red">
+  <button>Primary 9 color has become red</button>
+</div>
+```
+
+## Themes
+
+Design tokens are organized in themes. The Oryx [preset package](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-presets.html) provides standard themes to get you started. You can use a standard theme, customize a standard theme, or create your own.
+
+<!-- TODO: add a note link to the theme docs once its ready -->

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

@@ -13,7 +13,7 @@ Oryx is currently running under an *Early Access Release*. Early Access Releases
 
 The [presets package](https://www.npmjs.com/package/@spryker-oryx/presets) contains standard feature sets and resources that are used to create sample applications without writing [boilerplate](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-boilerplate.html). Presets might be too opinionated to use for a production application, but they let you get started quickly.
 
-Presets are typically used to demonstrate or try out Oryx applications. In product applications, the boilerplate is set up in more optimized way, by leaving out the features that are not used.
+Presets are typically used to demonstrate or try out Oryx applications. In production applications, the boilerplate is set up in a more optimized way, by leaving out the features that are not used.
 
 ## Dependencies
 
@@ -49,7 +49,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: