Skip to content

Commit

Permalink
Add docs about alpha colors
Browse files Browse the repository at this point in the history
  • Loading branch information
Jeremy-Walton committed Feb 7, 2024
1 parent 0a61d7e commit f43ad65
Showing 1 changed file with 63 additions and 0 deletions.
63 changes: 63 additions & 0 deletions src/stories/Tokens/Color/ColorWithAlpha.mdx
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit f43ad65

Please sign in to comment.