docs: new Colors doc page

src/essentials/Colors/Colors.ts

@@ -1,6 +1,6 @@
 import { SemanticColorsSchema } from './types';
 
-// Global Colors Tier (--wave-g-color-...)
+// Bare Colors Tier (--wave-b-color-...)
 export const Colors = {
  white: 'hsl(0, 0%, 100%)',
  black: 'hsl(0, 0%, 0%)',
@@ -109,7 +109,7 @@ export const SemanticColors = {
  },
  neutral: {
  default: Colors.white,
- emphasized: Colors.blue.primary[50],
+ emphasized: Colors.blue.primary[50]
  },
  accent: {
  faded: Colors.blue.secondary[50],
@@ -193,7 +193,7 @@ export const SemanticColors = {
  danger: {
  faded: Colors.orange[350],
  default: Colors.orange[900]
- },
+ }
  },
  shadow: {
  default: Colors.blue.primary[200]

src/essentials/Colors/RedesignedColors.ts

@@ -1,6 +1,6 @@
 import { SemanticColorsSchema } from './types';
 
-// Global Tier (--wave-g-color-...)
+// Bare Tier (--wave-b-color-...)
 export const Colors = {
  white: 'hsl(0, 0%, 99%)',
  black: 'hsl(0, 0%, 0%)',
@@ -102,7 +102,7 @@ export const SemanticColors = {
  },
  neutral: {
  default: Colors.white,
- emphasized: Colors.neutral[50],
+ emphasized: Colors.neutral[50]
  },
  accent: {
  faded: Colors.primary[50],
@@ -186,7 +186,7 @@ export const SemanticColors = {
  danger: {
  faded: Colors.red[350],
  default: Colors.red[900]
- },
+ }
  },
  shadow: {
  default: Colors.neutral[200]

src/essentials/Colors/docs/Colors.storybook.mdx

@@ -1,119 +1,80 @@
-import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';
-import { Colors } from '../Colors';
-import { SemanticColorsTable } from './SemanticColorsTable';
+import { Meta } from '@storybook/blocks';
+import { Colors, SemanticColors } from '../Colors';
+import { CssVariablesTable } from './SemanticColorsTable';
 
 <Meta title="Essentials/Colors" component={Colors} />
 
 # Colors
 
-## Brand
-
-Elements that must reflect the FREENOW brand should use the primary brand colors. Each color has darker and lighter shades.
-
-<ColorPalette>
- <ColorItem
- title="Action Blue"
- subtitle=""
- colors={{
- ACTION_BLUE_1000: Colors.ACTION_BLUE_1000,
- ACTION_BLUE_900: Colors.ACTION_BLUE_900,
- ACTION_BLUE_350: Colors.ACTION_BLUE_350,
- ACTION_BLUE_50: Colors.ACTION_BLUE_50
- }}
- />
- <ColorItem
- title="Freedom Red"
- subtitle=""
- colors={{
- FREEDOM_RED_1000: Colors.FREEDOM_RED_1000,
- FREEDOM_RED_900: Colors.FREEDOM_RED_900
- }}
- />
-</ColorPalette>
-
-## Neutral Colors
-
-Text, backgrounds, lines and borders should use neutral colors. There are additional darker and lighter shades of
-Authentic Blue, especially for certain backgrounds.
-
-<ColorPalette>
- <ColorItem
- title="Authentic Blue"
- subtitle="dark shades"
- colors={{
- AUTHENTIC_BLUE_1100: Colors.AUTHENTIC_BLUE_1100,
- AUTHENTIC_BLUE_900: Colors.AUTHENTIC_BLUE_900,
- AUTHENTIC_BLUE_550: Colors.AUTHENTIC_BLUE_550
- }}
- />
- <ColorItem
- title="Authentic Blue"
- subtitle="light shades"
- colors={{
- AUTHENTIC_BLUE_350: Colors.AUTHENTIC_BLUE_350,
- AUTHENTIC_BLUE_200: Colors.AUTHENTIC_BLUE_200,
- AUTHENTIC_BLUE_50: Colors.AUTHENTIC_BLUE_50,
- WHITE: Colors.WHITE
- }}
- />
-</ColorPalette>
-
-## UI Colors
-
-Action buttons, alert messages, and form elements should use the main UI Colors. Input fields, for example, can
-get positive and negative feedback, whereas alert messages can have warning feedback.
-
-<ColorPalette>
- <ColorItem
- title="Positive Green"
- subtitle=""
- colors={{
- POSITIVE_GREEN_1000: Colors.POSITIVE_GREEN_1000,
- POSITIVE_GREEN_900: Colors.POSITIVE_GREEN_900,
- POSITIVE_GREEN_350: Colors.POSITIVE_GREEN_350,
- POSITIVE_GREEN_50: Colors.POSITIVE_GREEN_50
- }}
- />
- <ColorItem
- title="Attention Yellow"
- subtitle=""
- colors={{
- ATTENTION_YELLOW_900: Colors.ATTENTION_YELLOW_900,
- ATTENTION_YELLOW_350: Colors.ATTENTION_YELLOW_350,
- ATTENTION_YELLOW_50: Colors.ATTENTION_YELLOW_50
- }}
- />
- <ColorItem
- title="Negative Orange"
- subtitle=""
- colors={{
- NEGATIVE_ORANGE_1000: Colors.NEGATIVE_ORANGE_1000,
- NEGATIVE_ORANGE_900: Colors.NEGATIVE_ORANGE_900,
- NEGATIVE_ORANGE_350: Colors.NEGATIVE_ORANGE_350,
- NEGATIVE_ORANGE_50: Colors.NEGATIVE_ORANGE_50
- }}
- />
- <ColorItem
- title="Bumpy Magenta"
- subtitle=""
- colors={{
- BUMPY_MAGENTA_1000: Colors.BUMPY_MAGENTA_1000,
- BUMPY_MAGENTA_900: Colors.BUMPY_MAGENTA_900,
- BUMPY_MAGENTA_350: Colors.BUMPY_MAGENTA_350,
- BUMPY_MAGENTA_50: Colors.BUMPY_MAGENTA_50
- }}
- />
-</ColorPalette>
-
-## Functional Reference
-
-In the table below you can find all functional colors with their name, and their color values. They can be accessed with
-the `themeGet` function which is exported directly from the library.
-
-```jsx
-import { themeGet } from '@freenow/wave';
-
-const myTextColor = themeGet('semanticColors.text.secondary');
+Wave has a set of colors that are used throughout the design system. HSL model is used to define colors.
+
+The exact set of colors depend on the theme that is used. Two themes provided as a part of the library:
+
+- `classic` - the default theme with primary blue color;
+- `modern` - the redesigned theme with maroon primary color.
+
+Each theme provides a set of CSS variables used to style components. They are divided into two tiers:
+
+- _bare colors_ - matching color names provided by the theme. this tier is theme-specific and changes when the theme changes;
+- _semantic colors_ - color names that convey semantic meaning, e.g. `foreground-primary`. This tier is theme-agnostic and does not change when the theme changes.
+
+You can create you own theme by creating a set of semantic CSS variables with predefined names.
+
+## Semantic Colors
+
+Semantic color tokens represent not just a color value but also a semantic role it's used for.
+In Wave, most color tokens belong to one of three roles: _foreground_, _background_, and _border_.
+By assigning semantic roles to colors, we achieve predictable theming and dark mode support.
+
+You can build your custom components using the semantic color tokens, and they will automatically support theming and dark mode.
+Prefer to use them for your app.
+
+Every color token follows the naming convention:
+
+- design system prefix for semantic colors `wave-s`;
+- semantic role `foreground`, `background-surface`, `background-element`, or `border`;
+- color name `primary`, `neutral`, `info`, `accent`, `success`, `warning`, `danger`, `disabled`;
+- optional modifier `default`, `faded` or `highlighted`.
+
+Use `getSemanticColor` function to reduce boilerplate when using semantic colors in your components:
+
+```ts
+const BeautifulParagraph = styled.p`
+ background-color: ${getSemanticColor('background-surface-primary-default')};
+ color: ${getSemanticColor('foreground-on-background-primary')};
+`;
 ```
 
-<SemanticColorsTable />
+<CssVariablesTable tokens={SemanticColors} tier="s" />
+
+## Bare Colors
+
+Bare color tokens are static and not themeable. They are used to define semantic colors and should not be used directly in your components.
+
+We provide CSS variables for bare colors as an **escape hatch** for cases when you need to use a color that is not covered by semantic colors.
+Please, report such cases to us, so we can add the missing semantic color.
+
+Bare color tokens aren't accessible via `getSemanticColor` function. Read the CSS variable directly, they have `--wave-b-` prefix, followed by the color name:
+
+```ts
+const BeautifulParagraph = styled.p`
+ color: var('--wave-b-red-900')};
+`;
+```
+
+<CssVariablesTable tokens={Colors} tier="b" />
+
+## HSL variables (`-hsl`)
+
+Wave stores HSL color values in semantic tokens. It becomes a challenge to apply opacity to a color, without making the whole component transparent.
+That's why together with semantic tokens, we expose HSL channels as separate variables. They follow the same convention as semantic tokens, but ends with the `-hsl` suffix:
+
+For example, `background-surface-primary-default` stores `hsl(210, 100%, 50%)`, but `background-surface-primary-default-hsl` stores `210, 100%, 50%`
+
+Use them, when you need an alpha channel:
+
+```ts
+const BeautifulParagraph = styled.p`
+ background-color: hsla(${getSemanticColor('background-surface-primary-default-hsl')}, 0.5);
+`;
+```