Skip to content

Theme: Add new caution color ramp #72782

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 31, 2025
Merged

Theme: Add new caution color ramp #72782

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
72d2b26
Theme: Add new caution color ramp
aduth Oct 29, 2025
a9f45e6
Add documentation for color token scheme
aduth Oct 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions packages/theme/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,58 @@ A theming package that's part of the WordPress Design System. It has two parts:

In the **[Design Tokens Reference](docs/ds-tokens.md)** document there is a complete reference of all available design tokens including colors, spacing, typography, and more.

### Color Tokens

The design system defines color tokens using the following naming scheme:

```
--wpds-<element>-<tone>[-<emphasis>][-<state>]
```

**Element** specifies what the color is applied to.

| Value | Description |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `bg-surface` | Backgrounds of layout or container surfaces. |
| `bg-interactive` | Backgrounds of interactive elements such as buttons, inputs, and toggles. |
| `bg-track` | Backgrounds of track components like scrollbars and slider tracks. |
| `bg-thumb` | Backgrounds of thumb components like scrollbar thumbs and slider thumbs. |
| `fg-content` | Foreground color for text and icons in static content. |
| `fg-interactive` | Foreground color for text and icons in interactive elements such as links and buttons. |
| `stroke-surface` | Decorative borders and dividers for non-interactive surfaces. |
| `stroke-interactive` | Accessible borders for interactive controls. |
| `stroke-focus` | Stroke color specifically for focus rings. |

**Tone** defines the semantic intent of the color.

| Value | Description |
| --------- | ---------------------------------------------------------------------------------------- |
| `neutral` | Neutrally toned UI elements. |
| `brand` | Brand-accented or primary action colors. |
| `success` | Positive or completed states. |
| `info` | Informational or system-generated context. |
| `caution` | Heads-up or low-severity issues; “proceed carefully.” |
| `warning` | Higher-severity or time-sensitive issues that require user attention but are not errors. |
| `error` | Blocking issues, validation failures, or destructive actions. |

> [!NOTE]
> `caution` and `warning` represent two escalation levels of non-error severity.
> Use **`caution`** for guidance or minor risks, and **`warning`** when the user must act to prevent an error.

**Emphasis** adjusts color strength relative to the base tone, if specified. The default is a normal emphasis.

| Value | Description |
| -------------------- | ------------------------------------------- |
| `strong` | Higher contrast and/or elevated emphasis. |
| `weak` | Subtle variant for secondary or muted elements. |

**State** represents the interactive state of the element, if specified. The default is an idle state.

| Value | Description |
| ---------- | ---------------------------------------- |
| `active` | Hovered, pressed, or selected state. |
| `disabled` | Unavailable or inoperable state. |

Copy link
Contributor

@jameskoster jameskoster Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does focus count as interaction? Some of our components can still be focused in disabled state.

Copy link
Member Author

@aduth aduth Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does focus count as interaction? Some of our components can still be focused in disabled state.

Ideating with my AI friend, how does "inoperable" sound in place of "interactive"? As far as conveying the idea that the element likely won't receive clicks or keypresses, but could be focused.

Copy link
Contributor

@jameskoster jameskoster Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works for me :D

## Theme Provider

The `ThemeProvider` is a React component that should wrap your application to provide design tokens and theme context to the child UI components.
Expand Down
34 changes: 34 additions & 0 deletions packages/theme/docs/ds-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ Do not edit directly.
| `--wpds-color-bg-surface-info-weak` | Background color for surfaces with info tone and weak emphasis. |
| `--wpds-color-bg-surface-warning` | Background color for surfaces with warning tone and normal emphasis. |
| `--wpds-color-bg-surface-warning-weak` | Background color for surfaces with warning tone and weak emphasis. |
| `--wpds-color-bg-surface-caution` | Background color for surfaces with caution tone and normal emphasis. |
| `--wpds-color-bg-surface-caution-weak` | Background color for surfaces with caution tone and weak emphasis. |
| `--wpds-color-bg-surface-error` | Background color for surfaces with error tone and normal emphasis. |
| `--wpds-color-bg-surface-error-weak` | Background color for surfaces with error tone and weak emphasis. |
| `--wpds-color-bg-interactive-neutral` | Background color for interactive elements with neutral tone and normal emphasis. |
Expand Down Expand Up @@ -60,6 +62,16 @@ Do not edit directly.
| `--wpds-color-bg-thumb-brand-disabled` | Background color for thumbs with a brand tone and normal emphasis (eg. slider thumb and filled track), in their disabled state. |
| `--wpds-color-fg-content-neutral` | Foreground color for content like text with normal emphasis. |
| `--wpds-color-fg-content-neutral-weak` | Foreground color for content like text with weak emphasis. |
| `--wpds-color-fg-content-success` | Foreground color for content like text with success tone and normal emphasis. |
| `--wpds-color-fg-content-success-weak` | Foreground color for content like text with success tone and weak emphasis. |
| `--wpds-color-fg-content-info` | Foreground color for content like text with info tone and normal emphasis. |
| `--wpds-color-fg-content-info-weak` | Foreground color for content like text with info tone and weak emphasis. |
| `--wpds-color-fg-content-warning` | Foreground color for content like text with warning tone and normal emphasis. |
| `--wpds-color-fg-content-warning-weak` | Foreground color for content like text with warning tone and weak emphasis. |
| `--wpds-color-fg-content-caution` | Foreground color for content like text with caution tone and normal emphasis. |
| `--wpds-color-fg-content-caution-weak` | Foreground color for content like text with caution tone and weak emphasis. |
| `--wpds-color-fg-content-error` | Foreground color for content like text with error tone and normal emphasis. |
| `--wpds-color-fg-content-error-weak` | Foreground color for content like text with error tone and weak emphasis. |
| `--wpds-color-fg-interactive-neutral` | Foreground color for interactive elements with neutral tone and normal emphasis. |
| `--wpds-color-fg-interactive-neutral-active` | Foreground color for interactive elements with neutral tone and normal emphasis that are hovered, focused, or active. |
| `--wpds-color-fg-interactive-neutral-disabled` | Foreground color for interactive elements with neutral tone and normal emphasis, in their disabled state. |
Expand Down Expand Up @@ -281,3 +293,25 @@ Do not edit directly.
| `--wpds-color-private-bg-bg-fill-inverted1` | N/A |
| `--wpds-color-private-bg-fg-fill-inverted` | N/A |
| `--wpds-color-private-bg-surface1` | N/A |
| `--wpds-color-private-caution-bg-fill1` | N/A |
| `--wpds-color-private-caution-fg-fill` | N/A |
| `--wpds-color-private-caution-bg-fill2` | N/A |
| `--wpds-color-private-caution-surface2` | N/A |
| `--wpds-color-private-caution-surface6` | N/A |
| `--wpds-color-private-caution-surface5` | N/A |
| `--wpds-color-private-caution-surface4` | N/A |
| `--wpds-color-private-caution-surface3` | N/A |
| `--wpds-color-private-caution-fg-surface4` | N/A |
| `--wpds-color-private-caution-fg-surface3` | N/A |
| `--wpds-color-private-caution-fg-surface2` | N/A |
| `--wpds-color-private-caution-fg-surface1` | N/A |
| `--wpds-color-private-caution-stroke3` | N/A |
| `--wpds-color-private-caution-stroke4` | N/A |
| `--wpds-color-private-caution-stroke2` | N/A |
| `--wpds-color-private-caution-stroke1` | N/A |
| `--wpds-color-private-caution-bg-fill-dark` | N/A |
| `--wpds-color-private-caution-fg-fill-dark` | N/A |
| `--wpds-color-private-caution-bg-fill-inverted2` | N/A |
| `--wpds-color-private-caution-bg-fill-inverted1` | N/A |
| `--wpds-color-private-caution-fg-fill-inverted` | N/A |
| `--wpds-color-private-caution-surface1` | N/A |
1 change: 1 addition & 0 deletions packages/theme/src/color-ramps/lib/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ export const DEFAULT_SEED_COLORS = {
primary: '#3858e9',
info: '#0090ff',
success: '#4ab866',
caution: '#f0d149',
warning: '#f0b849',
error: '#cc1818',
};
8 changes: 8 additions & 0 deletions packages/theme/src/color-ramps/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,13 @@ export const Default: StoryObj< typeof ColorGen > = {
},
ramp: buildAccentRamp( DEFAULT_SEED_COLORS.warning, bgRamp ).ramp,
};
const cautionRampObj = {
seed: {
name: 'bgFill1' as const,
value: DEFAULT_SEED_COLORS.caution,
},
ramp: buildAccentRamp( DEFAULT_SEED_COLORS.caution, bgRamp ).ramp,
};
const errorRampObj = {
seed: {
name: 'bgFill1' as const,
Expand Down Expand Up @@ -109,6 +116,7 @@ export const Default: StoryObj< typeof ColorGen > = {
infoRampObj,
successRampObj,
warningRampObj,
cautionRampObj,
errorRampObj,
] }
/>
Expand Down
58 changes: 58 additions & 0 deletions packages/theme/src/prebuilt/css/design-tokens.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,12 @@
--wpds-color-bg-surface-brand: var(
--wpds-color-private-primary-surface1
); /* Background color for surfaces with brand tone and normal emphasis. */
--wpds-color-bg-surface-caution: var(
--wpds-color-private-caution-surface4
); /* Background color for surfaces with caution tone and normal emphasis. */
--wpds-color-bg-surface-caution-weak: var(
--wpds-color-private-caution-surface2
); /* Background color for surfaces with caution tone and weak emphasis. */
--wpds-color-bg-surface-error: var(
--wpds-color-private-error-surface4
); /* Background color for surfaces with error tone and normal emphasis. */
Expand Down Expand Up @@ -111,12 +117,42 @@
--wpds-color-bg-track-neutral-weak: var(
--wpds-color-private-bg-stroke1
); /* Background color for tracks with a neutral tone and weak emphasis (eg. scrollbar track). */
--wpds-color-fg-content-caution: var(
--wpds-color-private-caution-fg-surface4
); /* Foreground color for content like text with caution tone and normal emphasis. */
--wpds-color-fg-content-caution-weak: var(
--wpds-color-private-caution-fg-surface3
); /* Foreground color for content like text with caution tone and weak emphasis. */
--wpds-color-fg-content-error: var(
--wpds-color-private-error-fg-surface4
); /* Foreground color for content like text with error tone and normal emphasis. */
--wpds-color-fg-content-error-weak: var(
--wpds-color-private-error-fg-surface3
); /* Foreground color for content like text with error tone and weak emphasis. */
--wpds-color-fg-content-info: var(
--wpds-color-private-info-fg-surface4
); /* Foreground color for content like text with info tone and normal emphasis. */
--wpds-color-fg-content-info-weak: var(
--wpds-color-private-info-fg-surface3
); /* Foreground color for content like text with info tone and weak emphasis. */
--wpds-color-fg-content-neutral: var(
--wpds-color-private-bg-fg-surface4
); /* Foreground color for content like text with normal emphasis. */
--wpds-color-fg-content-neutral-weak: var(
--wpds-color-private-bg-fg-surface3
); /* Foreground color for content like text with weak emphasis. */
--wpds-color-fg-content-success: var(
--wpds-color-private-success-fg-surface4
); /* Foreground color for content like text with success tone and normal emphasis. */
--wpds-color-fg-content-success-weak: var(
--wpds-color-private-success-fg-surface3
); /* Foreground color for content like text with success tone and weak emphasis. */
--wpds-color-fg-content-warning: var(
--wpds-color-private-warning-fg-surface4
); /* Foreground color for content like text with warning tone and normal emphasis. */
--wpds-color-fg-content-warning-weak: var(
--wpds-color-private-warning-fg-surface3
); /* Foreground color for content like text with warning tone and weak emphasis. */
--wpds-color-fg-interactive-brand: var(
--wpds-color-private-primary-fg-surface3
); /* Foreground color for interactive elements with brand tone and normal emphasis. */
Expand Down Expand Up @@ -181,6 +217,28 @@
--wpds-color-private-bg-surface4: #eaeaea;
--wpds-color-private-bg-surface5: #dfdfdf;
--wpds-color-private-bg-surface6: #d0d0d0;
--wpds-color-private-caution-bg-fill-dark: #1f1e1b;
--wpds-color-private-caution-bg-fill-inverted1: #3d2e00;
--wpds-color-private-caution-bg-fill-inverted2: #1f1e1b;
--wpds-color-private-caution-bg-fill1: #f0d149;
--wpds-color-private-caution-bg-fill2: #dabb2b;
--wpds-color-private-caution-fg-fill: #1f1e1b;
--wpds-color-private-caution-fg-fill-dark: #f6f1da;
--wpds-color-private-caution-fg-fill-inverted: #f6f1da;
--wpds-color-private-caution-fg-surface1: #c6a800;
--wpds-color-private-caution-fg-surface2: #a58700;
--wpds-color-private-caution-fg-surface3: #866a00;
--wpds-color-private-caution-fg-surface4: #291d00;
--wpds-color-private-caution-stroke1: #b8ab76;
--wpds-color-private-caution-stroke2: #988d61;
--wpds-color-private-caution-stroke3: #866a00;
--wpds-color-private-caution-stroke4: #644e00;
--wpds-color-private-caution-surface1: #faf1cb;
--wpds-color-private-caution-surface2: #fdf9e7;
--wpds-color-private-caution-surface3: #ffffff;
--wpds-color-private-caution-surface4: #f8ebb6;
--wpds-color-private-caution-surface5: #f4df8c;
--wpds-color-private-caution-surface6: #e7d072;
--wpds-color-private-error-bg-fill-dark: #231c1b;
--wpds-color-private-error-bg-fill-inverted1: #6d0000;
--wpds-color-private-error-bg-fill-inverted2: #231c1b;
Expand Down
12 changes: 12 additions & 0 deletions packages/theme/src/prebuilt/js/design-tokens.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ export default [
'--wpds-color-bg-surface-info-weak',
'--wpds-color-bg-surface-warning',
'--wpds-color-bg-surface-warning-weak',
'--wpds-color-bg-surface-caution',
'--wpds-color-bg-surface-caution-weak',
'--wpds-color-bg-surface-error',
'--wpds-color-bg-surface-error-weak',
'--wpds-color-bg-interactive-neutral',
Expand Down Expand Up @@ -48,6 +50,16 @@ export default [
'--wpds-color-bg-thumb-brand-disabled',
'--wpds-color-fg-content-neutral',
'--wpds-color-fg-content-neutral-weak',
'--wpds-color-fg-content-success',
'--wpds-color-fg-content-success-weak',
'--wpds-color-fg-content-info',
'--wpds-color-fg-content-info-weak',
'--wpds-color-fg-content-warning',
'--wpds-color-fg-content-warning-weak',
'--wpds-color-fg-content-caution',
'--wpds-color-fg-content-caution-weak',
'--wpds-color-fg-content-error',
'--wpds-color-fg-content-error-weak',
'--wpds-color-fg-interactive-neutral',
'--wpds-color-fg-interactive-neutral-active',
'--wpds-color-fg-interactive-neutral-disabled',
Expand Down
Loading
Loading