diff --git a/_data/sidebars/scos_dev_sidebar.yml b/_data/sidebars/scos_dev_sidebar.yml index cce87509b5e..a8bbc6c568e 100644 --- a/_data/sidebars/scos_dev_sidebar.yml +++ b/_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: diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/oryx-presets.md b/docs/scos/dev/front-end-development/202212.0/oryx/oryx-presets.md index ed6a48bf3e1..4ab2fa88cd0 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/oryx-presets.md +++ b/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: diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-color-system.md b/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-color-system.md index f8cc2e4aafe..ac919d5d0d5 100644 --- a/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-color-system.md +++ b/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. \ No newline at end of file +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. diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-design-tokens.md b/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-design-tokens.md new file mode 100644 index 00000000000..11684795f92 --- /dev/null +++ b/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 +
+ +
+``` + +## 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. + + diff --git a/docs/scos/dev/front-end-development/202212.0/oryx/styling/typography.md b/docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-typography.md similarity index 100% rename from docs/scos/dev/front-end-development/202212.0/oryx/styling/typography.md rename to docs/scos/dev/front-end-development/202212.0/oryx/styling/oryx-typography.md diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/oryx-presets.md b/docs/scos/dev/front-end-development/202307.0/oryx/oryx-presets.md index 61fb63dda84..35e9fd777c8 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/oryx-presets.md +++ b/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: diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-color-system.md b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-color-system.md index b760f04d812..e4917143bfa 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-color-system.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-color-system.md @@ -11,13 +11,12 @@ Oryx is currently running under an *Early Access Release*. Early Access Releases {% endinfo_block %} -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. -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. +An important part of the application user interface is 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 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. -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 @@ -39,16 +38,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 | +| 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 @@ -60,7 +59,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 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. @@ -118,7 +116,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]` diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-design-tokens.md b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-design-tokens.md new file mode 100644 index 00000000000..4b9ff1c530c --- /dev/null +++ b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-design-tokens.md @@ -0,0 +1,55 @@ +--- +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 +--- + +{% info_block warningBox %} + +Oryx is currently running under an Early Access Release. Early Access Releases are subject to specific legal terms, they are unsupported and do not provide production-ready SLAs. They can also be deprecated without a General Availability Release. Nevertheless, we welcome feedback from early adopters on these cutting-edge, exploratory features. + +{% endinfo_block %} + +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 +
+ +
+``` + +## 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. + + diff --git a/docs/scos/dev/front-end-development/202307.0/oryx/styling/typography.md b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-typography.md similarity index 93% rename from docs/scos/dev/front-end-development/202307.0/oryx/styling/typography.md rename to docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-typography.md index 981dc51f1ea..a488ec08a9c 100644 --- a/docs/scos/dev/front-end-development/202307.0/oryx/styling/typography.md +++ b/docs/scos/dev/front-end-development/202307.0/oryx/styling/oryx-typography.md @@ -5,6 +5,13 @@ last_updated: July 9, 2023 template: concept-topic-template --- + +{% info_block warningBox %} + +Oryx is currently running under an Early Access Release. Early Access Releases are subject to specific legal terms, they are unsupported and do not provide production-ready SLAs. They can also be deprecated without a General Availability Release. Nevertheless, we welcome feedback from early adopters on these cutting-edge, exploratory features. + +{% endinfo_block %} + Typography is an important part of the look and feel of a web page. It contributes to the readability of text but also defines how page structure is perceived. Big headers typically go first and are perceived as more important, whereas smaller text seems less important. The typography system lets you set up font size, weight, and line height globally. Components don't define _values_ for fonts directly in their CSS but use _design tokens_ to connect to the font values. Design tokens are CSS variables that you can configure in your project implementation. @@ -15,7 +22,7 @@ Like all design tokens, the typography system is configurable by themes, so that Oryx is based on web components, using the shadow DOM. The shadow DOM doesn't leak out any styles outside a component, and components don't inherit styles from ancestor elements. However, there are a few exceptions. Font face and size, line height and color are the few CSS properties that cascade down the shadow DOM. This lets you define those rules high up in the DOM tree. -Because most design system components inehrit typography from ancestor elements, you can provide the basis typography configuration in the root of the application. Oryx applications use the `` component, which provides this setup: +Because most design system components inherit typography from ancestor elements, you can provide the basis typography configuration in the root of the application. Oryx applications use the `` component, which provides this setup: ```css :host {