Migrating to v2

1. Remove PandaCSS

pnpm remove @pandacss/dev
rm panda.config.ts
rm -rf styled-system/

Delete all generated PandaCSS artifacts. Remove any prepare or codegen scripts that ran panda codegen.

2. Install Tailwind v4

pnpm add -D tailwindcss@4 @tailwindcss/postcss

3. Update your CSS entry

/* app/globals.css */
@import '@oztix/roadie-core/css';

/* Scan component dist for Tailwind class strings */
@source "../../node_modules/@oztix/roadie-components/dist";

The @source directive tells Tailwind to scan the component library so all component classes are included in your output CSS.

4. Update PostCSS config

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

View migration

View was a flex-column layout primitive. Replace with div and Tailwind classes. v2 is grid-first — use grid for vertical stacks.

{/* v1 */}
<View gap='200'>
  <p>Item 1</p>
  <p>Item 2</p>
</View>

{/* v2 */}
<div className='grid gap-4'>
  <p>Item 1</p>
  <p>Item 2</p>
</div>

{/* v1 */}
<View
  flexDirection='row'
  gap='100'
  alignItems='center'
>
  <Icon />
  <p>Label</p>
</View>

{/* v2 */}
<div className='flex items-center gap-2'>
  <Icon />
  <p>Label</p>
</div>

{/* v1 */}
<View
  display='grid'
  gridTemplateColumns='repeat(3, 1fr)'
  gap='200'
>
  {items}
</View>

{/* v2 */}
<div className='grid grid-cols-3 gap-4'>
  {items}
</div>

Container migration

{/* v1 */}
<Container>
  {content}
</Container>

{/* v2 */}
<div className='container-8xl'>
  {content}
</div>

Text migration

The Text component is removed. Use raw <p> or <span> with utility classes.

{/* v1 */}
<Text
  emphasis='subtle'
  size='sm'
>
  Secondary text
</Text>

{/* v2 */}
<p className='text-sm text-subtle'>
  Secondary text
</p>

Heading migration

The Heading component is removed. Use raw heading elements with display text utilities.

{/* v1 */}
<Heading
  as='h1'
  textStyle='display.ui'
  level={1}
>
  Page title
</Heading>

{/* v2 */}
<h1 className='text-display-ui-1 text-strong'>
  Page title
</h1>

Two display style families are available: text-display-ui-1 through 6 for UI headings, and text-display-prose-1 through 6 for long-form content. See the Typography foundation.

colorPalette is now intent

The colorPalette prop is renamed to intent. Some values are also renamed:

{/* v1 */}
<Button colorPalette='primary'>
  Save
</Button>

{/* v2 */}
<Button intent='brand' emphasis='strong'>
  Save
</Button>

Button as link → LinkButton

In v1, you could use asChild or the as prop on Button to render as a link, or apply button recipe styles to an anchor. In v2, use the dedicated LinkButton and LinkIconButton components instead. They accept an as prop for custom link components like Next.js Link.

{/* v1 — asChild or as prop */}
<Button asChild colorPalette='primary'>
  <a href='/about'>About</a>
</Button>

{/* v1 — recipe on anchor */}
<a href='/about' className={button()}>
  About
</a>

{/* v2 — LinkButton */}
<LinkButton href='/about' intent='brand'
  emphasis='strong'>
  About
</LinkButton>

{/* v2 — with Next.js Link */}
<LinkButton as={Link} href='/about'>
  About
</LinkButton>

appearance is now emphasis

The appearance prop is renamed to emphasis. This applies to Accordion and any custom components that used the old name.

{/* v1 */}
<Accordion appearance='contained'>
  ...
</Accordion>

{/* v2 */}
<Accordion emphasis='subtle'>
  ...
</Accordion>

Dark mode

Dark mode is now class-based instead of data-attribute-based. The CSS also sets color-scheme so native browser UI (scrollbars, form controls) matches the active theme.

{/* v1 */}
<div data-color-mode='dark'>
  ...
</div>

{/* v2 */}
<div className='dark'>
  ...
</div>

Use getThemeScript() from @oztix/roadie-core/theme for flash-free SSR setup. For React apps, ThemeProvider now manages dark mode — use useTheme() instead of useAccent().

// Flash prevention (any framework — no React dependency)
import { getThemeScript } from '@oztix/roadie-core/theme'
// <script>{getThemeScript({ followSystem: true })}</script>

// React: useAccent() is deprecated, use useTheme()
import { useTheme } from '@oztix/roadie-components'
const { isDark, setDark, accentColor, setAccentColor } = useTheme()

See the Colors foundation for full dark mode setup instructions.

css() and inline styles

{/* v1 */}
import { css } from 'styled-system/css'

<div className={css({
  display: 'flex',
  gap: '200',
  padding: '400',
  bg: 'neutral.2'
})}>
  {content}
</div>

{/* v2 */}
<div className='flex gap-4 p-8 bg-subtle'>
  {content}
</div>

sva() and cva() recipes

Replace PandaCSS slot recipes with class-variance-authority (CVA) and Tailwind classes.

// v1 — PandaCSS recipe
import { sva } from 'styled-system/css'

const card = sva({
  slots: ['root', 'header', 'body'],
  base: {
    root: { bg: 'neutral.1', p: '400' },
    header: { fontWeight: 'bold' },
    body: { color: 'neutral.11' }
  }
})

// v2 — CVA + Tailwind
import { cva } from 'class-variance-authority'
import { cn } from '@oztix/roadie-core/utils'

const cardVariants = cva(
  'rounded-xl emphasis-raised p-8', {
  variants: {
    emphasis: {
      raised: 'emphasis-raised',
      subtle: 'emphasis-subtle',
    }
  }
})

styled() factory

// v1 — PandaCSS styled factory
import { styled } from 'styled-system/jsx'

const StyledCard = styled('div', {
  base: { bg: 'neutral.1', p: '400' }
})

// v2 — Plain component + cn()
import { cn } from '@oztix/roadie-core/utils'

function Card({ className, ...props }) {
  return (
    <div
      className={cn(
        'rounded-xl emphasis-raised p-8',
        className
      )}
      {...props}
    />
  )
}

splitCssProps()

splitCssProps() is removed. Since v2 uses className strings instead of CSS-in-JS props, there are no CSS props to split. Simply spread all props to the element.

Import cleanup

Remove all PandaCSS imports:

// Remove all of these:
import { css } from 'styled-system/css'
import { styled } from 'styled-system/jsx'
import { sva, cva } from 'styled-system/css'
import { token } from 'styled-system/tokens'
import { View, Container } from 'styled-system/jsx'
import type { HTMLStyledProps } from 'styled-system/jsx'
import type { JsxStyleProps } from 'styled-system/types'

// v1 — Lucide
import { Heart } from 'lucide-react'

<Heart size={16} />

// v2 — Phosphor (client component)
import { HeartIcon } from '@phosphor-icons/react'

<HeartIcon weight='bold' className='size-4' />

See the Iconography foundation for complete guidelines.

Interaction utilities

Two CSS utilities handle interactive element styling:

• is-interactive — for buttons, cards, clickable elements. Provides cursor, transitions, active scale, focus ring, disabled state.
• is-interactive-field — for form inputs. Provides state-based color transitions: neutral at rest, accent on focus, danger when invalid.
• is-interactive-field-group — for composite form controls like the Combobox input group.

See Interactions foundation.

Motion tokens

Duration and easing tokens replace hardcoded animation values. All motion respects prefers-reduced-motion automatically.

/* Use tokens for custom transitions */
.my-element {
  transition:
    opacity var(--duration-moderate) var(--ease-standard),
    transform var(--duration-slow) var(--ease-enter);
}

/* Or use built-in motion utilities */
.entering {
  animation: motion-fade-in var(--duration-slow) var(--ease-enter);
}

See Motion foundation.

Shape tiers

Consistent border-radius tiers across all components:

• rounded-sm — inline (marks, highlights)
• rounded-md — small (code, prose images)
• rounded-lg — field (inputs, textareas)
• rounded-xl — container (cards, popovers)
• rounded-2xl — large (modals, dialogs)
• rounded-full — buttons, badges, pills

See Shape foundation.