From eec62984459940dcdfd860a06f980da8e9d85298 Mon Sep 17 00:00:00 2001 From: Geri Reid <39526800+GeriReid@users.noreply.github.com> Date: Mon, 7 Nov 2022 15:46:10 +0000 Subject: [PATCH] docs(PPDSC-2548): update content (#453) * docs(PPDSC-2548): update content * docs(PPDSC-2548): wip * docs(PPDSC-2548): update content * docs(PPDSC-2548): update content Co-authored-by: Luke Finch --- site/pages/theme/presets/style-presets.tsx | 146 +++---- .../theme/presets/transition-presets.tsx | 361 +++++++++--------- .../theme/presets/typography-presets.tsx | 115 +++--- 3 files changed, 302 insertions(+), 320 deletions(-) diff --git a/site/pages/theme/presets/style-presets.tsx b/site/pages/theme/presets/style-presets.tsx index d805b0f004..1fc8e02bcd 100644 --- a/site/pages/theme/presets/style-presets.tsx +++ b/site/pages/theme/presets/style-presets.tsx @@ -115,7 +115,7 @@ const CSS_PROPS = [ ), description: - 'The signaling of overflowed content that is not displayed to the user', + 'The signalling of overflowed content that isn’t displayed to the user', }, { token: 'textTransform', @@ -139,7 +139,7 @@ const CSS_PROPS = [ CSS ), - description: 'The white space inside an element and how it is handled', + description: 'The whitespace inside an element and how it’s handled', }, { token: 'wordbreak', @@ -214,7 +214,7 @@ const CSS_PROPS = [ acceptedValues: ( foundations shadows ), - description: 'The box shadow to an element', + description: 'The box shadow of an element', }, { token: 'backgroundColor', @@ -235,7 +235,7 @@ const CSS_PROPS = [ acceptedValues: ( foundations gradient ), - description: 'The transition between two or more specified colors', + description: 'The transition between two or more specified colours', }, { token: 'outlineColor', @@ -295,58 +295,58 @@ const STYLE_PRESET_STATES = [ example: getImage('theme/style-presets/base'), state: 'base', description: - 'The base style and behaviour (baseline CSS) of an element before it has been interacted with by a user', + 'The base style and behaviour (baseline CSS) of an element before the user has interacted with it', }, { example: getImage('theme/style-presets/hover'), state: 'hover', description: - 'The style and behaviour when a user’s cursor hovers over an interactive element. The cursor shows as a “pointer” and style of an element changes to visually communicate and provide feedback to a user that an element is interactive', + 'The style and behaviour when the user’s cursor hovers over an interactive element. The cursor shows as a “pointer” and the style of the element changes to visually communicate that it’s interactive', }, { example: getImage('theme/style-presets/focus'), state: 'focus', description: - 'Highlights an element to a user that has received focus, by using an input method such as a keyboard or voice', + 'Highlights an element that has received focus from the user via an input method such as keyboard or voice', }, { example: getImage('theme/style-presets/active'), state: 'active', - description: `When using a mouse, "activation" typically starts when a user presses down a primary mouse button. Sometimes referred to as ‘pressed’`, + description: `When using a mouse, "activation" typically starts when the user presses down a primary mouse button. Sometimes referred to as “pressed”`, }, { example: getImage('theme/style-presets/hover-active'), state: 'hover:active', description: - 'The style and behaviour when a user’s cursor hovers over an interactive element and a user presses down a primary mouse button', + 'The style and behaviour when the user’s cursor hovers over an interactive element and the user presses down a primary mouse button', }, { example: getImage('theme/style-presets/valid-hover-active'), state: 'valid:hover:active', description: - 'The style and behaviour when a user’s cursor hovers over an interactive element in a valid state, and a user presses down a primary mouse button', + 'The style and behaviour when the user’s cursor hovers over an interactive element in a valid state, and the user presses down a primary mouse button', }, { example: getImage('theme/style-presets/invalid-hover-active'), state: 'invalid:hover:active', description: - 'The style and behaviour when a user’s cursor hovers over an interactive element in an invalid state, and a user presses down a primary mouse button', + 'The style and behaviour when the user’s cursor hovers over an interactive element in an invalid state, and the user presses down a primary mouse button', }, { example: getImage('theme/style-presets/visited'), state: 'visited', description: - 'Visually represents text links a user has already visited, distinguishing them from links that have not been visited', + 'Visually represents text links the user has already visited, distinguishing them from links that haven’t been visited', }, { example: getImage('theme/style-presets/disabled'), state: 'disabled', - description: `Communicates that an element exists, but is not available to a user in that scenario. It is used to maintain layout consistency and communicate to a user that an element may become available if another condition has been met. When a user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, + description: `Communicates that an element exists, but isn’t available to the user in that scenario. Maintains layout consistency and communicates to the user that an element may become available if another condition is met. When the user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, }, { example: getImage('theme/style-presets/checked'), state: 'checked', - description: `The style of a component changes to visually communicate and provide feedback to a user that a component has been checked (e.g. a “checked” checkbox)`, + description: `The style of a component changes to visually communicate and provide feedback to the user that a component has been checked (e.g. a “checked” checkbox)`, }, { example: getImage('theme/style-presets/invalid'), @@ -358,159 +358,159 @@ const STYLE_PRESET_STATES = [ example: getImage('theme/style-presets/valid'), state: 'valid', description: - 'Components in an valid state change style and can display an valid icon (e.g. when the input information in a form validates successfully)', + 'Components in a valid state change style and can display a valid icon (e.g. when the input information in a form validates successfully)', }, { example: getImage('theme/style-presets/loading'), state: 'loading', - description: `When a component can’t be displayed because it is in a transitional "loading" state (e.g. images that haven't loaded yet)`, + description: `When a component can’t be displayed because it’s in a transitional "loading" state (e.g. images that haven't loaded yet)`, }, { example: getImage('theme/style-presets/selected'), state: 'selected', - description: `The style of a component changes to visually communicate and provide feedback to a user that a component has been selected (e.g. in a Tab menu, "selected" would be the selected Tab)`, + description: `The style of a component changes to visually communicate and provide feedback to the user that a component has been selected (e.g. in a tab menu, "selected" is the selected tab)`, }, { example: getImage('theme/style-presets/selected-hover'), state: 'selected:hover', description: - 'The style of a component changes to visually communicate and provide feedback to a user that a component has been selected, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component has been selected and is in a hover state', }, { example: getImage('theme/style-presets/selected-focus'), state: 'selected:focus', description: - 'The style of a component changes to visually communicate and provide feedback to a user that a component has been selected, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component has been selected and is in a focus state', }, { example: getImage('theme/style-presets/selected-disabled'), state: 'selected:disabled', - description: `Communicates that an element exists and selected, but is not available to the user in that scenario. It is used to maintain layout consistency and communicate to the user that an element may become available if another condition has been met. When the user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, + description: `Communicates that an element exists and is selected, but isn’t available to the user in that scenario. Maintains layout consistency and communicates to the user that an element may become available if another condition is met. When the user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, }, { example: getImage('theme/style-presets/selected-valid'), state: 'selected:valid', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, and in a selected state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid and in a selected state', }, { example: getImage('theme/style-presets/selected-valid-focus'), state: 'selected:valid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, selected, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, selected and in a focus state', }, { example: getImage('theme/style-presets/selected-invalid'), state: 'selected:invalid', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, and in a selected state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid and in a selected state', }, { example: getImage('theme/style-presets/selected-invalid-focus'), state: 'selected:invalid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, selected, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, selected and in a focus state', }, { example: getImage('theme/style-presets/selected-valid-hover'), state: 'selected:valid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, selected, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, selected and in a hover state', }, { example: getImage('theme/style-presets/selected-invalid-hover'), state: 'selected:invalid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, selected, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, selected and in a hover state', }, { example: getImage('theme/style-presets/checked-hover'), state: 'checked:hover', description: - 'The style of a component changes to visually communicate and provide feedback to a user that a component has been checked, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component has been checked and is in a hover state', }, { example: getImage('theme/style-presets/checked-focus'), state: 'checked:focus', description: - 'The style of a component changes to visually communicate and provide feedback to a user that a component has been checked, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component has been checked and is in a focus state', }, { example: getImage('theme/style-presets/checked-disabled'), state: 'checked:disabled', - description: `Communicates that an element exists and checked, but is not available to the user in that scenario. It is used to maintain layout consistency and communicate to the user that an element may become available if another condition has been met. When the user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, + description: `Communicates that an element exists and is checked, but is not available to the user in that scenario. Maintains layout consistency and communicates to the user that an element may become available if another condition is met. When the user hovers over an element in a disabled state, the cursor shows as “not-allowed”`, }, { example: getImage('theme/style-presets/checked-valid'), state: 'checked:valid', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, and in a checked state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid and in a checked state', }, { example: getImage('theme/style-presets/checked-valid-hover'), state: 'checked:valid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, checked, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, checked and in a hover state', }, { example: getImage('theme/style-presets/checked-valid-focus'), state: 'checked:valid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, checked, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, checked and in a focus state', }, { example: getImage('theme/style-presets/checked-invalid'), state: 'checked:invalid', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, and in a checked state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid and in a checked state', }, { example: getImage('theme/style-presets/checked-invalid-hover'), state: 'checked:invalid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, checked, and in a hover state', + 'The style of a component changes to visually communicate anThe style of a component changes to visually communicate and provide feedback to the user that a component is invalid, checked and in a hover state', }, { example: getImage('theme/style-presets/checked-invalid-focus'), state: 'checked:invalid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, checked, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, checked and in a focus state', }, { example: getImage('theme/style-presets/valid-hover'), state: 'valid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid and in a hover state', }, { example: getImage('theme/style-presets/valid-focus'), state: 'valid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is valid and in a focus state', }, { example: getImage('theme/style-presets/invalid-hover'), state: 'invalid:hover', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, and in a hover state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid and in a hover state', }, { example: getImage('theme/style-presets/invalid-focus'), state: 'invalid:focus', description: - 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid, and in a focus state', + 'The style of a component changes to visually communicate and provide feedback to the user that a component is invalid and in a focus state', }, { example: getImage('theme/style-presets/visited-hover'), state: 'visited:hover', description: - 'Visually represents text links a user has already visited, and in a hover state', + 'Visually represents text links the user has already visited, in a hover state', }, { example: getImage('theme/style-presets/visited-focus'), state: 'visited:focus', description: - 'Visually represents text links a user has already visited, and in a focus state', + 'Visually represents text links the user has already visited, in a focus state', }, { example: getImage('theme/style-presets/focus'), @@ -591,14 +591,14 @@ const STYLE_PRESET_STATES = [ const StylePresets = (layoutProps: LayoutProps) => ( ( headline="Overview" description={ <> - Style Presets define properties such as colour, border-radius and - text-decoration, across multiple states. For example, one style - preset can contain the style for all states of a button. + Style presets define properties such as colour, border radius and + text decoration across multiple states. For example, a style + preset might contain the styles for all of a button’s states.

- In combination with{' '} + Together with{' '} - Typography Presets + typography presets - , Sizing, and{' '} - Spacing, Style - Presets provide the visual attributes of a component. + , sizing and{' '} + spacing, style + presets provide a component’s visual attributes. } showSeparator @@ -637,8 +637,8 @@ const StylePresets = (layoutProps: LayoutProps) => ( ( /> } > - Careful consideration should be given when choosing CSS values due - to the impact on the theming system. + Choose CSS values carefully because of the impact on the theming + system. @@ -666,8 +666,8 @@ const StylePresets = (layoutProps: LayoutProps) => (
( - Style Presets can be applied to NewsKit components in a number of - ways,{' '} + You can apply style presets to components in several ways.{' '} - learn more about using a theme in code + Learn more about using a theme in code + {' '} + to better understand the trade-offs of each approach. +
+
+ For more advanced use cases, access style presets from the theme + by calling{' '} + + getStylePreset {' '} - to better understand the trade-offs associated with each approach. - For more advanced use cases, Style Presets can be accessed from - the theme by calling{' '} - getStylePreset{' '} or Emotion’s{' '} useTheme hook. @@ -703,9 +706,8 @@ const StylePresets = (layoutProps: LayoutProps) => ( headline="Code example" description={ <> - This example demonstrates declaring style presets for the Button - component. It can be passed to the{' '} - createTheme function: + You can declare style presets for the button component by passing + it to the createTheme function: } showSeparator @@ -743,14 +745,14 @@ const StylePresets = (layoutProps: LayoutProps) => ( - Custom Style Presets can be added to the theme. See the{' '} + See the{' '} - Creating Themes + creating themes guide {' '} - guide for more details. + for more details. } showSeparator diff --git a/site/pages/theme/presets/transition-presets.tsx b/site/pages/theme/presets/transition-presets.tsx index 94c94690fb..6ca488ce9c 100644 --- a/site/pages/theme/presets/transition-presets.tsx +++ b/site/pages/theme/presets/transition-presets.tsx @@ -45,7 +45,7 @@ const PROPERTIES = [ ), example: motionDuration000, description: - 'Specifies how many milliseconds delay for the transition effect to start', + 'Specifies how many milliseconds before the transition effect starts', }, { tokenName: 'transitionDuration', @@ -53,8 +53,7 @@ const PROPERTIES = [ motionDuration ), example: motionDuration020, - description: - 'Specifies how many milliseconds a transition effect takes to complete', + description: 'Specifies how many milliseconds a transition effect lasts', }, { tokenName: 'transitionTimingFunction', @@ -84,9 +83,9 @@ const PRESETS = [ ), token: 'backgroundColorChange', description: - 'Transition background colour from the initial state to the final state.', + 'Transition background colour from the initial state to the final state', implementation: - 'Can be applied to components when interacting eg. on hover, or triggered on page load.', + 'Apply to components when interacting (e.g. on hover) or trigger on page load', }, { example: getImage( @@ -94,9 +93,9 @@ const PRESETS = [ ), token: 'borderColorChange', description: - 'Transition border colour from the initial state to the final state.', + 'Transition border colour from the initial state to the final state', implementation: - 'Can be applied to components when interacting eg. on hover, or triggered on page load.', + 'Apply to components when interacting (e.g. on hover) or trigger on page load', }, { example: getImage( @@ -104,9 +103,9 @@ const PRESETS = [ ), token: 'fontColorChange', description: - 'Transition font colour from the initial state to the final state.', + 'Transition font colour from the initial state to the final state', implementation: - 'Can be applied to components when interacting eg. on hover, or triggered on page load.', + 'Apply to components when interacting (e.g. on hover) or trigger on page load', }, { example: getImage( @@ -114,11 +113,11 @@ const PRESETS = [ ), token: 'iconColorChange', description: - 'Transition icon colour from the initial state to the final state.', + 'Transition icon colour from the initial state to the final state', implementation: ( <> - Can be applied to icons via the svg fill property{' '} - getCssSvgFillObject. + Apply to icons via the svg fill property{' '} + getCssSvgFillObject ), }, @@ -127,9 +126,9 @@ const PRESETS = [ 'theme/transition-presets/predefined-transition-presets/fade', ), token: 'fade', - description: 'Fade from transparent to opaque.', + description: 'Fade from transparent to opaque', implementation: - 'Can be applied to components when interacting eg. on hover, triggered on page load, or applied to components when entering (mount), or exiting (unmount).', + 'Apply to components when interacting (e.g. on hover), trigger on page load or apply to components when entering (mount) or exiting (unmount)', }, { example: getImage( @@ -139,32 +138,32 @@ const PRESETS = [ description: ( <> Slide in from the left to right, and back from right to left (back to - its original starting position). + original starting position)

- When applied to a element or component like the Drawer,{' '} - slideLeft causes the Drawer panel to slide in + When applied to an element or component like the drawer,{' '} + slideLeft causes the drawer panel to slide in from off the left edge of the screen to the right, and back again off - the left edge of the screen. + the left edge of the screen ), implementation: ( <> The transition base state keeps the element positioned to the left (translateX(-100%)) until the transition is - activated. + activated

The enterActive state changes the transform - value to translateX(0) and moves the element to the right. + value to translateX(0) and moves the element to the right

The exitActive state brings it back to its - original starting position on the left (translateX(-100%)). + original starting position on the left (translateX(-100%))

- Can be applied to components and triggered on page load, or when - entering (mount), or exiting (unmount). + Apply to components and trigger on page load, or when entering (mount) + or exiting (unmount) ), }, @@ -176,32 +175,32 @@ const PRESETS = [ description: ( <> Slide in from the right to left, and back from left to right (back to - its original starting position). + original starting position)

- When applied to a element or component like the Drawer,{' '} - slideRight causes the Drawer panel to slide in + When applied to an element or component like the drawer,{' '} + slideRight causes the drawer panel to slide in from off the right edge of the screen to the left, and back again off - the right edge of the screen. + the right edge of the screen ), implementation: ( <> The transition base state keeps the element positioned to the right (translateX(100%)) until the transition is - activated. + activated

The enterActive state changes the transform - value to translateX(0) and moves the element to the left. + value to translateX(0) and moves the element to the left

The exitActive state brings it back to its - original starting position on the right (translateX(100%)). + original starting position on the right (translateX(100%))

- Can be applied to components and triggered on page load, or when - entering (mount), or exiting (unmount). + Apply to components and trigger on page load, or when entering (mount) + or exiting (unmount) ), }, @@ -213,32 +212,32 @@ const PRESETS = [ description: ( <> Slide in from the top to bottom, and back from bottom to top (back to - its original starting position). + original starting position)

- When applied to a element or component like the Drawer,{' '} - slideTop causes the Drawer panel to slide in + When applied to an element or component like the drawer,{' '} + slideTop causes the drawer panel to slide in from off the top edge of the screen to the bottom, and back again off - the top edge of the screen. + the top edge of the screen ), implementation: ( <> The transition base state keeps the element positioned to the top (translateY(-100%)) until the transition is - activated. + activated

The enterActive state changes the transform - value to translateY(0) and moves the element to the bottom. + value to translateY(0) and moves the element to the bottom

The exitActive state brings it back to its - original starting position on the top (translateY(-100%)). + original starting position on the top (translateY(-100%))

- Can be applied to components and triggered on page load, or when - entering (mount), or exiting (unmount). + Apply to components and trigger on page load, or when entering (mount), + or exiting (unmount) ), }, @@ -250,13 +249,13 @@ const PRESETS = [ description: ( <> Slide in from the bottom to top, and back from top to bottom (back to - its original starting position). + original starting position)

- When applied to a element or component like the Drawer,{' '} - slideBottom causes the Drawer panel to slide in + When applied to an element or component like the drawer,{' '} + slideBottom causes the drawer panel to slide in from off the bottom edge of the screen to the top, and back again off - the bottom edge of the screen. + the bottom edge of the screen

@@ -265,19 +264,19 @@ const PRESETS = [ <> The transition base state keeps the element positioned to the bottom (translateY(100%)) until the transition is - activated. + activated

The enterActive state changes the transform - value to translateY(0) and moves the element to the top. + value to translateY(0) and moves the element to the top

The exitActive state brings it back to its - original starting position on the bottom (translateY(100%)). + original starting position on the bottom (translateY(100%))

- Can be applied to components and triggered on page load, or when - entering (mount), or exiting (unmount). + Apply to components and trigger on page load, or when entering (mount) + or exiting (unmount) ), }, @@ -287,9 +286,9 @@ const PRESETS = [ ), token: 'moveUp', description: - 'Moves upwards (translate) from the start point of the child element.', + 'Move upwards (translate) from the start point of the child element', implementation: - 'Can be applied to components and triggered on page load, or when entering (mount), or exiting (unmount).', + 'Apply to components and trigger on page load, or when entering (mount) or exiting (unmount)', }, { example: getImage( @@ -297,32 +296,31 @@ const PRESETS = [ ), token: 'grow', description: - 'Expands outwards (scales) from the center of the child element.', + 'Expand outwards (scales) from the centre of the child element', implementation: - 'Can be applied to components and triggered on page load, or when entering (mount), or exiting (unmount).', + 'Apply to components and trigger on page load, or when entering (mount) or exiting (unmount)', }, { example: getImage( 'theme/transition-presets/predefined-transition-presets/shiftabsolute', ), token: 'shiftAbsolute', - description: 'Transition inset from the initial state to the final state.', + description: 'Transition inset from the initial state to the final state', implementation: - 'Can be applied to components to achieve movement when interacting eg. applied to the Switch thumb on click/tap.', + 'Apply to components to add movement upon user interaction (e.g. the switch thumb on click/tap)', }, { example: getImage( 'theme/transition-presets/predefined-transition-presets/opacitychange', ), token: 'opacityChange', - description: - 'Transition opacity from the initial state to the final state.', + description: 'Transition opacity from the initial state to the final state', implementation: ( <> - Can be applied to components to achieve an opacity change eg. applied to - the feedback element that appears on hover for components like the{' '} - Checkbox, or{' '} - Radio Button. + Apply to components to change their opacity upon user interaction (e.g. + the feedback element that appears on hover for components like{' '} + checkbox, or{' '} + radio button ), }, @@ -331,18 +329,18 @@ const PRESETS = [ 'theme/transition-presets/predefined-transition-presets/widthchange', ), token: 'widthChange', - description: 'Transition width from the initial state to the final state.', + description: 'Transition width from the initial state to the final state', implementation: - 'Can be applied to components to achieve a width change when interacting eg. applied to the expandable horizontal volume control audio player subcomponent on hover or focus.', + 'Can be applied to components to achieve a width change when interacting eg. applied to the expandable horizontal volume control audio player subcomponent on hover or focus', }, { example: getImage( 'theme/transition-presets/predefined-transition-presets/maxheightchange', ), token: 'maxHeightChange', - description: 'Expands height (max-height) of the child element.', + description: 'Expands height (max-height) of the child element', implementation: - 'Can be applied to components when interacting eg. on click.', + 'Can be applied to components when interacting eg. on click', }, ]; @@ -354,7 +352,7 @@ const USER_INTERACTION = [ name: 'base', type: 'TransitionPresetStyles', description: - 'Defines the CSS property, duration, delay and transition timing for the transition of the element.', + 'Defines the CSS property, duration, delay and timing for the transition of the element', }, ]; @@ -366,7 +364,7 @@ const ENTER_EXIT_COMPONENT = [ name: 'base', type: 'TransitionPresetStyles', description: - 'Defines the initial style prior to starting the enter transition if a component is rendered (in the DOM) but is visibly hidden off the screen, until an action is triggered.', + 'Defines the initial style before the enter transition starts, if a component is rendered (in the DOM) but is visibly hidden off-screen until an action is triggered', }, { example: getImage( @@ -374,8 +372,7 @@ const ENTER_EXIT_COMPONENT = [ ), name: 'enter', type: 'TransitionPresetStyles', - description: - 'Defines the initial style prior to starting the enter transition.', + description: 'Defines the initial style before the enter transition starts', }, { example: getImage( @@ -385,11 +382,11 @@ const ENTER_EXIT_COMPONENT = [ type: 'TransitionPresetStyles', description: ( <> - Defines the enter transition including CSS property that is - transitioned, the duration, the delay and the timing function. + Defines the enter transition, including the CSS property that’s + transitioned, duration, delay and timing function

- Defines the final values of the enter transition. + Defines the final values of the enter transition ), }, @@ -400,7 +397,7 @@ const ENTER_EXIT_COMPONENT = [ name: 'enterDone', type: 'TransitionPresetStyles', description: - 'Defines the final style after the enter transition has completed.', + 'Defines the final style after the enter transition has completed', }, { example: getImage( @@ -408,7 +405,7 @@ const ENTER_EXIT_COMPONENT = [ ), name: 'exit', type: 'TransitionPresetStyles', - description: 'Defines the style prior to starting the exit transition.', + description: 'Defines the style before the exit transition starts', }, { example: getImage( @@ -418,11 +415,11 @@ const ENTER_EXIT_COMPONENT = [ type: 'TransitionPresetStyles', description: ( <> - Defines the exit transition including CSS property that is transitioned, - the duration, the delay and the timing function. + Defines the exit transition, including the CSS property that’s + transitioned, duration, delay and timing function

- Defines the final values of the exit transition. + Defines the final values of the exit transition ), }, @@ -433,7 +430,7 @@ const ENTER_EXIT_COMPONENT = [ name: 'exitDone', type: 'TransitionPresetStyles', description: - 'Defines the final style after the exit transition has completed. This is the state that persists after the transition.', + 'Defines the final style after the exit transition has completed. This is the state that persists after the transition', }, ]; @@ -461,14 +458,14 @@ const infoIcon = ( const TransitionPresets = (layoutProps: LayoutProps) => ( ( id="overview" toc="Overview" headline="Overview" - description="Transition Presets define attributes such as the visual style, size, or position of an element across multiple states over time. Transition Presets can be reused through the system on multiple elements." + description="Transition presets define attributes such as the visual style, size or position of an element across multiple states over time. You can reuse transition presets on multiple elements throughout the system." showSeparator > @@ -492,8 +489,8 @@ const TransitionPresets = (layoutProps: LayoutProps) => (
(
( role="region" aria-label="transition presets" > - You can also add your own Transition Presets. See the{' '} + You can add your own transition presets. See the{' '} - Creating a theme + creating a theme {' '} guide for more details. @@ -540,25 +537,25 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( - States are used to define the{' '} + States define the{' '} CSS property - , duration, delay and transition timing, and the initial and final - styling of an element. + , duration, delay and transition timing, as well as the initial + and final styling of an element. } > @@ -566,11 +563,10 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( headline="1. States for transitions triggered upon user interaction" description={ <> - Transition presents applied to elements upon user interaction e.g. - changing the background colour of a{' '} - Button on hover. The - following states are used for transitions triggered upon user - interaction: + You can apply these transition presets to elements upon user + interaction (e.g. changing the background colour of a{' '} + button on hover). The + following states are used: } > @@ -581,14 +577,14 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( - Transition presets applied to mount and unmount components e.g.{' '} - Modal on-screen appearing - and disappearing. The following states are used for transitions - triggered upon enter (mount) and exit (unmount) of a component. - The states represent class names applied to an element: + You can apply these transition presets upon entry (mount) and exit + (unmount) of a component (e.g. a{' '} + modal appearing and + disappearing). The following states are used and represent class + names applied to an element: } showSeparator @@ -603,17 +599,20 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( - The{' '} + See the{' '} - Component Defaults + component defaults page {' '} - page details the different ways in which you can override and - apply Transition Presets to NewsKit components. For more advanced - use cases, these values can be accessed from the theme by calling{' '} + for the different ways to override and apply transition presets to + NewsKit components. +
+
+ For more advanced use cases, access these values from the theme by + calling{' '} getTransitionPreset {' '} @@ -622,18 +621,17 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( getTransitionPresetFromTheme {' '} - (a function used to retrieve token values from theme or component - props). + (used to retrieve token values from theme or component props). } /> - 1. This example demonstrates a Transition Preset{' '} - backgroundColorChange. + 1. Here’s the backgroundColorChange{' '} + transition preset. } > @@ -652,8 +650,8 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( description={ <> 2. When combined with the following{' '} - stylePreset the background colour will - transition between states. + stylePreset, the background colour + transitions between states. } > @@ -672,9 +670,8 @@ const TransitionPresets = (layoutProps: LayoutProps) => ( - 3. This example demonstrates applying{' '} - backgroundColorChange Transition preset - to a simple box element. + 3. backgroundColorChange applied to a + simple box element. } > @@ -693,12 +690,12 @@ $\{getTransitionPresetFromTheme('backgroundColorChange')} - 1. This example demonstrates two Transition Presets,{' '} + 1. Here are two transition presets:{' '} backgroundColorChange and{' '} - borderColorChange + borderColorChange. } > @@ -725,8 +722,8 @@ transitionPresets.borderColorChange = { description={ <> 2. When combined with the following{' '} - stylePreset the background and border - colours will transition between states with different durations. + stylePreset, the background and border + colours transition between states with different durations. } > @@ -749,10 +746,9 @@ transitionPresets.borderColorChange = { - 3. This example demonstrates applying{' '} - backgroundColorChange and{' '} - borderColorChange Transition preset to a - simple Box component. + 3. backgroundColorChange and{' '} + borderColorChange applied to a simple box + component. } > @@ -775,23 +771,24 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} icon={infoIcon} role="region" aria-label="single instance" - title="Note" + title="Apply to all instances" > - These example only applies to a single instance. Use{' '} + These examples only apply to a single instance of a component. To + apply to all instances, use{' '} - Component Defaults - {' '} - if you want to apply to all instances of a component. + component defaults + + . - 1. This example demonstrates a Transition Preset,{' '} - slideLeft. This Transition Preset is used - to slide an element in from the left edge of the screen. + 1. Here’s the slideLeft transition + preset, used to slide an element in from the left edge of the + screen. } > @@ -830,9 +827,7 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - 2. Applying the transition preset to the Drawer in the defaults. - + <>2. Apply the transition preset to the drawer in the defaults. } > @@ -863,17 +858,16 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - The example below demonstrates overriding a transition preset - applied in the defaults of the{' '} - Drawer component. + Here’s how to override a transition preset applied in the defaults + of the drawer component: } > @@ -896,17 +890,16 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - The example below demonstrates extending two predefined Transition - presets - fade and{' '} - moveUp applied to a Modal component. The - Duration value and Timing function of both Transition Presets are - overridden and delay is added to the - fade Transition Preset when the component + Here’s how to extend two predefined transition presets -{' '} + fade and moveUp{' '} + applied to a modal component. The duration and timing functions of + both presets are overridden and delay is added to the{' '} + fade transition preset when the component appears on the screen.

- For both Transition Presets, the Duration and Timing functions are - updated from the enter to the exit state of the transition. + For both transition presets, the duration and timing functions are + updated from the enter to the exit state of the transition: } showSeparator @@ -956,13 +949,13 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - Custom Transition Presets can be added to the theme. See the{' '} + See the{' '} - Creating a theme + creating a theme {' '} guide for more details. @@ -973,8 +966,8 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - For additional guidance on how to communicate a design to the - product team for engineers to build, refer to the{' '} + For help communicating designs to engineers, see the{' '} - NewsKit Handoff guidance. + handoff guidance. } @@ -1009,28 +1001,26 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} - Considering users that may have a{' '} + Users who experience{' '} - sensitivity to motion + motion sensitivity {' '} - (perceived movement on the screen), is core to the NewsKit motion - system. By following the guidelines below, we ensure that any - users who experience sensitivity to motion have the option to view - a more basic experience that reduces motion where possible. + have the option of a more basic experience that reduces motion + where possible. } /> The{' '} @@ -1042,21 +1032,22 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} {' '} CSS media feature detects if the user has requested that their operating system or browser minimises the amount of non-essential - motion displayed to the user. To ensure experiences are inclusive - it is recommended to implement the{' '} - prefers-reduced-motion feature to - elements that have motion. By default, we support this feature for - components in the NewsKit Design System that have motion applied - to them eg. the Drawer, &{' '} - Modal components. + motion displayed. +
+
+ We also recommend using the{' '} + prefers-reduced-motion feature on + elements with motion. By default, we support this feature for + components that have motion applied (e.g.{' '} + drawer, and{' '} + modal).

- To see which browsers support this feature, please refer to this - link + Check which browsers support reduced motion . @@ -1065,7 +1056,7 @@ $\{getTransitionPresetFromTheme(['backgroundColorChange', 'borderColorChange'])} diff --git a/site/pages/theme/presets/typography-presets.tsx b/site/pages/theme/presets/typography-presets.tsx index 933e282f50..3d0f738819 100644 --- a/site/pages/theme/presets/typography-presets.tsx +++ b/site/pages/theme/presets/typography-presets.tsx @@ -109,14 +109,14 @@ const typographyPresetsTable = [ columnHeader: COLUMN_HEADER, rows: editorialRows, description: - 'These styles are used in more expressive scenarios where they may be more aligned to a brand style, these are used in components like the title bar and card.', + 'Use these styles in more expressive scenarios where you want to align more closely with your brand style, such as title bars and cards.', }, { header: 'Utility', columnHeader: COLUMN_HEADER, rows: utilityRows, description: - 'These styles are used in more functional scenarios where a clear message needs to be communicated, these are used in components like the buttons, tabs, inline messages, and banners.', + 'Use these styles in more functional scenarios where a clear message needs to be communicated (e.g. buttons, tabs, inline messages and banners).', }, ], }, @@ -147,12 +147,13 @@ const TypographyPresets = (layoutProps: LayoutProps) => ( headline="Overview" description={ <> - Typography Presets define properties such as font-family, + Typography presets define properties such as font-family, font-weight and line-height, in one design token. In combination with{' '} - Style Presets, - Sizing, and Spacing{' '} - they provide the visual attributes of a component. + style presets, + sizing, and{' '} + spacing they + provide the visual attributes of a component. } showSeparator @@ -163,33 +164,25 @@ const TypographyPresets = (layoutProps: LayoutProps) => ( - Typography Presets define properties such as font-family, - font-weight and line-height, in one design token. In combination - with{' '} - Style Presets, - Sizing, and Spacing{' '} - they provide the visual attributes of a component. - - } + headline="Default typography presets" /> - Typography Presets can be applied to NewsKit components in a - number of ways, learn more about{' '} + You can apply typography presets to components in several ways. + Learn more about{' '} using a theme to better understand the trade-offs associated with each approach. - For more advanced use cases, Style Presets can be accessed from - the theme by calling{' '} +
+
+ For more advanced use cases, access style presets from the theme + by calling{' '} getTypographyPreset {' '} @@ -200,32 +193,32 @@ const TypographyPresets = (layoutProps: LayoutProps) => ( /> - Custom Typography Presets can be added to the theme. See the{' '} + You can add custom typography presets to the theme. See the{' '} - Creating a theme + creating a theme {' '} - guide for more details. + guide for more. } childrenColSpan={ContentColSpan.TEXT} > - Thoroughly consider adding additional Typography Presets due to the + Thoroughly consider adding additional typography presets due to the impact on the theming feature when using multiple themes. - If additional CSS attributes are required on an existing - Typography Preset, for ad hoc usage, pass a{' '} - Text Block to the - styled function. + If you need additional CSS attributes on an existing typography + preset for ad hoc usage, pass a{' '} + text block to the + styled function: } showSeparator @@ -247,11 +240,10 @@ font-style:italic; id="text-crop" toc="Text-crop" headline="Text-crop" - description="To keep consistent and predictable space from design to code, we use a - text-cropping utility that removes additional space (leading) around a - text block. This allows us to maintain our 4px baseline and keep - designs pixel-perfect. Refer to the Text Crop documentation for more - detailed information." + description="To keep consistent and predictable spacing from design to code, + we use a text cropping utility to remove additional space (leading) around + text blocks. This lets you maintain a 4px baseline and keeps designs pixel + perfect. See the text crop documentation for more." showSeparator /> @@ -259,11 +251,10 @@ font-style:italic; - While there is no official minimum font size for the web, it - is generally agreed upon that 16px for body text is a good + While there’s no official minimum font size for the web, + it’s generally agreed that 16px for body text is a good starting point.

- Of course, some text will be smaller for elements such as - labels and headers will be larger. + Of course, text will be smaller for elements such as labels + and larger for headers.

- To ensure that text is legible, NewsKit recommended that the - smallest font-size applied to text is no less 12px for web. + We recommend not going smaller than 12px. ), media: getIllustrationComponent('theme/typography/font-size'), @@ -298,17 +288,17 @@ font-style:italic; title: 'Line Height', description: ( <> - Providing an adequate amount of space between lines is - critical to the legibility of text. As per W3C accessibility - guidelines line spacing should be at least space-and-a-half - within paragraphs, and paragraph spacing is at least 1.5 - times larger than the line spacing. + Adequate space between lines is critical to text legibility. + W3C accessibility guidelines say line spacing should be at + least space-and-a-half within paragraphs, and paragraph + spacing should be at least 1.5 times larger than line + spacing.

- Using relative line-heights, NewsKit ensures consistent - spacing of all headings and body-text sizes. Heading and - Headline styles are set to a default of 1.125-times the font - size and body text set at 1.5-times the font size. + NewsKit uses relative line heights to ensure consistent + spacing for all headings and body text sizes. Heading and + headline styles are set to a default of 1.125x the font size + and body text set at 1.5x the font size. ), media: getIllustrationComponent('theme/typography/line-height'), @@ -317,16 +307,15 @@ font-style:italic; title: 'Line length', description: ( <> - Line-length, also known as a measure, is the number of - characters contained in a line of text. Line-length should - fall between 50 and 80 characters wide, including spaces, to - ensure readability. + Line length (also known as a measure) is the number of + characters in a line of text. For readability, keep between + 50 and 80 characters, including spaces.

Lines narrower than 50 characters require the eye to jump to the next line too frequently, breaking the reader’s rhythm. Lines wider than 80 characters make it difficult to continue - to the correct line in a large body of the text. + to the correct line in a large body of text. ), media: getIllustrationComponent('theme/typography/line-length'),