-
Notifications
You must be signed in to change notification settings - Fork 45
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into output-references
- Loading branch information
Showing
25 changed files
with
505 additions
and
46 deletions.
There are no files selected for viewing
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| '@primer/primitives': minor | ||
| --- | ||
|
|
||
| Adding new themeOverride preprocessor |
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| # Title | ||
| # Neutral Scales | ||
|
|
||
| ## Status | ||
|
|
||
|
|
||
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| # Token overrides | ||
|
|
||
| ## Status | ||
|
|
||
| | Stage | Status | | ||
| | -------- | ------ | | ||
| | Approved | ✅ | | ||
| | Adopted | 🚧 | | ||
|
|
||
| ## Context | ||
|
|
||
| When creating tokens, like `fgColor-default` we need to be able to define different color values for different conditions (mostly themes). | ||
| For example we use a dark color `#1f2328` in `light` mode and a light color `#f0f6fc` in dark mode. | ||
|
|
||
| In some cases we use different files, like `color-light.json5` and `color-dark.json5`, however this is not always practical. Specifically for component tokens, where it can be desired to create one token file per component, separate files for all color modes does not scale well. | ||
|
|
||
| ## Decision | ||
|
|
||
| This ADR provides a solution for thoses cases by allowing to specifiy specific overrides for a token within the `$extensions` property. | ||
|
|
||
| ```json5 | ||
| { | ||
| "button": { | ||
| "default": { | ||
| "bgColor": { | ||
| $value: "{base.neutral.2}" // default value, | ||
| $extensions: { | ||
| "org.primer.overrides": { | ||
| "dark": "{base.neutral.8}" // value use the dark mode, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To allow for more advanced overrides, you can provide an object with multiple properties instead of a value string. | ||
|
|
||
| ```json5 | ||
| { | ||
| "button": { | ||
| "default": { | ||
| "bgColor": { | ||
| $value: "{base.neutral.2}" // default value, | ||
| $extensions: { | ||
| "org.primer.overrides": { | ||
| "dark": { | ||
| $value: "{base.neutral.8}", // value use the dark theme | ||
| $description: "A dark theme description", // specific description for dark theme | ||
| }, | ||
| "dark-dimmed": "{base.neutral.9}" // value use the dark-dimmed theme | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| This feature is implemented using a [`preprocessor`](https://styledictionary.com/reference/hooks/preprocessors/) for style dictionary. To enable this, you need to make two changes in any [`platform`](https://styledictionary.com/reference/config/#platform) configuration that should have this feature enabled: | ||
|
|
||
| Add the `themeOverrides` preprocessor to the platform config: | ||
|
|
||
| ```diff | ||
| { | ||
| prefix, | ||
| buildPath, | ||
| + preprocessors: ['themeOverrides'], | ||
| transforms: [ | ||
| 'name/pathToKebabCase', | ||
| 'color/hex', | ||
| //... | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Pass the current theme to the platform config options: | ||
|
|
||
| ```diff | ||
| { | ||
| prefix, | ||
| buildPath, | ||
| preprocessors: ['themeOverrides'], | ||
| transforms: [ | ||
| 'name/pathToKebabCase', | ||
| 'color/hex', | ||
| //... | ||
| ], | ||
| options: { | ||
| basePxFontSize: 16, | ||
| + themeOverrides: { | ||
| + theme: "dark", | ||
| + }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Options | ||
|
|
||
| It is possible to change the `$extensions` property name and the default `value` property using the platform config options: | ||
|
|
||
| ```diff | ||
| { | ||
| prefix, | ||
| buildPath, | ||
| preprocessors: ['themeOverrides'], | ||
| transforms: [ | ||
| 'name/pathToKebabCase', | ||
| 'color/hex', | ||
| //... | ||
| ], | ||
| options: { | ||
| basePxFontSize: 16, | ||
| themeOverrides: { | ||
| theme: "dark", | ||
| + extensionProp: "theme", // defaults to 'org.primer.overrides' | ||
| + valueProp: "value", // defaults to "$value" | ||
| }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Impact | ||
|
|
||
| - we can now move to dedicated component files in `primitives`, making editing a lot easier | ||
| - `primer/brand` can now integrate more of our workflows and tooling as they already use a "one file per component" model | ||
|
|
||
| ### Alternatives | ||
|
|
||
| Creating dedicated theme files for each component, e.g. `button-light.json5`, `button-dark.json5`, `button-light-high-contrast.json5`, ... |
This file contains 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
This file contains 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
Oops, something went wrong.