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..944f61757d --- /dev/null +++ b/site/components/illustrations/components/hero-component-defaults-illustration.tsx @@ -0,0 +1,168 @@ +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/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap b/site/components/sidebar/__tests__/__snapshots__/sidebar.test.tsx.snap index 83742eef74..c785a5a40f 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 diff --git a/site/pages/theme/theming/component-defaults.mdx b/site/pages/theme/theming/component-defaults.mdx deleted file mode 100644 index dcffd544e5..0000000000 --- a/site/pages/theme/theming/component-defaults.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. diff --git a/site/pages/theme/theming/component-defaults.tsx b/site/pages/theme/theming/component-defaults.tsx new file mode 100644 index 0000000000..736f9c4c1f --- /dev/null +++ b/site/pages/theme/theming/component-defaults.tsx @@ -0,0 +1,281 @@ +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'; +import {ComponentPageCell} from '../../../components/layout-cells'; +import { + ContentSection, + ContentPrimary, + ContentSecondary, + ContentTertiary, + ContentColSpan, +} 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. + + + } + 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', + }`} + + + + + +); + +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', },