Component-specific design tokens not used

[philippone]

Hello Astro UXDS Team,

First off, thank you for creating and maintaining this design system! We are actively using it in our projects and find it very valuable.

While working on theming the components to match our brand, we noticed an opportunity for improvement. Some components, such as the Push Button, seem to be using lower-level system or reference tokens (e.g., color-palette-green-500) directly in their styling, instead of their designated component-specific tokens (e.g., push-button-color-background-selected-default).

This makes it challenging to customize the look and feel of individual components by overriding their specific tokens.

Push Button

A clear example of this can be found in the Push Button component. According to the specification, its styles should be defined by push-button-* tokens, but the implementation sometimes uses more generic system or palette tokens.

To Reproduce

• Specification of Push Button
• Comparison of just a few tokens of spec and Implementation:

---

CSS	Spec/Expected	Implementation	Hex
color	push-button-color-text-unselected-default	color-text-interactive-default	#4dacff
background	push-button-color-background-unselected-default	not used (maybe wrong spec)	#00000000
border color	push-button-color-border-unselected-default	push-button-color-border-unselected-default	#4dacff
selected
Background	push-button-color-background-selected-default	color-palette-green-500	#56f000
Border Color	push-button-color-border-selected-default	color-palette-green-500	#56f000
...

As you can see, the hex values are correct but the component tokens are not used and therefore it's hard to apply our own styling.

Is this somehow intentional?

To help align the component with the specification and to highlight my findings, I've started a draft pull request. This PR replaces the system tokens with the appropriate component tokens within the Push Button's styling.

Environment (please complete the following information):

• Browser: Chrome
• @astrouxds/astro-web-components version: 7.27.0
• Framework, if applicable: Svelte

[dmcalester]

Hi @philippone,

Thanks so much for the PR. After reviewing our implementation and current guidance, the component tokens were originally intended as a theming entry point for Astro. They were originally created to support teams implementing the overall look and feel of Astro in another system like MUI or PrimeNG. It appears we did erroneously add component tokens to some, but not all, of the components. The preferred method is to use system tokens so no single element diverges from the system.

However, we are considering a new pattern that would allow for component-level overrides. Would you be able to share your use case for needing more granular control of the tokens? It would really help us determine if the pattern we’re considering would meet the needs of the community while also supporting a consistent system.

If you‘d prefer to discuss your use cases more over email, feel free to reach out directly to support@astrouxds.com or directly to me at duncan@rocketcom.com.

[philippone]

Hi @dmcalester ,

We are currently applying a custom theme to the AstroUX components and run into some issues related to the design token implementation.

Our goal is to customize our theme primarily by changing system tokens (and reference tokens). However, we've found that some components bypass the token hierarchy, making them difficult to theme without dangerous workarounds.

The preferred method is to use system tokens so no single element diverges from the system.

I completely agree. We tried to change as much (reference and) system tokens as possible before changing component tokens.

In some cases, it did not work to match our theme and we had to break out of the system.

Examples

1. Push Button Selected State

The rux-push-button's selected state is using a reference token directly.

• Our Theme: Change the selected button background from green to blue.

• AstroUX Specification: The docs correctly show a component token --push-button-color-background-selected-default which is mapped from --color-palette-green-500.

• Problem: The component's SCSS implementation uses the reference token --color-palette-green-500 directly for the background-color.

• Impact: This makes it impossible to theme this specific component state without either:

  1. Redefining the global reference token --color-palette-green-500 to a blue value, which is semantically incorrect and would have unintended side effects.

  2. Overriding the component's CSS directly, which defeats the purpose of the token system.

2. Secondary Button Text Color

You can find another theming problem in the rux-button. The secondary variant uses a background token for a text color property.

• Problem: The button's SCSS implementation sets the color property to var(--color-background-interactive-default).

• Impact: This is semantically incorrect. Using a background token for text color only works in the astro theme. In any theme where the interactive background color is light, the text becomes unreadable.

• AstroUX Specification: According to the specs, the correct token for this property is --button-color-text-secondary-default.

component-level overrides

However, we are considering a new pattern that would allow for component-level overrides.

I guess, this matches my understanding of a token system. Each component token maps to a system token, which has a concrete reference value. I expected such a token system when reading the specification.

According to your documentation the component token is already mapped to a reference token (in the example case)

--color-palette-green-500: #56f000;
--push-button-color-background-selected-default: var(--color-palette-green-500);

But the component token --push-button-color-background-selected-default is not used in the implementation.

At the moment, the intention of component tokens is only for theming existing component libraries?
Does your implementation (of the Push Button) should use a system token instead of a reference token?

You already have a really good specification that probably supports component-level overrides but unfortunately your implementation is not using it.

[dmcalester]

@philippone

Thank you for the detailed breakdown of your issue. This is definitely a flaw in the system – and looking deeper, we’ve catalogued a few other issues. I was wondering if you have a priority of which components you need component tokens for – it seems push button is an important one, but are there others on the list you need urgently?

Also, as a separate inquiry, I’d be interested to hear your use case for the push button. We’ve been discussing internally if it still has value.

[philippone]

Hello @dmcalester ,

we're currently using the following components

• rux-button
• rux-push-button
• rux-global-status-bar
• rux-icon
• rux-container
• rux-card
• rux-tab + rux-tabs
• rux-tab-panels + * rux-tab-panel
• rux-tag
• rux-status
• rux-table
• rux-table-header
• rux-table-header-row
• rux-table-header-cell
• rux-table-body
• rux-table-row
• rux-table-cell
• rux-input
• rux-textarea
• rux-select + rux-option

We have customised css for the following components to match our theme

• rux-button
• rux-push-button
• rux-tab
• rux-card
• rux-tag
• rux-status

Also, as a separate inquiry, I’d be interested to hear your use case for the push button. We’ve been discussing internally if it still has value.

We're using it as a filter control similar to the filter chips from Material Design