diff --git a/packages/paste-website/src/pages/customization/creating-a-custom-theme.mdx b/packages/paste-website/src/pages/customization/creating-a-custom-theme.mdx index f456021d62..cd8783de3b 100644 --- a/packages/paste-website/src/pages/customization/creating-a-custom-theme.mdx +++ b/packages/paste-website/src/pages/customization/creating-a-custom-theme.mdx @@ -40,7 +40,7 @@ export const getStaticProps = async () => { -A custom theme can be created either manually or using the [Paste Theme Designer](https://remix.twilio.design). A [Paste Theme](/theme) is categorized into groups of [Design Tokens](/tokens). The value of any Design Token from any Group can be changed when supplied to the Customization Provider via the theme object. The following token groups are available for customization: +A custom theme can be created either manually or using the [Paste Theme Designer](https://remix.twilio.design). A [Paste Theme](/theme) is categorized into groups of [design tokens](/tokens). The value of any design token from any group can be changed when supplied to the Customization Provider via the theme object. The following token groups are available for customization: @@ -87,7 +87,7 @@ If you’re looking for a visual approach to creating a custom theme, then t The theme designer comes with a UI so you can visually see what tokens are used in various components. For ease of use, each set of tokens is separated into categories. Once a category is selected, you can change individual token values and immediately see what component(s) will be affected by that change. Once all token changes have been made, you can then export your custom theme. -Once exported from the Theme Designer, you can store that JSON object in you application and import in where you initialize the Customization Provider to provide your application with an entire custom theme. +Once exported from the theme designer, you can store that JSON object in you application and import in where you initialize the Customization Provider to provide your application with an entire custom theme. ```jsx import {CustomizationProvider} from '@twilio-paste/core/customization'; @@ -118,9 +118,9 @@ The theme designer can also be used to import a custom theme if you wish to make ### Creating a branded theme -Something simple, yet effective that you might want to do is apply branding to your custom application. With Paste, a quick way to do that is to change the Primary colors within in the theme to be a tint of your primary brand color. +Something simple, yet effective that you might want to do is apply branding to your custom application. With Paste, a quick way to do that is to change the primary colors within in the theme to be a tint of your primary brand color. -As an example you might provide the Customization Provider a theme object that only sets values for the follow Design Tokens, based on your own companies branding: +As an example you might provide the Customization Provider a theme object that only sets values for the follow design tokens, based on your own company's branding: ```json { @@ -171,9 +171,9 @@ This will apply your companies brand color as the primary accent to all Paste co > -### Customizating typography +### Customizing typography -Another small customization might involve changing the typography that is supplied with Paste. Maybe your companies brand guidelines stipulate that you should use a certain font family? By changing the set of typography tokens on the theme, you can make ajustments to the font family and sizing ramps used in Paste to suit your companies needs. +Another small customization might involve changing the typography that is supplied with Paste. Maybe your company's brand guidelines stipulate that you should use a certain font family. By changing the set of typography tokens on the theme, you can make adjustments to the font family and sizing ramps used in Paste to suit your company's needs. To achieve the result displayed below, we have provided Paste with the following partial theme object. diff --git a/packages/paste-website/src/pages/customization/customization-provider.mdx b/packages/paste-website/src/pages/customization/customization-provider.mdx index 57e00c7314..a70b355acd 100644 --- a/packages/paste-website/src/pages/customization/customization-provider.mdx +++ b/packages/paste-website/src/pages/customization/customization-provider.mdx @@ -120,7 +120,7 @@ const MyApp = () => ( You can set a collection of Component Elements that you want to customize at the Customization Provider level. A Component Element is a DOM node within a component that you can target by name and provide custom CSS for. There maybe one or more exposed Component Elements for any given component within Paste. Component Elements can also be created for your own custom components for your customers to customize. -To read about how to customize components, head to the [Customizating Components](/customization/customizing-component-elements) page. +To read about how to customize components, head to the [Customizing Components](/customization/customizing-component-elements) page. ``` import {CustomizationProvider} from '@twilio-paste/core/customization'; diff --git a/packages/paste-website/src/pages/inclusive-design/index.mdx b/packages/paste-website/src/pages/inclusive-design/index.mdx index acd44837f8..c5f5585312 100644 --- a/packages/paste-website/src/pages/inclusive-design/index.mdx +++ b/packages/paste-website/src/pages/inclusive-design/index.mdx @@ -12,6 +12,7 @@ import {Card} from '@twilio-paste/card'; import {Stack} from '@twilio-paste/stack'; import {Alert} from '@twilio-paste/alert'; import {Anchor} from '@twilio-paste/anchor'; +import {Box} from '@twilio-paste/box'; import {Disclosure, DisclosureHeading, DisclosureContent} from '@twilio-paste/disclosure'; import Link from 'next/link'; import DefaultLayout from '../../layouts/DefaultLayout'; @@ -65,161 +66,165 @@ We recommend using this guide in the following ways: Baseline tips that are useful for all builders of web based experiences. - - - - Alternative text for media content - - - - Provide captions and transcripts for video content - Provide descriptive captions for figures - Provide transcripts for audio content - - Provide alternative text for images that convey information{' '} - - (Learn more about this) - - - - Ensure PDF content is accessible (include tags){' '} - - (Learn more about this) - - - - Avoid images of text, since this text that cannot be translated, selected, or understood by assistive - technology - - Provide alternatives and/or descriptions for complex visualizations - - - - - - Other considerations - - - - - Remove potentially insensitive or uninclusive language, and use "singular they" pronouns in UIs. Consider - using a service like alexjs to catch any issues. - - - Make sure controls do not elicit unexpected or jarring behavior (For example, do not change behavior or - context unexpectedly when a user changes focus - or adjusts a control - - - Make sure text and background colors contrast sufficiently (Read more about why this matters) - - - - - + + + + + Alternative text for media content + + + + Provide captions and transcripts for video content + Provide descriptive captions for figures + Provide transcripts for audio content + + Provide alternative text for images that convey information{' '} + + (Learn more about this) + + + + Ensure PDF content is accessible (include tags){' '} + + (Learn more about this) + + + + Avoid images of text, since this text that cannot be translated, selected, or understood by assistive + technology + + Provide alternatives and/or descriptions for complex visualizations + + + + + + Other considerations + + + + + Remove potentially insensitive or uninclusive language, and use "singular they" pronouns in UIs. Consider + using a service like alexjs to catch any issues. + + + Make sure controls do not elicit unexpected or jarring behavior (For example, do not change behavior or + context unexpectedly when a user changes focus + or adjusts a control + + + Make sure text and background colors contrast sufficiently (Read more about why this matters) + + + + + + ## Considerations for product designers The tips below are important considerations for the product design process. However, they are useful for engineers as well and must be considered at all stages of product development. - - - - Form elements and composition - - - - Give all form elements permanently visible labels - Give grouped form elements group labels - Place labels above form elements - Mark invalid fields clearly and provide associated error messages - Do not auto-focus form fields, on page load - Break up long and complex forms into discrete sections and/or screens - - Make forms as short as possible. For example, consider offering shortcuts like autocompleting an address by - using the postcode. - - - - - - - Text and typographic considerations - - - - - Make sure heading levels describe a logical section/subsection structure (Read more about this) - - Translate / spell out acronyms the first time you use them - Employ well-balanced, highly legible fonts (not too complex or elaborate) - - Do not use very thin font faces (Read an article about why this matters) - - Underline links — at least in body copy - - Avoid justified body text since it creates rivers of spacing that can be hard to read. (Read more about why this matters) - - - Provide enough spacing between lines of text (`line-height`) to allow for readers to track text (Read more about this) - - - Avoid all-caps text (Read more about this) - - - Ensure that content is written as clearly and simply as possible (Read more about why it matters) - - - Warn users of links that have unusual behaviors, like linking off-site, or loading a new tab - - - Make voice activation cues in your UI obvious with the use of text labels and / or visual affordances. - - - Do not mark up subheadings/straplines with separate heading elements (Read more about this) - - Begin long, multi-section documents with a table of contents - - Make sure the purpose of a link is clearly described: "read more" vs. "read more about accessibility" - - - - - - - Visual design and visual affordances - - - - Include only clear, meaningful animations - Do not rely on color as the only means of differentiation of visual elements - Make UI controls look like controls; give them strong perceived affordance - Avoid pure white or pure black shades - Indicate swipe gesture support clearly, and provide simple tap-based alternatives - Ensure primary calls to action are easy to recognize and reach - Use well-established, therefore recognizable, icons and symbols - Don't make users perform actions to reveal content unless completely necessary - If content is meant to be hidden, ensure it is properly hidden to all users - Inform the user when there are important changes to the application state - - - - - - Other considerations - - - - Use the same design patterns to solve the same problems - Label and describe the same things with the same terminology - Do not trigger "infinite scroll" by default; provide buttons to load more items - - Avoid time constraints where possible; provide a clear warning and option to extend where not possible - - - - - + + + + + Form elements and composition + + + + Give all form elements permanently visible labels + Give grouped form elements group labels + Place labels above form elements + Mark invalid fields clearly and provide associated error messages + Do not auto-focus form fields, on page load + Break up long and complex forms into discrete sections and/or screens + + Make forms as short as possible. For example, consider offering shortcuts like autocompleting an address by + using the postcode. + + + + + + + Text and typographic considerations + + + + + Make sure heading levels describe a logical section/subsection structure (Read more about this) + + Translate / spell out acronyms the first time you use them + Employ well-balanced, highly legible fonts (not too complex or elaborate) + + Do not use very thin font faces (Read an article about why this matters) + + Underline links — at least in body copy + + Avoid justified body text since it creates rivers of spacing that can be hard to read. (Read more about why this matters) + + + Provide enough spacing between lines of text (`line-height`) to allow for readers to track text (Read more about this) + + + Avoid all-caps text (Read more about this) + + + Ensure that content is written as clearly and simply as possible (Read more about why it matters) + + + Warn users of links that have unusual behaviors, like linking off-site, or loading a new tab + + + Make voice activation cues in your UI obvious with the use of text labels and / or visual affordances. + + + Do not mark up subheadings/straplines with separate heading elements (Read more about this) + + Begin long, multi-section documents with a table of contents + + Make sure the purpose of a link is clearly described: "read more" vs. "read more about accessibility" + + + + + + + Visual design and visual affordances + + + + Include only clear, meaningful animations + Do not rely on color as the only means of differentiation of visual elements + Make UI controls look like controls; give them strong perceived affordance + Avoid pure white or pure black shades + Indicate swipe gesture support clearly, and provide simple tap-based alternatives + Ensure primary calls to action are easy to recognize and reach + Use well-established, therefore recognizable, icons and symbols + Don't make users perform actions to reveal content unless completely necessary + If content is meant to be hidden, ensure it is properly hidden to all users + Inform the user when there are important changes to the application state + + + + + + Other considerations + + + + Use the same design patterns to solve the same problems + Label and describe the same things with the same terminology + Do not trigger "infinite scroll" by default; provide buttons to load more items + + Avoid time constraints where possible; provide a clear warning and option to extend where not possible + + + + + + ## Considerations for UX and front-end engineers