From e781b181cd81b6bb3acce9c00df6ad985470e74e Mon Sep 17 00:00:00 2001 From: Kristian Antrobus Date: Mon, 2 Dec 2024 12:37:24 -0600 Subject: [PATCH 1/2] chore(website): replace legacy blockquote with new component --- .../blog/2022-09-23-paste-newsletter.mdx | 77 +++--- .../blog/2022-12-09-paste-newsletter.mdx | 70 ++--- .../blog/2023-11-08-paste-newsletter.mdx | 87 ++++--- .../src/pages/components/alert/index.mdx | 92 +++---- .../src/pages/components/input/index.mdx | 96 +++---- .../pages/components/keyboard-key/index.mdx | 22 +- .../pages/components/media-object/index.mdx | 80 +++--- .../src/pages/components/pagination/index.mdx | 108 ++++---- .../src/pages/components/switch/index.mdx | 82 +++--- .../artificial-intelligence/index.mdx | 200 ++++++++++----- .../src/pages/patterns/filter/index.mdx | 239 ++++++++++++------ 11 files changed, 690 insertions(+), 463 deletions(-) diff --git a/packages/paste-website/src/pages/blog/2022-09-23-paste-newsletter.mdx b/packages/paste-website/src/pages/blog/2022-09-23-paste-newsletter.mdx index 84397df276..cefe26526d 100644 --- a/packages/paste-website/src/pages/blog/2022-09-23-paste-newsletter.mdx +++ b/packages/paste-website/src/pages/blog/2022-09-23-paste-newsletter.mdx @@ -1,35 +1,36 @@ export const meta = { - title: 'Paste Design System Newsletter - September 2022 Edition', - slug: '/blog/2022-09-23-paste-newsletter/', - date: '2022-09-23', - author: 'Paste', - avatar: 'https://avatars.githubusercontent.com/t/3335688?s=280&v=4', + title: "Paste Design System Newsletter - September 2022 Edition", + slug: "/blog/2022-09-23-paste-newsletter/", + date: "2022-09-23", + author: "Paste", + avatar: "https://avatars.githubusercontent.com/t/3335688?s=280&v=4", author_link: null, - status: 'published', + status: "published", external_link: null, excerpt: "What's new in Paste in September 2022? NEW components, NEW icons, insights into our customer experience, and more!", }; -import Image from 'next/image'; -import {Anchor} from '@twilio-paste/anchor'; -import {Paragraph} from '@twilio-paste/paragraph'; -import {Box} from '@twilio-paste/box'; -import {Table, THead, TBody, Tr, Td, Th} from '@twilio-paste/table'; -import {ResponsiveImage} from '../../components/ResponsiveImage'; -import {Blockquote} from '../../components/Blockquote'; -import SwitchExample from '../../assets/images/articles/2022-09-23-paste-newsletter/switch-example.gif'; -import InlineCodeExample from '../../assets/images/articles/2022-09-23-paste-newsletter/inline-code-example.png'; -import CodeBlockExample from '../../assets/images/articles/2022-09-23-paste-newsletter/code-block-example.gif'; -import CalloutExample from '../../assets/images/articles/2022-09-23-paste-newsletter/callout-example.png'; -import MinimizableDialog from '../../assets/images/articles/2022-09-23-paste-newsletter/minimizable-dialog-example.gif'; -import NewIcons from '../../assets/images/articles/2022-09-23-paste-newsletter/new-icons-example.png'; -import UiKit from '../../assets/images/articles/2022-09-23-paste-newsletter/ui-kit-example.png'; -import ToggleButton from '../../assets/images/articles/2022-09-23-paste-newsletter/toggle-button-example.gif'; -import StickyHeaders from '../../assets/images/articles/2022-09-23-paste-newsletter/sticky-headers-example.gif'; -import Ramona from '../../assets/images/articles/2022-09-23-paste-newsletter/ramona-pastemate.png'; -import DefaultLayout from '../../layouts/DefaultLayout'; -import {getNavigationData} from '../../utils/api'; +import Image from "next/image"; +import { Anchor } from "@twilio-paste/anchor"; +import { Paragraph } from "@twilio-paste/paragraph"; +import { Box } from "@twilio-paste/box"; +import { Table, THead, TBody, Tr, Td, Th } from "@twilio-paste/table"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; + +import { ResponsiveImage } from "../../components/ResponsiveImage"; +import SwitchExample from "../../assets/images/articles/2022-09-23-paste-newsletter/switch-example.gif"; +import InlineCodeExample from "../../assets/images/articles/2022-09-23-paste-newsletter/inline-code-example.png"; +import CodeBlockExample from "../../assets/images/articles/2022-09-23-paste-newsletter/code-block-example.gif"; +import CalloutExample from "../../assets/images/articles/2022-09-23-paste-newsletter/callout-example.png"; +import MinimizableDialog from "../../assets/images/articles/2022-09-23-paste-newsletter/minimizable-dialog-example.gif"; +import NewIcons from "../../assets/images/articles/2022-09-23-paste-newsletter/new-icons-example.png"; +import UiKit from "../../assets/images/articles/2022-09-23-paste-newsletter/ui-kit-example.png"; +import ToggleButton from "../../assets/images/articles/2022-09-23-paste-newsletter/toggle-button-example.gif"; +import StickyHeaders from "../../assets/images/articles/2022-09-23-paste-newsletter/sticky-headers-example.gif"; +import Ramona from "../../assets/images/articles/2022-09-23-paste-newsletter/ramona-pastemate.png"; +import DefaultLayout from "../../layouts/DefaultLayout"; +import { getNavigationData } from "../../utils/api"; export default DefaultLayout; @@ -227,8 +228,8 @@ Our survey used a scale of 1-5 (1 being strongly disagree, 5 being strongly agre We are excited to the share the following insights: - When asked how strongly they agreed to{' '} - Paste being easy to use to design and build customer interfaces, our participants averaged{' '} + When asked how strongly they agreed to{" "} + Paste being easy to use to design and build customer interfaces, our participants averaged{" "} 4.00/5. @@ -238,12 +239,22 @@ We are excited to the share the following insights: In addition, some participants specified: -
- It's great to have a standardized component library that lines up with Twilio standards. It allows me to focus on - my business logic. -
- -
I really appreciate how approachable Paste is - it's really easy to get up and running.
+ +
+ + It's great to have a standardized component library that lines up with Twilio standards. It allows me to + focus on my business logic. + +
+ + + +
+ + I really appreciate how approachable Paste is - it's really easy to get up and running. + +
+ These results are music to our ears 🎶 diff --git a/packages/paste-website/src/pages/blog/2022-12-09-paste-newsletter.mdx b/packages/paste-website/src/pages/blog/2022-12-09-paste-newsletter.mdx index ac0b2e1e3d..ce34a3ba3b 100644 --- a/packages/paste-website/src/pages/blog/2022-12-09-paste-newsletter.mdx +++ b/packages/paste-website/src/pages/blog/2022-12-09-paste-newsletter.mdx @@ -1,28 +1,29 @@ export const meta = { - title: 'Paste Design System Newsletter - December 2022 Edition', - slug: '/blog/2022-12-09-paste-newsletter/', - date: '2022-12-09', - author: 'Paste', - status: 'published', - avatar: 'https://avatars.githubusercontent.com/t/3335688?s=280&v=4', + title: "Paste Design System Newsletter - December 2022 Edition", + slug: "/blog/2022-12-09-paste-newsletter/", + date: "2022-12-09", + author: "Paste", + status: "published", + avatar: "https://avatars.githubusercontent.com/t/3335688?s=280&v=4", excerpt: "What's new in Paste in December 2022? New components, new variants, and more!", }; -import Image from 'next/image'; -import {Anchor} from '@twilio-paste/anchor'; -import {Paragraph} from '@twilio-paste/paragraph'; -import {Box} from '@twilio-paste/box'; -import {Table, THead, TBody, Tr, Td, Th} from '@twilio-paste/table'; -import {ResponsiveImage} from '../../components/ResponsiveImage'; -import {Blockquote} from '../../components/Blockquote'; -import ChatLog from '../../assets/images/articles/2022-12-09-paste-newsletter/animated-chat-log.gif'; -import PageNav from '../../assets/images/articles/2022-12-09-paste-newsletter/in-page-nav.gif'; -import ChatComposer from '../../assets/images/articles/2022-12-09-paste-newsletter/chat-composer.gif'; -import DisplayHeading from '../../assets/images/articles/2022-12-09-paste-newsletter/display-heading.png'; -import Robb from '../../assets/images/articles/2022-12-09-paste-newsletter/robb-niznik.jpeg'; -import Justin from '../../assets/images/articles/2022-12-09-paste-newsletter/justin-young.png'; -import DefaultLayout from '../../layouts/DefaultLayout'; -import {getNavigationData} from '../../utils/api'; +import Image from "next/image"; +import { Anchor } from "@twilio-paste/anchor"; +import { Paragraph } from "@twilio-paste/paragraph"; +import { Box } from "@twilio-paste/box"; +import { Table, THead, TBody, Tr, Td, Th } from "@twilio-paste/table"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; + +import { ResponsiveImage } from "../../components/ResponsiveImage"; +import ChatLog from "../../assets/images/articles/2022-12-09-paste-newsletter/animated-chat-log.gif"; +import PageNav from "../../assets/images/articles/2022-12-09-paste-newsletter/in-page-nav.gif"; +import ChatComposer from "../../assets/images/articles/2022-12-09-paste-newsletter/chat-composer.gif"; +import DisplayHeading from "../../assets/images/articles/2022-12-09-paste-newsletter/display-heading.png"; +import Robb from "../../assets/images/articles/2022-12-09-paste-newsletter/robb-niznik.jpeg"; +import Justin from "../../assets/images/articles/2022-12-09-paste-newsletter/justin-young.png"; +import DefaultLayout from "../../layouts/DefaultLayout"; +import { getNavigationData } from "../../utils/api"; export default DefaultLayout; @@ -56,7 +57,7 @@ export const getStaticProps = async () => { ### Chat Log animations - + The final piece of [the Chat Log package](/components/chat-log) is complete— animation! There is a new useChatLogger hook that manages a list of messages, bookends, and events and a new ChatLogger component that animates the list into a Chat Log. @@ -66,7 +67,7 @@ The final piece of [the Chat Log package](/components/chat-log) is complete— a ### In Page Navigation - + The In Page Navigation component is a collection of links that navigate users to related pages. Although stylistically similar to Tabs, this component’s structure allows for straightforward integration with routers like React Router. @@ -76,7 +77,7 @@ The In Page Navigation component is a collection of links that navigate users to ### Chat Composer - + A highly anticipated component, the Chat Composer is a rich text input that users can type chat messages into. It is built with [the Lexical text editor](https://lexical.dev/) and can be extended to include the features you need through Lexical’s plugins. @@ -135,14 +136,14 @@ Robb enjoys going on hikes, listening to his records, and volunteering at Therap In this edition of Pastemates, we're spotlighting a mate from Twilio Contact Center Sales, Justin Young! Justin has been busy emboldening the Twilio Builder Spirit, stitching together the new Flex UI and its inbuilt support of Paste, with builder.io, to create a drag and drop Flex UI builder! -
+
@@ -150,14 +151,14 @@ In this edition of Pastemates, we're spotlighting a mate from Twilio Contact Cen Justin registered Paste React components to Builder.io which allows Justin and his team to rapidly create rich Paste-based experiences in the Flex UI using a drag and drop editor. By exposing paste component properties like variants in the Builder.io editor, Justin can choose between different styles of buttons, alerts and any other Paste component that they have wired up. As you can see by the video demo's the authoring is easy and intuitive and the customer experiences and functionality it creates are excellent and fully functional. Another benefit to his team is that they can begin to build complex components using many different Paste components, and save them as templates for easy re-use in customer demos. -
+
@@ -165,10 +166,15 @@ Justin registered Paste React components to Builder.io which allows Justin and h In Justin’s own words: -
- I am no designer, but this is already better than every flex demo we’ve ever built from a UX perspective because of - access to paste -
+ +
+ + I am no designer, but this is already better than every flex demo we’ve ever built from a UX perspective because + of access to paste + + +
+ We're stoked that Justin and team were able to create this builder experience all on their own, just by the Flex and Paste teams collaborating together! We can't wait to see what other people build next, with Paste on top of Flex. diff --git a/packages/paste-website/src/pages/blog/2023-11-08-paste-newsletter.mdx b/packages/paste-website/src/pages/blog/2023-11-08-paste-newsletter.mdx index 7d3f2637ef..65f3a69b38 100644 --- a/packages/paste-website/src/pages/blog/2023-11-08-paste-newsletter.mdx +++ b/packages/paste-website/src/pages/blog/2023-11-08-paste-newsletter.mdx @@ -1,35 +1,34 @@ export const meta = { - title: 'Paste Design System Newsletter - November 2023 Edition', - slug: '/blog/2023-11-08-paste-newsletter/', - date: '2023-11-08', - author: 'Paste', - avatar: 'https://avatars.githubusercontent.com/t/3335688?s=280&v=4', - status: 'published', + title: "Paste Design System Newsletter - November 2023 Edition", + slug: "/blog/2023-11-08-paste-newsletter/", + date: "2023-11-08", + author: "Paste", + avatar: "https://avatars.githubusercontent.com/t/3335688?s=280&v=4", + status: "published", excerpt: "What's new in Paste in November 2023? AI is here!", }; -import Image from 'next/image'; -import {Paragraph} from '@twilio-paste/paragraph'; -import {Box} from '@twilio-paste/box'; -import {ResponsiveImage} from '../../components/ResponsiveImage'; -import {Blockquote} from '../../components/Blockquote'; - -import Pastebot from '../../assets/images/articles/2023-11-08-paste-newsletter/Pastebot.png'; -import DocsSearch from '../../assets/images/articles/2023-11-08-paste-newsletter/DocsSearch.png'; -import Figma1 from '../../assets/images/articles/2023-11-08-paste-newsletter/Figma1.gif'; -import Figma2 from '../../assets/images/articles/2023-11-08-paste-newsletter/Figma2.png'; -import Figma3 from '../../assets/images/articles/2023-11-08-paste-newsletter/Figma3.png'; -import DocsImprovements from '../../assets/images/articles/2023-11-08-paste-newsletter/DocsImprovements.png'; -import PageTemplates from '../../assets/images/articles/2023-11-08-paste-newsletter/PageTemplates.png'; -import NumberComponents from '../../assets/images/articles/2023-11-08-paste-newsletter/NumberComponents.png'; -import EditableCodeBlock from '../../assets/images/articles/2023-11-08-paste-newsletter/EditableCodeBlock.png'; -import ErrorPattern from '../../assets/images/articles/2023-11-08-paste-newsletter/ErrorPattern.png'; -import Pastemate1 from '../../assets/images/articles/2023-11-08-paste-newsletter/Pastemate1.png'; -import Pastemate2 from '../../assets/images/articles/2023-11-08-paste-newsletter/Pastemate2.png'; - - -import DefaultLayout from '../../layouts/DefaultLayout'; -import {getNavigationData} from '../../utils/api'; +import Image from "next/image"; +import { Paragraph } from "@twilio-paste/paragraph"; +import { Box } from "@twilio-paste/box"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; + +import { ResponsiveImage } from "../../components/ResponsiveImage"; +import Pastebot from "../../assets/images/articles/2023-11-08-paste-newsletter/Pastebot.png"; +import DocsSearch from "../../assets/images/articles/2023-11-08-paste-newsletter/DocsSearch.png"; +import Figma1 from "../../assets/images/articles/2023-11-08-paste-newsletter/Figma1.gif"; +import Figma2 from "../../assets/images/articles/2023-11-08-paste-newsletter/Figma2.png"; +import Figma3 from "../../assets/images/articles/2023-11-08-paste-newsletter/Figma3.png"; +import DocsImprovements from "../../assets/images/articles/2023-11-08-paste-newsletter/DocsImprovements.png"; +import PageTemplates from "../../assets/images/articles/2023-11-08-paste-newsletter/PageTemplates.png"; +import NumberComponents from "../../assets/images/articles/2023-11-08-paste-newsletter/NumberComponents.png"; +import EditableCodeBlock from "../../assets/images/articles/2023-11-08-paste-newsletter/EditableCodeBlock.png"; +import ErrorPattern from "../../assets/images/articles/2023-11-08-paste-newsletter/ErrorPattern.png"; +import Pastemate1 from "../../assets/images/articles/2023-11-08-paste-newsletter/Pastemate1.png"; +import Pastemate2 from "../../assets/images/articles/2023-11-08-paste-newsletter/Pastemate2.png"; + +import DefaultLayout from "../../layouts/DefaultLayout"; +import { getNavigationData } from "../../utils/api"; export default DefaultLayout; @@ -79,7 +78,6 @@ We’ve updated the [Paste docs site](https://paste.twilio.design/) search featu ### New Figma features for better design and engineering collaboration - - + We added variables and modes to the [Paste Components & Themes](https://www.figma.com/file/l2qtpQVMmXzQPVB3rEAA8i/Paste-Components-%26-Themes?type=design&node-id=3015-46646&mode=design&t=LavBWI8WtuCpWbz0-0) (newly renamed — thanks, **Chof**!) Figma library to allow easier swapping between Twilio, Twilio Dark, Evergreen, and Default themes. This update combines styles from 4 of our theme libraries and our component library into one single easy-to-import file. @@ -135,7 +133,10 @@ Introducing [page templates](/page-templates)! Brand new to Paste, page template - + @@ -171,7 +172,8 @@ We’ve just completed our annual round of roadmap reviews with product teams to - Improved the [In Page Navigation](/components/in-page-navigation) component with design updates and additional documentation. ## ✨ Pastemates™ spotlight -*Pastemates are individuals and teams who have been critical contributors to Paste, through advocating for adoption within their products and channeling important feedback and contributions back into the system.* + +_Pastemates are individuals and teams who have been critical contributors to Paste, through advocating for adoption within their products and channeling important feedback and contributions back into the system._ @@ -181,7 +183,16 @@ We’ve just completed our annual round of roadmap reviews with product teams to In this edition of Pastemates, we're spotlighting a mate from the Web Platform team, Pablo Deeleman! Pablo lives the Twilio Builder spirit, building complex prototypes with just out-of-the-box Paste components. During his time on the Event Streams team, he pushed the boundaries of what could be built with Paste "as is": -
The whole node connectors UI, including the animations, is done with plain vanilla Paste components and primitives with no further tampering. No custom React/UI…was necessary to deliver this experience, and although it might seem quite a complex development, the whole UI was built in a couple of hours.
+ +
+ + The whole node connectors UI, including the animations, is done with plain vanilla Paste components and primitives + with no further tampering. No custom React/UI…was necessary to deliver this experience, and although it might seem + quite a complex development, the whole UI was built in a couple of hours. + + +
+ @@ -195,11 +206,11 @@ We love Pablo’s demonstration of what can be achieved with Just Plain Paste™ ## 👀 What we're working on next -| Feature | Description | -| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Page Header component** | A standardized but flexible compositional component used at the top of a variety of pages. | -| **Design components for AI UI kit** | Design for components that enable new AI experiences at Twilio, mainly focused around generative AI and chat. | -| **Paste Copilot** | A Chat GPT powered support chat experience to help answer your Paste building and designing questions. | +| Feature | Description | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| **Page Header component** | A standardized but flexible compositional component used at the top of a variety of pages. | +| **Design components for AI UI kit** | Design for components that enable new AI experiences at Twilio, mainly focused around generative AI and chat. | +| **Paste Copilot** | A Chat GPT powered support chat experience to help answer your Paste building and designing questions. | diff --git a/packages/paste-website/src/pages/components/alert/index.mdx b/packages/paste-website/src/pages/components/alert/index.mdx index c924e8e6a5..ec1faf3309 100644 --- a/packages/paste-website/src/pages/components/alert/index.mdx +++ b/packages/paste-website/src/pages/components/alert/index.mdx @@ -1,32 +1,33 @@ export const meta = { - title: 'Alert', - package: '@twilio-paste/alert', - description: 'An alert notifies a user to high-priority or time-sensitive information.', - slug: '/components/alert/', + title: "Alert", + package: "@twilio-paste/alert", + description: "An alert notifies a user to high-priority or time-sensitive information.", + slug: "/components/alert/", }; -import {Alert} from '@twilio-paste/alert'; -import {Text} from '@twilio-paste/text'; -import {Box} from '@twilio-paste/box'; -import {Button} from '@twilio-paste/button'; -import {Anchor} from '@twilio-paste/anchor'; -import {Card} from '@twilio-paste/card'; -import {Heading} from '@twilio-paste/heading'; -import {Paragraph} from '@twilio-paste/paragraph'; -import {DoDont, Do, Dont} from '../../../components/DoDont'; -import {Blockquote} from '../../../components/Blockquote'; -import {Codeblock} from '../../../components/codeblock'; -import {SidebarCategoryRoutes} from '../../../constants'; -import Changelog from '@twilio-paste/alert/CHANGELOG.md'; -import packageJson from '@twilio-paste/alert/package.json'; -import ComponentPageLayout from '../../../layouts/ComponentPageLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +import { Alert } from "@twilio-paste/alert"; +import { Text } from "@twilio-paste/text"; +import { Box } from "@twilio-paste/box"; +import { Button } from "@twilio-paste/button"; +import { Anchor } from "@twilio-paste/anchor"; +import { Card } from "@twilio-paste/card"; +import { Heading } from "@twilio-paste/heading"; +import { Paragraph } from "@twilio-paste/paragraph"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; + +import { DoDont, Do, Dont } from "../../../components/DoDont"; +import { Codeblock } from "../../../components/codeblock"; +import { SidebarCategoryRoutes } from "../../../constants"; +import Changelog from "@twilio-paste/alert/CHANGELOG.md"; +import packageJson from "@twilio-paste/alert/package.json"; +import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; export default ComponentPageLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Alert'); + const feature = await getFeature("Alert"); return { props: { data: { @@ -37,14 +38,14 @@ export const getStaticProps = async () => { mdxHeadings, pageHeaderData: { categoryRoute: SidebarCategoryRoutes.COMPONENTS, - githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/alert', - storybookUrl: '/?path=/story/components-alert--neutral', + githubUrl: "https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/alert", + storybookUrl: "/?path=/story/components-alert--neutral", }, }, }; }; - + {` Some information on this page may be out-of-date. This page was last updated at 9:00 a.m. PST. We're currently looking into this issue. `} @@ -62,14 +63,15 @@ Use an Alert for one of these types of information: - **Warning.** Critical information that will help a user avoid an issue. - **Error.** Critical information that's preventing a user from continuing a flow and if there's action required on their end to resolve the issue. -
- A notification sent irrespective of the current user goal would likely be ignored, and may even annoy users because it - will disrupt their current task and be irrelevant to their current needs. -
+ +
+ + A notification sent irrespective of the current user goal would likely be ignored, and may even annoy users + because it will disrupt their current task and be irrelevant to their current needs. + + +
+ ### Accessibility @@ -86,22 +88,26 @@ Alert uses multiple methods to indicate type. - Set up your contact preferences. You can now set up your contact preferences on your dashboard. Go to contact preferences + Set up your contact preferences. You can now set up your contact preferences on your dashboard.{" "} + Go to contact preferences - Some information on this page may be out-of-date. This page was last updated at 9:00 a.m. PST. We're currently looking into this issue. + Some information on this page may be out-of-date. This page was last updated at 9:00 a.m. PST. + We're currently looking into this issue. - Please update your billing information or we'll suspend your account on March 2. We couldn't renew your subscription with the information we currently have. Update billing information + Please update your billing information or we'll suspend your account on March 2. We couldn't renew + your subscription with the information we currently have. Update billing information - alert('dismissed')} variant="neutral"> - Set up your contact preferences. You can now set up your contact preferences on your dashboard. Go to contact preferences + alert("dismissed")} variant="neutral"> + Set up your contact preferences. You can now set up your contact preferences on your dashboard.{" "} + Go to contact preferences @@ -113,7 +119,7 @@ In most cases, a neutral Alert should be dismissible (_i.e._, have a close butto You may use the [Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for neutral Alerts. - + {` Set up your contact preferences. You can now set up your contact preferences on your dashboard. Go to contact preferences `} @@ -129,7 +135,7 @@ Be cautious about using a warning Alert because they can be stressful for a user You may use the [Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for warning Alerts. - + {` Some information on this page may be out-of-date. This page was last updated at 9:00 a.m. PST. We're currently looking into this issue. `} @@ -145,7 +151,7 @@ For additional guidance on what kind of component to use, use the [Alert vs. Cal You may use the [Text primitive](/primitives/text) as a child of Alert, but if you do, be sure to pass `color="inherit"` for error Alerts. - + {` Please update your billing information or we'll suspend your account on March 2. We couldn't renew your subscription with the information we currently have. Update billing information `} @@ -163,7 +169,7 @@ Don't make it dismissible if all these conditions are true: Keep in mind that the longer an Alert is present, the more it starts looking like part of the page and loses its interruptive intent. This might make users start to ignore important Alert information. - + {` alert('dismissed')} variant="neutral"> We've enabled new security options for your account. Learn more `} @@ -177,7 +183,7 @@ To change the dismiss button's label text, use the `i18nDismissLabel` prop. To change the label of a variant's icon, use the matching i18n prop for the variant. For an `error` variant, for example, set the `i18nErrorLabel` prop. - + {` alert('fermée')} variant="warning" i18nWarningLabel="(avertissement)"> C'est une alerte d'avertissement. `} @@ -285,7 +291,7 @@ In general, the persistence and behavior on scroll of an Alert should match the - A call to action{' '} + A call to action{" "} diff --git a/packages/paste-website/src/pages/components/input/index.mdx b/packages/paste-website/src/pages/components/input/index.mdx index 584b1c6188..3d5ab8cc56 100644 --- a/packages/paste-website/src/pages/components/input/index.mdx +++ b/packages/paste-website/src/pages/components/input/index.mdx @@ -1,35 +1,36 @@ export const meta = { - title: 'Input - Components', - package: '@twilio-paste/input', - description: 'An input allows users to enter text on a single line.', - slug: '/components/input/', + title: "Input - Components", + package: "@twilio-paste/input", + description: "An input allows users to enter text on a single line.", + slug: "/components/input/", }; -import {Label} from '@twilio-paste/label'; -import {Input} from '@twilio-paste/input'; -import {HelpText} from '@twilio-paste/help-text'; -import {Anchor} from '@twilio-paste/anchor'; -import {Box} from '@twilio-paste/box'; -import {Text} from '@twilio-paste/text'; -import {Button} from '@twilio-paste/button'; -import {Table, THead, TBody, Td, Th, Tr} from '@twilio-paste/table'; -import {InformationIcon} from '@twilio-paste/icons/esm/InformationIcon'; -import {UnorderedList, ListItem} from '@twilio-paste/list'; -import {Callout, CalloutHeading, CalloutText} from '@twilio-paste/callout'; -import {DoDont, Do, Dont} from '../../../components/DoDont'; -import {Codeblock} from '../../../components/codeblock'; -import {Blockquote} from '../../../components/Blockquote'; -import {SidebarCategoryRoutes} from '../../../constants'; -import Changelog from '@twilio-paste/input/CHANGELOG.md'; -import packageJson from '@twilio-paste/input/package.json'; -import ComponentPageLayout from '../../../layouts/ComponentPageLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +import { Label } from "@twilio-paste/label"; +import { Input } from "@twilio-paste/input"; +import { HelpText } from "@twilio-paste/help-text"; +import { Anchor } from "@twilio-paste/anchor"; +import { Box } from "@twilio-paste/box"; +import { Text } from "@twilio-paste/text"; +import { Button } from "@twilio-paste/button"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; +import { Table, THead, TBody, Td, Th, Tr } from "@twilio-paste/table"; +import { InformationIcon } from "@twilio-paste/icons/esm/InformationIcon"; +import { UnorderedList, ListItem } from "@twilio-paste/list"; +import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; + +import { DoDont, Do, Dont } from "../../../components/DoDont"; +import { Codeblock } from "../../../components/codeblock"; +import { SidebarCategoryRoutes } from "../../../constants"; +import Changelog from "@twilio-paste/input/CHANGELOG.md"; +import packageJson from "@twilio-paste/input/package.json"; +import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; export default ComponentPageLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Input'); + const feature = await getFeature("Input"); return { props: { data: { @@ -40,14 +41,14 @@ export const getStaticProps = async () => { mdxHeadings, pageHeaderData: { categoryRoute: SidebarCategoryRoutes.COMPONENTS, - githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/input', - storybookUrl: '/?path=/story/components-input--default-input', + githubUrl: "https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/input", + storybookUrl: "/?path=/story/components-input--default-input", }, }, }; }; - + {`<> {}} required/> @@ -89,7 +90,7 @@ The Input component should include the base input, along with supporting element Accessibility insight - Make sure to connect the Label to the Input. This is done with the{' '} + Make sure to connect the Label to the Input. This is done with the{" "} htmlFor prop on the label, and the id prop on the input. Those two need to match. @@ -100,7 +101,7 @@ The Input component should include the base input, along with supporting element - + {`<> {}} required/> @@ -113,7 +114,7 @@ The Input component should include the base input, along with supporting element - **Prefix/suffix text** — Text that can be used as a prefix and/or suffix to the value that is entered. Use prefix/suffix to help users format text. - **Icon** — Icons can be placed in the same area as the prefix and suffix text. Icons should trigger an action (like clearing a field) or in rare cases, provide further context to what value should be entered to make a field's purpose more immediately visible (like a search icon). - + {`<> $} onChange={()=>{}} required /> @@ -121,7 +122,7 @@ The Input component should include the base input, along with supporting element `} - + {`<> - The number input type should only be used for incremental numbers...The number input type is not appropriate for - values that happen to only consist of numbers but aren't strictly speaking a number, such as postal codes in many - countries or credit card numbers. - + +
+ + The number input type should only be used for incremental numbers...The number input type is not appropriate for + values that happen to only consist of numbers but aren't strictly speaking a number, such as postal codes in many + countries or credit card numbers.{" "} + + +
+ In most cases, include a default value that the user can change and would not cause harm if accidentally used. Use [Help Text](/components/help-text) to explain what inputs are accepted, like minimum or maximum values or step intervals, especially if there's no default value. Help Text should also include any important contextual information about what the number input represents. - + {`<> @@ -210,7 +212,7 @@ Help Text should also include any important contextual information about what th Provide translated strings for the 'increment' and 'decrement' button labels to make NumberInput localized. The `i18nStepUpLabel` and `i18nStepDownLabel` props should be used for this purpose. - + {`<> @@ -226,7 +228,7 @@ Change a form field to its error state and use [Help Text](/components/help-text An error Help Text is placed below the field to inform a user of any errors in their value. Change the Help Text to `variant=“error”` and add error copy before the original help text copy. Review the [error state pattern](/patterns/error-state) for guidance on writing error messages. - + {`<> {}} hasError /> @@ -240,7 +242,7 @@ Use a disabled form field to show users that they can't interact with the field. If you want to show information that can't be edited, use a [read-only](#read-only-input) form field or consider another way of showing static information. - + {`<> {}} disabled /> @@ -252,7 +254,7 @@ If you want to show information that can't be edited, use a [read-only](#read-on Use a read-only form field when a field's value can't be changed, but users should be able to read or apply focus on the field. For example, use a read-only form field if a user needs to copy the value. - + {`<> {}} readOnly /> @@ -277,7 +279,7 @@ Give users enough information in help text to prevent input and formatting error Stack form fields vertically with `$space-80` spacing between each field. - + {`<> @@ -296,7 +298,7 @@ Avoid placing multiple form fields on the same horizontal row to help make it ea Use text or required indicators to show users which fields they must fill out. - + {`<> {}} required/> diff --git a/packages/paste-website/src/pages/components/keyboard-key/index.mdx b/packages/paste-website/src/pages/components/keyboard-key/index.mdx index a225938902..3b0055a0cd 100644 --- a/packages/paste-website/src/pages/components/keyboard-key/index.mdx +++ b/packages/paste-website/src/pages/components/keyboard-key/index.mdx @@ -1,6 +1,7 @@ import { KeyboardKey, KeyboardKeyGroup, useKeyCombination, useKeyCombinations } from "@twilio-paste/keyboard-key"; import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; import { Anchor } from "@twilio-paste/anchor"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; import { Box } from "@twilio-paste/box"; import { Button } from "@twilio-paste/button"; import { useMenuState, Menu, MenuButton, MenuItem } from "@twilio-paste/menu"; @@ -13,7 +14,6 @@ import { SearchIcon } from "@twilio-paste/icons/esm/SearchIcon"; import packageJson from "@twilio-paste/keyboard-key/package.json"; import { SidebarCategoryRoutes } from "../../../constants"; -import { Blockquote } from "../../../components/Blockquote"; import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; import { getFeature, getNavigationData } from "../../../utils/api"; import { Do, DoDont, Dont } from "../../../components/DoDont"; @@ -69,14 +69,18 @@ A Keyboard Key distinguishes a keyboard command or shortcut from other text. Keyboard shortcuts are used for extremely frequent platform-level actions (like activating search), or in canvas or productivity tools like Studio or Flex. In general, **avoid implementing keyboard shortcuts**, especially with single keys, because they can override shortcuts that are already set by operating systems, browsers, assistive technologies, or user preferences. -
- Not every task on your application needs a shortcut, so observe your users interacting with your application to - determine the most common tasks and prioritize keyboard shortcuts for these. -
+ +
+ + Not every task on your application needs a shortcut, so observe your users interacting with your application to + determine the most common tasks and prioritize keyboard shortcuts for these. + + +
+ Keyboards can also vary across operating systems and global regions, so make sure your key commands work for all users. diff --git a/packages/paste-website/src/pages/components/media-object/index.mdx b/packages/paste-website/src/pages/components/media-object/index.mdx index a58469999f..af67ffccf6 100644 --- a/packages/paste-website/src/pages/components/media-object/index.mdx +++ b/packages/paste-website/src/pages/components/media-object/index.mdx @@ -1,32 +1,33 @@ export const meta = { - title: 'Media Object - Layout', - package: '@twilio-paste/media-object', + title: "Media Object - Layout", + package: "@twilio-paste/media-object", description: - 'Media Object is a layout utility that allows an image or figure to be positioned horizontally next to some form of content.', - slug: '/components/media-object/', + "Media Object is a layout utility that allows an image or figure to be positioned horizontally next to some form of content.", + slug: "/components/media-object/", }; -import {Box} from '@twilio-paste/box'; -import {Text} from '@twilio-paste/text'; -import {Avatar} from '@twilio-paste/avatar'; -import {Paragraph} from '@twilio-paste/paragraph'; -import {Alert} from '@twilio-paste/alert'; -import {Menu, MenuButton, SubMenuButton, MenuItem, MenuGroup, MenuSeparator, useMenuState} from '@twilio-paste/menu'; -import {MediaObject, MediaFigure, MediaBody} from '@twilio-paste/media-object'; -import {ChevronDownIcon} from '@twilio-paste/icons/esm/ChevronDownIcon'; -import {subMenuExample} from '../../../component-examples/MenuExamples.ts'; -import {Blockquote} from '../../../components/Blockquote'; -import {SidebarCategoryRoutes, TWILIO_RED} from '../../../constants'; -import {PasteIcon} from '../../../components/icons/PasteIcon'; -import packageJson from '@twilio-paste/media-object/package.json'; -import ComponentPageLayout from '../../../layouts/ComponentPageLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +import { Box } from "@twilio-paste/box"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; +import { Text } from "@twilio-paste/text"; +import { Avatar } from "@twilio-paste/avatar"; +import { Paragraph } from "@twilio-paste/paragraph"; +import { Alert } from "@twilio-paste/alert"; +import { Menu, MenuButton, SubMenuButton, MenuItem, MenuGroup, MenuSeparator, useMenuState } from "@twilio-paste/menu"; +import { MediaObject, MediaFigure, MediaBody } from "@twilio-paste/media-object"; + +import { ChevronDownIcon } from "@twilio-paste/icons/esm/ChevronDownIcon"; +import { subMenuExample } from "../../../component-examples/MenuExamples.ts"; +import { SidebarCategoryRoutes, TWILIO_RED } from "../../../constants"; +import { PasteIcon } from "../../../components/icons/PasteIcon"; +import packageJson from "@twilio-paste/media-object/package.json"; +import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; export default ComponentPageLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Media Object'); + const feature = await getFeature("Media Object"); return { props: { data: { @@ -37,14 +38,14 @@ export const getStaticProps = async () => { mdxHeadings, pageHeaderData: { categoryRoute: SidebarCategoryRoutes.COMPONENTS, - githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/layout/media-object', - storybookUrl: '/?path=/story/layout-media-object--default', + githubUrl: "https://github.com/twilio-labs/paste/tree/main/packages/paste-core/layout/media-object", + storybookUrl: "/?path=/story/layout-media-object--default", }, }, }; }; - + {` @@ -66,17 +67,18 @@ export const getStaticProps = async () => { First created by [Nicole Sullivan](http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/) back in 2010, the Media Object in Paste aims to serve many of the same purposes as the original concept. It's a layout pattern that you will see all across the web, on almost all the websites you will come across. We're pretty sure you'll **never unsee this going forward**. -
- What is the internet made of? At least the UI layer is mainly composed of media blocks. -
+ +
+ + What is the internet made of? At least the UI layer is mainly composed of media blocks. + + +
+ **So what's a media object?** An image or figure positioned horizontally next to some form of content. The figure can sit on either or both sides of the content. That's it. It sounds really simple, but it's literally everywhere on the Internet. For example, the top left of this website uses a Media Object. - + {` @@ -117,7 +119,7 @@ the visual or content hierarchy of your page. ### Basic Media Object - + {` @@ -132,7 +134,7 @@ the visual or content hierarchy of your page. To set some spacing between the `MediaFigure` and `MediaBody`, set the `spacing` property on the `MediaFigure`. This prop takes any spacing token. - + {` + {` + {` Some Text @@ -187,7 +189,7 @@ To place the `MediaFigure` after the `MediaBody`, at the end of the `MediaObject To have a `MediaFigure` at either end of the `MediaObject`, add a `MediaFigure` before and after the `MediaBody`, setting the second `MediaFigure` to `align="end"`. - + {` + {` Chimamanda Ngozi Adichie: Racism should never have happened and so you don't get a cookie for reducing it. `} @@ -224,7 +226,7 @@ The Alert is a classic Media Object layout. The status level icon is the Media F Here we're center aligning an avatar next to a timestamp and username. - + {` @@ -244,7 +246,7 @@ Here we're center aligning an avatar next to a timestamp and username. By placing the figure at the end of the Media Object and top aligning it to a chat bubble, we can start to compose a custom chat log UI. - + {` diff --git a/packages/paste-website/src/pages/components/pagination/index.mdx b/packages/paste-website/src/pages/components/pagination/index.mdx index 4f4a75dc10..55f6cf4c9e 100644 --- a/packages/paste-website/src/pages/components/pagination/index.mdx +++ b/packages/paste-website/src/pages/components/pagination/index.mdx @@ -1,16 +1,17 @@ export const meta = { - title: 'Pagination', - package: '@twilio-paste/pagination', - description: 'Pagination lets users navigate through content or a dataset that’s been broken up into multiple pages.', - slug: '/components/pagination/', + title: "Pagination", + package: "@twilio-paste/pagination", + description: "Pagination lets users navigate through content or a dataset that’s been broken up into multiple pages.", + slug: "/components/pagination/", }; -import {useUID} from '@twilio-paste/uid-library'; -import {Anchor} from '@twilio-paste/anchor'; -import {Box} from '@twilio-paste/box'; -import {Text} from '@twilio-paste/text'; -import {Heading} from '@twilio-paste/heading'; -import {Paragraph} from '@twilio-paste/paragraph'; +import { useUID } from "@twilio-paste/uid-library"; +import { Anchor } from "@twilio-paste/anchor"; +import { Box } from "@twilio-paste/box"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; +import { Text } from "@twilio-paste/text"; +import { Heading } from "@twilio-paste/heading"; +import { Paragraph } from "@twilio-paste/paragraph"; import { Pagination, PaginationItems, @@ -19,28 +20,28 @@ import { PaginationNumbers, PaginationNumber, PaginationEllipsis, -} from '@twilio-paste/pagination'; -import {Button} from '@twilio-paste/button'; -import {Table, THead, TBody, Th, Td, Tr} from '@twilio-paste/table'; -import {Grid, Column} from '@twilio-paste/grid'; -import {UnorderedList, ListItem} from '@twilio-paste/list'; -import {Stack} from '@twilio-paste/stack'; -import Changelog from '@twilio-paste/pagination/CHANGELOG.md'; -import {Callout, CalloutHeading, CalloutText} from '@twilio-paste/callout'; -import {DoDont, Do, Dont} from '../../../components/DoDont'; -import {Codeblock} from '../../../components/codeblock'; -import {SidebarCategoryRoutes} from '../../../constants'; -import {Blockquote} from '../../../components/Blockquote'; -import {defaultExample, numberExample, positioningExample} from '../../../component-examples/PaginationExamples'; -import packageJson from '@twilio-paste/pagination/package.json'; -import ComponentPageLayout from '../../../layouts/ComponentPageLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +} from "@twilio-paste/pagination"; +import { Button } from "@twilio-paste/button"; +import { Table, THead, TBody, Th, Td, Tr } from "@twilio-paste/table"; +import { Grid, Column } from "@twilio-paste/grid"; +import { UnorderedList, ListItem } from "@twilio-paste/list"; +import { Stack } from "@twilio-paste/stack"; +import Changelog from "@twilio-paste/pagination/CHANGELOG.md"; +import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; + +import { DoDont, Do, Dont } from "../../../components/DoDont"; +import { Codeblock } from "../../../components/codeblock"; +import { SidebarCategoryRoutes } from "../../../constants"; +import { defaultExample, numberExample, positioningExample } from "../../../component-examples/PaginationExamples"; +import packageJson from "@twilio-paste/pagination/package.json"; +import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; export default ComponentPageLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Pagination'); + const feature = await getFeature("Pagination"); return { props: { data: { @@ -51,15 +52,15 @@ export const getStaticProps = async () => { mdxHeadings, pageHeaderData: { categoryRoute: SidebarCategoryRoutes.COMPONENTS, - githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/pagination', - storybookUrl: '/?path=/story/components-pagination--arrows', + githubUrl: "https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/pagination", + storybookUrl: "/?path=/story/components-pagination--arrows", }, }, }; }; {` @@ -109,7 +110,7 @@ Use the default Pagination component for paged datasets like event logs, where t At minimum, the default Pagination component shows the Pagination arrows. However whenever possible, show the **current** page number too, so that users know where they are in a dataset and get confirmation that they’ve moved to a new page. - + {defaultExample} @@ -117,7 +118,7 @@ At minimum, the default Pagination component shows the Pagination arrows. Howeve Use Pagination as an anchor if the URL changes for each page. Both the `PaginationArrow` and `PaginationNumber` components can be set as anchors using the `as="a"` prop and including an `href` prop. - + {` @@ -139,7 +140,7 @@ Use Pagination as an anchor if the URL changes for each page. Both the `Paginati Use Pagination as a button if the URL doesn’t change for each page. Both the `PaginationArrow` and `PaginationNumber` components are buttons by default. - + {` @@ -161,7 +162,7 @@ Use Pagination as a button if the URL doesn’t change for each page. Both the ` Adding labels to Pagination can help give customers more information about what kind of data is in view and in what direction the pages are moving. For example, when a dataset is sorted chronologically, it might not be immediately clear whether the "Next" button takes you forward or backward in time. - + {`<> @@ -179,7 +180,7 @@ To give customers further clarity on where they are in a data set, you can add c - The current page label - The left and right arrow controls - + {` @@ -198,7 +199,7 @@ This variant also allows customers to skip ahead pages in a dataset, though this Considering the tradeoffs for showing the total count of a dataset - By default,{' '} + By default,{" "} Twilio APIs might not support showing current page number or the total count of a dataset @@ -269,7 +270,15 @@ The Pagination component should be centered underneath the content it controls s When the number of pages exceeds 7, `PaginationEllipsis` can be used to indicate there are remaining pages. {` @@ -309,7 +318,7 @@ When the number of pages exceeds 7, `PaginationEllipsis` can be used to indicate Double `PaginationEllipsis` is used when the current page is more than 3 pages from the first or last page. {` @@ -343,17 +352,18 @@ Most Twilio datasets show 10 or 50 rows per page by default. However, a generic If a single default can’t satisfy customers’ needs, you can give customers a way to change the number of items in view. Try to keep these options limited to reduce cognitive overhead, especially if the choice isn’t critical to the customer’s main goal. -
- Many sites let users choose how many items they’ll see on each page. This is often overkill...It’s usually better to - offer a single default number — such as 10 or 20 — [or] give users the choice between two numbers, say 10 and 50, - where the second number is substantially bigger than the default. If the choice is between two relatively similar - numbers (such as 10 and 20), users might as well click the Next Page button rather than suffer the cognitive overhead - of trying to decide their display preference. -
+ +
+ + Many sites let users choose how many items they’ll see on each page. This is often overkill...It’s usually better + to offer a single default number — such as 10 or 20 — [or] give users the choice between two numbers, say 10 and + 50, where the second number is substantially bigger than the default. If the choice is between two relatively + similar numbers (such as 10 and 20), users might as well click the Next Page button rather than suffer the + cognitive overhead of trying to decide their display preference. + + +
+ Consider [contributing a Table Actions pattern](/introduction/contributing/patterns) to help standardize this across Twilio! diff --git a/packages/paste-website/src/pages/components/switch/index.mdx b/packages/paste-website/src/pages/components/switch/index.mdx index 83440aba57..8ac51f74b8 100644 --- a/packages/paste-website/src/pages/components/switch/index.mdx +++ b/packages/paste-website/src/pages/components/switch/index.mdx @@ -1,19 +1,20 @@ export const meta = { - title: 'Switch', - package: '@twilio-paste/switch', - description: 'A Switch is an interactive binary control.', - slug: '/components/switch/', + title: "Switch", + package: "@twilio-paste/switch", + description: "A Switch is an interactive binary control.", + slug: "/components/switch/", }; -import {Anchor} from '@twilio-paste/anchor'; -import {Avatar} from '@twilio-paste/avatar'; -import {Text} from '@twilio-paste/text'; -import {Box} from '@twilio-paste/box'; -import {Switch, SwitchGroup} from '@twilio-paste/switch'; -import {HelpText} from '@twilio-paste/help-text'; -import {useUID} from '@twilio-paste/uid-library'; -import {SidebarCategoryRoutes} from '../../../constants'; -import {Blockquote} from '../../../components/Blockquote'; +import { Anchor } from "@twilio-paste/anchor"; +import { Avatar } from "@twilio-paste/avatar"; +import { Text } from "@twilio-paste/text"; +import { Box } from "@twilio-paste/box"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; +import { Switch, SwitchGroup } from "@twilio-paste/switch"; +import { HelpText } from "@twilio-paste/help-text"; +import { useUID } from "@twilio-paste/uid-library"; + +import { SidebarCategoryRoutes } from "../../../constants"; import { basicSwitch, helpTextSwitch, @@ -25,16 +26,16 @@ import { controlledSwitch, switchGroup, switchGroupInternationalized, -} from '../../../component-examples/SwitchExamples.ts'; -import packageJson from '@twilio-paste/switch/package.json'; -import ComponentPageLayout from '../../../layouts/ComponentPageLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +} from "../../../component-examples/SwitchExamples.ts"; +import packageJson from "@twilio-paste/switch/package.json"; +import ComponentPageLayout from "../../../layouts/ComponentPageLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; export default ComponentPageLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Switch'); + const feature = await getFeature("Switch"); return { props: { data: { @@ -45,14 +46,14 @@ export const getStaticProps = async () => { mdxHeadings, pageHeaderData: { categoryRoute: SidebarCategoryRoutes.COMPONENTS, - githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/switch', - storybookUrl: '/?path=/story/components-switch--default-switch', + githubUrl: "https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/switch", + storybookUrl: "/?path=/story/components-switch--default-switch", }, }, }; }; - + {basicSwitch} @@ -66,15 +67,16 @@ Use Switch when the interaction result is **immediate**. Users shouldn't need to Use a [Checkbox](/components/checkbox) to present a user with a single binary choice that is part of a form or otherwise requires a user to take an additional action to confirm input. -
- Users expect the same immediate results from a digital toggle as they do from their real-world counterparts (e.g., - light switches). Immediate results are a facet of toggle switches that grants users the freedom and control to update - their preferences as needed. -
+ +
+ + Users expect the same immediate results from a digital toggle as they do from their real-world counterparts (e.g., + light switches). Immediate results are a facet of toggle switches that grants users the freedom and control to + update their preferences as needed. + + +
+ ### Accessibility @@ -94,13 +96,13 @@ The Switch can either be controlled, meaning there is an external state that det To make an uncontrolled Switch, you do not pass the `checked` or `onChange` prop. - + {uncontrolledSwitch} To make a controlled Switch, you must pass the `checked` and `onChange` prop. - + {controlledSwitch} @@ -110,7 +112,7 @@ To make a controlled Switch, you must pass the `checked` and `onChange` prop. A Switch is always displayed with a visible label. The _label text should never change_ based on the state of the Switch. - + {basicSwitch} @@ -118,7 +120,7 @@ A Switch is always displayed with a visible label. The _label text should never In cases where the Switch requires additional context, you can display this information as help text below the Switch and label. This can help keep Switch labels concise. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. - + {helpTextSwitch} @@ -127,7 +129,7 @@ In cases where the Switch requires additional context, you can display this info When a Switch is required to be 'on', a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user. - + {requiredSwitch} @@ -136,7 +138,7 @@ The label text should also be written in such a way that this requirement is cle Use a disabled Switch to indicate to users that it is not interactive. If interactivity is dependent on another action, make that clear using help text. - + {disabledSwitch} @@ -145,7 +147,7 @@ is dependent on another action, make that clear using help text. Multiple Switches and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any Switch or other content. - + {switchGroup} @@ -154,7 +156,7 @@ The group legend must be the first element inside the group. It must appear befo To internationalize a Switch, simply pass different text to the Switch and SwitchGroup. The only exception to this is the required dot in the legend of a required SwitchGroup. To change the required dot's text, use the `i18nRequiredLabel` prop. - + {switchGroupInternationalized} @@ -164,7 +166,7 @@ the required dot in the legend of a required SwitchGroup. To change the required The default Switch state is off. - + {onSwitch} @@ -173,7 +175,7 @@ The default Switch state is off. Use the disabled on Switch to indicate to users that it is not interactive and cannot be turned off. If interactivity is dependent on another action, make that clear using help text. - + {disabledOnSwitch} diff --git a/packages/paste-website/src/pages/experiences/artificial-intelligence/index.mdx b/packages/paste-website/src/pages/experiences/artificial-intelligence/index.mdx index 158ce4a9aa..30881b576f 100644 --- a/packages/paste-website/src/pages/experiences/artificial-intelligence/index.mdx +++ b/packages/paste-website/src/pages/experiences/artificial-intelligence/index.mdx @@ -1,40 +1,41 @@ export const meta = { - title: 'Artificial Intelligence', + title: "Artificial Intelligence", description: - 'AI experiences help our customers meet their goals better and faster through predictions, recommendations, and insights.', - slug: '/experiences/artificial-intelligence/', + "AI experiences help our customers meet their goals better and faster through predictions, recommendations, and insights.", + slug: "/experiences/artificial-intelligence/", }; -import { SidebarCategoryRoutes } from "../../../constants"; -import {ResponsiveImage} from '../../../components/ResponsiveImage'; -import {Blockquote} from '../../../components/Blockquote'; -import {Anchor} from '@twilio-paste/anchor'; -import {ArtificialIntelligenceIcon} from '@twilio-paste/icons/esm/ArtificialIntelligenceIcon'; -import {Button} from '@twilio-paste/button'; -import {ButtonGroup} from '@twilio-paste/button-group'; -import {Badge} from '@twilio-paste/badge'; -import {Box} from '@twilio-paste/box'; -import {ChatComposerContainer, ChatComposer, ChatComposerActionGroup} from '@twilio-paste/chat-composer'; -import {SendIcon} from '@twilio-paste/icons/esm/SendIcon'; -import {Label} from '@twilio-paste/label'; -import {TextArea} from '@twilio-paste/textarea'; -import {HelpText} from '@twilio-paste/help-text'; -import {Callout, CalloutHeading, CalloutText} from '@twilio-paste/callout'; -import {Heading} from '@twilio-paste/heading'; -import {Popover, PopoverContainer, PopoverButton} from '@twilio-paste/popover'; -import {NewIcon} from '@twilio-paste/icons/esm/NewIcon'; +import { Anchor } from "@twilio-paste/anchor"; +import { ArtificialIntelligenceIcon } from "@twilio-paste/icons/esm/ArtificialIntelligenceIcon"; +import { Button } from "@twilio-paste/button"; +import { ButtonGroup } from "@twilio-paste/button-group"; +import { Badge } from "@twilio-paste/badge"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; +import { Box } from "@twilio-paste/box"; +import { ChatComposerContainer, ChatComposer, ChatComposerActionGroup } from "@twilio-paste/chat-composer"; +import { SendIcon } from "@twilio-paste/icons/esm/SendIcon"; +import { Label } from "@twilio-paste/label"; +import { TextArea } from "@twilio-paste/textarea"; +import { HelpText } from "@twilio-paste/help-text"; +import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; +import { Heading } from "@twilio-paste/heading"; +import { Popover, PopoverContainer, PopoverButton } from "@twilio-paste/popover"; +import { NewIcon } from "@twilio-paste/icons/esm/NewIcon"; import { ProductMessagingIcon } from "@twilio-paste/icons/esm/ProductMessagingIcon"; import { ProductSendGridIcon } from "@twilio-paste/icons/esm/ProductSendGridIcon"; import { ProductCLIIcon } from "@twilio-paste/icons/esm/ProductCLIIcon"; -import {Paragraph} from '@twilio-paste/paragraph'; -import DefaultLayout from '../../../layouts/DefaultLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; +import { Paragraph } from "@twilio-paste/paragraph"; + +import DefaultLayout from "../../../layouts/DefaultLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; +import { SidebarCategoryRoutes } from "../../../constants"; +import { ResponsiveImage } from "../../../components/ResponsiveImage"; export default DefaultLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Artificial Intelligence'); + const feature = await getFeature("Artificial Intelligence"); return { props: { data: { @@ -45,9 +46,12 @@ export const getStaticProps = async () => { }; }; - - - + @@ -55,7 +59,22 @@ export const getStaticProps = async () => { - + {` @@ -98,30 +117,38 @@ These AI experience guidelines are a starting point for designing AI-powered exp These guidelines reference “Twilio Segment’s AI Handbook for Product Development”. The full handbook includes information that can’t be publicly shared yet, including: - Which user problems AI solutions are and aren’t good for. -- A breakdown of customer types, user journeys, and AI feature types. +- A breakdown of customer types, user journeys, and AI feature types. - Research insights on what customers consider high-risk vs. low-risk features. - A list of biases to prevent against. -- Methods of conducting research at different design phases, especially when the AI model isn’t developed enough for customer testing. +- Methods of conducting research at different design phases, especially when the AI model isn’t developed enough for customer testing. You can find a link in #seg-ai-handbook-feedback on Slack, or reach out to your design partner. ## Twilio policies When developing AI features, ensure you: + - **(Mandatory)** Partner with the Legal and Privacy teams to communicate Twilio’s terms and conditions, and include any opt-in requirements. Start by submitting a Privacy Impact Assessment (more details in Switchboard). - Follow Twilio’s AI approach, including the trust principles: **Transparent, Responsible, Accountable**. Refer to the AI Handbook for practical guidelines on how to achieve these principles. - Review these policies: “Generative AI policy”, “AI responsible use policy”, and “Global procurement policy.” Links to each are in the AI handbook. - - Standardized legal language and opt-in guidance for AI features is in development - If you’re working on a new feature and need legal text, reach out in #help-design-system to get connected with teams who are working to standardize our legal language for AI. While this is happening, continue partnering with Privacy and Legal for your feature. + + + Standardized legal language and opt-in guidance for AI features is in development + + + If you’re working on a new feature and need legal text, reach out in #help-design-system to get connected with + teams who are working to standardize our legal language for AI. While this is happening, continue partnering with + Privacy and Legal for your feature. + ## Designing AI features Start with these base design principles: + 1. Follow Twilio AI policies. 2. Inform users about data privacy. 3. Ensure customers can evaluate AI outcomes, fast, by allowing them to compare those outcomes to their current experience. @@ -131,6 +158,7 @@ Start with these base design principles: 7. Build customers’ confidence in the output. Helpful resources on how to design human-centered AI experiences: + - [Twilio’s generative AI design framework cards](https://www.figma.com/community/file/1392507403743352508/generative-ai-design-framework) - [Shape of AI](https://www.shapeof.ai/) - [Google’s people + AI guidebook](https://pair.withgoogle.com/guidebook) @@ -147,6 +175,7 @@ When using Twilio AI features, customers care most about **data privacy** and th Based on your use case, you might also include information about how the AI model works and when customers’ data quality can improve AI feature performance. Since AI can power a wide range of features, customers can be unsure where to start. Use [Twilio’s generative AI design framework cards](https://www.figma.com/community/file/1392507403743352508/generative-ai-design-framework) and the [Shape of AI wayfinders](https://www.shapeof.ai/pattern-types/wayfinders) to prompt customers to the feature and describe it in a simple way, so that they can evaluate AI outcomes faster. When introducing the feature, let customers know: + - How they can give feedback - How they can ask questions - What they should consider as they use the feature so they can ask the _right questions_, especially about their data and generated outcomes. @@ -159,16 +188,20 @@ While AI features are still in rapid development, work with your Product Marketi Just because AI features are new, doesn’t mean we need to invent entirely new visual and interaction patterns for them. Start by asking yourself first: **“How would I design this feature if it did the same thing but didn’t use AI?”** Remember that customers have specific goals and tasks to achieve, and the task is rarely just “To use AI”. Avoid being too heavy-handed with communicating how a feature has been built or changed with AI since introducing new interaction patterns and unnecessary messaging can distract from the customer’s goals. -
-With AI-driven products, there can be a temptation to communicate the “newness” or “magic” of the system’s predictions through its UI metaphors. -However, unfamiliar UI touchpoints can make it harder for users to learn to use your system, potentially leading to degraded understanding of, or trust in, your product…Instead, anchor new users with familiar UI patterns and features. -
+ +
+ + With AI-driven products, there can be a temptation to communicate the “newness” or “magic” of the system’s + predictions through its UI metaphors. However, unfamiliar UI touchpoints can make it harder for users to learn to + use your system, potentially leading to degraded understanding of, or trust in, your product…Instead, anchor new + users with familiar UI patterns and features. + + +
+ With AI features, there’s also a higher chance for things to go wrong. Be proactive about risks, error handling, and confidence: + - Give customers the ability to review, edit, undo, and give feedback on output. - Design for poor data, common errors, biases, and customers being overly dependent on AI suggestions. Use the [error state pattern](/patterns/error-state) for ways to message errors. - Show clear information that AI-generated output can be wrong or irrelevant. @@ -184,6 +217,7 @@ During your pilot or beta, collect customer feedback at least twice. Compared to ### Content produced by AI In addition to AI features, content you produce with the help of AI should adhere to these basic guidelines: + - If a substantial amount of your work relied on AI, clearly state that. If possible, link to the model you used. - Fact check the AI-produced content. LLMs produce hallucinations, resulting in content that is inconsistent with real-work facts or user inputs. - Make sure the AI-produced content doesn’t violate Twilio policies, especially copyright and intellectual property. @@ -196,6 +230,7 @@ Learn more on the [Twilio Style Guide](https://library.twilio.com/guidelines/gui ## Ingredients The AI UI Kit includes these components: + - [ArtificialIntelligenceIcon](/components/icon) - [Badge](/components/badge) - [Button](/components/button) @@ -203,26 +238,36 @@ The AI UI Kit includes these components: - [Skeleton Loader](/components/skeleton-loader) Components also used for AI chat experiences: + - [AI Chat Log](/components/ai-chat-log) - [Avatar](/components/avatar) - [Chat Composer](/components/chat-composer) - [Side Panel](/components/side-panel) Related patterns: + - [Error state](/patterns/error-state) - - Need more AI components? - Our AI Kit was first designed primarily with chat and basic predictive and generative experiences in mind. If these components and patterns don’t meet your needs, please let us know in a Github Discussion. + + Need more AI components? + + Our AI Kit was first designed primarily with chat and basic predictive and generative experiences in mind. If + these components and patterns don’t meet your needs, please let us know in a{" "} + + Github Discussion + + . + ## Examples -### Signposting +### Signposting When you need to indicate that a feature is using AI for transparency and/or marketing, use a `decorative20` Badge and the ArtificialIntelligenceIcon to help customers quickly identify these features, especially for: + - Recommendations - Predictions and insights - Automated tasks @@ -231,7 +276,7 @@ If you need to highlight the feature even more, use the marketing [Card](/compon Keep in mind that over time, more and more of our features will use AI. Evaluate an experience holistically, and use AI badges and marketing when they matter most. Don’t blanket an experience in AI marketing at the expense of other business goals. - + {` Twilio AI `} @@ -239,9 +284,26 @@ Keep in mind that over time, more and more of our features will use AI. Evaluate ### Generative feature -Use [Twilio’s generative AI design framework cards](https://www.figma.com/community/file/1392507403743352508/generative-ai-design-framework) and the [Shape of AI wayfinders](https://www.shapeof.ai/pattern-types/wayfinders) to prompt customers to a generative AI feature. - - +Use [Twilio’s generative AI design framework cards](https://www.figma.com/community/file/1392507403743352508/generative-ai-design-framework) and the [Shape of AI wayfinders](https://www.shapeof.ai/pattern-types/wayfinders) to prompt customers to a generative AI feature. + + {` Help me build @@ -264,9 +326,12 @@ For a chat-based AI experience, handle most errors, flows, and interactions thro To develop a prompt and personality for the chat assistant, use [Twilio’s Voice and Tone guidelines](/foundations/content/voice-and-tone), especially emphasizing the “Conversational” principle of our guidelines. - - Want support with prompt engineering? - Reach out in a Github Discussion for prompt engineering support from a Content Designer to develop your chat assistant with Twilio Voice and Tone principles. + + Want support with prompt engineering? + + Reach out in a Github Discussion for prompt engineering support from a Content Designer to develop your chat + assistant with Twilio Voice and Tone principles. + @@ -294,7 +359,22 @@ export const SidePanelExample = (): React.ReactNode => { #### Chat empty state - + {` @@ -330,12 +410,16 @@ export const SidePanelExample = (): React.ReactNode => { `} -### Loading +### Loading - - More details about this pattern are coming soon! - We haven’t yet patternized a general Loading pattern. If you need more details and standard examples for your feature, please consider partnering with us to contribute it. + + More details about this pattern are coming soon! + + We haven’t yet patternized a general Loading pattern. If you need more details and standard examples for your + feature, please consider partnering with us to{" "} + contribute it. + diff --git a/packages/paste-website/src/pages/patterns/filter/index.mdx b/packages/paste-website/src/pages/patterns/filter/index.mdx index 2468ba3197..44a068d253 100644 --- a/packages/paste-website/src/pages/patterns/filter/index.mdx +++ b/packages/paste-website/src/pages/patterns/filter/index.mdx @@ -1,35 +1,36 @@ export const meta = { - title: 'Filter', - description: 'Filters enable users to narrow down and refine results across various types of content pages, including rich content pages, data tables, lists, data insights, and more.', - slug: '/patterns/filter/', + title: "Filter", + description: + "Filters enable users to narrow down and refine results across various types of content pages, including rich content pages, data tables, lists, data insights, and more.", + slug: "/patterns/filter/", }; -import {Anchor} from '@twilio-paste/anchor'; -import {Box} from '@twilio-paste/box'; -import {Card} from '@twilio-paste/card'; -import {Grid, Column} from '@twilio-paste/grid'; -import {Heading} from '@twilio-paste/heading'; -import {Callout, CalloutHeading, CalloutText} from '@twilio-paste/callout'; -import {UnorderedList, OrderedList, ListItem} from '@twilio-paste/list' -import {DoDont, Do, Dont} from '../../../components/DoDont'; - -import DefaultLayout from '../../../layouts/DefaultLayout'; -import {getFeature, getNavigationData} from '../../../utils/api'; -import {Blockquote} from '../../../components/Blockquote'; -import {ResponsiveImage} from '../../../components/ResponsiveImage'; -import MainImage from '../../../assets/images/patterns/filter-main.png'; -import UsageImage from '../../../assets/images/patterns/filter-usage.png'; -import FilterBarImage from '../../../assets/images/patterns/filter-filter_bar.png'; -import FetchingImage from '../../../assets/images/patterns/filter-fetching.png'; -import DynamicImage from '../../../assets/images/patterns/filter-dynamic.png'; -import Responsive1Image from '../../../assets/images/patterns/filter-responsive.png'; -import Responsive2Image from '../../../assets/images/patterns/filter-responsive_2.png'; +import { Anchor } from "@twilio-paste/anchor"; +import { Box } from "@twilio-paste/box"; +import { Card } from "@twilio-paste/card"; +import { Grid, Column } from "@twilio-paste/grid"; +import { Heading } from "@twilio-paste/heading"; +import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; +import { UnorderedList, OrderedList, ListItem } from "@twilio-paste/list"; +import { Blockquote, BlockquoteContent, BlockquoteCitation } from "@twilio-paste/blockquote"; + +import { DoDont, Do, Dont } from "../../../components/DoDont"; +import DefaultLayout from "../../../layouts/DefaultLayout"; +import { getFeature, getNavigationData } from "../../../utils/api"; +import { ResponsiveImage } from "../../../components/ResponsiveImage"; +import MainImage from "../../../assets/images/patterns/filter-main.png"; +import UsageImage from "../../../assets/images/patterns/filter-usage.png"; +import FilterBarImage from "../../../assets/images/patterns/filter-filter_bar.png"; +import FetchingImage from "../../../assets/images/patterns/filter-fetching.png"; +import DynamicImage from "../../../assets/images/patterns/filter-dynamic.png"; +import Responsive1Image from "../../../assets/images/patterns/filter-responsive.png"; +import Responsive2Image from "../../../assets/images/patterns/filter-responsive_2.png"; export default DefaultLayout; export const getStaticProps = async () => { const navigationData = await getNavigationData(); - const feature = await getFeature('Filter'); + const feature = await getFeature("Filter"); return { props: { data: { @@ -40,12 +41,8 @@ export const getStaticProps = async () => { }; }; - - - - @@ -58,14 +55,14 @@ export const getStaticProps = async () => { // import the components for filter group patterns as required import { FormPillGroup, useFormPillState } from "@twilio-paste/core/form-pill-group"; -import {Input} from '@twilio-paste/core/input'; -import {MultiselectCombobox, useMultiselectCombobox} from "@twilio-paste/core/combobox"; -import {Button} from '@twilio-paste/core/button'; -import {ButtonGroup} from "@twilio-paste/core/button-group"; -import {Disclosure, DisclosureContent, DisclosureHeading} from "@twilio-paste/core/disclosure"; -import {Badge} from "@twilio-paste/core/badge"; -import {Checkbox, CheckboxGroup} from "@twilio-paste/core/checkbox"; -import {Radio, RadioGroup} from "@twilio-paste/core/radio-group"; +import { Input } from "@twilio-paste/core/input"; +import { MultiselectCombobox, useMultiselectCombobox } from "@twilio-paste/core/combobox"; +import { Button } from "@twilio-paste/core/button"; +import { ButtonGroup } from "@twilio-paste/core/button-group"; +import { Disclosure, DisclosureContent, DisclosureHeading } from "@twilio-paste/core/disclosure"; +import { Badge } from "@twilio-paste/core/badge"; +import { Checkbox, CheckboxGroup } from "@twilio-paste/core/checkbox"; +import { Radio, RadioGroup } from "@twilio-paste/core/radio-group"; import { Popover, PopoverButton, PopoverContainer, usePopoverState } from "@twilio-paste/core/popover"; ``` @@ -80,33 +77,65 @@ This pattern provides recommendations for selection methods, layout, and behavio Familiarize yourself with your feature’s filter values and categories. List all filtering criteria available. - Map out the relationships between different filters and choose the ones that will be part of your feature. Remember filters should give users a sense of control and not overwhelm them. -
- A truly usable faceted search provides filter categories and filter values that are appropriate, predictable, free of jargon, and prioritized -
+ + Map out the relationships between different filters and choose the ones that will be part of your feature. + Remember filters should give users a sense of control and not overwhelm them. + + +
+ + A truly usable faceted search provides filter categories and filter values that are appropriate, predictable, + free of jargon, and prioritized + + +
+ - Check our Form documentation to choose the best selection method for your filter use case. + + Check our Form documentation to choose the best + selection method for your filter use case. + Determine users' intent and their relationship with the product and dataset. - Categorize filters into the most relevant and commonly used filters versus the more advanced or less used ones. - Determine how many different types of users will access the feature and how much the filtering criteria will vary from use case to use case. If necessary, consider allowing users to add custom filters to provide a more tailored experience. - Identify any filter values that naturally lead to additional refinement options, and consider implementing conditional filters. + + Categorize filters into the most relevant and commonly used filters versus the more advanced or less used ones. + + + Determine how many different types of users will access the feature and how much the filtering criteria will + vary from use case to use case. If necessary, consider allowing users to{" "} + add custom filters to provide a more tailored experience. + + + Identify any filter values that naturally lead to additional refinement options, and consider implementing{" "} + conditional filters. + Determine any technical constraints. - Ensure you have a good understanding of how the data is set up, including which filtering behaviors and combinations are not possible. - Evaluate carefully the best filtering behavior for fetching results. Keep in mind user intent, but also loading times and the size of the dataset. - Ensure that all filter options correspond to data present in the results. Avoid including filters for data that are not visible or accessible within the dataset. - Evaluate the expected growth of your filtering criteria and ensure it can manage larger datasets without notable performance decline. + + Ensure you have a good understanding of how the data is set up, including which filtering behaviors and + combinations are not possible. + + + Evaluate carefully the best filtering behavior for fetching results. + Keep in mind user intent, but also loading times and the size of the dataset. + + + Ensure that all filter options correspond to data present in the results. Avoid including filters for data that + are not visible or accessible within the dataset. + + + Evaluate the expected growth of your filtering criteria and ensure it can manage larger datasets without notable + performance decline. + @@ -114,15 +143,20 @@ This pattern provides recommendations for selection methods, layout, and behavio ### Accessibility When using the filter pattern, ensure that users: + Can easily identify and understand labels for each selection method, filter value, or category. - Are notified of state changes. For example, when a button changes from the disabled state to the default state, or when the dataset enters a loading state. + + Are notified of state changes. For example, when a button changes from the disabled state to the default state, or + when the dataset enters a loading state. + Can complete all actions with the keyboard. - Check accessibility considerations for each component part of the filter feature, for example if you’re using Time Picker, follow its accessibility guidelines. + Check accessibility considerations for each component part of the filter feature, for example if you’re using Time + Picker, follow its accessibility guidelines. @@ -135,6 +169,7 @@ A filter bar is the default way of displaying filters. Use it when all filters are relevant and necessary to the search. It can also be used in combination with a [More filters Side Panel](#more-filters-side-panel) when there are secondary filter criteria. #### Ingredients + - [Heading](/components/heading) - [Form Pill Group](/components/form-pill-group) - [Detail Text](/components/detail-text) (for number of results) @@ -205,19 +240,39 @@ export const FilterPatternExample = ({data}): React.ReactNode => { /> #### Surfacing results + - When a filter value is selected by the user, the corresponding Form Pill will enter a selected state. - When a single filter value is selected, the filter updates to display the name of the selected filter. - When two or more filter values are selected per filter category, the total number of selected filters will be displayed in a counter badge. - In some scenarios, it is necessary to have filter values pre-selected by default to display results. Since the selection was not made by the user, the Form Pill will remain in its default state, displaying the pre-selected filter value. + + When a filter value is selected by the user, the corresponding Form Pill will enter a selected state. + + + When a single filter value is selected, the filter updates to display the name of the selected filter. + + + When two or more filter values are selected per filter category, the total number of selected filters will be + displayed in a counter badge. + + + In some scenarios, it is necessary to have filter values pre-selected by default to display results. Since the + selection was not made by the user, the Form Pill will remain in its default state, displaying the pre-selected + filter value. + - +{" "} + + - - + + ### More filters Side Panel @@ -225,6 +280,7 @@ export const FilterPatternExample = ({data}): React.ReactNode => { Use it in scenarios where the list of filters is extensive and there are filters that are not a priority to the search. Prioritize the most relevant and commonly used filters in the filter bar for visibility, while offering advanced filtering options in a Side Panel. #### Ingredients + - [Secondary rounded Button](/components/button#rounded-small-button) (for more filters) - [Side Panel](/components/side-panel) - [Neutral counter Badge](/components/badge) @@ -321,12 +377,18 @@ export const MoreFilterPatternExample = ({data, filterList}): React.ReactNode => #### Surfacing results - In the “More filters” Side Panel when filters are selected, a counter Badge will be displayed in the right corner of the filter value (disclosure) + + In the “More filters” Side Panel when filters are selected, a counter Badge will be displayed in the right corner of + the filter value (disclosure) + “More filters” Button will have a counter Badge with the number of selected filter values. - + @@ -451,19 +513,28 @@ export const AddFilterPatternExample = ({data, filterList}): React.ReactNode => /> #### Surfacing results + Selected filters will be added to the filter bar where they will become functional. Added filters behave as a normal filter with the only difference being they can be removed. - Added filters can be removed through the “Add filters” Popover or through the specific filter’s Popover. + + Added filters can be removed through the “Add filters” Popover or through the specific filter’s Popover. + - - + + ## Composition @@ -619,12 +690,17 @@ Use it when filter selections naturally lead to additional criteria, or where ce Batch filtering requires the user to click an “Apply” button to see the results. - +{" "} + Use batch filtering when: + - There are categories with multiple interdependent filter values, and the user might want to take more time selecting the right group of filters. + + There are categories with multiple interdependent filter values, and the user might want to take more time selecting + the right group of filters. + The dataset cannot be refreshed automatically and the system needs time to load the data. You want to prevent "no results" scenarios. @@ -635,18 +711,25 @@ To load results: Once the user clicks the "Apply" button, the Popover will autom Dynamic filters are applied as soon as a filter selection is made. - +{" "} + + Use dynamic filtering when: + - The filter experience is more explorative and users need to play around with the filters to find their desired results. + + The filter experience is more explorative and users need to play around with the filters to find their desired + results. + The user is expected to make multiple quick filter changes during the task. - - Be cautious when dynamically updating results, as they can divert user attention. - + Be cautious when dynamically updating results, as they can divert user attention. To load results: Dynamic filtering is designed to allow users to experiment with different filters. The Popover will remain open until the user closes it, while the results load in the background. @@ -727,12 +810,18 @@ A clear filter option will be available when filters are selected. By default, " On mobile screen sizes, consolidate all filter options under a "Filter" button to optimize screen space and usability. - +{" "} + + At smaller screen sizes, filter Pills will overflow onto the next row. All other actions (such as "More filters", “Add filters”, "Clear all” and table actions) move to the last row to maintain a clean and organized layout. - +{" "} + From 3d265c9c3a9d0163a56abe0ee7eff46ac490015b Mon Sep 17 00:00:00 2001 From: Kristian Antrobus Date: Mon, 2 Dec 2024 12:54:25 -0600 Subject: [PATCH 2/2] chore(website): add blockquote to docs site deps --- packages/paste-website/package.json | 1 + yarn.lock | 1 + 2 files changed, 2 insertions(+) diff --git a/packages/paste-website/package.json b/packages/paste-website/package.json index 3839473171..e494a5989a 100644 --- a/packages/paste-website/package.json +++ b/packages/paste-website/package.json @@ -43,6 +43,7 @@ "@twilio-paste/avatar": "^9.1.0", "@twilio-paste/badge": "^8.3.1", "@twilio-paste/base-radio-checkbox": "^13.1.0", + "@twilio-paste/blockquote": "^0.0.0", "@twilio-paste/box": "^10.3.0", "@twilio-paste/breadcrumb": "^11.1.1", "@twilio-paste/button": "^14.1.2", diff --git a/yarn.lock b/yarn.lock index 1c254da49f..05b5a84731 100644 --- a/yarn.lock +++ b/yarn.lock @@ -16128,6 +16128,7 @@ __metadata: "@twilio-paste/avatar": ^9.1.0 "@twilio-paste/badge": ^8.3.1 "@twilio-paste/base-radio-checkbox": ^13.1.0 + "@twilio-paste/blockquote": ^0.0.0 "@twilio-paste/box": ^10.3.0 "@twilio-paste/breadcrumb": ^11.1.1 "@twilio-paste/button": ^14.1.2