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

Changes from 1 commit
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
Prev Previous commit
Add documentation for color token scheme 
Co-Authored-By: James Koster <846565+jameskoster@users.noreply.github.com>
  • Loading branch information
@aduth @jameskoster
aduth and jameskoster committed Oct 31, 2025
commit a9f45e6ed323ee22f51692db813a63299ba0277e
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
Loading