Skip to content

Commit

Permalink
feat: --output-references CLI arg for build-tokens, registers filters…
Browse files Browse the repository at this point in the history
…, and updates CSS vars format (#3203)

* feat: --output-references CLI arg for build-tokens, registers filters, and updates CSS vars format

### Changes

#### 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.
  • Loading branch information
adamstankiewicz authored Sep 3, 2024
1 parent 0e1ef04 commit 63a61de
Show file tree
Hide file tree
Showing 47 changed files with 1,006 additions and 1,375 deletions.
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
.PHONY: build
build:
rm -rf ./dist
tsc --project tsconfig.build.json
Expand Down
10 changes: 10 additions & 0 deletions bin/paragon-scripts.js
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,21 @@ const COMMANDS = {
description: 'Include only source design tokens in the build.',
defaultValue: false,
},
{
name: '--output-references',
description: 'Include references in the build output.',
defaultValue: true,
},
{
name: '-t, --themes',
description: 'Specify themes to include in the token build.',
defaultValue: 'light',
},
{
name: '-v, --verbose',
description: 'Enable verbose logging.',
defaultValue: false,
},
],
},
'replace-variables': {
Expand Down
81 changes: 55 additions & 26 deletions lib/build-tokens.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
const path = require('path');
const minimist = require('minimist');
const { initializeStyleDictionary, createCustomCSSVariables, colorTransform } = require('../tokens/style-dictionary');
const {
initializeStyleDictionary,
colorTransform,
} = require('../tokens/style-dictionary');
const { createIndexCssFile } = require('../tokens/utils');

/**
Expand All @@ -13,24 +16,37 @@ const { createIndexCssFile } = require('../tokens/utils');
* @param {string|string[]} [commandArgs.themes=['light']] - The themes (variants) for which to build tokens.
*/
async function buildTokensCommand(commandArgs) {
const StyleDictionary = await initializeStyleDictionary();

const defaultParams = {
themes: ['light'],
'build-dir': './build/',
'source-tokens-only': false,
'output-references': true,
verbose: false,
};

const alias = {
'build-dir': 'b',
themes: 't',
verbose: '-v',
};

const {
'build-dir': buildDir,
source: tokensSource,
'source-tokens-only': hasSourceTokensOnly,
'output-references': outputReferences,
themes,
} = minimist(commandArgs, { alias, default: defaultParams, boolean: 'source-tokens-only' });
verbose,
} = minimist(
commandArgs,
{
alias,
default: defaultParams,
boolean: ['source-tokens-only', 'output-references', 'verbose'],
},
);

const StyleDictionary = await initializeStyleDictionary({ themes });

const coreConfig = {
include: [
Expand All @@ -43,33 +59,35 @@ async function buildTokensCommand(commandArgs) {
platforms: {
css: {
prefix: 'pgn',
transformGroup: 'css',
// NOTE: buildPath must end with a slash
buildPath: buildDir.slice(-1) === '/' ? buildDir : `${buildDir}/`,
options: {
fileHeader: 'customFileHeader',
},
files: [
{
format: 'css/custom-variables',
destination: 'core/variables.css',
filter: hasSourceTokensOnly ? 'isSource' : undefined,
options: {
outputReferences: !hasSourceTokensOnly,
outputReferences,
},
},
{
format: 'css/custom-media-breakpoints',
destination: 'core/custom-media-breakpoints.css',
filter: hasSourceTokensOnly ? 'isSource' : undefined,
options: {
outputReferences: !hasSourceTokensOnly,
outputReferences,
},
},
],
transforms: StyleDictionary.hooks.transformGroups.css.filter(item => item !== 'size/rem').concat('color/sass-color-functions', 'str-replace'),
options: {
fileHeader: 'customFileHeader',
},
},
},
log: {
verbosity: verbose ? 'verbose' : 'default',
},
};

const getStyleDictionaryConfig = (themeVariant) => ({
Expand All @@ -91,45 +109,56 @@ async function buildTokensCommand(commandArgs) {
transform: (token) => colorTransform(token, themeVariant),
},
},
format: {
'css/custom-variables': formatterArgs => createCustomCSSVariables({
formatterArgs,
themeVariant,
}),
},
platforms: {
css: {
...coreConfig.platforms.css,
files: [
{
format: 'css/custom-variables',
destination: `themes/${themeVariant}/variables.css`,
filter: hasSourceTokensOnly ? 'isSource' : undefined,
filter: hasSourceTokensOnly
? `isSource.${themeVariant}`
: `isThemeVariant.${themeVariant}`,
options: {
outputReferences: !hasSourceTokensOnly,
outputReferences,
},
},
{
format: 'css/utility-classes',
destination: `themes/${themeVariant}/utility-classes.css`,
filter: hasSourceTokensOnly ? 'isSource' : undefined,
options: {
outputReferences: !hasSourceTokensOnly,
outputReferences,
},
},
],
},
},
});

new StyleDictionary(coreConfig).buildAllPlatforms();
createIndexCssFile({ buildDir, isTheme: false });
// Create list of style-dictionary configurations to build (core + theme variants)
const configs = [
{ config: coreConfig },
...themes.map((themeVariant) => {
const config = getStyleDictionaryConfig(themeVariant);
return {
config,
themeVariant,
};
}),
];

themes.forEach(async (themeVariant) => {
const config = getStyleDictionaryConfig(themeVariant);
new StyleDictionary(config).buildAllPlatforms();
createIndexCssFile({ buildDir, isTheme: true, themeVariant });
});
// Build tokens for each configuration
await Promise.all(configs.map(async ({ config, isThemeVariant, themeVariant }) => {
const sd = new StyleDictionary(config);
await sd.cleanAllPlatforms();
await sd.buildAllPlatforms();
createIndexCssFile({
buildDir,
isThemeVariant: !!isThemeVariant,
themeVariant,
});
}));
}

module.exports = buildTokensCommand;
8 changes: 4 additions & 4 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
"dependencies": {
"@popperjs/core": "^2.11.4",
Expand Down Expand Up @@ -114,7 +115,7 @@
"@babel/preset-typescript": "^7.16.7",
"@edx/eslint-config": "^3.2.0",
"@edx/stylelint-config-edx": "^2.3.0",
"@edx/typescript-config": "^1.0.1",
"@edx/typescript-config": "^1.1.0",
"@formatjs/cli": "^5.0.2",
"@semantic-release/changelog": "^6.0.1",
"@semantic-release/git": "^10.0.1",
Expand Down
2 changes: 1 addition & 1 deletion src/Form/_FormText.scss
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
.pgn__form-text {
font-size: var(--pgn-typography-font-size-small-base);
font-size: var(--pgn-typography-font-size-sm);
display: flex;
align-items: center;

Expand Down
4 changes: 2 additions & 2 deletions src/PageBanner/index.scss
Original file line number Diff line number Diff line change
Expand Up @@ -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);
background-color: var(--pgn-page-baner-bg, inherit);
color: var(--pgn-page-baner-color, inherit);

@include media-breakpoint-up(md) {
font-size: var(--pgn-typography-font-size-small-base);
font-size: var(--pgn-typography-font-size-sm);
}
}

Expand Down
2 changes: 1 addition & 1 deletion src/ProgressBar/index.scss
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,6 @@
.pgn__progress-hint {
box-sizing: border-box;
padding: 0 var(--pgn-spacing-progress-bar-hint-annotation-gap);
font-size: var(--pgn-typography-font-size-small-base);
font-size: var(--pgn-typography-font-size-sm);
}
}
2 changes: 1 addition & 1 deletion src/Stepper/index.scss
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@
}

.pgn__stepper-header-step-description {
font-size: var(--pgn-typography-font-size-small-x);
font-size: var(--pgn-typography-font-size-xs);
}

&.pgn__stepper-header-step-active ~ .pgn__stepper-header-step {
Expand Down
2 changes: 1 addition & 1 deletion src/Toast/index.scss
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
padding: 0;

p {
font-size: var(--pgn-typography-font-size-small-base);
font-size: var(--pgn-typography-font-size-sm);
margin: 0;
padding-right: .75rem;
}
Expand Down
9 changes: 4 additions & 5 deletions styles/css/core/custom-media-breakpoints.css
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
/*
* IMPORTANT: This file is the result of assembling design tokens.
* Do not edit directly.
* Generated on Tue, 27 Aug 2024 17:14:44 GMT
/**
* Do not edit directly, this file was auto-generated. while transforming design tokens.
* See <root>/tokens/README.md for more details.
*/

@custom-media --pgn-size-breakpoint-min-width-xs (min-width: 0rem);
@custom-media --pgn-size-breakpoint-min-width-xs (min-width: 0);
@custom-media --pgn-size-breakpoint-max-width-xs (max-width: 576px);
@custom-media --pgn-size-breakpoint-min-width-sm (min-width: 576px);
@custom-media --pgn-size-breakpoint-max-width-sm (max-width: 768px);
Expand Down
Loading

0 comments on commit 63a61de

Please sign in to comment.