diff --git a/libs/design/guides/foundations/color.md b/libs/design/guides/foundations/color.md index 9369637384..52f2912c02 100644 --- a/libs/design/guides/foundations/color.md +++ b/libs/design/guides/foundations/color.md @@ -2,7 +2,9 @@ Color helps to distinguish and create consistent experiences across products. It highlights key areas, conveys status, urgency, and guides attention. ## Color palettes -The design system includes three core palettes that reflect Daffodil's brand identity, three palettes used to indicate status, and a neutral palette that is dominant throughout the design system. These palettes are built using [HSLuv](https://www.hsluv.org/), a color space designed as a human-friendly alternative to the standard HSL. It aims to address the limitations of traidtional color spaces like RGB and HSL. +The default Daffodil design system theme features three core palettes that defines Daffodil's brand identity, three status indicating palettes, and a neutral palette that is dominant throughout the design system. These palettes are built using [HSLuv](https://www.hsluv.org/), a perceptually uniform color space designed to be more human-friendly than traditional models like RGB and HSL. By addressing the inconsistencies of conventional color spaces, HSLuv ensures predictable contrast and visual harmony. + +Each palette consists of a collection of [perceptually uniform colors](https://programmingdesignsystems.com/color/perceptually-uniform-color-spaces/) with consistent contrast ratios, enhancing accessibility and usability across the design system. These palettes are represented as Sass maps, where each individual color value is referred to as a **hue**. For guidance on how to set up your theme with customized palettes, see theming's [getting started](/libs/design/guides/theming/getting-started.md) guide. diff --git a/libs/design/guides/getting-started.md b/libs/design/guides/getting-started.md index abffe0ce88..0a56a605af 100644 --- a/libs/design/guides/getting-started.md +++ b/libs/design/guides/getting-started.md @@ -49,28 +49,26 @@ There is a minimal required global style for the Daffodil Design System to opera > For more information on our approach to these kinds of styles, see the [Global Styles guide.](/libs/design/guides/foundations/global-styles.md) ## Add a theme -A theme must be configured in order for the components to work properly. The components in the design library can be configured with customized colors in addition to a dark and light mode for those same colors. +A theme must be configured in order for Daffodil Design components to work properly. -To use `@daffodil/design`'s default theme, include the following in your `styles.scss` file: +The `daff-theme` mixin includes styles for all components. The example below demonstrates how to use Daffodil Design's default theme, where the `$theme` variable is the default configured theme. The mixin is included in the `html` selector to ensure that component styles are applied across the entire application. ```scss -@use '@daffodil/design/scss/theme' as daff; +@use '@daffodil/design/scss/theme' as daff-theme; -.daff-theme-light { - @include daff.daff-theme(daff.$theme); -} - -.daff-theme-dark { - @include daff.daff-theme(daff.$theme-dark); +html { + @include daff-theme.daff-theme(daff-theme.$theme); } ``` -See the [Theming guide](/libs/design/guides/theming/setting-up.md) for more information on how to customize your own theme. +The components in Daffodil Design can be configured with custom colors in addition to a dark and light mode for those same colors. See the [theming guide](/libs/design/guides/theming/setting-up.md) for more information on how to customize your own theme. ## Use a component Now you're ready to use Daffodil Design [components](/docs/design/components)! For example, here's how to use the [Hero](/libs/design/hero/README.md) component. ```ts +import { DAFF_HERO_COMPONENTS } from '@daffodil/design/hero'; + @Component({ standalone: true, selector: 'custom-component', @@ -98,4 +96,4 @@ With the component imported, you can add it to your `CustomComponent` template l ## Next steps We've just walked through the basics of setting up `@daffodil/design` and using the basic features of the Hero component. Now try to change the color of the [Hero](/libs/design/hero/README.md)! -Check out the [full list of components](/docs/design/components), try and add them to your sample app, and imagine all the wonderful things you can now build! \ No newline at end of file +Check out the [full list of components](/docs/design/components). Try and add them to your sample app and imagine all the wonderful things you can now build! \ No newline at end of file diff --git a/libs/design/guides/theming.md b/libs/design/guides/theming.md new file mode 100644 index 0000000000..1e1d9d8394 --- /dev/null +++ b/libs/design/guides/theming.md @@ -0,0 +1,195 @@ +# Theming +Daffodil's extensible theming architecture allows you to customize our components to match your brand or product's visual style using a set of universal variables, eliminating the need for individual component modifications. + +## Theming basics +Daffodil Design is built with [Sass](https://sass-lang.com/). You should be familiar with the basics of CSS and Sass, including variables, functions, and mixins. + +A theme must be configured in order for the components to work properly. + +## Default theme +The `daff-theme` mixin includes styles for all components. The example below demonstrates how to use Daffodil Design's default theme, where the `$theme` variable is the default configured theme. The mixin is included in the `html` selector to ensure that component styles are applied across the entire application. + +```scss +@use '@daffodil/design/scss/theme' as daff-theme; + +html { + @include daff-theme.daff-theme(daff-theme.$theme); +} +``` + +## Modes +Dark and light modes are supported out of the box in all Daffodil Design components, allowing you to easily switch appearances without additional work. + +### Usage +To support light and dark mode in your application: + +1. Include the `daff-theme` mixin with `$theme` and `$theme-dark` variables to the `.daff-theme-light` and `.daff-theme-dark` classes. + +```scss +@use '@daffodil/design/scss/theme' as daff-theme; + +.daff-theme-light { + @include daff-theme.daff-theme(daff-theme.$theme); +} + +.daff-theme-dark { + @include daff-theme.daff-theme(daff-theme.$theme-dark); +} +``` + +> The `$theme` and `$theme-dark` variables are based on Daffodil Design's default configured theme. Learn how to customize your own theme [here](/libs/design/guides/theming.md#customize-your-own-theme). + +2. Add `DAFF_THEME_INITIALIZER` to the `providers` of your root component. + +```ts +import { NgModule } from '@angular/core'; +import { DAFF_THEME_INITIALIZER } from '@daffodil/design'; + +@NgModule({ + providers: [ + DAFF_THEME_INITIALIZER, + ], +}) +class AppModule {} +``` + +3. Use `DaffThemingService` and `DaffTheme` to set up a theme switch component with a button to toggle between modes. + +```html + +``` + +```ts +import { + ChangeDetectionStrategy, + Component, + OnInit, +} from '@angular/core'; +import { + faMoon, + faSun, + IconDefinition, + FaIconComponent, +} from '@fortawesome/free-solid-svg-icons'; +import { Observable } from 'rxjs'; +import { map } from 'rxjs/operators'; + +import { + DaffTheme, + DaffThemingService, +} from '@daffodil/design'; + +export const THEME_SWITCH_TO_LIGHT_LABEL = 'Enable light mode'; +export const THEME_SWITCH_TO_DARK_LABEL = 'Enable dark mode'; + +@Component({ + selector: 'theme-switch-button', + templateUrl: './theme-switch-button.component.html', + changeDetection: ChangeDetectionStrategy.OnPush, + imports: [ + FaIconComponent, + ], +}) +export class ThemeSwitchButtonComponent implements OnInit { + theme$: Observable; + ariaLabel$: Observable; + icon$: Observable; + + constructor(private themeService: DaffThemingService) { } + + ngOnInit() { + this.theme$ = this.themeService.getTheme(); + this.ariaLabel$ = this.theme$.pipe( + map((theme) => theme === DaffTheme.Light ? THEME_SWITCH_TO_DARK_LABEL : THEME_SWITCH_TO_LIGHT_LABEL), + ); + this.icon$ = this.theme$.pipe( + map((theme) => theme === DaffTheme.Light ? faMoon : faSun), + ); + } + + onButtonClick() { + this.themeService.switchTheme(); + } +} +``` + +## Customize your own theme +Daffodil allows you to define your own themes to match your brand or product's visual style. The guides below will walk you through the entire process. + +### Create custom palettes +Create a palettes file that includes Sass maps that can be used as `$primary`, `$secondary`, and `$teritary` colors. Your Sass maps must have hues from 10 to 100, with a step increment of 10 like the example below: + +```scss +$daff-blue: ( + 10: #ebf1ff, + 20: #c4d8ff, + 30: #9dbeff, + 40: #79a7ff, + 50: #548fff, + 60: #1f66ff, + 70: #093cf3, + 80: #001bcb, + 90: #00098a, + 100: #000033 +); +``` + +### Configure your custom palettes +Configure your app to support the custom palettes and set defaults for each palette by using the `daff-configure-palettes` function: + +| Argument | Description | +| -------------- | ------------------------------------------------------------------------------ | +| $color-palette | The name of the palette to read from. | +| $hue | The hue number to read from the palette. This defaults to 60 if not specified. | + +```scss +@use '@daffodil/design/scss/theme' as daff-theme; +@use 'app-color-palettes' as palette; // path to palettes file + +$app-primary: daff-theme.daff-configure-palette(palette.$app-green, 60); +$app-secondary: daff-theme.daff-configure-palette(palette.$app-blue, 60); +$app-tertiary: daff-theme.daff-configure-palette(palette.$app-purple, 60); +``` + +### Define your themes +Define your themes by using the `daff-configure-theme` function: + +| Argument | Description | +| -------- | ------------------------------------------------------------------------- | +| $primary | Specifies the configured palette to use for your app's primary color. | +| $secondary | Specifies the configured palette to use for your app's secondary color. | +| $tertiary | Specifies the configured palette to use for your app's tertiary color. | +| $type | Specifies the type of theme. This can be `light` or `dark`. | + +```scss +@use '@daffodil/design/scss/theme' as daff-theme; +@use 'app-color-palettes' as palette; // path to palettes file + +$app-primary: daff-theme.daff-configure-palette(palette.$app-green, 60); +$app-secondary: daff-theme.daff-configure-palette(palette.$app-blue, 60); +$app-tertiary: daff-theme.daff-configure-palette(palette.$app-purple, 60); + +$theme-light: daff-theme.daff-configure-theme($app-primary, $app-secondary, $app-tertiary, 'light'); + +$app-primary-dark: daff-theme.daff-configure-palette(palette.$app-green, 50); +$app-secondary-dark: daff-theme.daff-configure-palette(palette.$app-blue, 50); +$app-tertiary-dark: daff-theme.daff-configure-palette(palette.$app-purple, 50); + +$theme-dark: daff-theme.daff-configure-theme($app-primary-dark, $app-secondary-dark, $app-tertiary-dark, 'dark'); +``` + +### Set up the styles file with your custom theme +```scss +@use '@daffodil/design/scss/theme' as daff-theme; +@use 'app-theme'; + +.daff-theme-light { + @include daff-theme.daff-theme(app-theme.$theme-light); +} + +.daff-theme-dark { + @include daff-theme.daff-theme(app-theme.$theme-dark); +} +``` diff --git a/libs/design/guides/theming/index.json b/libs/design/guides/theming/index.json deleted file mode 100644 index ac01e69144..0000000000 --- a/libs/design/guides/theming/index.json +++ /dev/null @@ -1,3 +0,0 @@ -[ - "setting-up" -] \ No newline at end of file diff --git a/libs/design/guides/theming/setting-up.md b/libs/design/guides/theming/setting-up.md deleted file mode 100644 index d606e09821..0000000000 --- a/libs/design/guides/theming/setting-up.md +++ /dev/null @@ -1,124 +0,0 @@ -# Setting up your theme -Daffodil's theming capabilities enable you to customize `@daffodil/design`'s component color styles to reflect your brand or product. - -## Overview -Themes allow you to customize `@daffodil/design` components to match your brand or product's visual style using a set of universal variables, eliminating the need for individual component modifications. - -## Before you begin -`@daffodil/design` is built with [Sass](https://sass-lang.com/). You should be familiar with the basics of CSS and Sass, including variables, functions, and mixins. - -## Modes -Dark and light modes are supported in all `@daffodil/design` components. When a mode is not specified, Daffodil defaults to the `light` mode. - -## Palettes -A palette is a collection of [perceptually uniform colors](https://programmingdesignsystems.com/color/perceptually-uniform-color-spaces/) with consistent contrast ratios. `@daffodil/design`'s color palettes are represented by a Sass map, with each value in a palette called a **hue**. - -`@daffodil/design` includes three core palettes that reflect our brand identity, three palettes used to indicate status, and a neutral palette that is dominant throughout the design system. You can choose to use our palettes or define your own. - -## Defining a theme - -### Using Daffodil's default theme - -```scss -@use '@daffodil/design/scss/theme' as daff-theme; -``` - -Create classes in the `styles.scss` file to include the `daff-theme` mixin for `$theme` and `$theme-dark` variables. This will allow you to set a click event on a button to switch between modes. View this setup in [Stackblitz](https://stackblitz.com/edit/ng13-daffodil-design). - -```scss -@use '@daffodil/design/scss/theme' as daff-theme; - -.app-theme-light { - @include daff-theme.daff-theme(daff-theme.$theme); -} - -.app-theme-dark { - @include daff-theme.daff-theme(daff-theme.$theme-dark); -} -``` - -### Customizing your own theme - -#### Create custom palettes -Create a palettes file that includes Sass maps that can be used as `$primary`, `$secondary`, and `$teritary` colors. Your Sass maps must have hues from 10 to 100, with a step increment of 10 like the example below: - -```scss -$daff-blue: ( - 10: #ebf1ff, - 20: #c4d8ff, - 30: #9dbeff, - 40: #79a7ff, - 50: #548fff, - 60: #1f66ff, - 70: #093cf3, - 80: #001bcb, - 90: #00098a, - 100: #000033 -); -``` - -#### Configure your custom palettes -Configure your app to support the custom palettes and set defaults for each palette by using the `daff-configure-palettes` function: - -| Argument | Description | -| -------------- | ------------------------------------------------------------------------------ | -| $color-palette | The name of the palette to read from. | -| $hue | The hue number to read from the palette. This defaults to 60 if not specified. | - -```scss -app-theme.scss - -@use '@daffodil/design/scss/theme' as daff-theme; -@use 'app-color-palettes' as palette; // path to palettes file - -$app-primary: daff-theme.daff-configure-palette(palette.$app-green, 60); -$app-secondary: daff-theme.daff-configure-palette(palette.$app-blue, 60); -$app-tertiary: daff-theme.daff-configure-palette(palette.$app-purple, 60); -``` - -#### Define your themes -Define your themes by using the `daff-configure-theme` function: - -| Argument | Description | -| -------- | ------------------------------------------------------------------------- | -| $primary | Specifies the configured palette to use for your app's primary color. | -| $secondary | Specifies the configured palette to use for your app's secondary color. | -| $tertiary | Specifies the configured palette to use for your app's tertiary color. | -| $type | Specifies the type of theme. This can be `light` or `dark`. | - -`app-theme.scss` - -```scss -@use '@daffodil/design/scss/theme' as daff-theme; -@use 'app-color-palettes' as palette; // path to palettes file - -$app-primary: daff-theme.daff-configure-palette(palette.$app-green, 60); -$app-secondary: daff-theme.daff-configure-palette(palette.$app-blue, 60); -$app-tertiary: daff-theme.daff-configure-palette(palette.$app-purple, 60); - -$theme: daff-theme.daff-configure-theme($app-primary, $app-secondary, $app-tertiary, 'light'); - -$app-primary-dark: daff-theme.daff-configure-palette(palette.$app-green, 50); -$app-secondary-dark: daff-theme.daff-configure-palette(palette.$app-blue, 50); -$app-tertiary-dark: daff-theme.daff-configure-palette(palette.$app-purple, 50); - -$theme-dark: daff-theme.daff-configure-theme($app-primary-dark, $app-secondary-dark, $app-tertiary-dark, 'dark'); -``` - -#### Setting up the styles file with your custom theme -Create classes in the `styles.scss` file to include the `daff-theme` mixin for `$theme` and `$theme-dark` variables. This will allow you to set a click event on a button to switch between modes. [View this setup in Stackblitz](https://stackblitz.com/edit/ng13-daffodil-design-custom-theme). - -`styles.scss` - -```scss -@use '@daffodil/design/scss/theme' as daff-theme; -@use 'app-theme'; - -.daff-theme-light { - @include daff-theme.daff-theme(app-theme.$theme); -} - -.daff-theme-dark { - @include daff-theme.daff-theme(app-theme.$theme-dark); -} -```