From e638b2e049097f69c1ceb62f3a424496f0de2a78 Mon Sep 17 00:00:00 2001 From: Tim Layton Date: Thu, 5 Dec 2019 10:23:50 -0800 Subject: [PATCH] add override docs, move overrides to tokens file (#2515) --- documentation/Color system.md | 32 +++++++++++++++++++++ pre-commit | 2 +- scripts/color-system-docs.js | 39 +++++++++++++++++++------- src/index.ts | 1 + src/utilities/theme/index.ts | 2 ++ src/utilities/theme/tokens.ts | 52 +++++++++++++++++++++++++++++++++++ src/utilities/theme/utils.ts | 46 ++----------------------------- 7 files changed, 119 insertions(+), 55 deletions(-) create mode 100644 src/utilities/theme/tokens.ts diff --git a/documentation/Color system.md b/documentation/Color system.md index 38973d32210..68ca5484b8d 100644 --- a/documentation/Color system.md +++ b/documentation/Color system.md @@ -14,6 +14,7 @@ - [highlight](#highlight) - [success](#success) - [decorative](#decorative) +- [Overrides](#Overrides) ## surface @@ -215,3 +216,34 @@ Used to decorate elements where color does convey a specific meaning in componen | 
--p-decorative-five-text
| For use as a decorative text color that is applied on a decorative surface. `-inverse`, `-light`, and `-dark` variants available. | ![](https://www.gifpng.com/64x64/4e0e1f/FFFFFF?border-width=16&border-type=rectangle&border-color=fafafa&text=%20) | ![](https://www.gifpng.com/64x64/ffffff/FFFFFF?border-width=16&border-type=rectangle&border-color=0c0d0e&text=%20) | --- + +## Overrides + +[↑ Back to top](#table-of-contents) + +| CSS variable | Value | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `--p-border-radius-base` | `0.4rem` | +| `--p-border-radius-wide` | `0.8rem` | +| `--p-card-shadow` | `0px 0px 5px var(--p-shadow-from-ambient-light), 0px 1px 2px var(--p-shadow-from-direct-light)` | +| `--p-popover-shadow` | `-1px 0px 20px var(--p-shadow-from-ambient-light), 0px 1px 5px var(--p-shadow-from-direct-light)` | +| `--p-modal-shadow` | `0px 6px 32px var(--p-shadow-from-ambient-light), 0px 1px 6px var(--p-shadow-from-direct-light)` | +| `--p-override-none` | `none` | +| `--p-override-transparent` | `transparent` | +| `--p-override-one` | `1` | +| `--p-override-visible` | `visible` | +| `--p-override-zero` | `0` | +| `--p-override-loading-z-index` | `514` | +| `--p-button-font-weight` | `500` | +| `--p-non-null-content` | `''` | +| `--p-banner-default-border` | `inset 0 0.2rem 0 0 var(--p-border-on-surface), inset 0 0 0 0.2rem var(--p-border-on-surface)` | +| `--p-banner-success-border` | `inset 0 0.2rem 0 0 var(--p-success-border), inset 0 0 0 0.2rem var(--p-success-border)` | +| `--p-banner-highlight-border` | `inset 0 0.2rem 0 0 var(--p-highlight-border), inset 0 0 0 0.2rem var(--p-highlight-border)` | +| `--p-banner-warning-border` | `inset 0 0.2rem 0 0 var(--p-warning-border), inset 0 0 0 0.2rem var(--p-warning-border)` | +| `--p-banner-critical-border` | `inset 0 0.2rem 0 0 var(--p-critical-border), inset 0 0 0 0.2rem var(--p-critical-border)` | +| `--p-badge-mix-blend-mode` | `luminosity` | +| `--p-border-subdued` | `0.1rem solid var(--p-border-subdued-on-surface)` | +| `--p-text-field-spinner-offset` | `0.2rem` | +| `--p-text-field-focus-ring-offset` | `-0.4rem` | +| `--p-text-field-focus-ring-border-radius` | `0.7rem` | +| `--p-button-group-item-spacing` | `0.2rem` | diff --git a/pre-commit b/pre-commit index bfa62a7437b..cf2f8c8a827 100755 --- a/pre-commit +++ b/pre-commit @@ -1,7 +1,7 @@ #!/usr/bin/ruby --disable-gems NON_COMMITTABLE_FILE_PATHS = ['playground/Playground.tsx'] -COLOR_DOC_SOURCE_FILE_PATHS = ['src/utilities/theme/role-variants.ts'] +COLOR_DOC_SOURCE_FILE_PATHS = ['src/utilities/theme/role-variants.ts', 'src/utilities/theme/tokens.ts'] module PreCommit extend self diff --git a/scripts/color-system-docs.js b/scripts/color-system-docs.js index cfd52fd50df..46fcb91625e 100644 --- a/scripts/color-system-docs.js +++ b/scripts/color-system-docs.js @@ -6,6 +6,7 @@ const { UNSTABLE_toCssCustomPropertySyntax: cssify, UNSTABLE_roleVariants: roleVariants, UNSTABLE_buildColors: colorFactory, + UNSTABLE_Tokens: Tokens, } = require('../'); const ColorSwatch = { @@ -46,9 +47,11 @@ const darkColors = colorFactory( ); const Template = { - anchor: (name) => `- [${name}](#${name})\n`, - role: (name, description) => - `## ${name}\n\n[↑ Back to top](#table-of-contents)\n\n${description}\n\n`, + tocItem: (name) => `- [${name}](#${name})\n`, + section: (name, description) => + `## ${name}\n\n[↑ Back to top](#table-of-contents)\n\n${ + description ? `${description}\n\n` : '' + }`, heading: '|CSS variable|Description|Light mode|Dark mode|\n|---|---|---|---|\n', hr: '\n\n---\n\n', @@ -65,6 +68,7 @@ const Template = { darkColors.surfaceBackground, )}&text=%20)|\n`; }, + overrideItem: (name, value) => `|\`${cssify(name)}\`|\`${value}\`|\n`, }; const boilerplate = @@ -72,24 +76,25 @@ const boilerplate = const tocTitle = '## Table of contents\n\n'; const tocContents = Object.keys(roleVariants).reduce( - (acc1, role) => acc1 + Template.anchor(role), + (accumulator, role) => accumulator + Template.tocItem(role), '', ); const contents = Object.entries(roleVariants).reduce( - (acc1, [role, variants]) => { - const children = variants.reduce((acc2, variant) => { + (tableMarkdown, [role, variants]) => { + const children = variants.reduce((rowMarkdown, variant) => { const light = toHex(lightColors[variant.name]); const dark = toHex(darkColors[variant.name]); return ( - acc2 + Template.variant(variant.name, variant.description, light, dark) + rowMarkdown + + Template.variant(variant.name, variant.description, light, dark) ); }, ''); return ( - acc1 + - Template.role(role, RoleDescription[role]) + + tableMarkdown + + Template.section(role, RoleDescription[role]) + Template.heading + children + Template.hr @@ -98,7 +103,21 @@ const contents = Object.entries(roleVariants).reduce( '', ); -const data = boilerplate + tocTitle + tocContents + contents; +const overridesContents = Object.entries(Tokens).reduce( + (accumulator, [override, value]) => { + return accumulator + Template.overrideItem(override, value); + }, + '|CSS variable|Value|\n|---|---|\n', +); + +const data = + boilerplate + + tocTitle + + tocContents + + Template.tocItem('Overrides') + + contents + + Template.section('Overrides') + + overridesContents; writeFileSync(resolvePath('documentation/Color system.md'), data); diff --git a/src/index.ts b/src/index.ts index defcce58d32..dfc6a5f672a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -15,5 +15,6 @@ export { buildColors as UNSTABLE_buildColors, roleVariants as UNSTABLE_roleVariants, toCssCustomPropertySyntax as UNSTABLE_toCssCustomPropertySyntax, + Tokens as UNSTABLE_Tokens, } from './utilities/theme'; /* eslint-enable @typescript-eslint/camelcase */ diff --git a/src/utilities/theme/index.ts b/src/utilities/theme/index.ts index 979f3cff933..e07bca67e15 100644 --- a/src/utilities/theme/index.ts +++ b/src/utilities/theme/index.ts @@ -12,3 +12,5 @@ export { buildColors, toCssCustomPropertySyntax, } from './utils'; + +export {Tokens} from './tokens'; diff --git a/src/utilities/theme/tokens.ts b/src/utilities/theme/tokens.ts new file mode 100644 index 00000000000..a0d24c828c9 --- /dev/null +++ b/src/utilities/theme/tokens.ts @@ -0,0 +1,52 @@ +const BorderRadius = { + borderRadiusBase: rem('4px'), + borderRadiusWide: rem('8px'), +}; + +const Shadow = { + cardShadow: + '0px 0px 5px var(--p-shadow-from-ambient-light), 0px 1px 2px var(--p-shadow-from-direct-light)', + popoverShadow: + '-1px 0px 20px var(--p-shadow-from-ambient-light), 0px 1px 5px var(--p-shadow-from-direct-light)', + modalShadow: + '0px 6px 32px var(--p-shadow-from-ambient-light), 0px 1px 6px var(--p-shadow-from-direct-light)', +}; + +const Overrides = { + overrideNone: 'none', + overrideTransparent: 'transparent', + overrideOne: '1', + overrideVisible: 'visible', + overrideZero: '0', + overrideLoadingZIndex: '514', + buttonFontWeight: '500', + nonNullContent: "''", + bannerDefaultBorder: buildBannerBorder('--p-border-on-surface'), + bannerSuccessBorder: buildBannerBorder('--p-success-border'), + bannerHighlightBorder: buildBannerBorder('--p-highlight-border'), + bannerWarningBorder: buildBannerBorder('--p-warning-border'), + bannerCriticalBorder: buildBannerBorder('--p-critical-border'), + badgeMixBlendMode: 'luminosity', + borderSubdued: `${rem('1px')} solid var(--p-border-subdued-on-surface)`, + textFieldSpinnerOffset: rem('2px'), + textFieldFocusRingOffset: rem('-4px'), + textFieldFocusRingBorderRadius: rem('7px'), + buttonGroupItemSpacing: rem('2px'), +}; + +export const Tokens = { + ...BorderRadius, + ...Shadow, + ...Overrides, +}; + +function rem(px: string) { + const baseFontSize = 10; + return `${parseInt(px, 10) / baseFontSize}rem`; +} + +function buildBannerBorder(cssVar: string) { + return `inset 0 ${rem('2px')} 0 0 var(${cssVar}), inset 0 0 0 ${rem( + '2px', + )} var(${cssVar})`; +} diff --git a/src/utilities/theme/utils.ts b/src/utilities/theme/utils.ts index 153cf6b53f2..f56addf9680 100644 --- a/src/utilities/theme/utils.ts +++ b/src/utilities/theme/utils.ts @@ -23,6 +23,7 @@ import { HslaSetting, } from './types'; import {roleVariants, UNSTABLE_Color} from './role-variants'; +import {Tokens} from './tokens'; export function buildCustomProperties( themeConfig: ThemeConfig, @@ -31,7 +32,7 @@ export function buildCustomProperties( return globalTheming ? customPropertyTransformer({ ...buildColors(themeConfig, roleVariants), - ...overrides(), + ...Tokens, }) : buildLegacyColors(themeConfig); } @@ -132,38 +133,6 @@ export function buildColors( ); } -function overrides() { - return { - overrideNone: 'none', - overrideTransparent: 'transparent', - overrideOne: '1', - overrideVisible: 'visible', - overrideZero: '0', - overrideLoadingZIndex: '514', - buttonFontWeight: '500', - nonNullContent: "''", - borderRadiusBase: rem('4px'), - borderRadiusWide: rem('8px'), - bannerDefaultBorder: buildBannerBorder('--p-border-on-surface'), - bannerSuccessBorder: buildBannerBorder('--p-success-border'), - bannerHighlightBorder: buildBannerBorder('--p-highlight-border'), - bannerWarningBorder: buildBannerBorder('--p-warning-border'), - bannerCriticalBorder: buildBannerBorder('--p-critical-border'), - badgeMixBlendMode: 'luminosity', - borderSubdued: `${rem('1px')} solid var(--p-border-subdued-on-surface)`, - textFieldSpinnerOffset: rem('2px'), - textFieldFocusRingOffset: rem('-4px'), - textFieldFocusRingBorderRadius: rem('7px'), - cardShadow: - '0px 0px 5px var(--p-shadow-from-ambient-light), 0px 1px 2px var(--p-shadow-from-direct-light)', - popoverShadow: - '-1px 0px 20px var(--p-shadow-from-ambient-light), 0px 1px 5px var(--p-shadow-from-direct-light)', - modalShadow: - '0px 6px 32px var(--p-shadow-from-ambient-light), 0px 1px 6px var(--p-shadow-from-direct-light)', - buttonGroupItemSpacing: rem('2px'), - }; -} - function customPropertyTransformer( properties: Record, ) { @@ -180,17 +149,6 @@ export function toCssCustomPropertySyntax(camelCase: string) { return `--p-${camelCase.replace(/([A-Z0-9])/g, '-$1').toLowerCase()}`; } -function rem(px: string) { - const baseFontSize = 10; - return `${parseInt(px, 10) / baseFontSize}rem`; -} - -function buildBannerBorder(cssVar: string) { - return `inset 0 ${rem('2px')} 0 0 var(${cssVar}), inset 0 0 0 ${rem( - '2px', - )} var(${cssVar})`; -} - function buildLegacyColors(theme?: ThemeConfig): CustomPropertiesLike { let colorPairs; const colors =