[DOCS] Update daff-illuminate function documentation

[xelaint]

📄 Documentation Request

What were you doing?

I don't understand how daff-illuminate works.

Expected behavior

I want to know what daff-illuminate does with usage examples and detailed documentation.

Existing Documentation

https://github.com/graycoreio/daffodil/tree/develop/libs/design/src/scss/theming/illuminate

Environment

Daffodil version: X.Y.Z
Angular version: X.Y.Z 

 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

[xelaint]

Possibly deprecate this function. Notes from daff-illuminate discussion:

// Returns a color 
// Smart switch a color with another color in the palette depending upon theme.
// Smart switch - 
$daff-????


"light" | 10 | (10,20..., 90) | 1 | 90

Theme Version (daff-switch-color-by-theme)
--
border: "dark" | (10,20..., 90) | 1 | 20
background: "dark" | (10,20..., 90) | 1 | 30

border: "light" | (10,20..., 90) | 1 | 90
background: "light" | (10,20..., 90) | 1 | 0

Color Version (similar to daff text contrast)
Given a color, give me back a text color.
daff-palette-contrast

// Given a color, give me back a color from the $palette that is "n" steps away in the opposite direction in the pallete for my color.
// For example, given a bright color, and a palette, this will give you a darker color in the given palette.
// Similarly, for example, given a dark color, and a palette, this will give you a brighter color in the given palette.
// This is especially useful for contrast text on top of a different color background. 
// Note, that this only works if your color palettes are perceptually uniform.
---
border: 10 | (10,20..., 90) | 1 | 20
background:  10 | (10,20..., 90) | 1 | 30

border: 10 | (10,20..., 90) | 1 | 90
background: 10 | (10,20..., 90) | 1 | 0

font-color: daff-text-contrast(color);

font-color: daff-text-contrast(color, $palette);

$color: daff-color(daff-map-get($theme, primary))
font-color: daff-text-contrast($color, $palette)
background: $color;

$color: daff-palette-contrast($theme, $palette, 1);  —> (spits out $primary, 10)
background: daff-palette-contrast($theme, $palette, 1);  —> (spits out $primary, 10 on light theme, spits out $primary, 90 on dark theme)
color: daff-text-contrast($color, $palette); —> (spits out opposite of $primary, 10)

daff-theme-aware-color($palette, 10) -> Gives the 90 on a dark theme, gives a 10 on a light theme.

// Revise Text-contrast api
// Create a new function called daff-theme-aware-color (internal only, not in public api)
// Potentially deprecate daff-illuminate after daff-theme-aware-color is finished
// Create a new function called daff-palette-contrast

Theme |  Color | Palette | "steps?" | Result |
-----
Light | A light green | Success Green Palette  | null |  |