@payfit/unity-themes/skills/unity-themes/references/patterns.md

# Unity theme styling patterns

## Responsive and state modifiers

Keep the `uy:` prefix before the complete Tailwind modifier chain.

```tsx
<div className="uy:grid uy:grid-cols-1 uy:md:grid-cols-2 uy:lg:grid-cols-3" />
```

When a Unity component exposes managed state through `data-*`, target that
state rather than the native pseudo-class.

```tsx
import { ListViewItem } from '@payfit/unity-components'
;<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
```

## Merge external classes with uyMerge

`uyMerge` knows Unity's custom class groups and token families.

```tsx
import { uyMerge } from '@payfit/unity-themes'

uyMerge('uy:p-100', 'uy:p-200')
// => 'uy:p-200'

uyMerge('uy:bg-surface-primary', 'uy:bg-surface-danger')
// => 'uy:bg-surface-danger'
```

## Define typed variants with uyTv

Use `uyTv` for reusable component variants and derive public props with
`VariantProps`.

```tsx
import type { VariantProps } from '@payfit/unity-themes'
import { uyTv } from '@payfit/unity-themes'

export const callout = uyTv({
  base: 'uy:inline-flex uy:items-center uy:gap-100 uy:rounded-100 uy:px-200 uy:py-100',
  variants: {
    intent: {
      info: 'uy:bg-surface-primary uy:text-content-inverted',
      danger: 'uy:bg-surface-danger uy:text-content-inverted',
      neutral: 'uy:bg-surface-neutral uy:text-content-neutral',
    },
    size: {
      sm: 'uy:typography-body-small',
      md: 'uy:typography-body',
    },
  },
  defaultVariants: { intent: 'info', size: 'md' },
})

export type CalloutVariantProps = VariantProps<typeof callout>
```

## Compose conditional classes with cn

Use `cn` for local boolean conditions, not for a reusable multi-axis variant
API.

```tsx
import { cn } from '@payfit/unity-themes'

function Row({ isActive }: { isActive: boolean }) {
  return (
    <div
      className={cn(
        'uy:flex uy:items-center uy:px-200 uy:py-100',
        isActive && 'uy:bg-surface-primary',
      )}
    />
  )
}
```