feat: tokens stability for breaking changes by martascorreia · Pull Request #3179 · solid-design-system/solid

martascorreia · 2026-07-22T16:27:12Z

Description:

closes #2764

Definition of Reviewable:

Documentation is created/updated
Migration Guide is created/updated

E2E tests (features, a11y, bug fixes) are created/updated

Stories (features, a11y) are created/updated
relevant tickets are linked

changeset-bot · 2026-07-22T16:27:21Z

🦋 Changeset detected

Latest commit: 1a00cfd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@solid-design-system/tokens	Major
@solid-design-system/docs	Major
@solid-design-system/mcp	Major
@solid-design-system/components	Major
@solid-design-system/styles	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-07-22T16:31:22Z

🚀 Storybook has been deployed for branch feat_tokens-stability

View Storybook

martascorreia · 2026-07-24T16:42:08Z

relates to #3075 as this branch already removes the automatic adding of legacy variables to the themes' stylesheets.

mariohamann · 2026-07-31T11:54:23Z

-:root, .sd-theme-sp {
-  /*
-   * Deprecated variables – manually overriding these in custom themes might lead to problems in future versions of Solid.
-   * Use the actual used value instead. Example:
-   * Instead of --sd-chip-border-width use --sd-marker-border-width for your overrides.
-   */
-  --sd-button--size-lg-border-radius: var(--sd-button-border-radius);
-  --sd-button--size-md-border-radius: var(--sd-button-border-radius);
-  --sd-button--size-sm-border-radius: var(--sd-button-border-radius);
-  --sd-button--secondary--inverted--color-border: var(--sd-button-secondary-inverted-color-border);
-  --sd-chip-font-size: var(--sd-marker-font-size);
-  --sd-chip-border-width: var(--sd-marker-border-width);
-  --sd-chip-font-weight: var(--sd-marker-font-weight);
-  --sd-flag-border-width: var(--sd-marker-border-width);
-  --sd-form-control-color-icon: var(--sd-form-control-color-icon-fill);
-  --sd-menu-color-icon: var(--sd-menu-item-color-icon-fill);
-  --sd-menu-color-text: var(--sd-menu-item-color-text);
-  --sd-menu--disabled-color-icon: var(--sd-menu-item--disabled-color-icon-fill);
-  --sd-menu--disabled-color-text: var(--sd-menu-item--disabled-color-text);
-  --sd-tag-font-weight: var(--sd-choice-control-font-weight);
-  --sd-tag--disabled-color-border: var(--sd-color-border-neutral-500);
-  --sd-navigation-item--current-color-text: var(--sd-navigation-item-color-text);
-  --sd-option--disabled-color-border: var(--sd-color-border-neutral-500);
-  --sd-audio__timestamp-color-text: var(--sd-color-text-neutral-700);
-  --sd-accordion__chevron-color-text: var(--sd-accordion-color-icon-fill, var(--sd-color-icon-fill-primary));
-  --sd-form-control__tooltip-color-icon: var(--sd-interactive--default-color-text);
 }


As these are removed it's now a Breaking Change.

mariohamann · 2026-07-31T11:55:30Z

 ### Deprecated CSS variables (tokens)

-The following CSS variables (tokens) are deprecated and will be removed in a future release. Update your custom styles to use the recommended replacements.
+The following CSS variables (tokens) are deprecated and will be removed in a future release. Please update your custom styles to use the recommended replacements.


They ARE removed now, right? :)

They are removed from the theming sheets, but not yet from the components, that is #3075. So I only added the paragraph after, but I can already rephrase it as removed.

About this, do you think we should leave the list from now on and keep adding to it every time we have a new deprecated variable? I add the extra "removed" column to differentiate between the already removed (for this breaking change) and the ones that we could remove in the future, but I'm not sure if this will confuse users:

What if we just put it into the Breaking Changes?

mariohamann · 2026-07-31T11:57:36Z

+  --text-3xl: var(--sd-text-3xl, 2rem);
+  --text-4xl: var(--sd-text-4xl, 2.5rem);
+  --text-base: var(--sd-text-base, 1rem);
+  --text-color-accent: rgba(var(--sd-color-text-accent, 45 157 0));
+  --text-color-black: rgba(var(--sd-color-text-black, 24 24 24));
+  --text-color-error: rgba(var(--sd-color-text-error, 204 25 55));
+  --text-color-neutral-500: rgba(var(--sd-color-text-neutral-500, 174 174 174));


As we now have fallbacks, we should definitely highlight to the users! Themes don't have to be installed anymore if there are only components using >v6 and higher or <v4 and lower.

…gn-system/solid into feat/tokens-stability

mariohamann and others added 3 commits May 26, 2026 13:29

first try

4994e2f

feat: css fallback

bff3b8c

feat: adding token fallback

a5ec026

martascorreia self-assigned this Jul 22, 2026

github-project-automation Bot moved this to 📋 Backlog in Solid Design System Project Board Jul 22, 2026

github-project-automation Bot added this to Solid Design System Project Board Jul 22, 2026

martascorreia temporarily deployed to github-pages July 22, 2026 16:27 — with GitHub Actions Inactive

martascorreia moved this from 📋 Backlog to 👀 In review in Solid Design System Project Board Jul 22, 2026

martascorreia moved this from 👀 In review to 🏗 In progress in Solid Design System Project Board Jul 22, 2026

martascorreia changed the title ~~feat: tokens stability~~ feat: tokens stability for breaking changes Jul 23, 2026

martascorreia changed the base branch from main to next July 23, 2026 10:10

feat: adding fallback as default behavior

f299915

martascorreia temporarily deployed to github-pages July 23, 2026 17:56 — with GitHub Actions Inactive

fix: small code improvements

d2cee3e

martascorreia temporarily deployed to github-pages July 23, 2026 18:30 — with GitHub Actions Inactive

feat: changeset + legacy variables default values

0d32066

martascorreia temporarily deployed to github-pages July 23, 2026 19:54 — with GitHub Actions Inactive

fix: reverting the fallback in all stylesheets

c616a05

martascorreia temporarily deployed to github-pages July 24, 2026 09:04 — with GitHub Actions Inactive

fix: repurposing legacy variables as token fallback

992dad9

martascorreia temporarily deployed to github-pages July 24, 2026 10:12 — with GitHub Actions Inactive

fix: clean up

9e8a3b3

martascorreia temporarily deployed to github-pages July 24, 2026 10:49 — with GitHub Actions Inactive

fix: documentation

53da4d1

martascorreia temporarily deployed to github-pages July 24, 2026 14:17 — with GitHub Actions Inactive

Merge branch 'next' into feat/tokens-stability

4560520

rahulsuvarna18 temporarily deployed to github-pages July 24, 2026 14:24 — with GitHub Actions Inactive

fix: pipeline

83580ca

martascorreia temporarily deployed to github-pages July 24, 2026 16:25 — with GitHub Actions Inactive

feat: migration guide

86af935

martascorreia temporarily deployed to github-pages July 24, 2026 16:41 — with GitHub Actions Inactive

Merge branch 'next' into feat/tokens-stability

ff7d7ac

martascorreia temporarily deployed to github-pages July 24, 2026 16:46 — with GitHub Actions Inactive

martascorreia assigned mariohamann, rahulsuvarna18, balco0110 and auroraVasconcelos Jul 27, 2026

martascorreia moved this from 🏗 In progress to 👀 In review in Solid Design System Project Board Jul 28, 2026

Merge branch 'next' into feat/tokens-stability

9dce98f

martascorreia temporarily deployed to github-pages July 28, 2026 08:13 — with GitHub Actions Inactive

fix: documentation + fallback values in legacy-variables

c832396

martascorreia temporarily deployed to github-pages July 29, 2026 15:32 — with GitHub Actions Inactive

fix: adding themes to legacy-variables

507d05b

martascorreia temporarily deployed to github-pages July 30, 2026 10:56 — with GitHub Actions Inactive

martascorreia added 2 commits July 30, 2026 12:08

Merge branch 'next' into feat/tokens-stability

848af68

Merge branch 'next' into feat/tokens-stability

952aaed

martascorreia temporarily deployed to github-pages July 30, 2026 11:18 — with GitHub Actions Inactive

mariohamann reviewed Jul 31, 2026

View reviewed changes

Comment thread .changeset/rich-teeth-prove.md Outdated

mariohamann reviewed Jul 31, 2026

View reviewed changes

fix: changeset + build icons

5f873db

martascorreia temporarily deployed to github-pages July 31, 2026 14:54 — with GitHub Actions Inactive

Merge branch 'next' into feat/tokens-stability

3c6212f

martascorreia temporarily deployed to github-pages August 3, 2026 11:50 — with GitHub Actions Inactive

martascorreia added 2 commits August 3, 2026 17:54

feat: added deprecated variables to the migration guide

0a78106

Merge branch 'feat/tokens-stability' of https://github.com/solid-desi…

1a00cfd

…gn-system/solid into feat/tokens-stability

martascorreia temporarily deployed to github-pages August 4, 2026 10:13 — with GitHub Actions Inactive

Navigation Menu

Uh oh!

feat: tokens stability for breaking changes - #3179

feat: tokens stability for breaking changes#3179
martascorreia wants to merge 26 commits into
nextfrom
feat/tokens-stability

martascorreia commented Jul 22, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 22, 2026

Uh oh!

martascorreia commented Jul 24, 2026

Uh oh!

Uh oh!

mariohamann Jul 31, 2026

Uh oh!

mariohamann Jul 31, 2026

Uh oh!

martascorreia Jul 31, 2026

Uh oh!

mariohamann Aug 3, 2026

Uh oh!

mariohamann Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

martascorreia commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

Definition of Reviewable:

Uh oh!

changeset-bot Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 22, 2026

Uh oh!

martascorreia commented Jul 24, 2026

Uh oh!

Uh oh!

mariohamann Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

mariohamann Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

martascorreia Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

mariohamann Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

mariohamann Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

martascorreia commented Jul 22, 2026 •

edited

Loading

changeset-bot Bot commented Jul 22, 2026 •

edited

Loading