# shopify/polaris-react architecture

> Architecture diagram of the GitHub repository shopify/polaris-react, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/polaris-react
- Repository: https://github.com/shopify/polaris-react

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    MonorepoRoot["Monorepo Root"]:::root
    PolarisTokens["polaris-tokens"]:::coreblue
    PolarisIcons["polaris-icons"]:::coreblue
    PolarisReact["polaris-react"]:::coreblue
    PolarisVscode["polaris-for-vscode"]:::docorange
    PolarisDocs["polaris.shopify.com"]:::docorange
    Stylelint["stylelint-polaris"]:::toolgreen
    PolarisMigrator["polaris-migrator"]:::toolgreen

    MonorepoRoot --> PolarisTokens
    MonorepoRoot --> PolarisIcons
    MonorepoRoot --> PolarisReact
    MonorepoRoot --> PolarisVscode
    MonorepoRoot --> PolarisDocs
    MonorepoRoot --> Stylelint
    MonorepoRoot --> PolarisMigrator

    PolarisTokens -->|"imports tokens"| PolarisReact
    PolarisIcons -->|"imports icons"| Icon
    PolarisReact -->|"used by docs"| PolarisDocs
    PolarisReact -->|"used by VSCode"| PolarisVscode

    subgraph "polaris-react"
        direction TB
        subgraph "Components Grid" 
            style ComponentsGrid fill:#f9f,stroke:#333,stroke-width:1px
            subgraph "Layout & Structure"
                Box["Box"]
                StackCmp["Stack"]
                InlineStack["InlineStack"]
                GridCmp["Grid"]
                FormLayout["FormLayout"]
            end
            subgraph "Inputs & Controls"
                Button["Button"]
                TextField["TextField"]
                Select["Select"]
                Checkbox["Checkbox"]
                RadioButton["RadioButton"]
                RangeSlider["RangeSlider"]
                Icon["Icon"]
            end
            subgraph "Navigation & Overlays"
                Modal["Modal"]
                Popover["Popover"]
                Tooltip["Tooltip"]
                Navigation["Navigation"]
                Tabs["Tabs"]
                TopBar["TopBar"]
            end
            subgraph "Data Display"
                Card["Card"]
                DataTable["DataTable"]
                List["List"]
                ResourceList["ResourceList"]
                Page["Page"]
                Banner["Banner"]
            end
            subgraph "Feedback & Indicators"
                Spinner["Spinner"]
                ProgressBar["ProgressBar"]
                Skeleton["Skeleton"]
            end
            subgraph "Utilities"
                Frame["Frame"]
                AppProvider["AppProvider"]
                PolarisTestProvider["PolarisTestProvider"]
            end
        end
        Utilities["Utilities (hooks, contexts, helpers)"]:::utility
        ConfigScripts["config & scripts"]:::config
        Storybook[".storybook"]:::storybook
        Utilities -->|"provides context"| ComponentsGrid
        ConfigScripts --> PolarisReact
        Storybook --> PolarisReact
    end

    click MonorepoRoot "https://github.com/shopify/polaris-react/tree/main//"
    click PolarisTokens "https://github.com/shopify/polaris-react/tree/main//polaris-tokens"
    click PolarisIcons "https://github.com/shopify/polaris-react/tree/main//polaris-icons"
    click PolarisReact "https://github.com/shopify/polaris-react/tree/main//polaris-react"
    click PolarisVscode "https://github.com/shopify/polaris-react/tree/main//polaris-for-vscode"
    click PolarisDocs "https://github.com/shopify/polaris-react/blob/main//polaris.shopify.com"
    click Stylelint "https://github.com/shopify/polaris-react/tree/main//stylelint-polaris"
    click PolarisMigrator "https://github.com/shopify/polaris-react/tree/main//polaris-migrator"
    click Storybook "https://github.com/shopify/polaris-react/blob/main//polaris-react/.storybook"
    click ConfigScripts "https://github.com/shopify/polaris-react/tree/main//polaris-react/config"
    click ConfigScripts "https://github.com/shopify/polaris-react/tree/main//polaris-react/scripts"
    click Box "https://github.com/shopify/polaris-react/tree/main//polaris-react/src/components"
    click Frame "https://github.com/shopify/polaris-react/tree/main//polaris-react/src/utilities"
    click Utilities "https://github.com/shopify/polaris-react/tree/main//polaris-react/src/utilities"

    classDef root fill:#ffffff,stroke:#000,stroke-width:2px
    classDef coreblue fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px
    classDef toolgreen fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    classDef docorange fill:#ffe6cc,stroke:#d79b00,stroke-width:2px
    classDef utility fill:#f5f5f5,stroke:#888,stroke-width:1px
    classDef config fill:#f5f5f5,stroke:#888,stroke-width:1px
    classDef storybook fill:#f5f5f5,stroke:#888,stroke-width:1px
```
