docs(design): color and theming docs update (#3310)

Author: xelaint

libs/design/guides/foundations/color.md

@@ -1,10 +1,15 @@
 # Color
-Color helps to distinguish and create consistent experiences across products.
+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.
+
+For guidance on how to set up your theme with customized palettes, see the [Theming](/libs/design/guides/foundations/theming.md) guide.
 
 ## Accessibility
 We are committed to complying with the [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG/). The design system is built to meet these guidelines automatically. If you choose to identify your own color palettes outside of Daffodil's colors, please make sure to choose primary, secondary, tertiary, and extended colors that will pass the guidelines. Ensure there is sufficient color contrast between elements so that people who are visually impaired can see and use your products.
 
-## Color Contrast
+### Color Contrast
 We have encoded many of the WCAG requirements into our SASS mixins and functions. This means that if you swap to a color palette that does not meet the requirements of WCAG compliance and try to use it within the components, our code will proactively complain and issue errors. This is entirely intentional and will not be changed. The current state of accessibility is lacking, and as a result, we are enforcing accessibility requirements at development time in order to make it easier for developers to accommodate these issues before they are in the hands of users.
 
 To verify contrast ratios, we recommend using this [contrast ratio calculator](https://contrast-ratio.com/).

libs/design/guides/foundations/theming.md

@@ -1,17 +1,46 @@
 # Theming
-Daffodil's theming capabilities enables you to customize `@daffodil/design` components to reflect your brand. A theme consists of custom color configurations that will work in dark and light themes.
+Daffodil's theming capabilities enable you to customize `@daffodil/design`'s component color styles to reflect your brand or product.
 
-## Custom Colors
-:stop: Before you begin, read the [accessibility guide on color in `@daffodil/design`](./color.md#accessibility).
+## 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.
 
-## Themes
-Dark and light modes are supported in all `@daffodil/design` components. When a theme is not specified, Daffodil defaults to the `light` mode.
+## 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**.
 
-## Predefined palettes
-`@daffodil/design` offers predefined palettes based on our brand guidelines. You can choose to use our palettes or define your own. No further configuration is needed in your `app-theme.scss` file if you choose to use `@daffodil/design`'s palettes. Below is an example of the structure of a predefined `@daffodil/design` palette.
+`@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: (
@@ -28,67 +57,58 @@ $daff-blue: (
 );
 ```
 
-### Defining your own palettes
-You can define your own palettes by creating a Sass map that matches the example from above. Your Sass maps must have hues from 10 to 100, with a step increment of 10.
+#### 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:
 
-### Setting up your custom theme file
-Configure your application to support the custom palettes you created by adding the following to your `app-theme.scss` file:
+| 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;
-
-// These palettes describe the colors that make up the "theme" of the components.
-
-$primary: daff-theme.daff-configure-palette(palette.$app-green, 60);
-$secondary: daff-theme.daff-configure-palette(palette.$app-blue, 60);
-$tertiary: daff-theme.daff-configure-palette(palette.$app-purple, 60);
-
-$theme: daff-theme.daff-configure-theme($primary, $secondary, $tertiary, 'light');
-
-$primary-dark: daff-theme.daff-configure-palette(palette.$app-green, 50);
-$secondary-dark: daff-theme.daff-configure-palette(palette.$app-blue, 50);
-$tertiary-dark: daff-theme.daff-configure-palette(palette.$app-purple, 50);
+app-theme.scss
 
-$theme-dark: daff-theme.daff-configure-theme($primary-dark, $secondary-dark, $tertiary-dark, 'dark');
+@use '@daffodil/design/scss/theme' as daff-theme;
+@use 'app-color-palettes' as palette; // path to palettes file
 
-$black: daff-theme.daff-map-deep-get($theme, 'core.black');
-$white: daff-theme.daff-map-deep-get($theme, 'core.white');
-$neutral: daff-theme.daff-map-deep-get($theme, 'core.neutral');
+$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);
 ```
 
-### Setting up the styles file with `@daffodil/design`'s theme
-Use `@daffodil/design`'s theme module to the `styles.scss` file:
+#### Define your themes
+Define your themes by using the `daff-configure-theme` function:
 
-```scss
-@use '@daffodil/design/scss/theme' as daff-theme;
-```
+| 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`.                  |
 
-Create classes in the `styles.scss` file to include the `theme` module 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)
+`app-theme.scss`
 
 ```scss
 @use '@daffodil/design/scss/theme' as daff-theme;
+@use 'app-color-palettes' as palette; // path to palettes file
 
-.daff-theme-light {
-	@include daff-theme.daff-theme(daff-theme.$theme);
-}
+$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);
 
-.daff-theme-dark {
-	@include daff-theme.daff-theme(daff-theme.$theme-dark);
-}
-```
+$theme: daff-theme.daff-configure-theme($app-primary, $app-secondary, $app-tertiary, 'light');
 
-### Setting up the styles file with your custom theme
-Add `app-theme.scss` to the `styles.scss` file:
+$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);
 
-```scss
-@use '@daffodil/design/scss/theme' as daff-theme;
-@use 'app-theme';
+$theme-dark: daff-theme.daff-configure-theme($app-primary-dark, $app-secondary-dark, $app-tertiary-dark, 'dark');
 ```
 
-> These lines include theme variables and functions that will generate the theme CSS and style the components.
+#### 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).
 
-Create classes in the `styles.scss` file to include the `theme` module 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;