add override docs, move overrides to tokens file (#2515)

Shopify · Dec 5, 2019 · e638b2e · e638b2e
1 parent d27aea0
commit e638b2e
Show file tree

Hide file tree

Showing 7 changed files with 119 additions and 55 deletions.
diff --git 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
 | <pre>--p-decorative-five-text</pre>     | 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
@@ -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
@@ -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,31 +68,33 @@ const Template = {
       darkColors.surfaceBackground,
     )}&text=%20)|\n`;
   },
+  overrideItem: (name, value) => `|\`${cssify(name)}\`|\`${value}\`|\n`,
 };
 
 const boilerplate =
   '# Color system\n\n⚠️ The color system is currently an unstable API, and is subject to change in non-major releases of Polaris react. Please use with caution.\n\n';
 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
@@ -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
@@ -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
@@ -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
@@ -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<string, HSLAColor | string>,
 ) {
@@ -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 =