Refactor: consolidate focus outline tokens into component file#1344
Merged
lukasoppermann merged 7 commits intomainfrom Apr 14, 2026
Merged
Refactor: consolidate focus outline tokens into component file#1344lukasoppermann merged 7 commits intomainfrom
lukasoppermann merged 7 commits intomainfrom
Conversation
Move all focus outline tokens into src/tokens/component/focus.json5 with consistent kebab-case naming (focus-outline-color, focus-outline-width, focus-outline-offset). Keep focus-outline composite token. Add deprecated aliases for old names (focus-outlineColor, outline-focus-width, outline-focus-offset). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
🦋 Changeset detectedLatest commit: 328a69e The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
Contributor
Design Token Diff (CSS)
|
Contributor
Design Token Diff (StyleLint)
|
Contributor
Design Token Diff (Figma)
|
Contributor
Design Token Diff (Fallbacks)
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR consolidates focus outline-related design tokens into a single component token file (src/tokens/component/focus.json5), standardizing naming (kebab-case) while providing deprecated aliases for legacy names and updating CSS variable fallbacks.
Changes:
- Added component-level
focus.*tokens (includingfocus.outlinecomposite) with standardized kebab-case names and deprecation aliases. - Removed legacy focus outline tokens from functional token files (border/color/size) as part of the consolidation.
- Added a new fallback mapping for the kebab-case CSS variable
--focus-outline-color.
Show a summary per file
| File | Description |
|---|---|
| src/tokens/component/focus.json5 | Introduces consolidated focus outline tokens + deprecated aliases |
| src/tokens/functional/size/border.json5 | Removes legacy outline.focus.* size tokens |
| src/tokens/functional/color/focus.json5 | Removes legacy focus.outlineColor functional color token file |
| src/tokens/functional/border/border.json5 | Removes legacy focus.outline border composite token definition |
| src/tokens/fallback/color-fallbacks.json | Adds fallback entry for --focus-outline-color |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/5 changed files
- Comments generated: 3
| @@ -66,34 +66,4 @@ | |||
| }, | |||
| }, | |||
| }, | |||
There was a problem hiding this comment.
Removing outline.focus.offset and outline.focus.width from this functional size file means the legacy --outline-focus-offset / --outline-focus-width variables will no longer be emitted in the functional/size/* CSS build (the size build only sources src/tokens/base/size/*.json5 + src/tokens/functional/size/*.json5, and does not include src/tokens/component/*.json5). If these are meant to remain available as deprecated aliases, keep deprecated token stubs here (with the old names) or update the size build sources/includes to pull in the component focus tokens.
Suggested change
| }, | |
| }, | |
| outline: { | |
| focus: { | |
| offset: { | |
| $value: '{borderWidth.thin}', | |
| $description: 'Deprecated alias for the legacy focus outline offset token. Kept here so --outline-focus-offset continues to be emitted in functional size builds', | |
| $type: 'dimension', | |
| }, | |
| width: { | |
| $value: '{borderWidth.thick}', | |
| $description: 'Deprecated alias for the legacy focus outline width token. Kept here so --outline-focus-width continues to be emitted in functional size builds', | |
| $type: 'dimension', | |
| }, | |
| }, | |
| }, |
Comment on lines
173
to
176
| "--buttonCounter-danger-fgColor-disabled": "var(--color-btn-danger-disabled-counter-fg)", | ||
| "--focus-outlineColor": "var(--color-accent-fg)", | ||
| "--focus-outline-color": "var(--color-accent-fg)", | ||
| "--focus-outline": "var(--color-accent-fg solid 2px)", |
There was a problem hiding this comment.
--focus-outline-color was added here, but the Storybook migration fallback map (docs/storybook/stories/Migration/v8/static-fallbacks.json) still only lists --focus-outlineColor and --focus-outline. If that file is intended to mirror this fallback list for the migration tables, it should be updated to include the new kebab-case variable as well to avoid inconsistent migration guidance.
Comment on lines
+75
to
+103
| // Deprecated: use focus.outline-offset and focus.outline-width instead | ||
| outline: { | ||
| focus: { | ||
| offset: { | ||
| $value: '{focus.outline-offset}', | ||
| $type: 'dimension', | ||
| $deprecated: '{focus.outline-offset}', | ||
| $description: 'Deprecated. Use focus.outline-offset instead.', | ||
| $extensions: { | ||
| 'org.primer.figma': { | ||
| collection: 'functional/size', | ||
| scopes: ['borderWidth', 'effectFloat'], | ||
| }, | ||
| }, | ||
| }, | ||
| width: { | ||
| $value: '{focus.outline-width}', | ||
| $type: 'dimension', | ||
| $deprecated: '{focus.outline-width}', | ||
| $description: 'Deprecated. Use focus.outline-width instead.', | ||
| $extensions: { | ||
| 'org.primer.figma': { | ||
| collection: 'functional/size', | ||
| scopes: ['borderWidth', 'effectFloat'], | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, |
There was a problem hiding this comment.
The deprecated legacy aliases outline.focus.offset / outline.focus.width are defined in this component token file, but the build for functional/size/* outputs (and deprecated/size.json) only sources src/tokens/base/size/*.json5 + src/tokens/functional/size/*.json5. As a result, these legacy size tokens likely won’t be present in the size outputs anymore. If backward compatibility for the legacy size token names is required, consider keeping these deprecated aliases in src/tokens/functional/size/border.json5 (or adjust the size build config to include src/tokens/component/*.json5).
Suggested change
| // Deprecated: use focus.outline-offset and focus.outline-width instead | |
| outline: { | |
| focus: { | |
| offset: { | |
| $value: '{focus.outline-offset}', | |
| $type: 'dimension', | |
| $deprecated: '{focus.outline-offset}', | |
| $description: 'Deprecated. Use focus.outline-offset instead.', | |
| $extensions: { | |
| 'org.primer.figma': { | |
| collection: 'functional/size', | |
| scopes: ['borderWidth', 'effectFloat'], | |
| }, | |
| }, | |
| }, | |
| width: { | |
| $value: '{focus.outline-width}', | |
| $type: 'dimension', | |
| $deprecated: '{focus.outline-width}', | |
| $description: 'Deprecated. Use focus.outline-width instead.', | |
| $extensions: { | |
| 'org.primer.figma': { | |
| collection: 'functional/size', | |
| scopes: ['borderWidth', 'effectFloat'], | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
Focus dimension tokens (--focus-outline-width, --focus-outline-offset, --outline-focus-offset, --outline-focus-width) were being output in every theme CSS file because component/focus.json5 is sourced in theme builds. These values are static and don't vary by theme, so they belong in css/functional/size/border.css. Changes: - src/platforms/css.ts: exclude dimension tokens from themed CSS output by adding token.$type !== 'dimension' to the themed file filter - scripts/buildTokens.ts: special-case the border size build to also source component/focus.json5, with a type filter (dimension + custom-string) so only size-related tokens are output in border.css. Uses a two-step build: standard build for doc/styleLint/fallbacks, then CSS-only build for the combined border + focus dimensions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
…Lint, figma) Extends the dimension token routing fix to non-CSS outputs. Previously, only the CSS themed filter excluded dimension tokens (via css.ts). The docJson, styleLint, and figma theme builds still included focus dimension tokens (--focus-outline-offset, --focus-outline-width, --outline-focus-offset, --outline-focus-width) in their themed output. Changes: - buildTokens.ts: Override docJson and styleLint platform filters for theme builds to exclude tokens with $type === 'dimension' - buildFigma.ts: Override figma platform filter for theme builds to exclude dimension tokens; add focus.json5 as source to the dimension build so focus dimension tokens appear in figma/dimension/dimension.json (with color/border type exclusion to prevent color token leakage, and borderColor.json5 + light.json5 in includes for reference resolution) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
…nt border outputs The previous border build used a two-step approach: step 1 built doc/styleLint/fallbacks from border.json5 only, step 2 built CSS with focus.json5 added. This meant fallback/docJson/styleLint border outputs were missing the focus dimension tokens. Replaced with a single unified build that sources both border.json5 and focus.json5, with all platform filters overridden to only emit dimension + custom-string tokens (excluding color/border types from focus.json5). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lukasoppermann
temporarily deployed
to
github-pages
GitHub Actions
Inactive
lukasoppermann
added
the
update snapshots
github-actions
bot
removed
the
update snapshots
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This implements changes from https://github.com/github/core-ux/issues/2051
Component-level focus tokens (new and improved):
focusobject insrc/tokens/component/focus.json5that definesoutline,outline-color,outline-width, andoutline-offsettokens, with accessibility-focused descriptions, usage guidance, and Figma metadata. Deprecated legacy tokens and provided migration paths.Deprecation and removal of old functional tokens:
outline-focus-offsetandoutline-focus-widthtokens.src/tokens/functional/border/border.json5, which is now replaced by the new component-level token.src/tokens/functional/color/focus.json5, consolidating color definition under the new structure.src/tokens/functional/size/border.json5, as these are now defined and managed in the new component token file.CSS variable fallback updates:
--focus-outline-colorinsrc/tokens/fallback/color-fallbacks.jsonto align with the new token naming.