Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(tokens): correct neutral gray token semantics across components (#852)

Cindy Zhangbb4cd260e590
diff --git a/packages/cli/docs/tokens.md b/packages/cli/docs/tokens.md
index b23c1a7a88..a5bc12f3fc 100644
--- a/packages/cli/docs/tokens.md
+++ b/packages/cli/docs/tokens.md
@@ -37,14 +37,30 @@ Control heights for consistent sizing across buttons, inputs, and selectors.
### Semantic Colors
-| Token | Usage |
-| --------------- | -------------------- |
-| --color-accent | Primary action color |
-| --color-surface | Background surface |
-| --color-wash | Secondary background |
-| --color-success | Success states |
-| --color-error | Error states |
-| --color-warning | Warning states |
+| Token | Usage |
+| --------------- | -------------------------------------------- |
+| --color-accent | Primary action color |
+| --color-surface | Background surface |
+| --color-wash | Page-level background (app shell, page body) |
+| --color-success | Success states |
+| --color-error | Error states |
+| --color-warning | Warning states |
+
+### Neutral Grays
+
+Three tokens for "gray" backgrounds. Choosing the right one depends on what the element _is_:
+
+| Token | Role | Use for |
+| --------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| --color-secondary | Neutral fill for elements | Buttons (default), badges, tokens, kbd, avatar fallback, pagination dots, status dots, selected nav items, icon containers |
+| --color-muted | Background for content areas | Sections, code blocks, table zebra stripes, progress/slider tracks, disabled input fills, featured cards |
+| --color-overlay-hover | Translucent hover/active state | Hover on ghost buttons, list item highlights, menu item highlights, table row hover |
+
+**Decision tree:**
+
+1. Is it a **hover/active/highlighted state**? → `--color-overlay-hover`
+2. Is it a **container with other content inside** (text, icons, controls)? → `--color-muted`
+3. Is it a **self-contained element sitting on a surface**? → `--color-secondary`
### Text Colors
diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsx
index 5505bc5a03..34a185416d 100644
--- a/packages/core/src/Avatar/XDSAvatar.tsx
+++ b/packages/core/src/Avatar/XDSAvatar.tsx
@@ -13,7 +13,6 @@
* - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
*/
-
import {useState, type ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import * as stylex from '@stylexjs/stylex';
@@ -129,7 +128,7 @@ const styles = stylex.create({
justifyContent: 'center',
width: '100%',
height: '100%',
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
color: colorVars['--color-text-secondary'],
fontFamily: typographyVars['--font-body'],
fontWeight: fontWeightVars['--font-weight-medium'],
diff --git a/packages/core/src/Kbd/XDSKbd.tsx b/packages/core/src/Kbd/XDSKbd.tsx
index fca7b2d2de..4ba19d197c 100644
--- a/packages/core/src/Kbd/XDSKbd.tsx
+++ b/packages/core/src/Kbd/XDSKbd.tsx
@@ -37,7 +37,7 @@ const styles = stylex.create({
height: '20px',
paddingInline: spacingVars['--spacing-1'],
borderRadius: radiusVars['--radius-1'],
- backgroundColor: colorVars['--color-wash'],
+ backgroundColor: colorVars['--color-secondary'],
borderBottomWidth: '2px',
borderBottomStyle: 'solid',
borderBottomColor: colorVars['--color-border'],
diff --git a/packages/core/src/NavItem/navItemStyles.stylex.ts b/packages/core/src/NavItem/navItemStyles.stylex.ts
index 81d32f2df9..f854dd4cd8 100644
--- a/packages/core/src/NavItem/navItemStyles.stylex.ts
+++ b/packages/core/src/NavItem/navItemStyles.stylex.ts
@@ -74,15 +74,15 @@ export const navItemStyles = stylex.create({
/** Selected/active page indicator — deemphasized background, medium weight */
selected: {
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
fontWeight: fontWeightVars['--font-weight-medium'],
':hover': {
'@media (hover: hover)': {
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
},
},
':active': {
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
},
},
diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsx
index 88daa7b193..07f9b76cb0 100644
--- a/packages/core/src/Pagination/XDSPagination.tsx
+++ b/packages/core/src/Pagination/XDSPagination.tsx
@@ -17,7 +17,6 @@
* label, data-testid, xstyle
*/
-
import {useTransition} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
@@ -213,7 +212,7 @@ const styles = stylex.create({
borderStyle: 'none',
padding: 0,
borderRadius: '50%',
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
cursor: 'pointer',
transitionProperty: 'background-color',
transitionDuration: durationVars['--duration-fast'],
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index ab07808e27..b2b6971cfa 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -59,7 +59,7 @@ const variantStyles = stylex.create({
backgroundColor: 'transparent',
},
wash: {
- backgroundColor: colorVars['--color-wash'],
+ backgroundColor: colorVars['--color-muted'],
},
});
diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsx
index 96808fd54c..8c54035953 100644
--- a/packages/core/src/StatusDot/XDSStatusDot.tsx
+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx
@@ -78,7 +78,7 @@ const variants = stylex.create({
backgroundColor: colorVars['--color-accent'],
},
neutral: {
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
},
});
diff --git a/packages/core/src/Table/XDSTableRow.tsx b/packages/core/src/Table/XDSTableRow.tsx
index dcf5069e1d..95579023b5 100644
--- a/packages/core/src/Table/XDSTableRow.tsx
+++ b/packages/core/src/Table/XDSTableRow.tsx
@@ -11,7 +11,6 @@
* - /packages/core/src/Table/index.ts
*/
-
import {useContext, type ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import * as stylex from '@stylexjs/stylex';
@@ -36,7 +35,7 @@ const stripedRowStyles = stylex.create({
row: {
backgroundColor: {
default: null,
- ':nth-child(even)': colorVars['--color-wash'],
+ ':nth-child(even)': colorVars['--color-muted'],
},
},
});
@@ -59,7 +58,7 @@ const stripedHoverRowStyles = stylex.create({
row: {
backgroundColor: {
default: null,
- ':nth-child(even)': colorVars['--color-wash'],
+ ':nth-child(even)': colorVars['--color-muted'],
':hover': {
'@media (hover: hover)': colorVars['--color-overlay-hover'],
},
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index 9fe1944ee0..99bc1984de 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -13,7 +13,6 @@
* - /apps/storybook/stories/TopNav.stories.tsx
*/
-
import {type ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import * as stylex from '@stylexjs/stylex';
@@ -73,11 +72,11 @@ const styles = stylex.create({
color: colorVars['--color-text-primary'],
fontWeight: fontWeightVars['--font-weight-semibold'],
backgroundColor: {
- default: colorVars['--color-muted'],
+ default: colorVars['--color-secondary'],
':hover': {
- '@media (hover: hover)': colorVars['--color-muted'],
+ '@media (hover: hover)': colorVars['--color-secondary'],
},
- ':active': colorVars['--color-muted'],
+ ':active': colorVars['--color-secondary'],
},
},
iconOnly: {
diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenuItem.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenuItem.tsx
index 0bca54742c..e6468813a5 100644
--- a/packages/core/src/TopNav/XDSTopNavMegaMenuItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMegaMenuItem.tsx
@@ -12,7 +12,6 @@
* - /packages/core/src/TopNav/index.ts
*/
-
import {type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
@@ -77,7 +76,7 @@ const styles = stylex.create({
width: 40,
height: 40,
borderRadius: radiusVars['--radius-2'],
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
flexShrink: 0,
color: colorVars['--color-icon-secondary'],
},
@@ -112,7 +111,7 @@ const styles = stylex.create({
width: 32,
height: 32,
borderRadius: radiusVars['--radius-2'],
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
flexShrink: 0,
color: colorVars['--color-icon-secondary'],
marginBlockStart: spacingVars['--spacing-0-5'],
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
index 4d86cd37db..77e771cf8e 100644
--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -140,7 +140,7 @@ const styles = stylex.create({
width: 40,
height: 40,
borderRadius: radiusVars['--radius-2'],
- backgroundColor: colorVars['--color-muted'],
+ backgroundColor: colorVars['--color-secondary'],
flexShrink: 0,
},
menuItemContent: {
diff --git a/packages/lab/src/CodeBlock/XDSCodeBlock.tsx b/packages/lab/src/CodeBlock/XDSCodeBlock.tsx
index bb1493671b..70e5aef257 100644
--- a/packages/lab/src/CodeBlock/XDSCodeBlock.tsx
+++ b/packages/lab/src/CodeBlock/XDSCodeBlock.tsx
@@ -38,7 +38,7 @@ const styles = stylex.create({
position: 'relative',
margin: 0,
borderRadius: radiusVars['--radius-2'],
- backgroundColor: colorVars['--color-wash'],
+ backgroundColor: colorVars['--color-muted'],
border: `1px solid ${colorVars['--color-border']}`,
overflow: 'hidden',
},
diff --git a/packages/lab/src/CodeEditor/XDSCodeEditor.tsx b/packages/lab/src/CodeEditor/XDSCodeEditor.tsx
index 3a4e6cebec..c9b7cb6eab 100644
--- a/packages/lab/src/CodeEditor/XDSCodeEditor.tsx
+++ b/packages/lab/src/CodeEditor/XDSCodeEditor.tsx
@@ -37,7 +37,7 @@ const styles = stylex.create({
position: 'relative',
display: 'flex',
borderRadius: radiusVars['--radius-2'],
- backgroundColor: colorVars['--color-wash'],
+ backgroundColor: colorVars['--color-muted'],
border: `1px solid ${colorVars['--color-border']}`,
overflow: 'hidden',
},