From f43ad6533dc0a6a1fb724e69cf98e86c6e62966b Mon Sep 17 00:00:00 2001
From: Jeremy Walton <jeremy.patrick.walton@gmail.com>
Date: Wed, 7 Feb 2024 10:46:38 -0500
Subject: [PATCH] Add docs about alpha colors

---
 src/stories/Tokens/Color/ColorWithAlpha.mdx | 63 +++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 src/stories/Tokens/Color/ColorWithAlpha.mdx

diff --git a/src/stories/Tokens/Color/ColorWithAlpha.mdx b/src/stories/Tokens/Color/ColorWithAlpha.mdx
new file mode 100644
index 00000000..283a7858
--- /dev/null
+++ b/src/stories/Tokens/Color/ColorWithAlpha.mdx
@@ -0,0 +1,63 @@
+import { Meta } from '@storybook/addon-docs'
+import { DesignTokenDocBlock } from 'storybook-design-token'
+
+import { createAlert } from '../../Components/Alert/Alert'
+import { createIcon } from '../../Components/Icon/Icon'
+
+<Meta title="Tokens/Color/Color with Alpha" />
+
+# Color With Alpha
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: createAlert({
+      title: 'Caution',
+      icon: 'priority_high',
+      description:
+        'Using alpha will impact Accessibility and if misused can also impact performance. Use these suggestions with caution and verify the resulting colors pass Accessibility standards!',
+      iconDocsClassFix: 'sb-unstyled',
+    }).outerHTML,
+  }}
+></div>
+
+There may be a case where you need to use the alpha channel in a color. This can be useful for creating more opaque or transparent looks built directly into a color instead of using the opacity property.
+
+Since colors are based on a scale and provided as tokens, the alpha channel cannot be used directly. There are a few ways to take advantage of it though!
+
+## Alpha Tokens
+
+One option for adding alpha support is to define alpha tokens that can sit alongside the color scale steps. This allows for use across your system in a way that matches the system.
+
+```css
+// Note the 40% luminoisty matches the --op-color-primary-base luminosity
+// Note the 100% luminoisty matches the --op-color-primary-on-base luminosity
+// Note the 88% luminoisty matches the --op-color-primary-on-base-alt luminosity
+
+--op-color-primary-base-alpha-40: hsl(var(--op-color-primary-h) var(--op-color-primary-s) 40% / 40%);
+--op-color-primary-on-base-alpha-40: hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100% / 40%);
+--op-color-primary-on-base-alt-alpha-40: hsl(var(--op-color-primary-h) var(--op-color-primary-s) 88% / 40%);
+```
+
+The downside of this approach is that it can be difficult to manage and can lead to a lot of tokens. It also requires a lot of manual work to create the tokens and keep them in sync with the color scale.
+
+## Color Mix
+
+Another option is to use the `color-mix` (see [color-mix()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix)) to create a new color with the alpha channel. This allows for more dynamic use of the alpha channel and can be used to create a new color on the fly or at the component level.
+
+```css
+%my-component-global {
+  --_op-my-component-opacity-disabled: calc(var(--op-opacity-disabled) * 100%); // converts 0.4 to 40%
+
+  --op-my-component-background-color: color-mix(in srgv, var(--op-color-primary-base) var(--_op-thing-opacity-disabled), var(--op-color-primary-plus-max));
+  --op-my-component-color: color-mix(in srgv, var(--op-color-primary-on-base) var(--_op-thing-opacity-disabled), var(--op-color-primary-plus-max));
+  --op-my-component-color-alt: color-mix(in srgv, var(--op-color-primary-on-base-alt) var(--_op-thing-opacity-disabled), var(--op-color-primary-plus-max));
+
+  background-color: var(--op-my-component-background-color);
+  color: var(--op-my-component-color);
+}
+```
+
+The benefit of this approach is that
+
+1. It can be used at the component level for specific use cases, or globally if you want it available at a higher level.
+2. It is tied directly to the color scale and will update if the scale if overridden. It does not duplicate luminosity values.