jb-core/theme/stories/colors.mdx

jb design system core modules

import {Meta,ColorPalette,ColorItem, Heading, Subheading, } from '@storybook/blocks'
import {defaultColors as colors} from 'jb-core/theme';

<Meta title="Theme/Colors" />
<Heading>Color Palette</Heading>
<Subheading >all color are based on oklch() color space</Subheading>
<br/>
<ColorPalette>
  <ColorItem title="single" description="" colors={{'black': colors.single.black.value,'white':colors.single.white.value, 'highlight':colors.single.highlight.value}}/>
  <ColorItem title="neutral" description="" colors={{'main':colors.neutral[0].value,'d1':colors.neutral[1].value,'d2':colors.neutral[2].value,'d3':colors.neutral[3].value,'d4':colors.neutral[4].value,'d5':colors.neutral[5].value,'d6':colors.neutral[6].value,'d7':colors.neutral[7].value,'d8':colors.neutral[8].value,'d9':colors.neutral[9].value,'d10':colors.neutral[10].value}}/>
  <ColorItem title="primary" description="" colors={{'main':colors.primary.main.value,'lighter':colors.primary.light.value, dark:colors.primary.dark.value,'subtle':colors.primary.subtle.value, 'contrast':colors.primary.contrast.value ,'hover':colors.primary.hover.value,'pressed':colors.primary.pressed.value}}/>
  <ColorItem title="secondary" description="" colors={{'main':colors.secondary.main.value, 'lighter':colors.secondary.light.value, dark:colors.secondary.dark.value,'subtle':colors.secondary.subtle.value, 'contrast':colors.secondary.contrast.value,'hover':colors.secondary.hover.value,'pressed':colors.secondary.pressed.value}}/>
  <ColorItem title="success" description="" colors={{'main':colors.green.main.value,'lighter':colors.green.light.value, dark:colors.green.dark.value,'subtle':colors.green.subtle.value, 'contrast':colors.green.contrast.value,'hover':colors.green.hover.value,'pressed':colors.green.pressed.value}}/>
  <ColorItem title="error" description="" colors={{'main':colors.red.main.value,"lighter":colors.red.light.value, dark:colors.red.dark.value,'subtle':colors.red.subtle.value, 'contrast':colors.red.contrast.value,'hover':colors.red.hover.value, 'pressed':colors.red.pressed.value}}/>
  <ColorItem title="warning" description="" colors={{'main':colors.yellow.main.value, 'lighter':colors.yellow.light.value, dark:colors.yellow.dark.value,'subtle':colors.yellow.subtle.value, 'contrast':colors.yellow.contrast.value,'hover':colors.yellow.hover.value, 'pressed':colors.yellow.pressed.value}}/>
</ColorPalette>


<Subheading>Customize Component colors</Subheading>

<p>in jb design system you have 3 way to change the components parts colors</p>
- <p>1. **general approach:** set the color palette variables base on your app design.</p>
- <p>2. **specific part approach:** set the color variables of specific part of the component.</p>
- <p>3. **component approach:** set the color variables of specific component.</p>

<p> for the first approach you can use the `--jb-*` variables of the color palette in your css. for example:</p>
```css
:root{
  --jb-primary: oklch(0.6 0.26 256);
  --jb-secondary: oklch(0.6 0.26 286);
  --jb-green: oklch(0.6 0.26 120);
  --jb-red: oklch(0.6 0.26 0);
  --jb-yellow: oklch(0.6 0.26 60);
}
```
<p>in this approach all components part that use primary color will use your primary color instead.</p>
<p> remember you can set this variable in every scope in your app like in your app root or in your page root. this will allow you to have multiple palette ot theme in one app.</p>
<p>for the second approach you can use the `--jb-component-name-*` variables</p>
<p>in this case component will override it's default color value for that specific parts. for example jb-input dont have any border by default but you can set it like this</p>
```css
:root{
  --jb-input-border-color: oklch(0.6 0.26 256);
  /*or*/
  --jb-input-border-color: var(--jb-primary);
}
```
<p>this will set the border color of the jb-input component to your primary color.</p>
<p>for the third approach you can use the `component-name` selector and set direct variable within</p>
```css
  jb-input{
    --border-color: oklch(0.6 0.26 256);
    /*or*/
    --border-color: var(--jb-primary);
  }
```
<p>this will be most useful when you want to set the variable or style in some specific state</p>
<p>for example you can set the border color of the jb-input component to your primary color when it is focused.</p>
```css
  jb-input:focus{
    --border-color: oklch(0.6 0.26 256);
    /*or*/
    --border-color: var(--jb-primary);
  }
  /*or show red border when input is in invalid state*/
  jb-input:state(invalid){
    --border-color: oklch(0.6 0.26 0);
    /*or*/
    --border-color: var(--jb-red);
  }
```

<Subheading>Color Rules</Subheading>

we use `oklch()` color space for all colors in our design system. This allows us to create a consistent and harmonious color palette that is easy to use and understand.
<p>
for example primary color is `oklch(0.6 0.26 256)` which is a blue color with a lightness of 60%, chroma of 0.26, and hue of 256 degrees.
for hover state we add `0.07` to lightness and `0.07` to chroma so it gets a little lighter and brighter.
for pressed state we subtract `0.1` to lightness and `0.05` to chroma so it gets a little darker and dimmer.
</p>
<br/>
<Subheading>Define custom colors</Subheading>
<br/>
<p>
  we use `JBColor` type for all colors in our design system. This allows us to create a consistent and harmonious color palette that is easy to use and understand.
  to creating your own custom color you must use `oklch()` color space for all colors in our design system. This allows us to create a consistent and harmonious color palette that is easy to use and understand.
  for example primary color is `oklch(0.6 0.26 256)` which is a blue color with a lightness of 60%, chroma of 0.26, and hue of 256 degrees.
</p>
<p>
after you define your color create a instance of `JBColor` class by providing the color you want to use. for example:
  
  ```ts
  const primary = new JBColor({lightness:0.6,chroma:0.26,hue:256},'--jb-primary');
  ```
after you all your base colors you can create a color variants base on your base color. for example:
</p>
<p>
  there are several function that will give you the color you want:
  - `getNeutralColor(lightness:number)` will give you a neutral color based on the lightness value you provide. it will return a color that is in the range of 0 to 10.
  - `getHoverColor(color:JBColor)` will give you a hover color based on the color you provide. it will return a color that is a little lighter and brighter than the original color.
  - `getPressedColor(color:JBColor)` will give you a pressed color based on the color you provide. it will return a color that is a little darker and dimmer than the original color.
  - `getLighterColor(color:JBColor)` will give you a lighter color based on the color you provide. it will return a color that is a little lighter than the original color.
  - `getDarkerColor(color:JBColor)` will give you a darker color based on the color you provide. it will return a color that is a little darker than the original color.
  - `getSubtleColor(color:JBColor)` will give you a subtle color based on the color you provide. it will return a color that is a more like pastel color for quieter tone.
  - `getContrastColor(color:JBColor)` will give you a contrast color based on the color you provide. it will give you a most contrast color based on your background color in light mode it is Dark and in light mode its light.
</p>
<br/>

## set color in javascript

jb-design system use css variables for colors and you can set this css variables in your app whenever you want. but beside that we put some easier way to set these variables using `createThemeColor` and `setColors` functions.    

```javascript
// you just pass each color base oklch color parameters and createThemeColor will give you the whole color group (includes lighter, darker ,...)
const colors = createThemeColor({
  //all colors are optional just set the colors you want to change if you not set it will use the default color.
  primary: {lightness:0.6,chroma:0.26,hue:256},
  secondary: {lightness:0.6,chroma:0.26,hue:286},
  yellow:{lightness:0.75,chroma:0.18,hue:70},
  green:{lightness:0.68,chroma:0.1484,hue:162.1},
  red:{lightness:0.6,chroma:0.22,hue:23.21}
}); 
// set the generated color in project root
setColors(colors);
```
base on above example you can modify the `colors` variable base on your need after creation and then pass them to `setColors` to actually setting it into your app.    
this method currently only support `JBColorGroup` color types. for single or neutral colors just use css variables.