-
Notifications
You must be signed in to change notification settings - Fork 69
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.
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
feat: expose --output-references CLI arg for building tokens, registers filters, and updates CSS vars format #3203
feat: expose --output-references CLI arg for building tokens, registers filters, and updates CSS vars format #3203
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## Peter_Kulko/style-dictionary-v4 #3203 +/- ##
===================================================================
- Coverage 93.76% 93.76% -0.01%
===================================================================
Files 229 229
Lines 3787 3785 -2
Branches 902 879 -23
===================================================================
- Hits 3551 3549 -2
- Misses 229 232 +3
+ Partials 7 4 -3 ☔ View full report in Codecov by Sentry. |
51fc736
to
2293939
Compare
{ | ||
name: '--output-references', | ||
description: 'Include references in the build output.', | ||
defaultValue: true, | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Currently, running build-tokens
with the CLI for a brand package (e.g., @edx/elm-theme
), the CSS build output does not include the references, i.e. CSS variables, instead hardcoding the raw value.
I believe we want to default to always including references, even for brand packages, to mitigate risk that updating a reference for a style property, won't change the actual style due to the missing use of the CSS variable.
However, I think it's also reasonable to not want this in some cases so having it be an option seems reasonable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
100% agree. Good call/addition!
{ | ||
name: '-v, --verbose', | ||
description: 'Enable verbose logging.', | ||
defaultValue: false, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Improves the utility of warning/error messages resulting from style-dictionary
during build-tokens
.
@@ -52,24 +65,30 @@ async function buildTokensCommand(commandArgs) { | |||
destination: 'core/variables.css', | |||
filter: hasSourceTokensOnly ? 'isSource' : undefined, | |||
options: { | |||
outputReferences: !hasSourceTokensOnly, | |||
outputReferences, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Now relies on the CLI option; outputReferences
is now distinct from hasSourceTokensOnly
.
lib/build-tokens.js
Outdated
formatting: { | ||
fileHeaderTimestamp: true, | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] The custom formatters are updated to rely on the default style-dictionary util fileHeader
, but rely on the optional formatting.fileHeaderTimestamp
to still include the timestamp in the build output.
I don't feel we need the custom message, so long as the timestamp is included.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good call! The default header looks like it covers everything we need, and I'm all for reducing complexity (even in small ways like this!)
/**
* Do not edit directly, this file was auto-generated.
* Generated on Tue, 03 Sep 2024 13:46:26 GMT
*/
@@ -52,7 +52,8 @@ | |||
"prepare": "husky || true", | |||
"build-tokens": "./bin/paragon-scripts.js build-tokens --build-dir ./styles/css", | |||
"replace-variables-usage-with-css": "./bin/paragon-scripts.js replace-variables -p src -t usage", | |||
"replace-variables-definition-with-css": "./bin/paragon-scripts.js replace-variables -p src -t definition" | |||
"replace-variables-definition-with-css": "./bin/paragon-scripts.js replace-variables -p src -t definition", | |||
"cli:help": "./bin/paragon-scripts.js help" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Adds a way to run the CLI help
command from Paragon root.
--pgn-elevation-zindex-400: 400; | ||
--pgn-elevation-zindex-200: 200; | ||
--pgn-elevation-zindex-0: 0; | ||
--pgn-elevation-zindex-fixed: 1030; /* z-index of for fixed element. */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By relying on the formattedVariables
helper function from style-dictionary/utils
, we get inline comments from the token's description
field, if any. Much of the other logic we had implemented is provided out-of-the-box (e.g., ordering of CSS variables).
|
||
return `${createCustomHeader(StyleDictionary, file).join('\n')}\n:root {\n${variables}\n}\n`; | ||
const { outputReferences, formatting } = options; | ||
const variables = formattedVariables({ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Relies on helper function formattedVariables
provided by style-dictionary/utils
to format tokens as CSS variables instead of re-implementing much of its same logic here.
2293939
to
1d894fe
Compare
@@ -1,5 +1,5 @@ | |||
.pgn__form-text { | |||
font-size: var(--pgn-typography-font-size-small-base); | |||
font-size: var(--pgn-typography-font-size-sm); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The token representing .small
was refactored slightly to be named pgn-typography-font-size-sm
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
var(--pgn-typography-font-size-sm)
We will also need to update the changed design tokens in the edx/elm-theme and ensure that in the consuming MFEs that have already switched to the design tokens in the test format, all tokens will be relevant.
Since we use only native CSS variables, consumers will not see an error/warning about a missing token. Such minor changes are unfortunately easy to miss.
I have described this issue before, maybe we should come back to it in the future. Please let me know your thoughts.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@PKulkoRaccoonGang I have a draft PR brewing to account for edx/elm-theme
, based on the changes introduced in this PR and the broader v3 -> v4 upgrade (e.g., adopting the DTCG format).
Note: this linked PR also accounts for a few style bug fixes as well that I noticed while QA'ing elm-theme
against the Paragon docs site locally.
I have described #3057 before, maybe we should come back to it in the future. Please let me know your thoughts.
100% agreed we should explore opportunities for linting and/or other validation of tokens, but as a future initiative.
@@ -4,12 +4,12 @@ | |||
min-height: 36px; | |||
display: flex; | |||
flex-wrap: nowrap; | |||
font-size: var(--pgn-typography-font-size-small-x); | |||
font-size: var(--pgn-typography-font-size-xs); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The token representing .x-small
was refactored slightly to be named pgn-typography-font-size-xs
.
.font-size-normal { | ||
font-size: $font-size-base !important; | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Adds a new CSS utility class, available to consumers, in place of the custom www
-only .fs-16
. This way, consumers have a way to override text back to normal/base font-size (e.g., when rendering text in a DataTable
row that by default uses .small
text).
@@ -738,14 +738,14 @@ $display4-weight: var(--pgn-typography-display-weight-4) !default; | |||
$display-line-height: var(--pgn-typography-display-line-height-base) !default; | |||
$display-mobile-line-height: var(--pgn-typography-display-line-height-mobile) !default; | |||
|
|||
$lead-font-size: var(--pgn-typography-font-size-lead) !default; | |||
$lead-font-size: var(--pgn-typography-font-size-lg) !default; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Renamed lead font size token to --pgn-typography-font-size-lg
to be consistent with naming of other font size tokens.
@@ -17,7 +17,7 @@ | |||
"weight-link": { "source": "$alert-link-font-weight", "$value": "{typography.font.weight.normal}", "$type": "fontWeight" }, | |||
"size": { "source": "$alert-font-size", "$value": ".875rem", "$type": "dimension" } | |||
}, | |||
"line-height": { "source": "$alert-line-height", "$value": "1.5rem", "$type": "dimension" } | |||
"line-height": { "source": "$alert-line-height", "$value": "1.5rem", "$type": "number" } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Fixes line number typography regressions.
@@ -27,7 +27,3 @@ body { | |||
.container-fluid { | |||
max-width: none; | |||
} | |||
|
|||
.fs-16 { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] removed in favor of new .font-size-normal
CSS utility class.
2d2ff2d
to
24c4d7b
Compare
f85546b
to
6a04c04
Compare
31019cb
to
b52b968
Compare
1d3eb5a
to
aa2548c
Compare
@import url("https://cdn.jsdelivr.net/npm/@edx/[email protected]/dist/core.min.css"); | ||
@import url("https://cdn.jsdelivr.net/npm/@edx/[email protected]/dist/light.min.css"); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] At the moment, 2U has no intentions to migrate the existing @edx/brand-edx.org
. Instead, MFEs will cutover directly to our new tokens-compatible theme @edx/elm-theme
upon upgrade to a Paragon version that relies on tokens.
95b9de0
to
ec15f2a
Compare
filter: hasSourceTokensOnly | ||
? `isSource.${themeVariant}` | ||
: `isThemeVariant.${themeVariant}`, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[inform] Currently, the registered format css/custom-variables
performs filtering within its own logic (i.e., filtering on dictionary.allTokens
), rather than treating the filter as a legit style-dictionary filter here. New filters are now registered to filter tokens by the appropriate themeVariant
file path within the filter
property here versus within the definition of css/custom-variables
.
Note that other custom filters (e.g., isSource
) can automatically opt into having sub-filters created specific to individual theme variants (e.g., isSource.light
).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just trying to wrap my head around this change a little bit. Before this change if hasSourceTokensOnly
was false
we'd have filter as undefined
- does that mean it used to apply to all variants?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Previously, hasSourceTokensOnly: false
would rely on filtering implemented within the format function, instead of as a true style-dictionary
filter implemented with .registerFilter
. That is, formatters should assume any token filtering happens before the format is applied, which already limits the contents of dictionary.allTokens
we previously filtered on explicitly.
There's some more detailed rationale about this change provided on my review of Peter's PR here, notably:
IMHO, having
unfilteredTokens
in thedictionary
here suggests a possible code smell that we might want to be doing such filtering as a legit custom filter registered withstyle-dictionary
(similar to how we seem to define anisSource
filter today viaregisterFilter
).
See the current implementation of createCustomCSSVariables
(source).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the added context! 100% agree that it's better to have
a true
style-dictionary
filter implemented with.registerFilter
than
filtering implemented within the format function
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks great! I left quite a few comments but they're mostly just questions. Thank you so much for all of this!
{ | ||
name: '--output-references', | ||
description: 'Include references in the build output.', | ||
defaultValue: true, | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
100% agree. Good call/addition!
lib/build-tokens.js
Outdated
formatting: { | ||
fileHeaderTimestamp: true, | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good call! The default header looks like it covers everything we need, and I'm all for reducing complexity (even in small ways like this!)
/**
* Do not edit directly, this file was auto-generated.
* Generated on Tue, 03 Sep 2024 13:46:26 GMT
*/
filter: hasSourceTokensOnly | ||
? `isSource.${themeVariant}` | ||
: `isThemeVariant.${themeVariant}`, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just trying to wrap my head around this change a little bit. Before this change if hasSourceTokensOnly
was false
we'd have filter as undefined
- does that mean it used to apply to all variants?
lib/build-tokens.js
Outdated
formatting: { | ||
fileHeaderTimestamp: true, | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see this block now exists in a couple spots in this file. It's only 3 lines so I'm not worried about the copypasta, but I am curious as to if there's a "built-in" way to have a "global" formatting setting. If there isn't a "built-in" way I'm thinking it might be cool to move this out to a const like we have with defaultParams
so if anyone wants to change the formatting they can do it in one place.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@adamstankiewicz I think this is the last lingering question I have before giving this a ✔️!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Plan to investigate later this afternoon. I do recall seeing somewhere in the style-dictionary docs about global settings, so it might be possible. If the global approach isn't possible, I agree abstracting out a defaultParams
or similar would be worthwhile to be more DRY. I'll share an update later :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just pushed up a commit to re-introduce a custom file header, and apply it globally across all files in the css
platform.
/**
* Do not edit directly, this file was auto-generated. while transforming design tokens.
* See <root>/tokens/README.md for more details.
*/
@mixin mobile-type { | ||
.display-1, | ||
.display-2, | ||
.display-3, | ||
.display-1 { | ||
font-size: $display1-mobile-size; | ||
line-height: $display-mobile-line-height; | ||
} | ||
|
||
.display-2 { | ||
font-size: $display2-mobile-size; | ||
line-height: $display-mobile-line-height; | ||
} | ||
|
||
.display-3 { | ||
font-size: $display3-mobile-size; | ||
line-height: $display-mobile-line-height; | ||
} | ||
|
||
.display-4 { | ||
font-size: $display-mobile-size; | ||
font-size: $display4-mobile-size; | ||
line-height: $display-mobile-line-height; | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking at this it seems we used to use the same size and line height for .display-1
through .display-4
, and this updates it so we have different sizes but not different line heights? Just curious as to the reasoning behind that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great question! So, the new 2U Paragon Elm Theme has distinct sizes for mobile .display-1
through .display-4
, but Paragon alpha
doesn't currently actually have the tokens/CSS support for level-specific mobile display font sizes. As such, this PR introduces tokens for distinct levels of display size for mobile.
Regarding why there's not currently level-specific mobile line heights is that the Elm Theme continues to rely on a single line height across all mobile display levels (i.e., line-height: 1
), which also happens to be the non-mobile default line height as well.
Paragon base theme defines display-mobile-line-height: 3.5rem
, and Elm Theme overrides this to be display-mobile-line-height: 1
.
There is also only a single line height value configured for all non-mobile display levels, too.
Note that using line-height: 1
(i.e., without a unit like rem
) defines the line height to be equal to the font-size which is distinct per level. Given this, line-height: 1
is technically still results in distinct computed line heights per mobile display level.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That sounds very reasonable! I do wonder if supporting different custom line heights for each is something we want to do. I'd lean towards thinking we should, but I could definitely be convinced otherwise.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, supporting that as a use case is how I'm leaning, FWIW. Though, maybe we roll with it as is for this PR and @PKulkoRaccoonGang's related PR(s) to do the style-dictionary upgrade to v4, and treat level-specific display line heights as a standalone fast follow to these PRs before master
-> alpha
, given it's not necessarily related to the v4 upgrade itself per se and would probably be a reasonably scoped individual contribution.
@@ -21,13 +21,17 @@ | |||
$color-levels: 100, 200, 300, 400, 500, 600, 700, 800, 900; | |||
|
|||
.x-small { | |||
font-size: $x-small-font-size; | |||
font-size: $x-small-font-size !important; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm always slightly wary of !important
, could you explain why it's needed here? (Depending on the reasoning it might be nice to add that as a comment in the file itself)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CSS utility class definitions generally should always have !important
. See list of other existing utility classes on the Paragon docs site to observe their inclusion of !important
.
See example(s) of CSS utility class definitions from Bootstrap v4 (source) as a reference, too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah yes, I was getting towards the end of the diff and missed the filename.
It looks like almost everything else in the file has !important
(only .icon-spin
doesn't) - is the lack of !important
in .icon-spin
intentional?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, in additional icon-spin
, the font-weight: normal
property on .micro
doesn't include !important
either, though I don't it should for font-weight
(you could want micro-sized copy with font-weight-bold
, etc.). IMHO, .micro
shouldn't be defining font-weight
at all.
Regarding .icon-spin
specifically, it appears to only be used with the StatefulButton
component across all of the openedx
GitHub organization. I actually wonder whether we truly want to consider this a global utility class or not, given its specific to icons.
For example, alternatively, should the Icon
component expose a spin
prop that extends the rendered icon to add the icon-spin
class conditionally?
E.g., proposed usage from StatefulButton
:
icons: {
pending: <Icon src={SpinnerSimple} spin />,
},
I'm struggling to identify use cases for .icon-spin
outside of the Icon
component. With icon-spin
as a global CS utility class, I could also see it getting abused to make things spin/animate on the page that shouldn't (e.g., non-icons).
My 2c recommendation:
- Remove
.icon-spin
as a CSS utility class, implementing it instead of a class name specific toIcon
component. - Expose optional
spin
prop onIcon
component. - Update
StatefulButton
to passspin
prop on itspending
icon.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My 2c recommendation:
- Remove
.icon-spin
as a CSS utility class, implementing it instead of a class name specific toIcon
component.- Expose optional
spin
prop onIcon
component.- Update
StatefulButton
to passspin
prop on itspending
icon.
This absolutely sounds like the right move to me!
IMHO,
.micro
shouldn't be definingfont-weight
at all.
Do we have a sense of what might break if it didn't?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That being said, I don't think either of those should be part of this PR. Just making a couple follow-up issues to address them seems like the right move to me.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO, .micro shouldn't be defining font-weight at all.
Do we have a sense of what might break if it didn't?
It shouldn't break anything. The font-weight in .micro
is font-weight: normal
, which corresponds to font-weight 400, the default body
font weight used elsewhere.
That being said, I don't think either of those should be part of this PR. Just making a couple follow-up issues to address them seems like the right move to me.
100% 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is pretty cool! LGTM!
…, and updates CSS vars format **CLI Enhancements** * Exposes `--output-references` CLI argument for `build-tokens` command. Defaults to `true`. Ensures brand package output with the CLI includes references in build output out-of-the-box. **Token Management Improvements** * Registers filter(s) `isThemeVariant.{'light'}`, handling future theme variants when implemented (e.g., `isThemeVariant.dark`). * Migrates `createCustomCSSVariables` to use `formattedVariables` to rely on out-of-the-box CSS variable formatting. The formatter still supports token-specific overrides of `outputReferences`. If a token has modifications via `modify`, the modified base reference is not included in the output. * Updates custom fileHeader implementation, including a relative path to design tokens documentation. * Fixes bug with line-height tokens, switching their `$type` from `dimension` to `number` to resolve typography style regressions. * Updates typography tokens related to font size, font weight, and line-height for more consistent naming structure when taking into account mobile. * Updates `@mobile-type` SCSS mixin to support level-specific customization of mobile typography styles for display 1-4. * Renames `"description"` field in tokens to `"$description""` per the DTCG format. **Documentation Site Enhancements** * Ensures the "Typography" foundations page properly previews the correct font size for regular "Body" text and includes the missing "HEADING LABEL" example. * Updates to "Colors" page in docs site: * Displays token name instead of CSS variable in the color swatch previews (see screenshot below). * Include `accent-a` and `accent-b` alongside other color names, rather than manually rendering `Swatch` for the accents. * Modifies the grid styles for color swatch preview to be more responsive. * Resolves `NaNpx` bug in `MeasuredItem` component on docs site, while computing the measurements to display for an element (e.g., font size). Instead, it renders an empty block while measurements are resolved. * Updates `CodeBlock` styles on docs site to add its border and background color only to the `LivePreview`, not the entire `CodeBlock` example. * Reduces whitespace on docs site homepage. * Simplifies columns on docs site header, ensuring `SiteTitle` is horizontally aligned in the center.
8234010
to
88a2504
Compare
63a61de
into
Peter_Kulko/style-dictionary-v4
…s format (#3203) * feat: --output-references CLI arg for build-tokens, registers filters, and updates CSS vars format * Exposes `--output-references` CLI argument for `build-tokens` command. Defaults to `true`. Ensures brand package output with the CLI includes references in build output out-of-the-box. * Registers filter(s) `isThemeVariant.{'light'}`, handling future theme variants when implemented (e.g., `isThemeVariant.dark`). * Migrates `createCustomCSSVariables` to use `formattedVariables` to rely on out-of-the-box CSS variable formatting. The formatter still supports token-specific overrides of `outputReferences`. If a token has modifications via `modify`, the modified base reference is not included in the output. * Updates custom fileHeader implementation, including a relative path to design tokens documentation. * Fixes bug with line-height tokens, switching their `$type` from `dimension` to `number` to resolve typography style regressions. * Updates typography tokens related to font size, font weight, and line-height for more consistent naming structure when taking into account mobile. * Updates `@mobile-type` SCSS mixin to support level-specific customization of mobile typography styles for display 1-4. * Renames `"description"` field in tokens to `"$description""` per the DTCG format. * Ensures the "Typography" foundations page properly previews the correct font size for regular "Body" text and includes the missing "HEADING LABEL" example. * Updates to "Colors" page in docs site: * Displays token name instead of CSS variable in the color swatch previews (see screenshot below). * Include `accent-a` and `accent-b` alongside other color names, rather than manually rendering `Swatch` for the accents. * Modifies the grid styles for color swatch preview to be more responsive. * Resolves `NaNpx` bug in `MeasuredItem` component on docs site, while computing the measurements to display for an element (e.g., font size). Instead, it renders an empty block while measurements are resolved. * Updates `CodeBlock` styles on docs site to add its border and background color only to the `LivePreview`, not the entire `CodeBlock` example. * Reduces whitespace on docs site homepage. * Simplifies columns on docs site header, ensuring `SiteTitle` is horizontally aligned in the center.
…s format (#3203) * feat: --output-references CLI arg for build-tokens, registers filters, and updates CSS vars format * Exposes `--output-references` CLI argument for `build-tokens` command. Defaults to `true`. Ensures brand package output with the CLI includes references in build output out-of-the-box. * Registers filter(s) `isThemeVariant.{'light'}`, handling future theme variants when implemented (e.g., `isThemeVariant.dark`). * Migrates `createCustomCSSVariables` to use `formattedVariables` to rely on out-of-the-box CSS variable formatting. The formatter still supports token-specific overrides of `outputReferences`. If a token has modifications via `modify`, the modified base reference is not included in the output. * Updates custom fileHeader implementation, including a relative path to design tokens documentation. * Fixes bug with line-height tokens, switching their `$type` from `dimension` to `number` to resolve typography style regressions. * Updates typography tokens related to font size, font weight, and line-height for more consistent naming structure when taking into account mobile. * Updates `@mobile-type` SCSS mixin to support level-specific customization of mobile typography styles for display 1-4. * Renames `"description"` field in tokens to `"$description""` per the DTCG format. * Ensures the "Typography" foundations page properly previews the correct font size for regular "Body" text and includes the missing "HEADING LABEL" example. * Updates to "Colors" page in docs site: * Displays token name instead of CSS variable in the color swatch previews (see screenshot below). * Include `accent-a` and `accent-b` alongside other color names, rather than manually rendering `Swatch` for the accents. * Modifies the grid styles for color swatch preview to be more responsive. * Resolves `NaNpx` bug in `MeasuredItem` component on docs site, while computing the measurements to display for an element (e.g., font size). Instead, it renders an empty block while measurements are resolved. * Updates `CodeBlock` styles on docs site to add its border and background color only to the `LivePreview`, not the entire `CodeBlock` example. * Reduces whitespace on docs site homepage. * Simplifies columns on docs site header, ensuring `SiteTitle` is horizontally aligned in the center.
Note: Amongst other changes, addresses some of my feedback on the related, base PR: #3186
Changes
CLI Enhancements
--output-references
CLI argument forbuild-tokens
command. Defaults totrue
. Ensures brand package output with the CLI includes references in build output out-of-the-box.Token Management Improvements
isThemeVariant.{'light'}
, handling future theme variants when implemented (e.g.,isThemeVariant.dark
).createCustomCSSVariables
to useformattedVariables
to rely on out-of-the-box CSS variable formatting. The formatter still supports token-specific overrides ofoutputReferences
. If a token has modifications viamodify
, the modified base reference is not included in the output.$type
fromdimension
tonumber
to resolve typography style regressions.@mobile-type
SCSS mixin to support level-specific customization of mobile typography styles for display 1-4."description"
field in tokens to"$description""
per the DTCG format.Documentation Site Enhancements
accent-a
andaccent-b
alongside other color names, rather than manually renderingSwatch
for the accents.NaNpx
bug inMeasuredItem
component on docs site, while computing the measurements to display for an element (e.g., font size). Instead, it renders an empty block while measurements are resolved.CodeBlock
styles on docs site to add its border and background color only to theLivePreview
, not the entireCodeBlock
example.SiteTitle
is horizontally aligned in the center.Informational Notes
calc
defined within tokens, while we could usesd-transforms
to register a transformts/resolveMath
(source), it does not wrap math calculations withcalc(...)
, effectively not evaluating the operation in CSS. There's several related issues (example, example) instyle-dictionary
andsd-transforms
about this issue, with no current resolution; only hacky workarounds.Deploy Preview
N/A
Updates "Colors" page color swatch previews:
Note: screenshot depicts a local checkout
@edx/elm-theme
Merge Checklist
example
app?Post-merge Checklist