shopify-polaris

Shopify Polaris — design system operations

Research snapshot: 2026-07-30. Scope note: Shopify archived the public Polaris React repository on 2026-01-06 after releasing Polaris Web Components on 2025-10-01. The detailed public contribution, release, and testing material below therefore describes the mature React-era operating model unless explicitly identified as current. Polaris React repository

1. Governance

• The public React-era model described a Polaris team that evaluated major changes, helped contributors, set priorities from feature-request feedback, reviewed pull requests, and could approve, request changes, merge, or close a proposal with an explanation. Internal support was provided in Shopify’s #polaris Slack channel. Contributing to Polaris, repository contribution guide
• All React repository work occurred on GitHub. Shopify team members and external contributors used the same pull-request review path. Repository contribution guide
• Contributions were expected to address a known gap and add value at scale. Minor changes could be initiated directly, while major work required greater involvement from the Polaris team and was expected to start with a proposal. Contributing to Polaris
• For version releases, anyone at Shopify could perform the release, with support from @Shopify/polaris-team or the internal Polaris developer group. Releasing
• The archived React repository no longer accepts contributions or feature requests. Polaris React repository

2. Component lifecycle

• The public React-era documentation did not publish a single proposed/draft/beta/stable lifecycle for individual components. It distinguished minor contributions (bugs, docs, icons, and limited style changes) from major contributions (new or redesigned components, API changes, and patterns), with major work requiring more evaluation and a contribution proposal. Contributing to Polaris
• A proposed major contribution was expected to show that existing patterns, components, and tokens had been exhausted; demonstrate value to Shopify Admin and other teams; provide evidence of effectiveness; assess effects on existing implementations; and identify resources to complete the work. Contributing to Polaris
• Package prereleases used a next branch and a beta npm distribution tag. This was a release mechanism for the next major version rather than a published maturity state applied to every component. Releasing
• Deprecation warnings were introduced in a minor release with an upgrade path, and removal occurred in the next major release. The documentation site grouped deprecated components separately and marked deprecated props inline. Repository contribution guide, Button component
• The React library itself is now deprecated and archived, with users directed to Polaris Web Components. Polaris React repository

3. Contribution process

• Except for Figma UI Kits, contributions were made through GitHub. Documentation, components, icons, and UI Kit work each had a contribution path; patterns required direct coordination with the Polaris team. Contributing to Polaris
• Contributors were asked to search existing issues and feature requests first. Non-trivial component, public API, or design changes were expected to begin with an issue using the component/change proposal template so the approach could be agreed before implementation. Bug fixes could begin as pull requests, although an issue was still recommended. Repository contribution guide
• A code pull request was expected to branch from main, include tests, pass the test suite, formatting, linting, and TypeScript checks, be inspected locally in Storybook, include a Changeset when a package version would change, and pass the contributor license agreement check. Repository contribution guide
• Breaking changes targeted next; a companion change on main introduced deprecation warnings and the upgrade path before removal. Repository contribution guide
• Snapshot packages could be generated from a pull request after CI passed and a Changeset existed, allowing the change to be tested in a consuming application before release. Releasing

4. Versioning and release cadence

• Polaris React packages followed semantic versioning: patch for fixes and non-public-API changes, minor for new components/props and deprecations, and major for removals and other breaking public API changes. Repository contribution guide
• Changesets recorded the packages to release, bump type, and changelog entry. Automation maintained a Version Packages pull request; merging that pull request to main triggered publication. A parallel next workflow produced beta prereleases. Repository contribution guide, Releasing
• Before publishing, the version pull request was snapshot-tested in Shopify’s consuming application and required passing CI. After release, the package was upgraded in Shopify’s application and contributors were asked to test for regressions. Releases were announced in internal Polaris and engineering channels. Releasing
• Documentation site changes deployed automatically when merged to the polaris.shopify.com directory on main. Releasing
• The public release instructions described readiness-driven automation but did not state a fixed calendar cadence. The archived repository records hundreds of package releases and exposes release notes through Changesets and GitHub releases. Polaris React releases

5. Documentation structure and templates

• A typical Polaris React component page contains: definition and purpose; interactive examples with React/HTML source; typed props and defaults; inline deprecation notices; best practices; comparisons with adjacent elements; content guidelines; related components; accessibility guidance; keyboard support; and links to edit, leave feedback, or create an issue. Button component
• Component pages group components by functional category and maintain a distinct deprecated section. Button component navigation
• The documentation site was part of the same monorepo as code and was deployed from main, which allowed docs changes to follow the same pull-request workflow. Polaris React repository, Releasing
• Changelog messages were required to use plain language, sentence case, a positive conversational tone, and avoid redundant wording. Documentation-only, development dependency, and infrastructure changes could be omitted from package changelogs. Repository contribution guide

6. Naming and token conventions

• Public CSS custom properties use the --p- prefix and semantic, kebab-case names. Color names proceed from domain and property to role/prominence and then state, for example --p-color-bg-surface-secondary-hover, --p-color-text-critical, and --p-color-border-focus. Each token entry includes a value and a usage description. Color tokens
• The React-era token directory grouped tokens by border, breakpoint, color, font, height, motion, shadow, space, text, width, and z-index. Token directory
• The older, now archived standalone token package generated lower camelCase names for JavaScript and kebab-case for JSON, Sass, and CSS custom properties. It is marked legacy and no longer accepts contributions. Legacy Polaris tokens repository
• Component names were plain product-language nouns such as Button, Banner, and Index table; older replacements were visibly prefixed or grouped as legacy/deprecated rather than silently reused. Components navigation

7. Accessibility criteria and enforcement

• Polaris React targeted WCAG 2.1 Level A and AA and stated that components were tested with automated and manual methods. Accessibility foundation
• The contribution testing guide recommended running Pa11y before submitting a pull request and required manual testing because many criteria cannot be automated. Its checklist covered semantic structure, color and non-text contrast, resizing/reflow, keyboard operation and focus, dynamic content, accessible names/roles/states, touch and motion input, media alternatives, and assistive-technology testing. Accessibility testing
• Component pages included implementation-specific accessibility and keyboard guidance, not only global guidance. Button component
• Accessibility issues were tracked with an Accessibility label; contributors were asked to search that backlog before filing a new issue. Accessibility testing
• The foundation documentation cautioned that accessible components do not guarantee an accessible product integration and asked teams to test complete user task flows after integration. Accessibility foundation

8. Audit and review cycle

• Pull-request gates included automated tests, formatting, linting, type checking, Storybook inspection, CI, and pre-release snapshot testing in a consuming Shopify application. Repository contribution guide, Releasing
• Existing accessibility problems were collected under a dedicated issue label, while deprecations were announced in minor versions before removal in a major version and surfaced in documentation. Accessibility testing, repository contribution guide
• The release process tested the aggregate Version Packages pull request in Shopify’s application before publication and again coordinated an application upgrade after publication, providing a regression check at the point of release. Releasing
• The cited public material did not define a fixed periodic component inventory or drift-audit interval. React-era drift was handled through continuous issue tracking, contribution review, integration testing, deprecation, and major-version removal.
• The 2025–2026 migration from Polaris React to Web Components is itself a system-wide deprecation event: the old repository is read-only and redirects adopters to the replacement. Polaris React repository