Migrate Styled Components To Vanilla Extract

Migrate styled-components to vanilla-extract

The repeatable procedure for converting this monorepo's styling from styled-components (the Studio's legacy styling library) to vanilla-extract. Adapted from the sanity-io/plugins skill of the same name for this repo's setup.

The infrastructure is already wired — never touch it during a component migration. packages/sanity and packages/@sanity/vision build .css.ts files into lib/bundle.css via vanillaExtract: true in their tsdown.config.ts, expose the ./bundle.css export, register vanillaExtractPlugin() in their vitest.config.mts, and the dev studios register it in sanity.cli.ts. A migration PR only converts component styles.

Ground rules

• Identical visual output is the goal. This is a refactor, not a redesign — every rule and specificity outcome must be preserved. Copy CSS values verbatim; do not "improve" them.
• Small PRs. Migrate one component (or one tightly-coupled cluster) per PR, conventional-commit titled, e.g. refactor(structure): migrate Scroller to vanilla-extract.
• Reference implementations: packages/@sanity/vision, packages/sanity/src/core/changeIndicators/ElementWithChangeBar.*, packages/sanity/src/structure/panes/document/document-layout/DocumentLayout.*, and for the dynamic shapes packages/sanity/src/core/components/popoverDialog/PopoverContainer.* (responsive widths through per-breakpoint variables) and packages/sanity/src/core/form/inputs/PortableText/text/TextBlock.styles.* (per-level styleVariants, private custom properties, theme-driven colors).

Step 1: Inventory

Classify each usage before touching code:

rg "from 'styled-components'" packages/sanity/src <target-dir>

Step 2: Migrate the code

Create a ComponentName.css.ts next to the component. Files calling vanilla-extract APIs (style, styleVariants, createVar, globalStyle, keyframes) must use the .css.ts extension — a plain .ts file throws "Styles were unable to be assigned to a file" at runtime.

Shape A — keep the component layer. When the styled element is used like a component, replace it with a style() rule plus a thin wrapper keeping the same name and API, so call sites don't change. Type with ComponentProps<typeof Primitive> (or ComponentProps<'div'>) — never forwardRef; ref is a regular prop on React 19 and flows through the spread. Merge, don't clobber: a fixed className={...} after {...props} silently drops a caller's className — merge with clsx (already a dependency):

import {Card} from '@sanity/ui'
import {clsx} from 'clsx'
import {type ComponentProps} from 'react'

import {floatingCard} from './FloatingCard.css'

export function FloatingCard(props: ComponentProps<typeof Card>) {
  const {className, ...rest} = props
  return <Card {...rest} className={clsx(floatingCard, className)} />
}

Renaming a Component.styled.ts to .tsx (or .ts → .tsx) keeps extension-less import paths at call sites unchanged.

Shape B — flatten single-use wrappers. When the styled element was an internal, single-use styled.div with no meaningful API, delete it and put the class directly on the element: <div className={paragraph}>{children}</div>.

Shape C — dynamic values through CSS variables. First check whether @sanity/ui already exposes the value as a CSS custom property — prefer e.g. var(--card-bg-color) over JS theme reads (see ElementWithChangeBar.css.ts). Otherwise keep static parts in style() and bridge only changing values with createVar() + assignInlineVars() (from @vanilla-extract/dynamic, not @vanilla-extract/css), reading the theme with useTheme_v2() (alias it useTheme_v2 as useThemeV2 to satisfy the camelCase lint):

// Wrapper.css.ts
import {createVar, style} from '@vanilla-extract/css'

export const paddingVar = createVar()
export const wrapper = style({paddingBottom: paddingVar})

<div className={wrapper} style={assignInlineVars({[paddingVar]: `${space[4]}px`})} />

assignInlineVars omits undefined values, so one class serves every instance.

Specificity against @sanity/ui: the && trick

@sanity/ui still uses styled-components, which injects its styles at runtime — usually after the extracted vanilla-extract stylesheet, so an equal-specificity class loses. When overriding a primitive's own styles (e.g. styled(Card) overriding Card's background), double the class:

export const transparentCard = style({
  selectors: {
    '&&': {background: 'none'},
  },
})

Where styled-components silently won specificity battles via CSSOM insertion order, reach for && rather than !important. Plain-element styles (styled.div) need no trick.

The cascade model (why order is not yours to rely on)

Three stylesheets meet on a migrated element, and their order differs between sanity dev and sanity build:

Consequences:

• Never rely on order against @sanity/ui. On an equal-specificity tie the winner flips between dev and prod. Beat the primitive's own rule by specificity: && (0,2,0) beats a plain component class (0,1,0). If the primitive rule you override already has two classes or a pseudo-class chain (e.g. Card's &[data-as='button']:not(:disabled)[data-selected]), count its specificity and exceed it — &&&, or &&[data-as='button']. Read the rule in node_modules/@sanity/ui/dist/*.js when unsure. !important stays banned.
• styled-components gave you order for free; vanilla-extract does not. A styled(X) wrapper was always injected after X, so its equal-specificity declarations won. After migration, both classes live in bundle.css in module evaluation order: within one .css.ts file, definition order; across files, the importing file comes after the imported one. So for a styled(LocalStyledThing) chain, define the override below the base in the same .css.ts (or compose it with style([base, {...}])). For an override whose base lives in another .css.ts, import that class into the overriding file — the import is what guarantees the ordering — or use &&.
• Two classes on one element from unrelated files (e.g. a styled.div root class plus a parent-state selector ${parent}:hover & defined elsewhere) are ordered by the same rule. When a declaration must win regardless of file order, raise its specificity rather than betting on order.
• @media blocks are hoisted. vanilla-extract emits a file's media queries after that file's base rules, which is what styled-components effectively did too. Media conditions cannot read custom properties, so theme breakpoints are written as literals from the default theme (table below) with a comment naming the theme key they mirror.

What each @sanity/ui primitive sets on itself

Use && when the migrated rule overrides one of these; plain style() otherwise.