From a8aef2ab96850a9587640b024052db8c8edc2b8c Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Thu, 18 Aug 2022 16:24:53 +0530 Subject: [PATCH 1/8] docs(PPDSC-2291): componen default initial ui changes --- .../hero-component-defaults-illustration.tsx | 191 ++++++++++++++++++ ...efaults.mdx => component-defaults-old.mdx} | 0 .../theme/theming/component-defaults.tsx | 86 ++++++++ site/routes.ts | 4 +- 4 files changed, 279 insertions(+), 2 deletions(-) create mode 100644 site/components/illustrations/components/hero-component-defaults-illustration.tsx rename site/pages/theme/theming/{component-defaults.mdx => component-defaults-old.mdx} (100%) create mode 100644 site/pages/theme/theming/component-defaults.tsx diff --git a/site/components/illustrations/components/hero-component-defaults-illustration.tsx b/site/components/illustrations/components/hero-component-defaults-illustration.tsx new file mode 100644 index 0000000000..7cbf300df3 --- /dev/null +++ b/site/components/illustrations/components/hero-component-defaults-illustration.tsx @@ -0,0 +1,191 @@ +import React from 'react'; +import {getSSRId} from 'newskit'; +import {Svg} from '../svg'; +import {Path} from '../path'; +import {Rect} from '../rect'; +import {Ellipse} from '../ellipse'; + +export const HeroComponentDefaultsIllustration: React.FC = () => { + const mask0 = getSSRId(); + const mask1 = getSSRId(); + const filter0 = getSSRId(); + + return ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ); +}; + +export default HeroComponentDefaultsIllustration; diff --git a/site/pages/theme/theming/component-defaults.mdx b/site/pages/theme/theming/component-defaults-old.mdx similarity index 100% rename from site/pages/theme/theming/component-defaults.mdx rename to site/pages/theme/theming/component-defaults-old.mdx diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx new file mode 100644 index 0000000000..06029544fc --- /dev/null +++ b/site/pages/theme/theming/component-defaults.tsx @@ -0,0 +1,86 @@ +import React from 'react'; +import {InlineMessage, toNewsKitIcon} from 'newskit'; +import {Info as FilledInfo} from '@emotion-icons/material/Info'; +import {Link} from '../../../components/link'; +import {InlineCode} from '../../../components/markdown-elements'; +import {LayoutProps} from '../../../components/layout'; +import {ComponentPageCell} from '../../../components/layout-cells'; +import { + ContentSection, + ContentPrimary, +} from '../../../components/content-structure'; +import {FoundationPageTemplate} from '../../../templates/foundation-page-template'; + +const IconFilledInfo = toNewsKitIcon(FilledInfo); + +const infoIcon = ( + +); + +const ComponentDefaults = (layoutProps: LayoutProps) => ( + + + + + Each NewsKit component has default design tokens (component + defaults) applied to define its default appearance, or behaviour. +
+
+ As part of the component defaults functionality, there is a + consistent overrides prop on all + components. This prop takes an object which mirrors the structure + of the component defaults. Each component documents the structure + of its component defaults on its respective documentation page. +
+
+ Component defaults can be overridden at either the theme level or + at a component level. + + Carefully consider if the desired impact of changing a component + default is to change a specific instance of a component or + multiple components. For example, changing the size used by all{' '} + button components at a + theme level, or changing the size of a specific instance of a + button at a component level. + + + } + showSeparator + /> + + + +); + +export default ComponentDefaults; diff --git a/site/routes.ts b/site/routes.ts index 86b9694b6c..95180f3352 100644 --- a/site/routes.ts +++ b/site/routes.ts @@ -284,10 +284,10 @@ export default [ id: '/theme/theming/using-a-theme', }, { - title: 'Component overrides & defaults', + title: 'Component defaults', illustration: 'theme/component-defaults/hero', description: - 'Each component in NewsKit has defaults that can be overridden to enhance the experience.', + 'A preselected option that is applied to a component to define its appearance or behaviour.', page: true, id: '/theme/theming/component-defaults', }, From 77958711f953dc8258230029679ade1ea2cb7b2b Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Fri, 19 Aug 2022 11:38:51 +0530 Subject: [PATCH 2/8] docs(PPDSC-2291): componen defaul ui changes --- .../theme/theming/component-defaults.tsx | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx index 06029544fc..8faacc3cfd 100644 --- a/site/pages/theme/theming/component-defaults.tsx +++ b/site/pages/theme/theming/component-defaults.tsx @@ -1,6 +1,7 @@ import React from 'react'; import {InlineMessage, toNewsKitIcon} from 'newskit'; import {Info as FilledInfo} from '@emotion-icons/material/Info'; +import {Code} from '../../../components/code'; import {Link} from '../../../components/link'; import {InlineCode} from '../../../components/markdown-elements'; import {LayoutProps} from '../../../components/layout'; @@ -8,6 +9,9 @@ import {ComponentPageCell} from '../../../components/layout-cells'; import { ContentSection, ContentPrimary, + ContentSecondary, + ContentTertiary, + ContentColSpan, } from '../../../components/content-structure'; import {FoundationPageTemplate} from '../../../templates/foundation-page-template'; @@ -76,9 +80,201 @@ const ComponentDefaults = (layoutProps: LayoutProps) => ( } + childrenColSpan={ContentColSpan.TEXT} showSeparator /> + + + + To override at the theme level, update a theme or{' '} + + create a theme + {' '} + with the changes under the overrides property (similar to changing + other areas of the theme). Components or interface elements that + are utilising the updated property will reflect these changes. + + } + childrenColSpan={ContentColSpan.TEXT} + /> + + Here is an example of overriding the component defaults for the + medium-sized button{' '} + component, changing the default{' '} + + typography presets + {' '} + and{' '} + style presets: + + } + showSeparator + > + + {`import {createTheme} from 'newskit'; + +const theme = createTheme({ + name: 'newskit-component-defaults-change', + overrides: { + componentDefaults: { + button: { + medium: { + typographyPreset: 'utilityButton010', + stylePreset: 'buttonOutlinedPrimary', + }, + }, + } + }, +});`} + + + Some components, like the button, will have variants in their + component defaults such as size. + + + + + + + + + {`import {Button} from 'newskit'; + +// Overrides: +; + +`} + + + These overrides will only apply to that specific instance of the + component. + + + The variant (in this case, “medium”) is not included in the + overrides. Variants are not specified in the component overrides + prop, only the theme. Some components which are built using multiple + components may have a nested structure to their component defaults. + + + + The example below shows overriding the{' '} + button component + appearance: + + } + showSeparator + > + + {`// Component Defaults: +byline: { + stylePreset: 'inkSubtle', + typographyPreset: 'utilityMeta020', + spaceStack: 'space020', + link: { + stylePreset: 'bylineLink', + typographyPreset: 'utilityMeta020', + }, + divider: { + stylePreset: 'bylineDivider', + spaceInline: 'space020', + }, +}, + +// Overrides +`} + + + + + + + Part of the functionality of the defaults and overrides system, + enables overriding of design tokens at specific breakpoints. For + example, setting different typography presets at different + breakpoints, can make the text larger on bigger devices than on + smaller devices. +

+ Properties that support this are documented as using the generic{' '} + MQ type, i.e.{' '} + MQ<string>. This means passing a + single string token to be used at all times, or a combination at + breakpoints. + + } + childrenColSpan={ContentColSpan.TEXT} + /> + + + {`typographyPreset: { + xs: 'editorialHeadline010', + md: 'editorialHeadline010', + lg: 'editorialHeadline010', + }`} + + + ); From 3c40c01b83200bbc3dbd43861841b08af3c4c0bd Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Fri, 19 Aug 2022 12:20:43 +0530 Subject: [PATCH 3/8] docs(PPDSC-2291): ui fixes --- site/pages/theme/theming/component-defaults.tsx | 2 +- site/routes.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx index 8faacc3cfd..866313927c 100644 --- a/site/pages/theme/theming/component-defaults.tsx +++ b/site/pages/theme/theming/component-defaults.tsx @@ -190,7 +190,7 @@ const theme = createTheme({ role="region" aria-label="variants" overrides={{ - marginBlockStart: 'space070', + marginBlockStart: 'space050', }} > The variant (in this case, “medium”) is not included in the diff --git a/site/routes.ts b/site/routes.ts index 95180f3352..22aba82e47 100644 --- a/site/routes.ts +++ b/site/routes.ts @@ -284,7 +284,7 @@ export default [ id: '/theme/theming/using-a-theme', }, { - title: 'Component defaults', + title: 'Component overrides & defaults', illustration: 'theme/component-defaults/hero', description: 'A preselected option that is applied to a component to define its appearance or behaviour.', From 693a56a1a68d5b57d997c29be7fb1d0ddcd53c0c Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Fri, 19 Aug 2022 16:01:34 +0530 Subject: [PATCH 4/8] docs(PPDSC-2291): ui fixes --- site/pages/theme/theming/component-defaults.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx index 866313927c..0740769c62 100644 --- a/site/pages/theme/theming/component-defaults.tsx +++ b/site/pages/theme/theming/component-defaults.tsx @@ -175,7 +175,6 @@ const theme = createTheme({ Date: Fri, 19 Aug 2022 17:15:10 +0530 Subject: [PATCH 5/8] docs(PPDSC-2291): design feedback changes --- site/pages/theme/theming/component-defaults.tsx | 2 +- site/routes.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx index 0740769c62..736f9c4c1f 100644 --- a/site/pages/theme/theming/component-defaults.tsx +++ b/site/pages/theme/theming/component-defaults.tsx @@ -153,7 +153,7 @@ const theme = createTheme({ diff --git a/site/routes.ts b/site/routes.ts index 22aba82e47..95180f3352 100644 --- a/site/routes.ts +++ b/site/routes.ts @@ -284,7 +284,7 @@ export default [ id: '/theme/theming/using-a-theme', }, { - title: 'Component overrides & defaults', + title: 'Component defaults', illustration: 'theme/component-defaults/hero', description: 'A preselected option that is applied to a component to define its appearance or behaviour.', From 9886fa53c733ba64478a9b0a3d496334cb6a3cd7 Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Fri, 19 Aug 2022 17:39:18 +0530 Subject: [PATCH 6/8] docs(PPDSC-2291): design feedback changes --- .../sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap b/site/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap index 41a0a26546..4ef2075b53 100644 --- a/site/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap +++ b/site/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap @@ -1640,7 +1640,7 @@ exports[`Sidebar renders correctly when closed 1`] = ` - Component overrides & defaults + Component defaults @@ -5558,7 +5558,7 @@ exports[`Sidebar renders correctly when closed 1`] = ` - Component overrides & defaults + Component defaults @@ -9334,7 +9334,7 @@ exports[`Sidebar renders correctly when open 1`] = ` - Component overrides & defaults + Component defaults @@ -13217,7 +13217,7 @@ exports[`Sidebar renders correctly when open 1`] = ` - Component overrides & defaults + Component defaults From 99ec2b78db33b9fa601694e6eebe133f702b5a98 Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Mon, 22 Aug 2022 09:33:12 +0530 Subject: [PATCH 7/8] docs(PPDSC-2291): design feedback hero image fixes --- .../hero-component-defaults-illustration.tsx | 147 ++++++++---------- 1 file changed, 62 insertions(+), 85 deletions(-) diff --git a/site/components/illustrations/components/hero-component-defaults-illustration.tsx b/site/components/illustrations/components/hero-component-defaults-illustration.tsx index 7cbf300df3..944f61757d 100644 --- a/site/components/illustrations/components/hero-component-defaults-illustration.tsx +++ b/site/components/illustrations/components/hero-component-defaults-illustration.tsx @@ -19,104 +19,51 @@ export const HeroComponentDefaultsIllustration: React.FC = () => { xmlns="http://www.w3.org/2000/svg" > - - - - - - - + - - + + @@ -126,35 +73,65 @@ export const HeroComponentDefaultsIllustration: React.FC = () => { id={mask1} mask-type="alpha" maskUnits="userSpaceOnUse" - x="725" - y="167" - width="256" - height="256" + x="726" + y="168" + width="257" + height="257" > + + + + + @@ -165,8 +142,8 @@ export const HeroComponentDefaultsIllustration: React.FC = () => { values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha" /> - - + + { From 4c6260cfb88de723ce31e827407d188accbad2b5 Mon Sep 17 00:00:00 2001 From: Srinivasan-Ramasamy Date: Mon, 22 Aug 2022 10:03:51 +0530 Subject: [PATCH 8/8] docs(PPDSC-2291): deleting unused file --- .../theme/theming/component-defaults-old.mdx | 42 ------------------- 1 file changed, 42 deletions(-) delete mode 100644 site/pages/theme/theming/component-defaults-old.mdx diff --git a/site/pages/theme/theming/component-defaults-old.mdx b/site/pages/theme/theming/component-defaults-old.mdx deleted file mode 100644 index dcffd544e5..0000000000 --- a/site/pages/theme/theming/component-defaults-old.mdx +++ /dev/null @@ -1,42 +0,0 @@ -import Layout from '../../../components/layout'; -import {Code, CodeFromFile} from '../../../components/code'; - -export default Layout; - -# Component Defaults - -Each component in NewsKit gets its default theme tokens from the theme itself. By not hardcoding tokens in the components, this means you can override the default tokens used by any component via the theme. For example, you could change the padding preset used by all Button components, or the typography preset used by all Byline components. Each component documents the structure of its component defaults on their respective documentation page. - -As part of the component defaults functionality, there is a consistent `overrides` prop on all components. This prop takes an object which mirrors the structure of the component defaults. You can use this to override individual tokens in that specific instance of the component. - -Part of the functionality of the defaults and overrides system allows you to override presets at specific breakpoints. For example you could set a different typography presets at different breakpoints, so you can make the text larger on bigger devices. This is done by passing an object - comprising of breakpoint keys and token values to the override. Such as: - - - {`typographyPreset: { - xs: 'editorialHeadline010', - md: 'editorialHeadline010', - lg: 'editorialHeadline010', -}`} - - -Properties which support this will be documented as using the generic `MQ` type, i.e. `MQ`. This means you can pass a single string token to be used at all times, or a combination at breakpoints like above. - -## Overriding at theme level - -Overriding at the theme level involves creating a theme with your changes under the overrides property, similar to how you would change other areas of the theme. Here is an example of overriding the component defaults for the medium size Button component, changing the default typography and style presets. Some components, like the button, will have variants in their component defaults such as size. - - - -You can override as many or as little component defaults as you wish. Each component documentation page details the component defaults it uses. - -## Overriding at component level - -You can also override at an individual component level, where the overrides will only apply to that specific instance of the component. The example below shows overriding the Button styles the same as above. - - - -Note that the variant (in this case, "medium") is not included in the overrides. Variants are not specified in the component overrides prop, only the theme. Some components which are built using multiple components may have a nested structure to their component defaults. - - - -The Byline for example, shown above, is a case of this nested approach. This allows you to specify the overrides for the nested components as well as the top level.