Sanity UI Design System

The Sanity UI monorepo contains the design system packages used across Sanity products. The core published packages are located in the packages/ directory and include:

• @sanity/ui: The primary React component library.
• @sanity/icons: Icon components (SVG converted to React).
• @sanity/color: The official color palette.
• @sanity/logos: Sanity and GROQ logo components.
• figma-plugin-sanity-ui: A Figma plugin for accessing Sanity UI theme tokens.
• figma-plugin-sanity-color: A Figma plugin for the @sanity/color palette.

All stories in the Sanity UI Storybook are automatically wrapped in a common decorator that provides:

1. A <ThemeProvider> for theme context.
2. A <Card> component with default padding.

Opting out of padding: If a story requires exact viewport dimensions (for example, when running interaction tests that assert responsive behavior), you can opt out of the default padding by using the padding: 0 parameter.

// Example of opting out of padding for responsive testing
export const Basic = {
  parameters: {
    padding: 0,
  },
};

The enrich-icon function is part of the Sanity Blueprint for the sanity.io/ui docs. It listens for created or updated icon documents in the mos42crl.production dataset that lack a description.

It uses Agent Actions to analyze the rasterized icon preview and automatically writes a search-friendly description and search tags. These fields power the semantic icon search on icons.sanity.dev.

Requirement: The function resolves the schema as _.schemas.production, so the studio schema must be deployed for Agent Actions to function correctly. You can deploy the schema using:

pnpm --filter sanity-ui-studio schema:deploy

The documentation site is a fully static Next.js application. Content is managed directly in the codebase rather than being fetched from a Sanity dataset at runtime.

Editing existing pages

Every page is defined by a page.tsx file located under src/app/(website)/. To change the content of a page, edit the corresponding page.tsx file or the content components found in src/components/page/article/.

Adding new pages

The navigation tree is automatically generated based on the file structure. To add a new page to the documentation:

1. Create a new folder within the routing structure.
2. Add a page.tsx file to that folder to define the page content.
3. Add a nav.ts file to the folder to define its title, ordering, and display flags.

Note: Group folders (e.g., docs/primitive/) only require a nav.ts file to organize the sub-pages.

In v4, Tooltip and Popover use React's <Activity> component to keep closed content mounted in the DOM (using display: none) to preserve internal state and pre-render content.

Key implications:

• Recursive Content: Popovers with recursive content must gate the recursion on the open state to avoid rendering an infinitely deep hidden tree.
• Testing: Assertions must check for visibility rather than existence in the DOM.
• Component Type: All components are now plain function components that accept ref as a regular prop (React 19 semantics).

Blueprints are deployed using @sanity/runtime-cli via GitHub workflows defined in .github/workflows/sanity-blueprint-docs.yml.

• Pull Requests: Runs blueprints doctor and blueprints plan.
• Pushes to main: Runs blueprints deploy.

Required Secrets/Environment Variables:

• SANITY_UI_DOCS_AUTH_TOKEN: A repository secret containing a token with deploy permissions for project mos42crl.
• SANITY_BLUEPRINT_STACK_ID: The stack ID used in the workflow environment.

While @sanity/ui v2 supported Node.js 14 or later, v3 has stricter requirements. You must use one of the following Node.js version ranges:

• >=20.19 <22
• >=22.12

Note: Node.js versions 22.0 through 22.11 are not supported.

Check your current version with:

node --version

In v4, static styles are extracted into a stylesheet at build time and are not loaded automatically. You must import the stylesheet once in your application, typically near where you render the <ThemeProvider>.

Without this import, components like SrOnly, Spinner, and certain text-overflow styles will render unstyled.

import '@sanity/ui/styles.css'

When contributing or writing stories for the Sanity UI Storybook, follow these conventions to ensure consistency:

• Export Naming: Every story file must export a named story called either Default or Basic.
• Titles: Do not create custom titles for stories; titles are automatically inferred from the folder structure.
• Simplicity: Keep stories simple. Minimize the use of custom or presentational props within the story itself.
• Data Passing: Use Storybook args to set component values instead of manually passing props.

To set up the monorepo for development, ensure you meet the requirements and run the installation and build commands.

Requirements

• Node.js: >=22.13
• pnpm: 11 (pinned via packageManager in package.json)

Installation

Run the following commands to install dependencies and build the packages:

pnpm install
pnpm build

To use Sanity UI components, install the main package along with its required peer dependencies: react, react-dom, and styled-components.

npm install @sanity/ui

# Install peer dependencies
npm install react react-dom styled-components