Skip to content

gentleeduck/duck-ui / skills/duck-variants

duck-variants

Verified

Use when working with the @gentleduck/variants package - the cva() function for creating type-safe component variant systems. Covers defining variants, extracting VariantProps, compound variants, the 'unset' escape hatch, and ClassValue types. Use for questions about styling patterns, variant authoring, or type inference.

FileKindSize
SKILL.mdskill md6.1 KB
---
name: duck-variants
description: >-
  Use when working with the @gentleduck/variants package  -  the cva() function for
  creating type-safe component variant systems. Covers defining variants, extracting
  VariantProps, compound variants, the 'unset' escape hatch, and ClassValue types.
  Use for questions about styling patterns, variant authoring, or type inference.
allowed-tools: Read Grep
argument-hint: "[variant-name-or-topic]"
---

# @gentleduck/variants

Expert scope: `packages/duck-variants/src/`. One function (`cva`) and utility types for type-safe component style variants. Results are memoized via a props-keyed cache.

## Exports

```ts
import { cva, type VariantProps, type CvaProps, type VariantParams,
  type VariantsOptions, type InferVariants, type ClassValue } from '@gentleduck/variants'
```

## API

### cva()  -  two call signatures

```ts
// 1. Two-arg: base string + options object
const alert = cva('rounded-lg border px-4 py-3 text-sm', {
  variants: { variant: { default: 'bg-card text-card-foreground', destructive: '...' } },
  defaultVariants: { variant: 'default' },
})

// 2. Single-arg: options object with optional `base` key
const alert = cva({
  base: 'rounded-lg border px-4 py-3 text-sm', // optional  -  omit for no base classes
  variants: { variant: { default: 'bg-card text-card-foreground', destructive: '...' } },
  defaultVariants: { variant: 'default' },
})
```

Returns `(props?: CvaProps<TVariants>) => string`. Props accept `class` and `className` to append extra classes. Tokens are deduplicated (first occurrence wins).

Variant values can be a `string` or `string[]` (array of class strings) in the config.

### Compound variants

Apply extra classes when multiple variant values match simultaneously. Conditions can be a single value or an array of values:

```ts
const button = cva('btn', {
  variants: {
    intent: { primary: 'bg-blue-500', danger: 'bg-red-500' },
    size: { sm: 'text-sm', lg: 'text-lg' },
  },
  defaultVariants: { intent: 'primary', size: 'sm' },
  compoundVariants: [
    { intent: ['primary', 'danger'], size: 'lg', className: 'uppercase' },
    // ↑ matches when intent is 'primary' OR 'danger' AND size is 'lg'
  ],
})
```

Each compound entry uses variant keys as conditions plus `class` and/or `className` for emitted classes. Both are applied if present.

### The `'unset'` escape hatch

Passing `'unset'` as a variant value skips that variant entirely  -  no classes emitted, even if `defaultVariants` specifies a value.
### Key types

| Type | Purpose |
|---|---|
| `VariantProps<typeof fn>` | Variant props only (strips `class`/`className` and array types). Use with `typeof`. |
| `CvaProps<TVariants>` | Full props of the returned function: variant keys + `class` + `className`. |
| `InferVariants<typeof config>` | Extracts `variants` record from a `VariantsOptions` config object (NOT a cva return). |
| `ClassValue` | `string \| number \| boolean \| ClassDictionary \| ClassArray`  -  supports nested arrays and conditional dictionaries like `{ 'bg-red': isError }`. |
## Creating a variant component from scratch

```ts
// 1. card.constants.ts  -  define variants
export const cardVariants = cva('rounded-lg border shadow-sm', {
  variants: {
    padding: { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' },
    elevation: { flat: 'shadow-none', raised: 'shadow-md' },
  },
  defaultVariants: { padding: 'md', elevation: 'flat' },
})

// 2. card.types.ts  -  derive props
import type { VariantProps } from '@gentleduck/variants'
import type { cardVariants } from './card.constants'

export interface CardProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof cardVariants> {}

// 3. card.tsx  -  component
import { cn } from '@gentleduck/libs/cn'
import { cardVariants } from './card.constants'
import type { CardProps } from './card.types'

export function Card({ padding, elevation, className, ...props }: CardProps) {
  return <div className={cn(cardVariants({ padding, elevation }), className)} {...props} />
}
```

## Composition patterns

### Compose two cva outputs at the call site

```ts
<div className={cn(layoutVariants({ direction: 'row' }), spacingVariants({ gap: 'md' }))} />
```

### Extend an existing component's variants without modifying it

```ts
import { buttonVariants } from '@gentleduck/registry-ui/button'

const fancyVariants = cva('', {
  variants: { glow: { on: 'shadow-lg shadow-blue-500/50', off: '' } },
  defaultVariants: { glow: 'off' },
})

export function FancyButton({ variant, size, glow, className, ...props }: FancyButtonProps) {
  return <button className={cn(buttonVariants({ variant, size }), fancyVariants({ glow }), className)} {...props} />
}
```

### Use variant function as a className utility (no component)

```ts
<Link className={buttonVariants({ variant: 'outline' })} href="/about">About</Link>
```

### Handling native `size` collisions

`Omit` the native HTML attribute when a variant is named `size`:

```ts
interface ButtonProps extends Omit<React.HTMLProps<HTMLButtonElement>, 'size'>,
  VariantProps<typeof buttonVariants> {}
```

## Error patterns

1. `VariantProps` returns `never`  -  pass `typeof myVariants`, not `myVariants`
2. `size` collision  -  native HTML `size` attribute conflicts; use `Omit<..., 'size'>`
3. Missing `defaultVariants`  -  all variant props become required in consumers
4. Using `class` in JSX  -  React requires `className`; `class` only works in plain objects
5. Passing `InferVariants` a cva function  -  it takes a `VariantsOptions` config, not a cva return

## Do not

- Use `type` alias for component props  -  use `interface` so it can be extended
- Inline variant definitions in the component  -  put them in `{name}.constants.ts`
- Forget to export the variant function  -  consumers need it for className composition
- Use `as const` on the cva call  -  it breaks type inference
- Omit `typeof` with `VariantProps`  -  it is `VariantProps<typeof x>`, not `VariantProps<x>`
- Wrap cva results in `cn()` at the definition site  -  cva already deduplicates; use `cn()` only in JSX
- Assume variants are required  -  with `defaultVariants`, all variant props are optional

## Source

`packages/duck-variants/src/variants.ts` (function) and `variants.types.ts` (types).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall