How shopify/polaris-react works
Project type and purpose
• This is a Turborepo-based monorepo containing multiple npm packages, tooling and sites for Shopify’s Polaris design system.
• Key workspaces:
• polaris-for-vscode (VS Code extension)
• polaris-tokens (design tokens library)
• polaris-react (React component library)
• polaris.shopify.com (Next.js documentation site)
• stylelint-polaris (custom stylelint rules)
• polaris-migrator (CLI for automated code migrations)
High-level architecture
• Monorepo as a vertical stack of package‐nodes.
• “Monorepo Root” at the top. Below it, stack each workspace in its own rectangle.
• polaris-tokens → polaris-react (design tokens consumed by React components)
• polaris-react → polaris.shopify.com (components rendered in the docs site)
• polaris-react → polaris-for-vscode (language server uses component metadata)
• polaris-migrator (standalone CLI, can be off to the side)
Polaris-react
a. Main sub-components
• src/components (all UI components)
• src/utilities (hooks, contexts, helpers)
• config & scripts (build, lint, test)
• .storybook (demo harness)
b. Component families
Components into a grid layout under the polaris-react node. For example, columns by category:
• Inputs & Controls: Button, TextField, Select, Checkbox, RadioButton, RangeSlider
• Navigation & Overlays: Modal, Popover, Tooltip, Navigation, Tabs, TopBar
• Data Display: Card, DataTable, List, ResourceList, Page, Banner
• Feedback & Indicators: Spinner, ProgressBar, Skeleton*
• Utilities: Frame, AppProvider, PolarisTestProvider
Category headers as rows and component names as cells in a grid.
Architectural patterns & design principles
• Monorepo with independent workspaces, shared config.
• React library follows a component-per-folder pattern, each with .stories.tsx, .test.tsx, styles, types.
• Utility-first approach: hooks and contexts live separately under src/utilities.
• Storybook for interactive development, Next.js for docs.