|
| 1 | +--- |
| 2 | +title: Getting started |
| 3 | +description: Learn what the Polaris design system is and how it’s used by UXers and developers to build world-class Shopify admin experiences. |
| 4 | +keywords: |
| 5 | + - about |
| 6 | + - polaris |
| 7 | + - design system |
| 8 | + - system |
| 9 | + - getting started |
| 10 | +icon: HintMajor |
| 11 | +--- |
| 12 | +## Quick start |
| 13 | + |
| 14 | +Polaris is the design system for the Shopify admin. There are many layers to being successful with Polaris but if you want to dive in, the first step you might want to do is download the resources. |
| 15 | + |
| 16 | +### Downloads and links |
| 17 | + |
| 18 | +For full descriptions of our resources, see the [develop](/getting-started/##develop) and [design](/getting-started/##design) resources sections. |
| 19 | + |
| 20 | +| Develop | Design | Start exploring | | | |
| 21 | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --- | --- | |
| 22 | +| <ul><li>[Polaris repo and commands](https://github.com/Shopify/polaris/tree/main/polaris-react)</li><ul><li>[Polaris for VS Code extension](https://marketplace.visualstudio.com/items?itemName=Shopify.polaris-for-vscode)</li><ul><li>[Component GitHub package repo](https://github.com/Shopify/polaris/tree/main/polaris-react)</li><ul><li>[Token GitHub Package Repo](https://github.com/Shopify/polaris/tree/main/polaris-tokens)</li><ul><li>[Performing a release](https://github.com/Shopify/polaris/blob/main/documentation/Releasing.md) | <ul><li>[ Design ](polaris.shopify.com/design)</li><ul><li>[Component Figma library](https://www.figma.com/community/file/1111360433678236702)</li><ul><li>[Token Figma library](https://www.figma.com/community/file/1111359207966840858)</li><ul><li>[Icon Figma library](https://www.figma.com/file/mMHFt3kEDNjLMZWowi6gnt/Polaris-Icons?node-id=753%3A2)</li><ul><li>[Product content](https://polaris.shopify.com/foundations/content/product-content)| <ul><li>[Experience values](https://polaris.shopify.com/foundations/foundations/experience-values)</li><ul><li>[Accessibility](https://polaris.shopify.com/foundations/foundations/accessibility)</li><ul><li>[React component library](https://polaris.shopify.com/components)</li><ul><li>[Token library](https://polaris.shopify.com/tokens/colors)</li><ul><li>[Icon library](https://polaris.shopify.com/icons)</li><ul><li>[Actionable language](https://polaris.shopify.com/foundations/content/actionable-language)</li><ul><li>[Error messages](https://polaris.shopify.com/foundations/patterns/error-messages) |
| 23 | + |
| 24 | + |
| 25 | +## Polaris 101 |
| 26 | + |
| 27 | +### What is Polaris? |
| 28 | + |
| 29 | +Polaris is the design system for the Shopify admin. It’s the shared language that guides how we build high-quality merchant experiences, and is grounded in deep merchant understanding. The Polaris components are available for web, iOS, and Android. The design system is made up of design guidance, code libraries, development opinions, and API documentation on how to build merchant experiences for the Shopify admin. Learn more about the [foundational pieces](/what-are-patterns-components-tokens) that make up the Polaris design system. |
| 30 | + |
| 31 | +#### Who is Polaris for? |
| 32 | + |
| 33 | +Polaris is used both internally at Shopify and externally by third-party developers and designers. The Shopify admin includes installable apps built by Shopify employees and third-party developers. Third-party developers can use App Bridge and Polaris to build their Shopify admin apps. Shopify admin apps are web-based and are embedded into the admin web, iOS, and Android platforms. To learn more about building Shopify apps check out [shopify.dev](https://shopify.dev/). |
| 34 | + |
| 35 | + |
| 36 | +#### What’s the Shopify admin? |
| 37 | + |
| 38 | +Merchants set up their store, configure settings, and manage their business using the Shopify admin. It includes core aspects of the merchant’s business, including orders, products, and customers. |
| 39 | + |
| 40 | +The Shopify admin is available across web and native platforms. The Polaris design system is available on every platform the Shopify admin is built for. |
| 41 | + |
| 42 | +### Patterns, components, and tokens |
| 43 | + |
| 44 | +#### Patterns |
| 45 | + |
| 46 | +Design patterns are best practice design guidance. They address situations that merchants commonly face, including: |
| 47 | + |
| 48 | +- Tasks, like searching and filtering |
| 49 | +- Situations, like errors and loading |
| 50 | +- UI characteristics, like feedback |
| 51 | +- Architecture, like navigation and page layout |
| 52 | + |
| 53 | +These patterns center on the merchant and how we build experiences to meet their needs. |
| 54 | + |
| 55 | +Design patterns often use one or more primitive components and adapt them to the context. Some patterns can link to compositions and will contain code examples where possible. |
| 56 | + |
| 57 | +For a deeper understanding of design patterns, read our guide to [admin design patterns](/foundations/patterns/design-patterns). |
| 58 | + |
| 59 | +#### Primitives |
| 60 | + |
| 61 | +Primitives are the building blocks of the Polaris design system. They’re the smallest units of the system that represent codified design decisions and reusable visual elements. The Polaris design system contains primitive tokens and primitive components that can be combined together to create admin UIs. |
| 62 | + |
| 63 | +#### Components |
| 64 | + |
| 65 | +Polaris components are the smallest reusable UI elements for supporting a variety of admin merchant experiences. Polaris components are one of our design system primitives, and are often referred to as primitive components. |
| 66 | + |
| 67 | +These primitive components are highly composable and can be assembled together to create a variety of patterns and user experiences within the admin. |
| 68 | + |
| 69 | +Polaris web components are packaged as the open source [@Shopify/polaris](https://github.com/Shopify/polaris/tree/main/polaris-react) React UI library. The Polaris React library is used in the Shopify admin web app as well as within embedded web views in the Shopify admin iOS and Android apps. |
| 70 | + |
| 71 | +Polaris React Native components are also used in the Shopify admin iOS and Android apps. The Polaris React Native library is only available to Shopify employees building with React Native. |
| 72 | + |
| 73 | +#### Tokens |
| 74 | + |
| 75 | +Design tokens represent reusable design decisions such as color, spacing, and typography. These tokens are used throughout the Polaris design system and Shopify admin to unify the merchant experience across the entire platform. |
| 76 | + |
| 77 | +Polaris design tokens are packaged up as the open source [@Shopify/polaris-tokens](https://github.com/Shopify/polaris/tree/main/polaris-tokens) library |
| 78 | + |
| 79 | +### Shared resources |
| 80 | + |
| 81 | +There are pieces of foundational knowledge that are useful for all disciplines to know. |
| 82 | + |
| 83 | +#### Foundations |
| 84 | +Our design foundations offer fundamental design elements and guidance for creating good merchant experiences. Here are some highlights to get started: |
| 85 | +- [Experience values](https://polaris.shopify.com/foundations/foundations/experience-values) |
| 86 | +- [Accessibility](https://polaris.shopify.com/foundations/foundations/accessibility) |
| 87 | + |
| 88 | + |
| 89 | +#### Content guidelines |
| 90 | +Content guidelines are weaved into most of our component pages, but there are also product content and patterns guidelines that help us speak to merchants in a consistent way. Here are some key guidelines to check out first: |
| 91 | +- [Error messages](https://polaris.shopify.com/foundations/patterns/error-messages) |
| 92 | +- [Product content](https://polaris.shopify.com/foundations/content/product-content) |
| 93 | +- [Actionable language](https://polaris.shopify.com/foundations/content/actionable-language) |
| 94 | + |
| 95 | +## Design |
| 96 | + |
| 97 | +### Resources |
| 98 | + |
| 99 | +#### Components |
| 100 | +Components are reusable building blocks made of interface elements and styles, packaged through code. Piece them together, improve them, and create new ones to solve merchant problems. |
| 101 | +- [Browse components](https://polaris.shopify.com/components) |
| 102 | +- [Component Figma library](https://www.figma.com/community/file/1111360433678236702) |
| 103 | + |
| 104 | +#### Tokens |
| 105 | +Design tokens are coded names that represent design decisions for elements like color, spacing, and typography. Applying them to our designs unifies merchant experiences. |
| 106 | +- [Browse tokens](https://polaris.shopify.com/tokens/colors) |
| 107 | +- [Token Figma library](https://www.figma.com/community/file/1111359207966840858) |
| 108 | + |
| 109 | + |
| 110 | +## Develop |
| 111 | + |
| 112 | +### Resources |
| 113 | + |
| 114 | +#### Polaris for VSCode |
| 115 | +Automatic autocompletion for Polaris tokens, right inside your favorite code editor. |
| 116 | +- [Download extension](https://marketplace.visualstudio.com/items?itemName=Shopify.polaris-for-vscode) |
| 117 | + |
| 118 | +#### Components |
| 119 | +Components are reusable building blocks made of interface elements and styles, packaged through code. Piece them together, improve them, and create new ones to solve merchant problems. |
| 120 | +- [Browse components](https://polaris.shopify.com/components) |
| 121 | +- [Component GitHub Package Repo](https://github.com/Shopify/polaris/tree/main/polaris-react) |
| 122 | + |
| 123 | +#### Tokens |
| 124 | +Design tokens are coded names that represent design decisions for elements like color, spacing, and typography. Applying them to our designs unifies merchant experiences. |
| 125 | +- [Browse tokens](https://polaris.shopify.com/tokens/colors) |
| 126 | +- [Token GitHub Package Repo](https://github.com/Shopify/polaris/tree/main/polaris-tokens) |
| 127 | + |
| 128 | +#### Icons |
| 129 | +The Polaris icon library has 400+ carefully designed icons focused on commerce and entrepreneurship. Use them as visual aids to help merchants complete tasks. |
| 130 | + - [Browse icons](https://polaris.shopify.com/icons) |
| 131 | + |
| 132 | +#### Releases |
| 133 | + |
| 134 | +Polaris uses [Changsets](https://github.com/changesets/changesets) to handle releasing the npm packages in repository. Our [GitHub action](https://github.com/changesets/action) creates a `version` PR called **"Version Packages"**, then keeps it up to date, recreating it when merged. This PR always has an up-to-date run of `changeset version` and performs a releases when changes are merged to the `main` branch. |
| 135 | + |
| 136 | +- [Perform a release](https://github.com/Shopify/polaris/blob/main/documentation/Releasing.md) |
0 commit comments