diff --git a/.changeset/fair-owls-hug.md b/.changeset/fair-owls-hug.md new file mode 100644 index 00000000000..64f44e9e7b6 --- /dev/null +++ b/.changeset/fair-owls-hug.md @@ -0,0 +1,5 @@ +--- +'polaris.shopify.com': patch +--- + +Use description and title front matter for pages rendered from /content diff --git a/polaris.shopify.com/content/components/account-connection/index.md b/polaris.shopify.com/content/components/account-connection/index.md index 791a391220c..afce145dd89 100644 --- a/polaris.shopify.com/content/components/account-connection/index.md +++ b/polaris.shopify.com/content/components/account-connection/index.md @@ -1,5 +1,6 @@ --- title: Account connection +description: The account connection component is used so merchants can connect or disconnect their store to various accounts. For example, if merchants want to use the Facebook sales channel, they need to connect their Facebook account to their Shopify store. category: Actions keywords: - AccountConnection @@ -19,12 +20,6 @@ examples: description: Use to let merchants connect or disconnect their store to their third-party accounts, like Facebook. --- -# Account connection - -The account connection component is used so merchants can connect or disconnect their store to various accounts. For example, if merchants want to use the Facebook sales channel, they need to connect their Facebook account to their Shopify store. - ---- - ## Best practices The account component should: diff --git a/polaris.shopify.com/content/components/action-list/index.md b/polaris.shopify.com/content/components/action-list/index.md index 1e19a01ba88..a0848922c36 100644 --- a/polaris.shopify.com/content/components/action-list/index.md +++ b/polaris.shopify.com/content/components/action-list/index.md @@ -1,5 +1,6 @@ --- title: Action list +description: Action lists render a list of actions or selectable options. This component is usually placed inside a [popover container](https://polaris.shopify.com/components/popover) to create a dropdown menu or to let merchants select from a list of options. category: Actions keywords: - ActionList @@ -35,12 +36,6 @@ examples: description: Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant. --- -# Action list - -Action lists render a list of actions or selectable options. This component is usually placed inside a [popover container](https://polaris.shopify.com/components/popover) to create a dropdown menu or to let merchants select from a list of options. - ---- - ## Best practices Actions lists should: diff --git a/polaris.shopify.com/content/components/app-provider/index.md b/polaris.shopify.com/content/components/app-provider/index.md index 6ade1a79990..8b9ec459747 100644 --- a/polaris.shopify.com/content/components/app-provider/index.md +++ b/polaris.shopify.com/content/components/app-provider/index.md @@ -1,5 +1,6 @@ --- title: App provider +description: App provider is a required component that enables sharing global settings throughout the hierarchy of your application. category: Structure keywords: - app @@ -29,12 +30,6 @@ examples: description: With a `colorScheme`, the app provider component will set the root color scheme for the App (such as light or dark). For `colorScheme` configuration, see the [CustomProperties](https://polaris.shopify.com/components/custom-properties) component documentation. --- -# App provider - -App provider is a required component that enables sharing global settings throughout the hierarchy of your application. - ---- - ## Best practices The app provider component is required to use Polaris. Without it, the components in your application will not function correctly. You must wrap the root (the top) of your application in the app provider component. diff --git a/polaris.shopify.com/content/components/autocomplete/index.md b/polaris.shopify.com/content/components/autocomplete/index.md index 39d057cef69..d990f14d914 100644 --- a/polaris.shopify.com/content/components/autocomplete/index.md +++ b/polaris.shopify.com/content/components/autocomplete/index.md @@ -1,5 +1,6 @@ --- title: Autocomplete +description: The autocomplete component is an input field that provides selectable suggestions as a merchant types into it. It allows merchants to quickly search through and select from large collections of options. It's a convenience wrapper around the `Combobox` and `Listbox` components with minor UI differences. category: Forms keywords: - autocomplete @@ -36,12 +37,6 @@ examples: description: Use to help merchants complete a destructive action quickly. --- -# Autocomplete - -The autocomplete component is an input field that provides selectable suggestions as a merchant types into it. It allows merchants to quickly search through and select from large collections of options. It's a convenience wrapper around the `Combobox` and `Listbox` components with minor UI differences. - ---- - ## Best practices The autocomplete component should: diff --git a/polaris.shopify.com/content/components/avatar/index.md b/polaris.shopify.com/content/components/avatar/index.md index 8fe2791f7c1..193a933f675 100644 --- a/polaris.shopify.com/content/components/avatar/index.md +++ b/polaris.shopify.com/content/components/avatar/index.md @@ -1,5 +1,6 @@ --- title: Avatar +description: Avatars are used to show a thumbnail representation of an individual or business in the interface. category: Images and icons keywords: - photo @@ -29,12 +30,6 @@ examples: description: Use a `square` shape when the avatar represents a non-person entity like an app, channel, or store. --- -# Avatar - -Avatars are used to show a thumbnail representation of an individual or business in the interface. - ---- - ## Best practices Avatars should be one of 4 sizes: diff --git a/polaris.shopify.com/content/components/badge/index.md b/polaris.shopify.com/content/components/badge/index.md index 2beeeef7cb3..2842b18800a 100644 --- a/polaris.shopify.com/content/components/badge/index.md +++ b/polaris.shopify.com/content/components/badge/index.md @@ -1,5 +1,6 @@ --- title: Badge +description: Badges are used to inform merchants of the status of an object or of an action that’s been taken. category: Images and icons keywords: - pills @@ -49,12 +50,6 @@ examples: description: Use when the status and progress accessibilityLabels are not appropriate to a given context. --- -# Badge - -Badges are used to inform merchants of the status of an object or of an action that’s been taken. - ---- - ## Best practices Badges benefit merchants by: diff --git a/polaris.shopify.com/content/components/banner/index.md b/polaris.shopify.com/content/components/banner/index.md index 853d665388d..2e4788bd569 100644 --- a/polaris.shopify.com/content/components/banner/index.md +++ b/polaris.shopify.com/content/components/banner/index.md @@ -1,5 +1,6 @@ --- title: Banner +description: Informs merchants about important changes or persistent conditions. Use this component if you need to communicate to merchants in a prominent way. Banners are placed at the top of the page or section they apply to, and below the page or section header. category: Feedback indicators keywords: - inform @@ -56,12 +57,6 @@ examples: description: Banners inside of cards render with less spacing and a pared-back design to fit within a content context. --- -# Banner - -Informs merchants about important changes or persistent conditions. Use this component if you need to communicate to merchants in a prominent way. Banners are placed at the top of the page or section they apply to, and below the page or section header. - ---- - ## Best practices Banners should: diff --git a/polaris.shopify.com/content/components/button-group/index.md b/polaris.shopify.com/content/components/button-group/index.md index 6e81303e654..5133a0f6c96 100644 --- a/polaris.shopify.com/content/components/button-group/index.md +++ b/polaris.shopify.com/content/components/button-group/index.md @@ -1,5 +1,6 @@ --- title: Button group +description: Button group displays multiple related actions stacked or in a horizontal row to help with arrangement and spacing. category: Actions keywords: - ButtonGroup @@ -29,12 +30,6 @@ examples: description: Use to emphasize several buttons as a thematically-related set among other controls. --- -# Button group - -Button group displays multiple related actions stacked or in a horizontal row to help with arrangement and spacing. - ---- - ## Best practices Button groups should: diff --git a/polaris.shopify.com/content/components/button/index.md b/polaris.shopify.com/content/components/button/index.md index 5616b2a19fb..408db9523cf 100644 --- a/polaris.shopify.com/content/components/button/index.md +++ b/polaris.shopify.com/content/components/button/index.md @@ -1,5 +1,6 @@ --- title: Button +description: Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view shipping settings”. category: Actions keywords: - CTA @@ -80,14 +81,6 @@ examples: description: Use when a button has been pressed and the associated action is in progress. --- -# Button - -Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view shipping settings”. - -For navigational actions that appear within or directly following a sentence, use the [link component](https://polaris.shopify.com/components/link). - ---- - ## Best practices Buttons should: diff --git a/polaris.shopify.com/content/components/callout-card/index.md b/polaris.shopify.com/content/components/callout-card/index.md index abfe711e8e1..fb5b5d30f7c 100644 --- a/polaris.shopify.com/content/components/callout-card/index.md +++ b/polaris.shopify.com/content/components/callout-card/index.md @@ -1,5 +1,6 @@ --- title: Callout card +description: Callout cards are used to encourage merchants to take an action related to a new feature or opportunity. They are most commonly displayed in the sales channels section of Shopify. category: Structure keywords: - CalloutCard @@ -33,12 +34,6 @@ examples: description: Make all callout cards dismissible so merchants can get rid of cards about features they’re not interested in. --- -# Callout card - -Callout cards are used to encourage merchants to take an action related to a new feature or opportunity. They are most commonly displayed in the sales channels section of Shopify. - ---- - ## Best practices Callout cards should: diff --git a/polaris.shopify.com/content/components/caption/index.md b/polaris.shopify.com/content/components/caption/index.md index d45fd0e23a1..dd4df9d59cc 100644 --- a/polaris.shopify.com/content/components/caption/index.md +++ b/polaris.shopify.com/content/components/caption/index.md @@ -1,5 +1,6 @@ --- title: Caption +description: Caption text size is smaller than the recommended size for general reading. On web, it should be used only in a graph or as a timestamp for a list item. On Android and iOS, it can also be used as help text or as other kinds of secondary text for list items. category: Titles and text keywords: - labels @@ -20,12 +21,6 @@ examples: description: Use to provide details in situations where content is compact and space is tight. --- -# Caption - -Caption text size is smaller than the recommended size for general reading. On web, it should be used only in a graph or as a timestamp for a list item. On Android and iOS, it can also be used as help text or as other kinds of secondary text for list items. - ---- - ## Best practices - Use for secondary labels in graphs and charts diff --git a/polaris.shopify.com/content/components/card/index.md b/polaris.shopify.com/content/components/card/index.md index fbb93bbcbb6..73e408361b7 100644 --- a/polaris.shopify.com/content/components/card/index.md +++ b/polaris.shopify.com/content/components/card/index.md @@ -1,5 +1,6 @@ --- title: Card +description: Cards are used to group similar concepts and tasks together to make Shopify easier for merchants to scan, read, and get things done. category: Structure keywords: - layout @@ -73,12 +74,6 @@ examples: description: Use when you need further control over the spacing of your card sections. --- -# Card - -Cards are used to group similar concepts and tasks together to make Shopify easier for merchants to scan, read, and get things done. - ---- - ## Best practices Cards should: diff --git a/polaris.shopify.com/content/components/checkbox/index.md b/polaris.shopify.com/content/components/checkbox/index.md index f07f1a000c5..d5bc8213a2f 100644 --- a/polaris.shopify.com/content/components/checkbox/index.md +++ b/polaris.shopify.com/content/components/checkbox/index.md @@ -1,5 +1,6 @@ --- title: Checkbox +description: Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have merchants indicate they agree to specific terms and services. category: Forms keywords: - accept @@ -19,12 +20,6 @@ examples: description: Use in forms to toggle the state of something on or off. Default checkboxes can appear as selected and disabled, or unselected. --- -# Checkbox - -Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have merchants indicate they agree to specific terms and services. - ---- - ## Best practices Checkboxes should: diff --git a/polaris.shopify.com/content/components/choice-list/index.md b/polaris.shopify.com/content/components/choice-list/index.md index 81689fb3bbb..a7bf2f63a2c 100644 --- a/polaris.shopify.com/content/components/choice-list/index.md +++ b/polaris.shopify.com/content/components/choice-list/index.md @@ -1,5 +1,6 @@ --- title: Choice list +description: A choice list lets you create a list of grouped radio buttons or checkboxes. Use this component if you need to group together a related list of interactive choices. category: Forms keywords: - ChoiceList @@ -35,12 +36,6 @@ examples: description: Use when you need merchants to view and/or interact with additional content under a choice. The content is only rendered when the choice is selected. Works for both single-choice and multi-choice list. --- -# Choice list - -A choice list lets you create a list of grouped radio buttons or checkboxes. Use this component if you need to group together a related list of interactive choices. - ---- - ## Best practices Choice lists should: diff --git a/polaris.shopify.com/content/components/collapsible/index.md b/polaris.shopify.com/content/components/collapsible/index.md index 0c5878fc233..18278606af0 100644 --- a/polaris.shopify.com/content/components/collapsible/index.md +++ b/polaris.shopify.com/content/components/collapsible/index.md @@ -1,5 +1,6 @@ --- title: Collapsible +description: The collapsible component is used to put long sections of information under a block that merchants can expand or collapse. category: Behavior keywords: - hide @@ -24,12 +25,6 @@ examples: description: Use for a basic “show more” interaction when you need to display more content. --- -# Collapsible - -The collapsible component is used to put long sections of information under a block that merchants can expand or collapse. - ---- - ## Best practices The collapsible component should: diff --git a/polaris.shopify.com/content/components/color-picker/index.md b/polaris.shopify.com/content/components/color-picker/index.md index ffb37cbae12..a1545e00d7d 100644 --- a/polaris.shopify.com/content/components/color-picker/index.md +++ b/polaris.shopify.com/content/components/color-picker/index.md @@ -1,5 +1,6 @@ --- title: Color picker +description: The color picker is used to let merchants select a color visually. For example, merchants use the color picker to customize the accent color of the email templates for their shop. category: Forms keywords: - ColorPicker @@ -25,12 +26,6 @@ examples: description: Use when attached to a visual builder to allow the designated object to have a transparent background that allows underlying objects to show through. --- -# Color picker - -The color picker is used to let merchants select a color visually. For example, merchants use the color picker to customize the accent color of the email templates for their shop. - ---- - ## Best practices - Use the alpha slider if you want to allow merchants to be able to select a transparent color diff --git a/polaris.shopify.com/content/components/combobox/index.md b/polaris.shopify.com/content/components/combobox/index.md index 397a2d11738..a0dee10becf 100644 --- a/polaris.shopify.com/content/components/combobox/index.md +++ b/polaris.shopify.com/content/components/combobox/index.md @@ -1,5 +1,6 @@ --- title: Combobox +description: Combobox is an accessible autocomplete input that enables merchants to filter a list of options and select one or more values. category: Forms keywords: - autocomplete @@ -30,12 +31,6 @@ examples: description: Use to indicate to merchants that the list data is being fetched. --- -# Combobox - -Combobox is an accessible autocomplete input that enables merchants to filter a list of options and select one or more values. - ---- - ## Anatomy ![A diagram of the Combobox component showing the smaller primitive components it is composed of.](/images/components/combobox/combobox-anatomy.png) diff --git a/polaris.shopify.com/content/components/contextual-save-bar/index.md b/polaris.shopify.com/content/components/contextual-save-bar/index.md index 9606e74167e..5543386af8f 100644 --- a/polaris.shopify.com/content/components/contextual-save-bar/index.md +++ b/polaris.shopify.com/content/components/contextual-save-bar/index.md @@ -1,5 +1,6 @@ --- title: Contextual save bar +description: The contextual save bar tells merchants their options once they have made changes to a form on the page. This component is also shown while creating a new object like a product or customer. Merchants can use this component to save or discard their work. category: Forms keywords: - form @@ -21,12 +22,6 @@ examples: description: Use the fullWidth flag when you want to remove the default max-width set on the contextual save bar. --- -# Contextual Save Bar - -The contextual save bar tells merchants their options once they have made changes to a form on the page. This component is also shown while creating a new object like a product or customer. Merchants can use this component to save or discard their work. - ---- - ## Required components The contextual save bar component must be wrapped in the [frame](https://polaris.shopify.com/components/frame) component. diff --git a/polaris.shopify.com/content/components/custom-properties/index.md b/polaris.shopify.com/content/components/custom-properties/index.md index f45bfa6d14e..9ada8085e14 100644 --- a/polaris.shopify.com/content/components/custom-properties/index.md +++ b/polaris.shopify.com/content/components/custom-properties/index.md @@ -1,5 +1,6 @@ --- title: CustomProperties +description: Use the custom properties component to share global theme settings throughout the hierarchy of your application. Custom properties is included by default as a child of the [app provider component](https://polaris.shopify.com/components/app-provider) but can be used independently to apply a base color scheme to its children. category: Structure keywords: - theme @@ -19,12 +20,6 @@ examples: description: Custom properties can be nested within the custom properties rendered by the app provider in order to override the color scheme at a local level. --- -# Custom Properties - -Use the custom properties component to share global theme settings throughout the hierarchy of your application. Custom properties is included by default as a child of the [app provider component](https://polaris.shopify.com/components/app-provider) but can be used independently to apply a base color scheme to its children. - ---- - ## Consuming custom properties colors in a component The CustomProperties component uses [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) to share color values with components. For a full list of available CSS custom properties, see the [Polaris tokens docs](https://github.com/Shopify/polaris/tree/main/polaris-tokens#readme). diff --git a/polaris.shopify.com/content/components/data-table/index.md b/polaris.shopify.com/content/components/data-table/index.md index 0d05e17e627..b7898cf016d 100644 --- a/polaris.shopify.com/content/components/data-table/index.md +++ b/polaris.shopify.com/content/components/data-table/index.md @@ -1,5 +1,6 @@ --- title: Data table +description: Data tables are used to organize and display all information from a data set. While a data visualization represents part of data set, a data table lets merchants view details from the entire set. This helps merchants compare and analyze the data. category: Lists and tables keywords: - DataTable @@ -43,12 +44,6 @@ examples: description: Use to fix the first column when horizontal scrolling becomes necessary. Keeps the context of the row as the user scrolls. --- -# Data table - -Data tables are used to organize and display all information from a data set. While a data visualization represents part of data set, a data table lets merchants view details from the entire set. This helps merchants compare and analyze the data. - ---- - ## Best practices Data tables should: diff --git a/polaris.shopify.com/content/components/date-picker/index.md b/polaris.shopify.com/content/components/date-picker/index.md index b79cf7f4641..6a091fe5bd0 100644 --- a/polaris.shopify.com/content/components/date-picker/index.md +++ b/polaris.shopify.com/content/components/date-picker/index.md @@ -1,5 +1,6 @@ --- title: Date picker +description: Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify. category: Forms keywords: - DatePicker @@ -33,12 +34,6 @@ examples: description: Dates may be disabed if you do not want them to be selectable --- -# Date picker - -Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify. - ---- - ## Best practices Date pickers should: diff --git a/polaris.shopify.com/content/components/description-list/index.md b/polaris.shopify.com/content/components/description-list/index.md index b22f39ce598..dc4c70a3425 100644 --- a/polaris.shopify.com/content/components/description-list/index.md +++ b/polaris.shopify.com/content/components/description-list/index.md @@ -1,5 +1,6 @@ --- title: Description list +description: Description lists are a way to organize and explain related information. They’re particularly useful when you need to list and define terms such as in a glossary. category: Lists and tables keywords: - DescriptionList @@ -17,13 +18,6 @@ examples: description: Use when you need to present merchants with a list of items or terms alongside descriptions and explanations. --- -# Description list - -Description lists are a way to organize and explain related information. -They’re particularly useful when you need to list and define terms such as in a glossary. - ---- - ## Best practices Description lists should: diff --git a/polaris.shopify.com/content/components/display-text/index.md b/polaris.shopify.com/content/components/display-text/index.md index 64f5dc79768..eae7cfe7cdd 100644 --- a/polaris.shopify.com/content/components/display-text/index.md +++ b/polaris.shopify.com/content/components/display-text/index.md @@ -1,5 +1,6 @@ --- title: Display text +description: Display styles make a bold visual statement. Use them to create impact when the main goal is visual storytelling. For example, use display text to convince or reassure merchants such as in marketing content or to capture attention during onboarding. category: Titles and text keywords: - DisplayText @@ -37,12 +38,6 @@ examples: description: Use for text that would otherwise use body text, but that needs to scale with other display text. --- -# Display text - -Display styles make a bold visual statement. Use them to create impact when the main goal is visual storytelling. For example, use display text to convince or reassure merchants such as in marketing content or to capture attention during onboarding. - ---- - ## Best practices - Use when the primary goal of the page is communication rather than interaction. diff --git a/polaris.shopify.com/content/components/drop-zone/index.md b/polaris.shopify.com/content/components/drop-zone/index.md index cc3c521e392..ce93f621e83 100644 --- a/polaris.shopify.com/content/components/drop-zone/index.md +++ b/polaris.shopify.com/content/components/drop-zone/index.md @@ -1,5 +1,6 @@ --- title: Drop zone +description: The drop zone component lets users upload files by dragging and dropping the files into an area on a page, or activating a button. category: Actions keywords: - upload @@ -48,12 +49,6 @@ examples: description: Use to trigger the file dialog from an action somewhere else on the page. --- -# Drop zone - -The drop zone component lets users upload files by dragging and dropping the files into an area on a page, or activating a button. - ---- - ## Best practices ### Drop zone diff --git a/polaris.shopify.com/content/components/empty-state/index.md b/polaris.shopify.com/content/components/empty-state/index.md index 59bd3880de5..8bc4899e599 100644 --- a/polaris.shopify.com/content/components/empty-state/index.md +++ b/polaris.shopify.com/content/components/empty-state/index.md @@ -1,5 +1,6 @@ --- title: Empty state +description: Empty states are used when a list, table, or chart has no items or data to show. This is an opportunity to provide explanation or guidance to help merchants progress. The empty state component is intended for use when a full page in the admin is empty, and not for individual elements or areas in the interface. category: Structure keywords: - EmptyState @@ -31,12 +32,6 @@ examples: title: With full width layout --- -# Empty state - -Empty states are used when a list, table, or chart has no items or data to show. This is an opportunity to provide explanation or guidance to help merchants progress. The empty state component is intended for use when a full page in the admin is empty, and not for individual elements or areas in the interface. - ---- - ## Best practices Empty states should: diff --git a/polaris.shopify.com/content/components/exception-list/index.md b/polaris.shopify.com/content/components/exception-list/index.md index a875d077e0f..ba42b7afcb5 100644 --- a/polaris.shopify.com/content/components/exception-list/index.md +++ b/polaris.shopify.com/content/components/exception-list/index.md @@ -1,5 +1,6 @@ --- title: Exception list +description: Use exception lists to help merchants notice important, standout information that adds extra context to a task. Exception lists often consist of a title and description. Each item in the list either has a bullet or icon at the front. category: Lists and tables keywords: - exception list @@ -12,12 +13,6 @@ examples: description: Use icons to add clarity or assist in visualizing the meaning --- -# Exception list - -Use exception lists to help merchants notice important, standout information that adds extra context to a task. Exception lists often consist of a title and description. Each item in the list either has a bullet or icon at the front. - ---- - ## Best practices The exception list component should: diff --git a/polaris.shopify.com/content/components/filters/index.md b/polaris.shopify.com/content/components/filters/index.md index a3592894aee..099ffa97c68 100644 --- a/polaris.shopify.com/content/components/filters/index.md +++ b/polaris.shopify.com/content/components/filters/index.md @@ -1,5 +1,6 @@ --- title: Filters +description: Filters is a composite component that filters the items of a list or table. category: Lists and tables keywords: - filters @@ -30,10 +31,6 @@ examples: title: With query field disabled --- -# Filters - -Filters is a composite component that filters the items of a list or table. - Merchants use filters to: - view different subsets of items in a list or table diff --git a/polaris.shopify.com/content/components/footer-help/index.md b/polaris.shopify.com/content/components/footer-help/index.md index af68c52c3aa..d193b3c06e8 100644 --- a/polaris.shopify.com/content/components/footer-help/index.md +++ b/polaris.shopify.com/content/components/footer-help/index.md @@ -1,5 +1,6 @@ --- title: Footer help +description: Footer help is used to refer merchants to more information related to the product or feature they’re using. category: Navigation keywords: - FooterHelp @@ -19,12 +20,6 @@ examples: description: Use to direct merchants to more information related to the product or feature they’re working on. --- -# Footer help - -Footer help is used to refer merchants to more information related to the product or feature they’re using. - ---- - ## Best practices Footer help should: diff --git a/polaris.shopify.com/content/components/form-layout/index.md b/polaris.shopify.com/content/components/form-layout/index.md index 7895187bb6b..a65748889fd 100644 --- a/polaris.shopify.com/content/components/form-layout/index.md +++ b/polaris.shopify.com/content/components/form-layout/index.md @@ -1,5 +1,6 @@ --- title: Form layout +description: Use form layout to arrange fields within a form using standard spacing. By default it stacks fields vertically but also supports horizontal groups of fields. category: Forms keywords: - FormLayout @@ -38,12 +39,6 @@ examples: description: For very short inputs, the width of the inputs may be reduced in order to fit more fields in the row. --- -# Form layout - -Use form layout to arrange fields within a form using standard spacing. By default it stacks fields vertically but also supports horizontal groups of fields. - ---- - ## Best practices Forms should: diff --git a/polaris.shopify.com/content/components/form/index.md b/polaris.shopify.com/content/components/form/index.md index e9910b331d3..98efa545a00 100644 --- a/polaris.shopify.com/content/components/form/index.md +++ b/polaris.shopify.com/content/components/form/index.md @@ -1,5 +1,6 @@ --- title: Form +description: A wrapper component that handles the submission of forms. category: Forms keywords: - form @@ -20,12 +21,6 @@ examples: description: Use in forms to toggle native form validation. --- -# Form - -A wrapper component that handles the submission of forms. - ---- - ## Best practices The form component should be used to: diff --git a/polaris.shopify.com/content/components/frame/index.md b/polaris.shopify.com/content/components/frame/index.md index 04300ce5324..9410d05d67a 100644 --- a/polaris.shopify.com/content/components/frame/index.md +++ b/polaris.shopify.com/content/components/frame/index.md @@ -1,5 +1,6 @@ --- title: Frame +description: The frame component, while not visible in the user interface itself, provides the structure for an application. It wraps the main elements and houses the primary [navigation](https://polaris.shopify.com/components/navigation), [top bar](https://polaris.shopify.com/components/top-bar), [toast](https://polaris.shopify.com/components/toast), and [contextual save bar](https://polaris.shopify.com/components/contextual-save-bar) components. category: Structure keywords: - navigation @@ -24,12 +25,6 @@ examples: description: Use to present the frame structure and all of its elements with an offset provided to the theme. --- -# Frame - -The frame component, while not visible in the user interface itself, provides the structure for an application. It wraps the main elements and houses the primary [navigation](https://polaris.shopify.com/components/navigation), [top bar](https://polaris.shopify.com/components/top-bar), [toast](https://polaris.shopify.com/components/toast), and [contextual save bar](https://polaris.shopify.com/components/contextual-save-bar) components. - ---- - ## Best practices For the best experience when creating an application frame, use the following components: diff --git a/polaris.shopify.com/content/components/fullscreen-bar/index.md b/polaris.shopify.com/content/components/fullscreen-bar/index.md index 1c584c73369..0eeb1171a02 100644 --- a/polaris.shopify.com/content/components/fullscreen-bar/index.md +++ b/polaris.shopify.com/content/components/fullscreen-bar/index.md @@ -1,5 +1,6 @@ --- title: Fullscreen bar +description: The Fullscreen bar is a header component that should be presented at the top of an app when it is in fullscreen mode. This is designed to ensure a uniform placement for a button to exit that mode. The Fullscreen bar can be customized by adding `children`. category: Navigation keywords: - topbar @@ -16,12 +17,6 @@ examples: description: Use this default to show ONLY the Back button. --- -# Fullscreen bar - -The Fullscreen bar is a header component that should be presented at the top of an app when it is in fullscreen mode. This is designed to ensure a uniform placement for a button to exit that mode. The Fullscreen bar can be customized by adding `children`. - ---- - ## Best practices The Fullscreen bar component should: diff --git a/polaris.shopify.com/content/components/grid/index.md b/polaris.shopify.com/content/components/grid/index.md index 777eb16d4dc..3c7f9530cc3 100644 --- a/polaris.shopify.com/content/components/grid/index.md +++ b/polaris.shopify.com/content/components/grid/index.md @@ -1,5 +1,6 @@ --- title: Grid +description: Create complex layouts based on [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/grid). category: Structure keywords: - one column @@ -30,12 +31,6 @@ examples: description: Use to create a layout that can be customized at specific breakpoints. --- -# Grid - -Create complex layouts based on [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/grid). - ---- - ## Related components - To lay out a set of smaller components in a row, [use the stack component](https://polaris.shopify.com/components/stack) diff --git a/polaris.shopify.com/content/components/heading/index.md b/polaris.shopify.com/content/components/heading/index.md index 761b231344c..06cc0252819 100644 --- a/polaris.shopify.com/content/components/heading/index.md +++ b/polaris.shopify.com/content/components/heading/index.md @@ -1,5 +1,6 @@ --- title: Heading +description: Headings are used as the titles of each major section of a page in the interface. For example, [card components](https://polaris.shopify.com/components/card) generally use headings as their title. category: Titles and text keywords: - titles @@ -19,12 +20,6 @@ examples: description: Use for the title of each top-level page section. --- -# Heading - -Headings are used as the titles of each major section of a page in the interface. For example, [card components](https://polaris.shopify.com/components/card) generally use headings as their title. - ---- - ## Best practices Headings should: diff --git a/polaris.shopify.com/content/components/icon/index.md b/polaris.shopify.com/content/components/icon/index.md index ed1dffc6018..186241dbbe5 100644 --- a/polaris.shopify.com/content/components/icon/index.md +++ b/polaris.shopify.com/content/components/icon/index.md @@ -1,5 +1,6 @@ --- title: Icon +description: Icons are used to visually communicate core parts of the product and available actions. They can act as wayfinding tools to help merchants more easily understand where they are in the product, and common interaction patterns that are available. category: Images and icons keywords: - iconography @@ -31,12 +32,6 @@ examples: description: When using changing color of an svg and it uses currentColor, the white color is applied. --- -# Icon - -Icons are used to visually communicate core parts of the product and available actions. They can act as wayfinding tools to help merchants more easily understand where they are in the product, and common interaction patterns that are available. - ---- - ## Accessibility Using icons can be a great help to merchants who have difficulties with reading, language, attention, and low vision. diff --git a/polaris.shopify.com/content/components/index-table/index.md b/polaris.shopify.com/content/components/index-table/index.md index 6dffa0c67cf..4bd3ecd7df7 100644 --- a/polaris.shopify.com/content/components/index-table/index.md +++ b/polaris.shopify.com/content/components/index-table/index.md @@ -1,5 +1,6 @@ --- title: Index table +description: An index table displays a collection of objects of the same type, like orders or products. The main job of an index table is to help merchants get an at-a-glance of the objects to perform actions or navigate to a full-page representation of it. category: Lists and tables keywords: - ResourceList @@ -77,10 +78,6 @@ examples: description: Use as a broad example that includes most of the elements and props available to index table. --- -# Index table - -An index table displays a collection of objects of the same type, like orders or products. The main job of an index table is to help merchants get an at-a-glance of the objects to perform actions or navigate to a full-page representation of it. - Index tables can also: - Support [customized index rows and columns](https://polaris.shopify.com/components/resource-item) diff --git a/polaris.shopify.com/content/components/inline-error/index.md b/polaris.shopify.com/content/components/inline-error/index.md index dea9900c2c2..1d68ce297bf 100644 --- a/polaris.shopify.com/content/components/inline-error/index.md +++ b/polaris.shopify.com/content/components/inline-error/index.md @@ -1,5 +1,6 @@ --- title: Inline error +description: Inline errors are brief, in-context messages that tell merchants something went wrong with a single or group of inputs in a form. Use inline errors to help merchants understand why a form input may not be valid and how to fix it. category: Forms keywords: - InlineError @@ -13,12 +14,6 @@ examples: description: Use when the merchant has entered information that is not valid into multiple fields inside of a form, or needs to be displayed in a non-standard position in the form layout. --- -# Inline error - -Inline errors are brief, in-context messages that tell merchants something went wrong with a single or group of inputs in a form. Use inline errors to help merchants understand why a form input may not be valid and how to fix it. - ---- - ## Best practices Inline errors should: diff --git a/polaris.shopify.com/content/components/keyboard-key/index.md b/polaris.shopify.com/content/components/keyboard-key/index.md index c0c1fdf492d..493752905ad 100644 --- a/polaris.shopify.com/content/components/keyboard-key/index.md +++ b/polaris.shopify.com/content/components/keyboard-key/index.md @@ -1,5 +1,6 @@ --- title: Keyboard key +description: Keyboard key is used to educate merchants about keyboard shortcuts. category: Images and icons keywords: - KeyboardKey @@ -15,12 +16,6 @@ examples: description: Use to list a related set of keyboard shortcuts. --- -# Keyboard key - -Keyboard key is used to educate merchants about keyboard shortcuts. - ---- - ## Best practices The keyboard key component should: diff --git a/polaris.shopify.com/content/components/layout/index.md b/polaris.shopify.com/content/components/layout/index.md index af506649443..e4618818e73 100644 --- a/polaris.shopify.com/content/components/layout/index.md +++ b/polaris.shopify.com/content/components/layout/index.md @@ -1,5 +1,6 @@ --- title: Layout +description: The layout component is used to create the main layout on a page. Layouts sections come in three main configurations. one-column, two-column, and annotated. One and two column layouts can be combined in the same page. Annotated layouts should be used on their own and only on settings pages. category: Structure keywords: - one column @@ -39,12 +40,6 @@ examples: description: Use for settings pages that need a banner or other content at the top. --- -# Layout - -The layout component is used to create the main layout on a page. Layouts sections come in three main configurations: one-column, two-column, and annotated. One and two column layouts can be combined in the same page. Annotated layouts should be used on their own and only on settings pages. - ---- - ## Best practices The layout component should: diff --git a/polaris.shopify.com/content/components/link/index.md b/polaris.shopify.com/content/components/link/index.md index 157b0973afe..9d53583fbc6 100644 --- a/polaris.shopify.com/content/components/link/index.md +++ b/polaris.shopify.com/content/components/link/index.md @@ -1,5 +1,6 @@ --- title: Link +description: Links take users to another place, and usually appear within or directly following a sentence. category: Navigation keywords: - URL @@ -34,14 +35,6 @@ examples: description: Use for text links that should open in a new browser tab (or window, depending on the merchant’s browser settings). Use this only when opening a page in the same tab might disrupt the merchant’s workflow. --- -# Link - -Links take users to another place, and usually appear within or directly following a sentence. - -For actions that aren’t related to navigation, use the [button component](https://polaris.shopify.com/components/button). - ---- - ## Best practices ### Buttons versus links diff --git a/polaris.shopify.com/content/components/list/index.md b/polaris.shopify.com/content/components/list/index.md index 5e79d397b42..59651152e84 100644 --- a/polaris.shopify.com/content/components/list/index.md +++ b/polaris.shopify.com/content/components/list/index.md @@ -1,5 +1,6 @@ --- title: List +description: Lists display a set of related text-only content. Each list item begins with a bullet or a number. category: Lists and tables keywords: - bulleted lists @@ -17,12 +18,6 @@ examples: description: Use for a text-only list of related items when an inherent order, priority, or sequence needs to be communicated. --- -# List - -Lists display a set of related text-only content. Each list item begins with a bullet or a number. - ---- - ## Best practices Lists should: diff --git a/polaris.shopify.com/content/components/listbox/index.md b/polaris.shopify.com/content/components/listbox/index.md index bd6294d0151..e2febd48aa4 100644 --- a/polaris.shopify.com/content/components/listbox/index.md +++ b/polaris.shopify.com/content/components/listbox/index.md @@ -1,5 +1,6 @@ --- title: Listbox +description: A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements. category: Lists and tables keywords: - list @@ -24,12 +25,6 @@ examples: description: Use to help merchants browse, filter, and choose from a list of options. --- -# Listbox - -A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements. - ---- - ## Anatomy ![A diagram of the Listbox component showing the smaller primitive components it can be composed of.](/images/components/listbox/listbox-anatomy.png) diff --git a/polaris.shopify.com/content/components/loading/index.md b/polaris.shopify.com/content/components/loading/index.md index 10a24256fa1..51bbd0c5210 100644 --- a/polaris.shopify.com/content/components/loading/index.md +++ b/polaris.shopify.com/content/components/loading/index.md @@ -1,5 +1,6 @@ --- title: Loading +description: The loading component is used to indicate to merchants that a page is loading or an upload is processing. category: Feedback indicators keywords: - spinner @@ -12,12 +13,6 @@ examples: description: Use to indicate that the page is loading. --- -# Loading - -The loading component is used to indicate to merchants that a page is loading or an upload is processing. - ---- - ## Required components The loading component must be wrapped in the [frame](https://polaris.shopify.com/components/frame) component. diff --git a/polaris.shopify.com/content/components/media-card/index.md b/polaris.shopify.com/content/components/media-card/index.md index 6210ab3ce22..c99427f09d0 100644 --- a/polaris.shopify.com/content/components/media-card/index.md +++ b/polaris.shopify.com/content/components/media-card/index.md @@ -1,5 +1,6 @@ --- title: Media card +description: Media cards provide a consistent layout to present visual information to merchants. Visual media is used to provide additional context to the written information it's paired with. category: Structure keywords: - MediaCard @@ -32,12 +33,6 @@ examples: description: Use when vertical screen space is not limited or when the video card is the page’s primary content. For example, in an empty state. --- -# Media card - -Media cards provide a consistent layout to present visual information to merchants. Visual media is used to provide additional context to the written information it's paired with. - ---- - ## Best practices Media cards should: diff --git a/polaris.shopify.com/content/components/modal/index.md b/polaris.shopify.com/content/components/modal/index.md index 2bd81fd7d01..7824864d4c5 100644 --- a/polaris.shopify.com/content/components/modal/index.md +++ b/polaris.shopify.com/content/components/modal/index.md @@ -1,5 +1,6 @@ --- title: Modal +description: Modals are overlays that require merchants to take an action before they can continue interacting with the rest of Shopify. They can be disruptive and should be used thoughtfully and sparingly. category: Overlays keywords: - modal @@ -54,12 +55,6 @@ examples: description: Use an external activator when technical limitations prevent you from passing the activator as an element or a ref. Make sure to focus the activator on close when choosing this approach. See the [accessibility features of a modal](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html) for more information regarding focus. --- -# Modal - -Modals are overlays that require merchants to take an action before they can continue interacting with the rest of Shopify. They can be disruptive and should be used thoughtfully and sparingly. - ---- - ## Best practices Use modals for confirmations and conditional changes. They should be thought of as temporary and not be used for information or actions that need to live on in the UI in a persistent way. Don’t use modals to display complex forms or large amounts of information. diff --git a/polaris.shopify.com/content/components/navigation/index.md b/polaris.shopify.com/content/components/navigation/index.md index 20d4c5f9b92..fc4c46e9fc1 100644 --- a/polaris.shopify.com/content/components/navigation/index.md +++ b/polaris.shopify.com/content/components/navigation/index.md @@ -1,5 +1,6 @@ --- title: Navigation +description: The navigation component is used to display the primary navigation in the sidebar of the [frame](https://polaris.shopify.com/components/frame) of an application. Navigation includes a list of links that merchants use to move between sections of the application. category: Navigation keywords: - navigation @@ -43,12 +44,6 @@ examples: description: This example shows how to use the shouldResizeIcon prop when using Major icons --- -# Navigation - -The navigation component is used to display the primary navigation in the sidebar of the [frame](https://polaris.shopify.com/components/frame) of an application. Navigation includes a list of links that merchants use to move between sections of the application. - ---- - ## Required components The navigation component must be passed to the [frame](https://polaris.shopify.com/components/frame) component. The mobile version of the navigation component appears in the [top bar](https://polaris.shopify.com/components/top-bar) component. diff --git a/polaris.shopify.com/content/components/option-list/index.md b/polaris.shopify.com/content/components/option-list/index.md index 734732d603e..9851e6b2cfc 100644 --- a/polaris.shopify.com/content/components/option-list/index.md +++ b/polaris.shopify.com/content/components/option-list/index.md @@ -1,5 +1,6 @@ --- title: Option list +description: The option list component lets you create a list of grouped items that merchants can pick from. This can include single selection or multiple selection of options. Option list usually appears in a popover, and sometimes in a modal or a sidebar. Option lists are styled differently than [choice lists](https://polaris.shopify.com/components/choice-list) and should not be used within a form, but as a standalone menu. category: Lists and tables keywords: - option list @@ -26,12 +27,6 @@ examples: description: Use when a set of selections won’t fit in the available screen space. --- -# Option list - -The option list component lets you create a list of grouped items that merchants can pick from. This can include single selection or multiple selection of options. Option list usually appears in a popover, and sometimes in a modal or a sidebar. Option lists are styled differently than [choice lists](https://polaris.shopify.com/components/choice-list) and should not be used within a form, but as a standalone menu. - ---- - ## Best practices The option list component should: diff --git a/polaris.shopify.com/content/components/page-actions/index.md b/polaris.shopify.com/content/components/page-actions/index.md index e6102b7752b..f86257782a4 100644 --- a/polaris.shopify.com/content/components/page-actions/index.md +++ b/polaris.shopify.com/content/components/page-actions/index.md @@ -1,5 +1,6 @@ --- title: Page actions +description: Page actions let merchants take key actions at the bottom of specific pages in the interface. This is important because sometimes the primary call to action is hard to access when merchants are at the bottom of a page. category: Structure keywords: - PageActions @@ -26,12 +27,6 @@ examples: description: Use to create a custom secondary action. --- -# Page actions - -Page actions let merchants take key actions at the bottom of specific pages in the interface. This is important because sometimes the primary call to action is hard to access when merchants are at the bottom of a page. - ---- - ## Best practices Page actions should: diff --git a/polaris.shopify.com/content/components/page/index.md b/polaris.shopify.com/content/components/page/index.md index 7b00805a461..826cdea725d 100644 --- a/polaris.shopify.com/content/components/page/index.md +++ b/polaris.shopify.com/content/components/page/index.md @@ -1,5 +1,6 @@ --- title: Page +description: Use to build the outer wrapper of a page, including the page title and associated actions. category: Structure keywords: - page @@ -63,12 +64,6 @@ examples: description: Use when the page needs visual separation between the page header and the content. --- -# Page - -Use to build the outer wrapper of a page, including the page title and associated actions. - ---- - ## Best practices The page component should: diff --git a/polaris.shopify.com/content/components/pagination/index.md b/polaris.shopify.com/content/components/pagination/index.md index 08eaf15cfaa..a110e5bff55 100644 --- a/polaris.shopify.com/content/components/pagination/index.md +++ b/polaris.shopify.com/content/components/pagination/index.md @@ -1,5 +1,6 @@ --- title: Pagination +description: Use pagination to let merchants move through an ordered collection of items that has been split into pages. On the web, pagination uses buttons to move back and forth between pages. On iOS and Android, pagination uses infinite scrolling. category: Navigation keywords: - lists @@ -30,12 +31,6 @@ examples: description: Add a label between navigation buttons to provide more context of the content being viewed by the user. --- -# Pagination - -Use pagination to let merchants move through an ordered collection of items that has been split into pages. On the web, pagination uses buttons to move back and forth between pages. On iOS and Android, pagination uses infinite scrolling. - ---- - ## Best practices On all platforms, pagination should: diff --git a/polaris.shopify.com/content/components/popover/index.md b/polaris.shopify.com/content/components/popover/index.md index 5aa4f203f7c..ba66f7e6650 100644 --- a/polaris.shopify.com/content/components/popover/index.md +++ b/polaris.shopify.com/content/components/popover/index.md @@ -1,5 +1,6 @@ --- title: Popover +description: Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page. category: Overlays keywords: - interactive @@ -37,12 +38,6 @@ examples: description: Use to help merchants browse, filter, and choose from a list of options. --- -# Popover - -Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page. - ---- - ## Best practices Popovers should: diff --git a/polaris.shopify.com/content/components/progress-bar/index.md b/polaris.shopify.com/content/components/progress-bar/index.md index 7456a8fce84..0bbc031ddfc 100644 --- a/polaris.shopify.com/content/components/progress-bar/index.md +++ b/polaris.shopify.com/content/components/progress-bar/index.md @@ -1,5 +1,6 @@ --- title: Progress bar +description: The progress bar component is used to visually represent the completion of a task or operation. It shows how much of the task has been completed and how much is still left. category: Feedback indicators releasedIn: 1.8.0 keywords: @@ -22,12 +23,6 @@ examples: description: Use the animated prop when you want to show a static progress bar. --- -# Progress bar - -The progress bar component is used to visually represent the completion of a task or operation. It shows how much of the task has been completed and how much is still left. - ---- - ## Best practices Progress bar components should: diff --git a/polaris.shopify.com/content/components/radio-button/index.md b/polaris.shopify.com/content/components/radio-button/index.md index df79bd8e715..c3bfb4d8197 100644 --- a/polaris.shopify.com/content/components/radio-button/index.md +++ b/polaris.shopify.com/content/components/radio-button/index.md @@ -1,5 +1,6 @@ --- title: Radio button +description: Use radio buttons to present each item in a list of options where merchants must make a single selection. category: Forms keywords: - RadioButton @@ -19,12 +20,6 @@ examples: description: Use radio buttons where merchants must make a single selection. --- -# Radio button - -Use radio buttons to present each item in a list of options where merchants must make a single selection. - ---- - ## Best practices Radio buttons should: diff --git a/polaris.shopify.com/content/components/range-slider/index.md b/polaris.shopify.com/content/components/range-slider/index.md index 177957a8663..3c220d049e9 100644 --- a/polaris.shopify.com/content/components/range-slider/index.md +++ b/polaris.shopify.com/content/components/range-slider/index.md @@ -1,5 +1,6 @@ --- title: Range slider +description: A range slider is an input field that merchants can use to select a numeric value within a given range (minimum and maximum values). category: Forms keywords: - RangeSlider @@ -27,12 +28,6 @@ examples: description: Use when two values need to be selected from a range of numbers. --- -# Range slider - -A range slider is an input field that merchants can use to select a numeric value within a given range (minimum and maximum values). - ---- - ## Best practices Range sliders should: diff --git a/polaris.shopify.com/content/components/resource-item/index.md b/polaris.shopify.com/content/components/resource-item/index.md index 176aa2c5cb4..a20db8ce945 100644 --- a/polaris.shopify.com/content/components/resource-item/index.md +++ b/polaris.shopify.com/content/components/resource-item/index.md @@ -1,5 +1,6 @@ --- title: Resource item +description: Resource items represent specific objects within a collection, such as products or orders. They provide contextual information on the resource type and link to the object’s detail page. category: Lists and tables keywords: - ResourceItem @@ -37,12 +38,6 @@ examples: description: Use to adjust the vertical alignment of item content. --- -# Resource item - -Resource items represent specific objects within a collection, such as products or orders. They provide contextual information on the resource type and link to the object’s detail page. - ---- - ## Required components The resource item component must be wrapped in the [resource list](https://polaris.shopify.com/components/resource-list) component. diff --git a/polaris.shopify.com/content/components/resource-list/index.md b/polaris.shopify.com/content/components/resource-list/index.md index b279a13e898..96c82bc06c3 100644 --- a/polaris.shopify.com/content/components/resource-list/index.md +++ b/polaris.shopify.com/content/components/resource-list/index.md @@ -1,5 +1,6 @@ --- title: Resource list +description: A resource list displays a collection of objects of the same type, like products or customers. The main job of a resource list is to help merchants find an object and navigate to a full-page representation of it. category: Lists and tables keywords: - ResourceList @@ -68,10 +69,6 @@ examples: description: Use as a broad example that includes most props available to resource list. --- -# Resource list - -A resource list displays a collection of objects of the same type, like products or customers. The main job of a resource list is to help merchants find an object and navigate to a full-page representation of it. - Resource lists can also: - Support [customized list items](https://polaris.shopify.com/components/resource-item) diff --git a/polaris.shopify.com/content/components/scrollable/index.md b/polaris.shopify.com/content/components/scrollable/index.md index 86ffaa6178f..8c67b85a217 100644 --- a/polaris.shopify.com/content/components/scrollable/index.md +++ b/polaris.shopify.com/content/components/scrollable/index.md @@ -1,5 +1,6 @@ --- title: Scrollable +description: The scrollable component is a container for long form content, such as terms of service, that allows for scrolling so merchants can expose more text as they read. category: Behavior keywords: - long form @@ -22,12 +23,6 @@ examples: description: Use when you need to programmatically scroll a child component into view in the scrollable container. --- -# Scrollable - -The scrollable component is a container for long form content, such as terms of service, that allows for scrolling so merchants can expose more text as they read. - ---- - ## Best practices Scrollable containers should: diff --git a/polaris.shopify.com/content/components/select/index.md b/polaris.shopify.com/content/components/select/index.md index 1a97fe66235..9b8a61eba1f 100644 --- a/polaris.shopify.com/content/components/select/index.md +++ b/polaris.shopify.com/content/components/select/index.md @@ -1,5 +1,6 @@ --- title: Select +description: Select lets merchants choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface. category: Forms keywords: - on off @@ -40,12 +41,6 @@ examples: description: Use to let merchants know when their select input is invalid in the context of a group of form inputs that the select depends on. --- -# Select - -Select lets merchants choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface. - ---- - ## Best practices The select component should: diff --git a/polaris.shopify.com/content/components/setting-toggle/index.md b/polaris.shopify.com/content/components/setting-toggle/index.md index f7cea04467f..cd288ee2ed2 100644 --- a/polaris.shopify.com/content/components/setting-toggle/index.md +++ b/polaris.shopify.com/content/components/setting-toggle/index.md @@ -1,5 +1,6 @@ --- title: Setting toggle +description: Use to give merchants control over a feature or option that can be turned on or off. category: Actions keywords: - SettingToggle @@ -20,12 +21,6 @@ examples: description: Use on settings pages to allow merchants to toggle a setting that has an activated or a deactivated state. --- -# Setting toggle - -Use to give merchants control over a feature or option that can be turned on or off. - ---- - ## Best practices Settings toggles should: diff --git a/polaris.shopify.com/content/components/sheet/index.md b/polaris.shopify.com/content/components/sheet/index.md index a8d21ced615..89c84d655ff 100644 --- a/polaris.shopify.com/content/components/sheet/index.md +++ b/polaris.shopify.com/content/components/sheet/index.md @@ -1,5 +1,6 @@ --- title: Sheet +description: A sheet is a large container that enters from the edge of the screen when triggered by the merchant. It’s used to provide merchants with actions and information contextual to the page. It doesn’t interrupt their flow like a modal. category: Overlays keywords: - sheet @@ -21,12 +22,6 @@ examples: description: Use to help merchants browse, filter, and choose from a list of options. --- -# Sheet - -A sheet is a large container that enters from the edge of the screen when triggered by the merchant. It’s used to provide merchants with actions and information contextual to the page. It doesn’t interrupt their flow like a modal. - ---- - ## Accessibility Sheets provide an opportunity to let merchants dig into more detail on their current task, or access information for their current task in a different way. Although merchants may be able to see content in the sheet and the main page content at the same time, they should only be expected to interact with one or the other at any given time. diff --git a/polaris.shopify.com/content/components/skeleton-body-text/index.md b/polaris.shopify.com/content/components/skeleton-body-text/index.md index 7efbca3fe15..8f20ae4a33e 100644 --- a/polaris.shopify.com/content/components/skeleton-body-text/index.md +++ b/polaris.shopify.com/content/components/skeleton-body-text/index.md @@ -1,5 +1,6 @@ --- title: Skeleton body text +description: Skeleton body text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. category: Feedback indicators releasedIn: 1.7.0 keywords: @@ -16,12 +17,6 @@ examples: description: Use this component to represent a short, single line of text, like a timestamp. --- -# Skeleton body text - -Skeleton body text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. - ---- - ## Best practices Skeleton body text component should: diff --git a/polaris.shopify.com/content/components/skeleton-display-text/index.md b/polaris.shopify.com/content/components/skeleton-display-text/index.md index 9a1f18953fa..6f88cf52b28 100644 --- a/polaris.shopify.com/content/components/skeleton-display-text/index.md +++ b/polaris.shopify.com/content/components/skeleton-display-text/index.md @@ -1,5 +1,6 @@ --- title: Skeleton display text +description: Skeleton display text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. category: Feedback indicators releasedIn: 1.7.0 keywords: @@ -19,12 +20,6 @@ examples: description: Use this component to represent small display text such as content headings. --- -# Skeleton display text - -Skeleton display text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. - ---- - ## Best practices Skeleton display text component should: diff --git a/polaris.shopify.com/content/components/skeleton-page/index.md b/polaris.shopify.com/content/components/skeleton-page/index.md index 7753b27b6e9..0adb88c6a79 100644 --- a/polaris.shopify.com/content/components/skeleton-page/index.md +++ b/polaris.shopify.com/content/components/skeleton-page/index.md @@ -1,5 +1,6 @@ --- title: Skeleton page +description: Skeleton page is used with other skeleton loading components to provide a low fidelity representation of the user interface (UI) before content appears on the page. It improves load times perceived by merchants. category: Feedback indicators releasedIn: 1.7.0 keywords: @@ -16,12 +17,6 @@ examples: description: Use this component to compose a loading version of a page where the page title and header content are known and stay the same. --- -# Skeleton page - -Skeleton page is used with other skeleton loading components to provide a low fidelity representation of the user interface (UI) before content appears on the page. It improves load times perceived by merchants. - ---- - ## Best practices Skeleton page component should: diff --git a/polaris.shopify.com/content/components/skeleton-tabs/index.md b/polaris.shopify.com/content/components/skeleton-tabs/index.md index fcfef20283c..508589bc3fa 100644 --- a/polaris.shopify.com/content/components/skeleton-tabs/index.md +++ b/polaris.shopify.com/content/components/skeleton-tabs/index.md @@ -1,5 +1,6 @@ --- title: Skeleton tabs +description: Skeleton tabs are used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. category: Feedback indicators releasedIn: 9.0 keywords: @@ -14,12 +15,6 @@ examples: title: With a custom count --- -# Skeleton tabs - -Skeleton tabs are used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card. - ---- - ## Best practices Skeleton tabs component should: diff --git a/polaris.shopify.com/content/components/skeleton-thumbnail/index.md b/polaris.shopify.com/content/components/skeleton-thumbnail/index.md index e98a17ead23..da8568a9060 100644 --- a/polaris.shopify.com/content/components/skeleton-thumbnail/index.md +++ b/polaris.shopify.com/content/components/skeleton-thumbnail/index.md @@ -1,5 +1,6 @@ --- title: Skeleton thumbnail +description: Skeleton thumbnail is used to provide a low fidelity representation of an image before it appears on the page, and improves load times perceived by merchants. Use for thumbnails in or outside of a card. category: Feedback indicators releasedIn: 3.7.2 keywords: @@ -22,12 +23,6 @@ examples: description: Use this component to represent extra small thumbnails. --- -# Skeleton image - -Skeleton thumbnail is used to provide a low fidelity representation of an image before it appears on the page, and improves load times perceived by merchants. Use for thumbnails in or outside of a card. - ---- - ## Best practices Skeleton thumbnail component should: diff --git a/polaris.shopify.com/content/components/spinner/index.md b/polaris.shopify.com/content/components/spinner/index.md index c19091828b2..92b3a46e661 100644 --- a/polaris.shopify.com/content/components/spinner/index.md +++ b/polaris.shopify.com/content/components/spinner/index.md @@ -1,5 +1,6 @@ --- title: Spinner +description: Spinners are used to notify merchants that their action is being processed. For loading states, spinners should only be used for content that can’t be represented with skeleton loading components, like for data charts. category: Feedback indicators releasedIn: 1.7.0 keywords: @@ -19,12 +20,6 @@ examples: description: Use to direct the focus state from the control to the spinner, to the content. --- -# Spinner - -Spinners are used to notify merchants that their action is being processed. For loading states, spinners should only be used for content that can’t be represented with skeleton loading components, like for data charts. - ---- - ## Accessibility SVGs are often conveyed inconsistently to assistive technologies. The `Spinner` component’s accessibility is also highly contextual. When the parent component is focusable, you’ll need to set the `hasFocusableParent` prop for the appropriate `role` attribute to be applied. diff --git a/polaris.shopify.com/content/components/stack/index.md b/polaris.shopify.com/content/components/stack/index.md index dce7419bb14..5180d858f25 100644 --- a/polaris.shopify.com/content/components/stack/index.md +++ b/polaris.shopify.com/content/components/stack/index.md @@ -1,5 +1,6 @@ --- title: Stack +description: Use to lay out a horizontal row of components or to achieve no-fuss vertical centering. A stack is made of flexible items that wrap each of the stack’s children. Options provide control of the wrapping, spacing, and relative size of the items in the stack. category: Structure keywords: - rows @@ -40,12 +41,6 @@ examples: description: Use for aligning buttons or secondary content to the right edge of another element, allowing it to wrap below on small screens. --- -# Stack - -Use to lay out a horizontal row of components or to achieve no-fuss vertical centering. A stack is made of flexible items that wrap each of the stack’s children. Options provide control of the wrapping, spacing, and relative size of the items in the stack. - ---- - ## Best practices Stacks should: diff --git a/polaris.shopify.com/content/components/subheading/index.md b/polaris.shopify.com/content/components/subheading/index.md index ce82faf2edc..5a3ae98b4c4 100644 --- a/polaris.shopify.com/content/components/subheading/index.md +++ b/polaris.shopify.com/content/components/subheading/index.md @@ -1,5 +1,6 @@ --- title: Subheading +description: Subheadings are used for the title of any sub-sections in top-level page sections. category: Titles and text keywords: - title bar @@ -15,12 +16,6 @@ examples: description: Used for the title of any sub-sections in top-level page sections. --- -# Subheading - -Subheadings are used for the title of any sub-sections in top-level page sections. - ---- - ## Best practices Subheadings should: diff --git a/polaris.shopify.com/content/components/tabs/index.md b/polaris.shopify.com/content/components/tabs/index.md index 4df3274bc4f..1b8bdc6cbe2 100644 --- a/polaris.shopify.com/content/components/tabs/index.md +++ b/polaris.shopify.com/content/components/tabs/index.md @@ -1,5 +1,6 @@ --- title: Tabs +description: Use to alternate among related views within the same context. category: Navigation keywords: - layout @@ -25,12 +26,6 @@ examples: description: Use to provide information about the popover contents --- -# Tabs - -Use to alternate among related views within the same context. - ---- - ## Best practices Tabs should: diff --git a/polaris.shopify.com/content/components/tag/index.md b/polaris.shopify.com/content/components/tag/index.md index 1e501fc0b84..8fc1c18efd6 100644 --- a/polaris.shopify.com/content/components/tag/index.md +++ b/polaris.shopify.com/content/components/tag/index.md @@ -1,5 +1,6 @@ --- title: Tag +description: Tags represent a set of interactive, merchant-supplied keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by merchants. category: Forms keywords: - indicator @@ -30,12 +31,6 @@ examples: description: A removable attribute to an object that allows merchants to navigate to a resource. --- -# Tag - -Tags represent a set of interactive, merchant-supplied keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by merchants. - ---- - ## Best practices Tags should: diff --git a/polaris.shopify.com/content/components/text-container/index.md b/polaris.shopify.com/content/components/text-container/index.md index 560ced0eb3d..fbe52e5fc7f 100644 --- a/polaris.shopify.com/content/components/text-container/index.md +++ b/polaris.shopify.com/content/components/text-container/index.md @@ -1,5 +1,6 @@ --- title: Text container +description: A text container is used to wrap text elements such as paragraphs, headings, and lists to give them vertical spacing. category: Titles and text releasedIn: 1.9.0 keywords: @@ -22,12 +23,6 @@ examples: description: Use the loose spacing option to separate concepts that are independent of each other. --- -# Text container - -A text container is used to wrap text elements such as paragraphs, headings, and lists to give them vertical spacing. - ---- - ## Best practices The closer the spacing, the closer the relationship between content topics. The closeness visually represents the relationship. diff --git a/polaris.shopify.com/content/components/text-field/index.md b/polaris.shopify.com/content/components/text-field/index.md index 85e15ad9843..0ecc8525c33 100644 --- a/polaris.shopify.com/content/components/text-field/index.md +++ b/polaris.shopify.com/content/components/text-field/index.md @@ -1,5 +1,6 @@ --- title: Text field +description: A text field is an input field that merchants can type into. It has a range of options and supports several text formats including numbers. category: Forms keywords: - TextField @@ -103,12 +104,6 @@ examples: description: Use to provide an autocomplete suggestion inline with the input value. See the combobox component's tag multi-select example for full implementation of the inline autocomplete pattern. --- -# Text field - -A text field is an input field that merchants can type into. It has a range of options and supports several text formats including numbers. - ---- - ## Best practices Text fields should: diff --git a/polaris.shopify.com/content/components/text-style/index.md b/polaris.shopify.com/content/components/text-style/index.md index 00e03499620..7c1e78d04a4 100644 --- a/polaris.shopify.com/content/components/text-style/index.md +++ b/polaris.shopify.com/content/components/text-style/index.md @@ -1,5 +1,6 @@ --- title: Text style +description: Text style enhances text with additional visual meaning. For example, using subdued text to de-emphasize it from its surrounding text. category: Titles and text keywords: - TextStyle @@ -39,12 +40,6 @@ examples: description: Use to display inline snippets of code or code-like text. --- -# Text style - -Text style enhances text with additional visual meaning. For example, using subdued text to de-emphasize it from its surrounding text. - ---- - ## Best practices Text style should be: diff --git a/polaris.shopify.com/content/components/thumbnail/index.md b/polaris.shopify.com/content/components/thumbnail/index.md index c4bd9d3ae7e..a530d53f269 100644 --- a/polaris.shopify.com/content/components/thumbnail/index.md +++ b/polaris.shopify.com/content/components/thumbnail/index.md @@ -1,5 +1,6 @@ --- title: Thumbnail +description: Use thumbnails as a visual anchor and identifier for an object. They should be used along with text to provide context. category: Images and icons keywords: - photo @@ -27,12 +28,6 @@ examples: description: Use to render an icon inside of thumbnail. --- -# Thumbnail - -Use thumbnails as a visual anchor and identifier for an object. They should be used along with text to provide context. - ---- - ## Best practices On web, thumbnails should: diff --git a/polaris.shopify.com/content/components/toast/index.md b/polaris.shopify.com/content/components/toast/index.md index 0b3f538548e..2592981eb22 100644 --- a/polaris.shopify.com/content/components/toast/index.md +++ b/polaris.shopify.com/content/components/toast/index.md @@ -1,5 +1,6 @@ --- title: Toast +description: The toast component is a non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. category: Feedback indicators keywords: - toast @@ -31,12 +32,6 @@ examples: description: Although error toast is still available and used in the system, we discourage its use. Reserve it for errors not caused by merchants, like a connection issue. Error toast should convey what went wrong in plain language and should not go over 3 words. For all other error message types, follow the [error message guidelines](https://polaris.shopify.com/patterns/error-messages). --- -# Toast - -The toast component is a non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. - ---- - ## Required components The toast component must be wrapped in the [frame](https://polaris.shopify.com/components/frame) component. diff --git a/polaris.shopify.com/content/components/tooltip/index.md b/polaris.shopify.com/content/components/tooltip/index.md index 112ae70e5e3..2c66e1d8a20 100644 --- a/polaris.shopify.com/content/components/tooltip/index.md +++ b/polaris.shopify.com/content/components/tooltip/index.md @@ -1,5 +1,6 @@ --- title: Tooltip +description: Tooltips are floating labels that briefly explain the function of a user interface element. They can be triggered when merchants hover, focus, tap, or click. category: Overlays keywords: - info @@ -19,12 +20,6 @@ examples: description: Use when the tooltip overlays interactive elements when active, for example a form input. The `dismissOnMouseOut` prop prevents the tooltip from remaining active when mouse hover or focus leaves its `children` and enters the tooltip's content. --- -# Tooltip - -Tooltips are floating labels that briefly explain the function of a user interface element. They can be triggered when merchants hover, focus, tap, or click. - ---- - ## Best practices Tooltips should: diff --git a/polaris.shopify.com/content/components/top-bar/index.md b/polaris.shopify.com/content/components/top-bar/index.md index 0f36ff5bb46..599c5fd9bbc 100644 --- a/polaris.shopify.com/content/components/top-bar/index.md +++ b/polaris.shopify.com/content/components/top-bar/index.md @@ -1,5 +1,6 @@ --- title: Top bar +description: The top bar is a header component that allows merchants to search, access menus, and navigate by clicking on the logo. It’s always visible at the top of interfaces like Shopify or Shopify Plus. Third-party apps that use the top bar can customize the color to match their brand using the [app provider](https://polaris.shopify.com/components/app-provider) component and are required to use their own logo. category: Navigation keywords: - global chrome @@ -24,12 +25,6 @@ examples: description: Provide specific keys and corresponding colors to the top bar theme for finer control. When giving more than just the `background`, providing all keys is necessary to prevent falling back to default colors. --- -# Top bar - -The top bar is a header component that allows merchants to search, access menus, and navigate by clicking on the logo. It’s always visible at the top of interfaces like Shopify or Shopify Plus. Third-party apps that use the top bar can customize the color to match their brand using the [app provider](https://polaris.shopify.com/components/app-provider) component and are required to use their own logo. - ---- - ## Required components The top bar component must be passed to the [frame](https://polaris.shopify.com/components/frame) component. diff --git a/polaris.shopify.com/content/components/video-thumbnail/index.md b/polaris.shopify.com/content/components/video-thumbnail/index.md index 60f1085733f..30ee9e08a37 100644 --- a/polaris.shopify.com/content/components/video-thumbnail/index.md +++ b/polaris.shopify.com/content/components/video-thumbnail/index.md @@ -1,5 +1,6 @@ --- title: Video thumbnail +description: Video thumbnails are a clickable placeholder image. When clicked, it opens a video player within a modal or full screen. category: Images and icons keywords: - video @@ -19,12 +20,6 @@ examples: description: Use to indicate the video’s play progress in relation to its duration. --- -# Video thumbnail - -Video thumbnails are a clickable placeholder image. When clicked, it opens a video player within a modal or full screen. - ---- - ## Best practices Video thumbnails should: diff --git a/polaris.shopify.com/content/components/visually-hidden/index.md b/polaris.shopify.com/content/components/visually-hidden/index.md index d2d3caa02c3..daf8451e65b 100644 --- a/polaris.shopify.com/content/components/visually-hidden/index.md +++ b/polaris.shopify.com/content/components/visually-hidden/index.md @@ -1,5 +1,6 @@ --- title: Visually hidden +description: Use when an element needs to be available to assistive technology (for example, a screen reader) but otherwise hidden. category: Titles and text keywords: - VisuallyHidden @@ -25,12 +26,6 @@ examples: description: Whenever one or more table columns has no need for a visible header, hide the header content rather than omitting it. Note that due to browser quirks the visually hidden component must go inside each ``. --- -# Visually hidden - -Use when an element needs to be available to assistive technology (for example, a screen reader) but otherwise hidden. - ---- - ## Best practices Visually hidden should: diff --git a/polaris.shopify.com/content/contributing/code-of-conduct/index.md b/polaris.shopify.com/content/contributing/code-of-conduct/index.md index f7938968767..909bddce3a6 100644 --- a/polaris.shopify.com/content/contributing/code-of-conduct/index.md +++ b/polaris.shopify.com/content/contributing/code-of-conduct/index.md @@ -1,18 +1,9 @@ --- -title: Components +title: Code of Conduct keywords: - - components - - contributing to polaris react - - how to add a prop - - how to add a prop type - - how to add a new component - - bug fix - - ux improvement - open source --- -# Code of Conduct - ## Our pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, ability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. diff --git a/polaris.shopify.com/content/contributing/components/index.md b/polaris.shopify.com/content/contributing/components/index.md index 8b2d96bc9df..a62b94b05c1 100644 --- a/polaris.shopify.com/content/contributing/components/index.md +++ b/polaris.shopify.com/content/contributing/components/index.md @@ -1,5 +1,6 @@ --- -title: Components +title: Contributing to Polaris React +description: Anyone is welcome to contribute to Polaris React components. There are several types of component contributions, but they typically fall under three categories; bug fix, enhancement, or new pattern. keywords: - components - contributing to polaris react @@ -14,10 +15,6 @@ keywords: - open source --- -# Contributing to Polaris React - -Anyone is welcome to contribute to Polaris React components. There are several types of component contributions, but they typically fall under three categories: bug fix, enhancement, or new pattern. - Bug fixes can be as simple as removing a typo, or as complex as refactoring a component to address a performance or accessibility issue. Enhancements usually add to or update the props of an existing component to extend its functionality or presentation. New patterns can be contributed by simply adding a new example to an existing component's documentation, or by adding new components or utilities. Often component contributions are a mix of these. Start planning your contribution as early as possible to account for the scope in your timeline. To get help with the strategy for your contribution early on, start a [discussion](https://github.com/Shopify/polaris/discussions/new) with the Polaris community. If you have a smaller question, reach out in #polaris if you work at Shopify, or the [Shopify Partners Slack](http://shopifypartners.slack.com) if you're an open source contributor. Once you've decided on the best way to solve the problem, submit a [feature proposal](https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md) or [bug report](https://github.com/Shopify/polaris/issues/new?assignees=&labels=%F0%9F%90%9BBug&template=ISSUE.md) issue. Then contribute the change by shipping a pull request. diff --git a/polaris.shopify.com/content/contributing/designing-with-a-system/index.md b/polaris.shopify.com/content/contributing/designing-with-a-system/index.md index e07e8704733..0cdf827e352 100644 --- a/polaris.shopify.com/content/contributing/designing-with-a-system/index.md +++ b/polaris.shopify.com/content/contributing/designing-with-a-system/index.md @@ -6,8 +6,6 @@ keywords: - designing with a system --- -# Designing with a system - ![Illustration of dozens of chairs of the same kind and a single chair of a diverent kind.](/images/contributing/designing-with-a-system/01.png) At Shopify, we often say, "Polaris is the floor, not the ceiling." The design system provides you with building blocks, and it's up to you to construct them in a way that best meets your user's needs. The idea behind Polaris not being a ceiling is that you shouldn't limit your ideas to fit into existing system pieces too early. Zoom out, figure out the best design solution to the problem, and then see if Polaris has all the pieces for you to design that solution. If there's a gap, then [contribute](https://polaris.shopify.com/contributing) to the system to make it better. diff --git a/polaris.shopify.com/content/contributing/documentation/index.md b/polaris.shopify.com/content/contributing/documentation/index.md index cba270fc1ec..685a47220cf 100644 --- a/polaris.shopify.com/content/contributing/documentation/index.md +++ b/polaris.shopify.com/content/contributing/documentation/index.md @@ -1,5 +1,5 @@ --- -title: Documentation +title: Documenting in Polaris keywords: - how to contribute to polaris documentation - how to contribute to the style guide @@ -7,10 +7,6 @@ keywords: - documentation guidelines --- -# Documenting in Polaris - -From fixing typos to drafting new pattern guidance, everyone is encouraged to contribute to Polaris documentation. - Shopify teams create documentation for polaris.shopify.com, but open source contributors are welcome to make copy edits as well as update or add examples to [component documentation](/contributing/components). To write effectively as a Shopify employee, use a cross-discipline lens. Make sure your content meets both UX and development needs. Before starting, check out our [style guide to the style guide](https://docs.google.com/document/d/1zVDsHIWhoir2svRjdtSdRbD_ruTz3K1nAJcQLGPVQwM/edit#heading=h.ni67tdntu9cr). diff --git a/polaris.shopify.com/content/contributing/figma-ui-kit/index.md b/polaris.shopify.com/content/contributing/figma-ui-kit/index.md index 682b6f818f9..c03728c944c 100644 --- a/polaris.shopify.com/content/contributing/figma-ui-kit/index.md +++ b/polaris.shopify.com/content/contributing/figma-ui-kit/index.md @@ -1,5 +1,5 @@ --- -title: Figma UI Kit +title: Contributing to the Figma UI Kit keywords: - ui kit - figma @@ -7,8 +7,6 @@ keywords: - how to fix a figma component --- -# Contributing to the Figma UI Kit - Any designer that works at Shopify can contribute to the Figma UI Kit. If you find a bug to fix or your team is contributing new patterns or variants to Polaris React components, we want you to feel empowered to contribute. Components, features, or patterns shouldn't be added to the Figma UI Kit if they are not part of Polaris React, as our goal is to keep Figma in sync with the code base. Only contributing changes to the Figma UI Kit when there's a counterpart in Polaris React prevents confusion and keeps tooling in sync across resources. diff --git a/polaris.shopify.com/content/contributing/icons/index.md b/polaris.shopify.com/content/contributing/icons/index.md index cfc7f119ff2..7020d797ceb 100644 --- a/polaris.shopify.com/content/contributing/icons/index.md +++ b/polaris.shopify.com/content/contributing/icons/index.md @@ -1,5 +1,5 @@ --- -title: Icons +title: Contributing to Polaris Icons keywords: - icons - add a new icon @@ -8,8 +8,6 @@ keywords: - how to contribute to polaris icons --- -# Contributing to Polaris Icons - Polaris Icons are important visual aids that help merchants understand actions and concepts across the Shopify Admin. Whether your team needs to add, modify, or deprectate an icon, all designers and developers that work at Shopify are welcome to contribute. Before proposing a new icon, search the [icon explorer](https://polaris.shopify.com/icons). If the icon you're looking for isn't included, create a proposal for the new icon and work with your team to add it. Any additions or changes should also be reflected in the [Figma UI Kit](/contributing/figma-ui-kit). diff --git a/polaris.shopify.com/content/contributing/illustrations/index.md b/polaris.shopify.com/content/contributing/illustrations/index.md index f6cf2eeb8e6..0eff65c9b04 100644 --- a/polaris.shopify.com/content/contributing/illustrations/index.md +++ b/polaris.shopify.com/content/contributing/illustrations/index.md @@ -8,8 +8,6 @@ keywords: - add --- -# Illustrations - Illustration contributions are welcome from any designer working at Shopify. Each illustration must be submitted for feedback from an illustrator in #illustration-guild on Slack. Polaris only supports illustrations within the Shopify Admin product and not marketing assets. diff --git a/polaris.shopify.com/content/contributing/index.md b/polaris.shopify.com/content/contributing/index.md index ab6c7f7e126..40695cb3133 100644 --- a/polaris.shopify.com/content/contributing/index.md +++ b/polaris.shopify.com/content/contributing/index.md @@ -1,14 +1,11 @@ --- title: Contributing to Polaris +description: Polaris thrives on contribution and community support. Anyone, regardless of discipline, is encouraged to contribute. No contribution is too small. We welcome everything from bug fixes or new components, to new UX guidelines. So if you find something to contribute, we hope you feel empowered to go for it. The Polaris team is here to help you along the way. keywords: - how to contribute to polaris - contribution --- -# Contributing to Polaris - -Polaris thrives on contribution and community support. Anyone, regardless of discipline, is encouraged to contribute. No contribution is too small. We welcome everything from bug fixes or new components, to new UX guidelines. So if you find something to contribute, we hope you feel empowered to go for it. The Polaris team is here to help you along the way. - ## Who can contribute Contribution to Polaris looks different depending on whether you work at Shopify. Shopify employees can contribute to any Polaris project, including the Figma UI Kit. Open source contributions are welcome for [Polaris React components](contributing/components) and their [documentation](/contributing/documentation). diff --git a/polaris.shopify.com/content/contributing/shipping-your-contribution/index.md b/polaris.shopify.com/content/contributing/shipping-your-contribution/index.md index 00ced207d2d..951be45fd27 100644 --- a/polaris.shopify.com/content/contributing/shipping-your-contribution/index.md +++ b/polaris.shopify.com/content/contributing/shipping-your-contribution/index.md @@ -1,5 +1,6 @@ --- title: Shipping your contribution +description: While Figma is used to host and maintain the Polaris UI Kit, all other resources in the Polaris design system live in [GitHub](https://github.com/Shopify/polaris). We manage work in progress in our [team backlog](https://github.com/orgs/Shopify/projects), and use GitHub discussions, issues, and pull requests to work in the open. keywords: - contributing to polaris - github @@ -8,10 +9,6 @@ keywords: - clone --- -# Shipping your contribution - -While Figma is used to host and maintain the Polaris UI Kit, all other resources in the Polaris design system live in [GitHub](https://github.com/Shopify/polaris). We manage work in progress in our [team backlog](https://github.com/orgs/Shopify/projects), and use GitHub discussions, issues, and pull requests to work in the open. - ## Project details ### How it's structured diff --git a/polaris.shopify.com/content/contributing/when-to-contribute-new-patterns/index.md b/polaris.shopify.com/content/contributing/when-to-contribute-new-patterns/index.md index b3f982da9aa..a107e984c5a 100644 --- a/polaris.shopify.com/content/contributing/when-to-contribute-new-patterns/index.md +++ b/polaris.shopify.com/content/contributing/when-to-contribute-new-patterns/index.md @@ -1,5 +1,6 @@ --- title: When to contribute new patterns +description: There will likely be times where the system and its components fall short of your preferred solution. You have a decision to make---should you stay consistent with what exists, or go with the best possible solution, regardless of consistency? keywords: - when to contribute to polaris - when to evolve the system @@ -7,10 +8,6 @@ keywords: - contribution guide --- -# When to contribute new patterns - -There will likely be times where the system and its components fall short of your preferred solution. You have a decision to make---should you stay consistent with what exists, or go with the best possible solution, regardless of consistency? - To help you figure this out, start by plotting out where each solution fits in this "perfect vs consistent" framework. Rate the solutions according to: - Consistency with the rest of the product (x axis) diff --git a/polaris.shopify.com/content/foundations/content/accessible-and-inclusive-language/index.md b/polaris.shopify.com/content/foundations/content/accessible-and-inclusive-language/index.md index 0eac76d69a3..10ff5d50ecc 100644 --- a/polaris.shopify.com/content/foundations/content/accessible-and-inclusive-language/index.md +++ b/polaris.shopify.com/content/foundations/content/accessible-and-inclusive-language/index.md @@ -1,5 +1,6 @@ --- title: Accessible and inclusive language +description: Our mission is to make commerce better for _everyone_. Building products for everyone means creating inclusive content. keywords: - copy instructions - copy rules @@ -29,10 +30,6 @@ keywords: - inclusive content --- -# Accessible and inclusive language - -Our mission is to make commerce better for _everyone_. Building products for everyone means creating inclusive content. - The words we use have power. Writing for everyone, everywhere means that we don’t exclude or harm any of our merchants, even if these words have been normalized. Write for more than one perspective, and limit assumptions or biases. For example, don’t assume that your audience is white, has a binary gender, or is nondisabled. Keep in mind that our merchants have intersectional identities, which means they can be from more than one historically-excluded group. diff --git a/polaris.shopify.com/content/foundations/content/actionable-language/index.md b/polaris.shopify.com/content/foundations/content/actionable-language/index.md index 4a207020b8b..adca14c1ff5 100644 --- a/polaris.shopify.com/content/foundations/content/actionable-language/index.md +++ b/polaris.shopify.com/content/foundations/content/actionable-language/index.md @@ -1,5 +1,6 @@ --- title: Actionable language +description: Merchants use Shopify to get things done. Content should be written and structured to help them understand and take the most important actions. keywords: - button content - button copy @@ -69,12 +70,6 @@ keywords: - down --- -# Actionable language - -Merchants use Shopify to get things done. Content should be written and structured to help them understand and take the most important actions. - ---- - ## Headings and subheadings Headings and subheadings are titles and subtitles that refer to sections of the interface. diff --git a/polaris.shopify.com/content/foundations/content/alternative-text/index.md b/polaris.shopify.com/content/foundations/content/alternative-text/index.md index 9e8d14be629..53f2f6fb231 100644 --- a/polaris.shopify.com/content/foundations/content/alternative-text/index.md +++ b/polaris.shopify.com/content/foundations/content/alternative-text/index.md @@ -1,5 +1,6 @@ --- title: Alternative text +description: Shopify aims to provide an [inclusive experience](/foundations/accessibility). Alternative text (alt text) helps people with low or loss of vision use our products. keywords: - speech synthesis - alt HTML element attribute @@ -34,10 +35,6 @@ keywords: - accessible components --- -# Alternative text - -Shopify aims to provide an [inclusive experience](/foundations/accessibility). Alternative text (alt text) helps people with low or loss of vision use our products. - Generally, alt text is text replacement for an image and is often represented by the alt HTML element attribute, `alt=""`, but is also used in other scenarios. Screen readers announce alt text to explain images to people with low or loss of vision. Alt text is also displayed if images fail to download for some reason (for example, due to an unstable network connection). diff --git a/polaris.shopify.com/content/foundations/content/grammar-and-mechanics/index.md b/polaris.shopify.com/content/foundations/content/grammar-and-mechanics/index.md index 35487f1e6f9..ecc0d809fdd 100644 --- a/polaris.shopify.com/content/foundations/content/grammar-and-mechanics/index.md +++ b/polaris.shopify.com/content/foundations/content/grammar-and-mechanics/index.md @@ -1,5 +1,6 @@ --- title: Grammar and mechanics +description: This guide is to help designers, developers, recruiters, UX-ers, product managers, support advisors, or anyone who writes public-facing text for Shopify. keywords: - writing instructions - writing rules @@ -18,12 +19,6 @@ keywords: - public-facing content --- -# Grammar and mechanics - -This guide is to help designers, developers, recruiters, UX-ers, product managers, support advisors, or anyone who writes public-facing text for Shopify. - ---- - ## Basics ### Active voice diff --git a/polaris.shopify.com/content/foundations/content/help-documentation/index.md b/polaris.shopify.com/content/foundations/content/help-documentation/index.md index 003c5da42fc..6a8ac4ff5b3 100644 --- a/polaris.shopify.com/content/foundations/content/help-documentation/index.md +++ b/polaris.shopify.com/content/foundations/content/help-documentation/index.md @@ -1,5 +1,6 @@ --- title: Help documentation +description: After you build an app or other integration, writing help documentation will show merchants how to use it. keywords: - writing instructions - writing guides @@ -29,10 +30,6 @@ keywords: - educational opportunities --- -# Help documentation - -After you build an app or other integration, writing help documentation will show merchants how to use it. - These guidelines are based on our experience writing help documentation for the [Shopify Help Center](https://help.shopify.com/). They’re all intended to serve the same goal: to educate and empower Shopify merchants. diff --git a/polaris.shopify.com/content/foundations/content/merchant-to-customer/index.md b/polaris.shopify.com/content/foundations/content/merchant-to-customer/index.md index 6bbac7bdddd..1800b8a4200 100644 --- a/polaris.shopify.com/content/foundations/content/merchant-to-customer/index.md +++ b/polaris.shopify.com/content/foundations/content/merchant-to-customer/index.md @@ -1,5 +1,6 @@ --- title: Merchant-to-customer content +description: Shopify creates content for different audiences. One of those audiences is merchants’ customers. A customer is a person or organization who interacts with a Shopify merchant or a merchant’s sales channel. keywords: - merchant to buyer - buyer @@ -11,10 +12,6 @@ keywords: - check out --- -# Merchant-to-customer content - -Shopify creates content for different audiences. One of those audiences is merchants’ customers. A customer is a person or organization who interacts with a Shopify merchant or a merchant’s sales channel. - Merchant-to-customer content represents the merchant, not Shopify, and should optimize the customers’ online or retail store experience. Every UX discipline is encouraged to create content at Shopify. Use this guide when you’re writing content that a customer will see on a Shopify store or receive from a merchant. diff --git a/polaris.shopify.com/content/foundations/content/naming/index.md b/polaris.shopify.com/content/foundations/content/naming/index.md index 091347b4a89..5ea0bad0c51 100644 --- a/polaris.shopify.com/content/foundations/content/naming/index.md +++ b/polaris.shopify.com/content/foundations/content/naming/index.md @@ -1,5 +1,6 @@ --- title: Naming +description: The names we give our products and features teach merchants how to use Shopify and how to find the things they need to run their business. keywords: - names - caps @@ -19,12 +20,6 @@ keywords: - capitalized names --- -# Naming - -The names we give our products and features teach merchants how to use Shopify and how to find the things they need to run their business. - ---- - ## Thoughtful naming Names influence how merchants and other audiences perceive and understand diff --git a/polaris.shopify.com/content/foundations/content/product-content/index.md b/polaris.shopify.com/content/foundations/content/product-content/index.md index c3576ea4b50..ecabad49a57 100644 --- a/polaris.shopify.com/content/foundations/content/product-content/index.md +++ b/polaris.shopify.com/content/foundations/content/product-content/index.md @@ -1,5 +1,6 @@ --- title: Product content +description: Thoughtful, consistent interface content is a core element of a well-designed user experience. keywords: - content standards - content guidelines @@ -27,10 +28,6 @@ keywords: - public-facing content --- -# Product content - -Thoughtful, consistent interface content is a core element of a well-designed user experience. - Our content standards will help you understand how to think strategically about the language in your products and apps. They’ll also give you clear, tactical suggestions designed to help you use language to craft better experiences. [Each component](/components/get-started) also includes content guidelines about how to write for specific interface elements. diff --git a/polaris.shopify.com/content/foundations/content/voice-and-tone/index.md b/polaris.shopify.com/content/foundations/content/voice-and-tone/index.md index 82498aa9e18..9df761d1521 100644 --- a/polaris.shopify.com/content/foundations/content/voice-and-tone/index.md +++ b/polaris.shopify.com/content/foundations/content/voice-and-tone/index.md @@ -1,5 +1,6 @@ --- title: Voice and tone +description: Learn how to apply Shopify’s voice and choose the right tone, no matter what product, feature, or app you’re building. keywords: - sound like Shopify - personality of Shopify @@ -12,12 +13,6 @@ keywords: - content tone --- -# Voice and tone - -Learn how to apply Shopify’s voice and choose the right tone, no matter what product, feature, or app you’re building. - ---- - ## What are voice and tone? Shopify’s voice is a reflection of who we are. We should always sound like diff --git a/polaris.shopify.com/content/foundations/design/colors/index.md b/polaris.shopify.com/content/foundations/design/colors/index.md index d5bc314e6b4..0aae91a371d 100644 --- a/polaris.shopify.com/content/foundations/design/colors/index.md +++ b/polaris.shopify.com/content/foundations/design/colors/index.md @@ -1,15 +1,12 @@ --- title: Colors +description: Our color system builds on the recognition of the Shopify brand colors to make the admin interface more usable. keywords: - visual patterns - color strategy - color use --- -# Colors - -Our color system builds on the recognition of the Shopify brand colors to make the admin interface more usable. - ![Diagram showcasing layers of color of various hues](/images/foundations/design/colors/color-intro@2x.png) --- diff --git a/polaris.shopify.com/content/foundations/design/data-visualizations/index.md b/polaris.shopify.com/content/foundations/design/data-visualizations/index.md index d5f50b6bd55..3fbfa374ab2 100644 --- a/polaris.shopify.com/content/foundations/design/data-visualizations/index.md +++ b/polaris.shopify.com/content/foundations/design/data-visualizations/index.md @@ -1,13 +1,10 @@ --- title: Data visualizations +description: Visualizations surface patterns in data, and provide immediate answers to a single, specific question. keywords: - data viz --- -# Data visualizations - -Visualizations surface patterns in data, and provide immediate answers to a single, specific question. - This section outlines data visualization practices at Shopify and how to leverage them. --- diff --git a/polaris.shopify.com/content/foundations/design/design/index.md b/polaris.shopify.com/content/foundations/design/design/index.md index c741d1616d2..da122381730 100644 --- a/polaris.shopify.com/content/foundations/design/design/index.md +++ b/polaris.shopify.com/content/foundations/design/design/index.md @@ -1,15 +1,12 @@ --- title: Design +description: These are the principles that shape how we design all the experiences across the Shopify admin. keywords: - visual design - design language - design --- -# Design - -These are the principles that shape how we design all the experiences across the Shopify admin. - ![Design of Polaris for Admin, showcasing an admin interface and a mobile view](/images/foundations/design/design-intro@2x.png) ### Fresh visual style diff --git a/polaris.shopify.com/content/foundations/design/icons/index.md b/polaris.shopify.com/content/foundations/design/icons/index.md index 85a2a65497b..a8d3da72579 100644 --- a/polaris.shopify.com/content/foundations/design/icons/index.md +++ b/polaris.shopify.com/content/foundations/design/icons/index.md @@ -1,5 +1,6 @@ --- title: Icons +description: Icons in the Shopify admin act as visual aids to help merchants complete tasks. They’re simple, informative, and build on the visual language of the design system. keywords: - shopify icons - icon sets @@ -19,10 +20,6 @@ keywords: - icon colors --- -# Icons - -Icons in the Shopify admin act as visual aids to help merchants complete tasks. They’re simple, informative, and build on the visual language of the design system. - ![A collection of various icons used in the Shopify Admin.](/images/foundations/design/icons/icons-intro@2x.png) --- diff --git a/polaris.shopify.com/content/foundations/design/illustrations/index.md b/polaris.shopify.com/content/foundations/design/illustrations/index.md index 10b2632e904..009831fe4de 100644 --- a/polaris.shopify.com/content/foundations/design/illustrations/index.md +++ b/polaris.shopify.com/content/foundations/design/illustrations/index.md @@ -1,14 +1,11 @@ --- title: Illustrations +description: The Shopify admin uses a precise illustration style to help merchants quickly and clearly understand how things work across every experience. keywords: - drawings - pictures --- -# Illustrations - -The Shopify admin uses a precise illustration style to help merchants quickly and clearly understand how things work across every experience. - ![The illustration of a chair, in simples straight lines, followed by a version with curves and some color, followed by a final version with filled shapes and shadows.](/images/foundations/design/illustrations/illustrations-intro@2x.png) --- diff --git a/polaris.shopify.com/content/foundations/design/interaction-states/index.md b/polaris.shopify.com/content/foundations/design/interaction-states/index.md index 16312609349..dfabe056d6c 100644 --- a/polaris.shopify.com/content/foundations/design/interaction-states/index.md +++ b/polaris.shopify.com/content/foundations/design/interaction-states/index.md @@ -1,5 +1,6 @@ --- title: Interaction states +description: Interaction states communicate the status of an element in the interface, establish confidence once an action is taken, and suggest the ability (or inability) to interact with the element. keywords: - visual patterns - color strategy @@ -13,10 +14,6 @@ keywords: - state --- -# Interaction states - -Interaction states communicate the status of an element in the interface, establish confidence once an action is taken, and suggest the ability (or inability) to interact with the element. - ![A collection of buttons in different states](/images/foundations/design/interaction-states/interaction-states-intro@2x.png) --- diff --git a/polaris.shopify.com/content/foundations/design/sounds/index.md b/polaris.shopify.com/content/foundations/design/sounds/index.md index fbd8d5f7446..66a11bd196c 100644 --- a/polaris.shopify.com/content/foundations/design/sounds/index.md +++ b/polaris.shopify.com/content/foundations/design/sounds/index.md @@ -1,15 +1,12 @@ --- title: Sounds +description: We use sound to communicate information and to enhance how merchants experience the Shopify admin. Sound patterns make interactions easier and more predictable. keywords: - audio - sonic - noise --- -# Sounds - -We use sound to communicate information and to enhance how merchants experience the Shopify admin. Sound patterns make interactions easier and more predictable. - ![Visual representation of sound waves as concentric circles](/images/foundations/design/sounds/sound-intro@2x.png) --- diff --git a/polaris.shopify.com/content/foundations/design/spacing/index.md b/polaris.shopify.com/content/foundations/design/spacing/index.md index 06a02447658..545ae19e6e2 100644 --- a/polaris.shopify.com/content/foundations/design/spacing/index.md +++ b/polaris.shopify.com/content/foundations/design/spacing/index.md @@ -1,5 +1,6 @@ --- title: Spacing +description: Consistent spacing creates visual balance that makes the user interface (UI) easier for merchants to scan. Apply consistent spacing to improve the quality of the UI. keywords: - spacing - space @@ -10,12 +11,6 @@ keywords: - padding --- -# Spacing - -Consistent spacing creates visual balance that makes the user interface (UI) easier for merchants to scan. Apply consistent spacing to improve the quality of the UI. - ---- - ## Principles ### Create visual rhythm diff --git a/polaris.shopify.com/content/foundations/design/typography/index.md b/polaris.shopify.com/content/foundations/design/typography/index.md index 256fec4d342..de52a0ecd9c 100644 --- a/polaris.shopify.com/content/foundations/design/typography/index.md +++ b/polaris.shopify.com/content/foundations/design/typography/index.md @@ -1,15 +1,12 @@ --- title: Typography +description: Shopify admin provides a constrained, purposeful set of typographic styles. These styles map to functional roles so you know when to use what. keywords: - type styles - font sizes - fonts --- -# Typography - -Shopify admin provides a constrained, purposeful set of typographic styles. These styles map to functional roles so you know when to use what. - By tying typographic styles to specific functions in the interface, we create a clear visual pattern for merchants to follow while they interact with our product. --- diff --git a/polaris.shopify.com/content/foundations/foundations/accessibility/index.md b/polaris.shopify.com/content/foundations/foundations/accessibility/index.md index a08c25ce852..de365f1fa94 100644 --- a/polaris.shopify.com/content/foundations/foundations/accessibility/index.md +++ b/polaris.shopify.com/content/foundations/foundations/accessibility/index.md @@ -1,5 +1,6 @@ --- title: Accessibility +description: Making commerce better for everyone means caring deeply about making quality products. A quality product should have a fantastic user experience (UX). keywords: - a11y - universal design @@ -17,9 +18,7 @@ keywords: - diverse --- -# Accessibility - -Making commerce better for everyone means caring deeply about making quality products. A quality product should have a fantastic user experience (UX), including: +This includes: - A beautiful and functional design - Consistent and useful [copy](/content/product-content) diff --git a/polaris.shopify.com/content/foundations/foundations/experience-values/index.md b/polaris.shopify.com/content/foundations/foundations/experience-values/index.md index c3ff8f90b38..c58630e3edc 100644 --- a/polaris.shopify.com/content/foundations/foundations/experience-values/index.md +++ b/polaris.shopify.com/content/foundations/foundations/experience-values/index.md @@ -1,5 +1,6 @@ --- title: Shopify experience values +description: At Shopify, we empower commerce at a global scale. We build products, tools, and services for people to start, manage, and scale their businesses. We manage enormous complexity for commerce giants, and give new entrepreneurs the best chance to succeed. keywords: - mission - approaches @@ -28,10 +29,6 @@ keywords: - polished --- -# Shopify experience values - -At Shopify, we empower commerce at a global scale. We build products, tools, and services for people to start, manage, and scale their businesses. We manage enormous complexity for commerce giants, and give new entrepreneurs the best chance to succeed. - These values are at the heart of how we build experiences at Shopify. They’re important whether you work at Shopify or you’re developing third-party apps or themes. --- diff --git a/polaris.shopify.com/content/foundations/foundations/formatting-localized-currency/index.md b/polaris.shopify.com/content/foundations/foundations/formatting-localized-currency/index.md index 023b3a01969..ac0ba83d4c0 100644 --- a/polaris.shopify.com/content/foundations/foundations/formatting-localized-currency/index.md +++ b/polaris.shopify.com/content/foundations/foundations/formatting-localized-currency/index.md @@ -1,5 +1,6 @@ --- title: Formatting localized currency +description: Currencies are formatted differently in different countries and languages. keywords: - internationalization - localization @@ -20,9 +21,7 @@ keywords: - japan --- -# Formatting localized currency - -Currencies are formatted differently in different countries and languages. There’s a currency formatting framework to: +There’s a currency formatting framework to: - Help more merchants sell globally - Localize currency formatting for merchants and customers everywhere diff --git a/polaris.shopify.com/content/foundations/foundations/information-architecture/index.md b/polaris.shopify.com/content/foundations/foundations/information-architecture/index.md index 3ece67b0811..e63dbb95993 100644 --- a/polaris.shopify.com/content/foundations/foundations/information-architecture/index.md +++ b/polaris.shopify.com/content/foundations/foundations/information-architecture/index.md @@ -1,5 +1,6 @@ --- title: Information architecture +description: Everything we create at Shopify has an underlying foundation of information architecture. If you’re a designer, a content strategist, or a UX developer, you’re already doing IA work. keywords: - IA principles - info architecture @@ -8,12 +9,6 @@ keywords: - navigation --- -# Information architecture (IA) - -Everything we create at Shopify has an underlying foundation of information architecture. If you’re a designer, a content strategist, or a UX developer, you’re already doing IA work. - ---- - ## Defining IA Information architecture is the practice of organizing, structuring, and labeling content in an effective and sustainable way. Whether you’re creating an app, part of the Shopify admin, a new feature, or an editorial page, these IA principles are here to help you make content usable and findable. diff --git a/polaris.shopify.com/content/foundations/foundations/internationalization/index.md b/polaris.shopify.com/content/foundations/foundations/internationalization/index.md index 4a04b16ddf3..6781f49216e 100644 --- a/polaris.shopify.com/content/foundations/foundations/internationalization/index.md +++ b/polaris.shopify.com/content/foundations/foundations/internationalization/index.md @@ -1,5 +1,6 @@ --- title: Internationalization +description: Make commerce better for everyone by building interfaces that work everywhere. These guidelines will help you design, write, and build products that can be used in every part of the world. keywords: - internationalization - localization @@ -17,10 +18,6 @@ keywords: - france --- -# Internationalization - -Make commerce better for everyone by building interfaces that work everywhere. These guidelines will help you design, write, and build products that can be used in every part of the world. - We want our merchants to experience Shopify in a way that’s appropriate and meaningful to them, no matter where they are in the world. We aim to build one experience that works for all merchants in all of our markets. However, when a certain experience doesn’t fit a specific market, we should tailor it. diff --git a/polaris.shopify.com/content/foundations/patterns/error-messages/index.md b/polaris.shopify.com/content/foundations/patterns/error-messages/index.md index fa85c92a3b3..d58e582d868 100644 --- a/polaris.shopify.com/content/foundations/patterns/error-messages/index.md +++ b/polaris.shopify.com/content/foundations/patterns/error-messages/index.md @@ -1,5 +1,6 @@ --- title: Error messages +description: Error messages can be scary. Make errors visible to merchants, easy to understand, and helpful. keywords: - error states - invalid @@ -9,10 +10,6 @@ keywords: - error pages --- -# Error messages - -Error messages can be scary. Make errors visible to merchants, easy to understand, and helpful. - Error messages should: - Tell merchants what happened. If there’s a solution, explain it. If possible, offer a one-click fix with a button. If there’s diff --git a/polaris.shopify.com/content/foundations/patterns/help-content/index.md b/polaris.shopify.com/content/foundations/patterns/help-content/index.md index c53f01b5d4d..74b6862a17c 100644 --- a/polaris.shopify.com/content/foundations/patterns/help-content/index.md +++ b/polaris.shopify.com/content/foundations/patterns/help-content/index.md @@ -1,5 +1,6 @@ --- title: Help content +description: Help content is educational text that describes interactive elements or offers information about concepts in the UI. keywords: - help text - learn more @@ -7,11 +8,6 @@ keywords: - help --- -# Help content - -​ -Help content is educational text that describes interactive elements or offers information about concepts in the UI. - The goal of help content is to teach merchants: - How to complete a task or make a good decision for their business diff --git a/polaris.shopify.com/content/foundations/patterns/home-cards/index.md b/polaris.shopify.com/content/foundations/patterns/home-cards/index.md index 749daae685f..0161cef3f37 100644 --- a/polaris.shopify.com/content/foundations/patterns/home-cards/index.md +++ b/polaris.shopify.com/content/foundations/patterns/home-cards/index.md @@ -1,15 +1,12 @@ --- title: Home cards +description: Home cards make actionable recommendations based on data from the merchant’s store, or give merchants feedback about their store’s performance. keywords: - home cards - insights - milestones --- -# Home cards - -Home cards make actionable recommendations based on data from the merchant’s store, or give merchants feedback about their store’s performance. - Home cards should: - track progress and give feedback diff --git a/polaris.shopify.com/content/foundations/patterns/loading/index.md b/polaris.shopify.com/content/foundations/patterns/loading/index.md index 1e128145281..322055fa33e 100644 --- a/polaris.shopify.com/content/foundations/patterns/loading/index.md +++ b/polaris.shopify.com/content/foundations/patterns/loading/index.md @@ -1,5 +1,6 @@ --- title: Loading +description: Navigating the Shopify admin should be fast, meaningful, and focused, but unintentional loading can get in the way and break a merchant's flow. To deliver a continuous experience, we need to consider loading states when planning and prototyping. slug: loading keywords: - page loading @@ -13,12 +14,6 @@ keywords: - principles --- -# Loading - -Navigating the Shopify admin should be fast, meaningful, and focused, but unintentional loading can get in the way and break a merchant's flow. To deliver a continuous experience, we need to consider loading states when planning and prototyping. - ---- - ### Join the conversation! Do you have ideas or feedback on how we can make these guidelines more empowering and useful? Please share your thoughts in the [GitHub discussion](https://github.com/Shopify/polaris/discussions/5976). diff --git a/polaris.shopify.com/content/foundations/patterns/page-layouts/index.md b/polaris.shopify.com/content/foundations/patterns/page-layouts/index.md index b3292731bea..528bdc708cb 100644 --- a/polaris.shopify.com/content/foundations/patterns/page-layouts/index.md +++ b/polaris.shopify.com/content/foundations/patterns/page-layouts/index.md @@ -1,5 +1,6 @@ --- title: Page layouts +description: Layout patterns provide common ways to arrange the content of a screen. keywords: - layout - page @@ -9,12 +10,6 @@ keywords: - stack --- -# Page Layouts - -Layout patterns provide common ways to arrange the content of a screen. - ---- - ## Structure of a screen A screen is the entire user interface (UI) of an application at a given time. diff --git a/polaris.shopify.com/content/foundations/patterns/pickers/index.md b/polaris.shopify.com/content/foundations/patterns/pickers/index.md index b20e6f7f5f6..24a493aec7d 100644 --- a/polaris.shopify.com/content/foundations/patterns/pickers/index.md +++ b/polaris.shopify.com/content/foundations/patterns/pickers/index.md @@ -1,5 +1,6 @@ --- title: Pickers +description: Picking experiences present merchants with options to browse, find, and select from to perform an action. Pickers can help merchants navigate to a new page, filter an index table, or input one or more values in a form. keywords: - customer segments - locations @@ -17,12 +18,6 @@ keywords: - single select --- -# Pickers - -Picking experiences present merchants with options to browse, find, and select from to perform an action. Pickers can help merchants navigate to a new page, filter an index table, or input one or more values in a form. - ---- - ## Best practices ### Use progressive disclosure diff --git a/polaris.shopify.com/content/foundations/patterns/text-fields/index.md b/polaris.shopify.com/content/foundations/patterns/text-fields/index.md index 82b9e173538..a06f462d331 100644 --- a/polaris.shopify.com/content/foundations/patterns/text-fields/index.md +++ b/polaris.shopify.com/content/foundations/patterns/text-fields/index.md @@ -1,15 +1,12 @@ --- title: Text fields +description: Text fields are a combination of the field label (the title) and the input area. Inputs can be typed text, URLs, date pickers, and more. keywords: - text fields - search - placeholder text --- -# Text fields - -Text fields are a combination of the field label (the title) and the input area. Inputs can be typed text, URLs, date pickers, and more. - Text fields can be grouped in a form or placed individually in the UI. Placeholder text should generally be avoided in text fields. Help text can be used below the text input area to guide the user on acceptable inputs. ![text-field-anatomy](/images/foundations/patterns/text-fields/text-field-anatomy@2x.png) diff --git a/polaris.shopify.com/content/updates/typography-updates/index.md b/polaris.shopify.com/content/updates/typography-updates/index.md index ad687f1a77c..61155069971 100644 --- a/polaris.shopify.com/content/updates/typography-updates/index.md +++ b/polaris.shopify.com/content/updates/typography-updates/index.md @@ -1,5 +1,6 @@ --- -title: Typography updates +title: Polaris typography updates +description: Learn about what changes are coming to Polaris typography. keywords: - typography - type @@ -8,10 +9,6 @@ keywords: - type styles --- -# Polaris typography updates - -Learn about what changes are coming to Polaris typography - ![Screen showing the new type styles](/images/updates/type-updates-feature@2x.png) --- diff --git a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx index fc2a4d17e47..91065cfd586 100644 --- a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx +++ b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx @@ -9,10 +9,8 @@ interface Props { markdownFile: MarkdownFile; } -function FoundationsPage({ - markdownFile: { readme, description, frontMatter }, -}: Props) { - let { title } = frontMatter; +function FoundationsPage({ markdownFile: { readme, frontMatter } }: Props) { + let { title, description } = frontMatter; if (title.includes("/")) { const parts = title.split("/"); @@ -24,7 +22,8 @@ function FoundationsPage({ - + + ); diff --git a/polaris.shopify.com/src/components/Markdown/Markdown.tsx b/polaris.shopify.com/src/components/Markdown/Markdown.tsx index b7fb8730076..86055b84560 100644 --- a/polaris.shopify.com/src/components/Markdown/Markdown.tsx +++ b/polaris.shopify.com/src/components/Markdown/Markdown.tsx @@ -7,17 +7,16 @@ import Code from "../Code"; interface Props { text: string; - skipH1?: boolean; } -function Markdown({ text, skipH1 }: Props) { +function Markdown({ text }: Props) { return ( { - return skipH1 ? <> :

{children}

; + return

{children}

; }, h2: ({ children }) => { if (children.length === 1 && typeof children[0] === "string") { diff --git a/polaris.shopify.com/src/pages/components/[component].tsx b/polaris.shopify.com/src/pages/components/[component].tsx index 4008fb8be5f..95a1bc47b51 100644 --- a/polaris.shopify.com/src/pages/components/[component].tsx +++ b/polaris.shopify.com/src/pages/components/[component].tsx @@ -54,11 +54,11 @@ const Components = ({ - + {typedStatus && } {propsForComponent && } - + ); @@ -81,12 +81,9 @@ export const getStaticProps: GetStaticProps< if (fs.existsSync(mdFilePath)) { const componentMarkdown = fs.readFileSync(mdFilePath, "utf-8"); const data: MarkdownData = parseMarkdown(componentMarkdown); - const readmeText = data.readme; - const readmeTextParts = readmeText.split(/\n\n/); - const description = - readmeTextParts.length > 2 ? readmeTextParts[2].trim() : ""; - const body = - readmeTextParts.length > 3 ? readmeTextParts.slice(3).join("\n\n") : ""; + + const description = data.frontMatter.description; + const body = data.readme; const readme = { description, diff --git a/polaris.shopify.com/src/pages/contributing/[doc].tsx b/polaris.shopify.com/src/pages/contributing/[doc].tsx index cd4de4ba99e..619d27399c4 100644 --- a/polaris.shopify.com/src/pages/contributing/[doc].tsx +++ b/polaris.shopify.com/src/pages/contributing/[doc].tsx @@ -14,16 +14,22 @@ import { MarkdownFile } from "../../types"; interface Props { readme: MarkdownFile["readme"]; title: string; + description?: string; } const contributingDirectory = path.join(process.cwd(), "content/contributing"); -const Contributing: NextPage = ({ readme, title }: Props) => { +const Contributing: NextPage = ({ + readme, + title, + description, +}: Props) => { return ( - - + + + {description ? : null} @@ -41,12 +47,15 @@ export const getStaticProps: GetStaticProps = async ({ if (fs.existsSync(mdFilePath)) { const markdown = fs.readFileSync(mdFilePath, "utf-8"); const { readme, frontMatter }: MarkdownFile = parseMarkdown(markdown); - const { name: title = "" } = frontMatter; + const { title, description } = frontMatter; const props: Props = { title, + description: description || null, readme, }; + console.log(props.title); + return { props }; } else { return { notFound: true }; diff --git a/polaris.shopify.com/src/pages/contributing/index.tsx b/polaris.shopify.com/src/pages/contributing/index.tsx index fc933caf4ef..2ab0d280794 100644 --- a/polaris.shopify.com/src/pages/contributing/index.tsx +++ b/polaris.shopify.com/src/pages/contributing/index.tsx @@ -11,16 +11,19 @@ import { MarkdownFile } from "../../types"; import PageMeta from "../../components/PageMeta"; interface Props { + title: string; + description: string; readme: MarkdownFile["readme"]; } -const Contributing: NextPage = ({ readme }) => { +const Contributing: NextPage = ({ readme, description, title }) => { return ( - - + + - + + ); @@ -34,11 +37,14 @@ export const getStaticProps: GetStaticProps< > = async () => { const fullPath = path.join(contributingDirectory, "index.md"); const content = fs.readFileSync(fullPath, "utf-8"); - const { readme } = parseMarkdown(content); + const { readme, frontMatter }: MarkdownFile = parseMarkdown(content); + const { title, description } = frontMatter; if (content) { const props: Props = { readme, + title, + description, }; return { props }; diff --git a/polaris.shopify.com/src/types.ts b/polaris.shopify.com/src/types.ts index 604a9a7c002..4ddd9069612 100644 --- a/polaris.shopify.com/src/types.ts +++ b/polaris.shopify.com/src/types.ts @@ -3,7 +3,6 @@ import { Icon } from "@shopify/polaris-icons/metadata"; export type MarkdownFile = { frontMatter: any; - description: string; readme: string; };