Build-Time Extraction

Stage 3: Class Application

Stage 2: CVA Resolution

Stage 1: Variant Definitions

safelist for

whitelist for

src/core/variants/
TypeScript CVA definitions

12 Variant Categories
spacing, colors, layout,
typography, effects

class-variance-authority
cva() function calls

Component props
p='lg', rounded='xl'

Generated classes
p-8 rounded-xl

Primitives
Block, Box, Grid, Flex, Stack

Composites
Card, Button, Badge

Layouts
DashLayout, LayoutBlock

scripts/cva-extractor.ts
AST-based extraction

src/lib/core-classes.json
618 classes

Tailwind CSS purge

tw-merge utility

Value Scale

Margin Variants

Padding Variants

p (all sides)

px (horizontal)

py (vertical)

pt (top)

pr (right)

pb (bottom)

pl (left)

m (all sides)

mx (horizontal)

my (vertical)

mt (top)

mr (right)

mb (bottom)

ml (left)

none → 0

xs → 1 (0.25rem)

sm → 2 (0.5rem)

md → 4 (1rem)

lg → 8 (2rem)

xl → 12 (3rem)

2xl → 16+ (4rem+)

auto → auto

// All sides padding
<Box p="lg">              // → p-8
<Box p="xl">              // → p-12

// Directional padding
<Box px="md" py="lg">     // → px-4 py-8
<Box pt="sm" pb="xl">     // → pt-2 pb-12

// Auto margins for centering
<Box mx="auto">           // → mx-auto
<Box ml="auto">           // → ml-auto

// Combined spacing
<Card p="xl" mb="lg">     // → p-12 mb-8

["p-0", "p-1", "p-2", "p-4", "p-6", "p-8", "p-12",
 "px-0", "px-1", "px-2", "px-4", "px-6", "px-8", "px-12",
 "py-0", "py-1", "py-2", "py-4", "py-8", "py-16", "py-32", "py-48",
 "m-0", "m-1", "m-2", "m-4", "m-6", "m-8", "m-12", "m-auto",
 "mx-auto", "my-auto", "mt-auto", "mb-auto", "ml-auto", "mr-auto"]

Generated Classes

Semantic Tokens

Color Props

bg
(background)

c
(text color)

borderColor
(border)

primary /
primary-foreground

secondary /
secondary-foreground

accent /
accent-foreground

destructive /
destructive-foreground

muted /
muted-foreground

card /
card-foreground

background /
foreground

border / input / ring

bg-primary
bg-secondary
bg-accent
bg-destructive
bg-muted
bg-card
bg-background

text-primary
text-secondary
text-foreground
text-muted-foreground

border-primary
border-border
border-input

// Background colors
<Card bg="card">                    // → bg-card
<Button bg="primary">               // → bg-primary
<Badge bg="destructive">            // → bg-destructive

// Text colors
<Text c="foreground">               // → text-foreground
<Text c="muted-foreground">         // → text-muted-foreground
<Title c="primary">                 // → text-primary

// Border colors
<Box borderColor="border">          // → border-border
<Box borderColor="input">           // → border-input

// Combined with hover states
<Button 
  bg="primary" 
  className="hover:bg-primary/90"
>                                   // → bg-primary hover:bg-primary/90

["bg-primary", "bg-primary-foreground", "bg-secondary", "bg-secondary-foreground",
 "bg-accent", "bg-accent-foreground", "bg-destructive", "bg-destructive-foreground",
 "bg-muted", "bg-muted-foreground", "bg-card", "bg-background", "bg-foreground",
 "bg-border", "bg-input", "bg-ring", "bg-transparent",
 "text-primary", "text-secondary", "text-foreground", "text-muted-foreground",
 "border-primary", "border-secondary", "border-border", "border-input"]

// Full width/height
<Box w="full" h="screen">              // → w-full h-screen

// Intrinsic sizing
<Box w="fit" h="auto">                 // → w-fit h-auto

// Minimum height
<Box minH="screen">                    // → min-h-screen
<Box minH="400px">                     // → min-h-[400px]

// Maximum width with centering
<Container maxW="4xl" mx="auto">       // → max-w-4xl mx-auto

// Positioning
<Box position="relative">              // → relative
<Box position="absolute">              // → absolute

["w-auto", "w-full", "w-screen", "w-fit", "w-min", "w-max", "w-px", "w-3", "w-4", "w-5", "w-6", "w-8", "w-10", "w-12",
 "h-auto", "h-full", "h-screen", "h-fit", "h-min", "h-max", "h-px", "h-3", "h-4", "h-5", "h-6", "h-8", "h-9", "h-10", "h-11", "h-12",
 "min-h-full", "min-h-screen", "min-h-[200px]", "min-h-[300px]", "min-h-[400px]", "min-h-[500px]",
 "max-w-sm", "max-w-md", "max-w-lg", "max-w-xl", "max-w-2xl", "max-w-4xl", "max-w-6xl", "max-w-full", "max-w-screen-sm", "max-w-screen-md",
 "static", "relative", "absolute", "fixed", "sticky"]

Leading Variant

tight → leading-tight

normal → leading-normal

relaxed → leading-relaxed

Align Variant

left → text-left

center → text-center

right → text-right

justify → text-justify

Weight Variant

normal → font-normal

medium → font-medium

semibold → font-semibold

bold → font-bold

Size Variant

xs → text-xs

sm → text-sm

base → text-base

lg → text-lg

xl → text-xl

2xl → text-2xl

3xl → text-3xl

4xl → text-4xl

5xl → text-5xl

// Size variants
<Text size="sm">                    // → text-sm
<Title size="3xl">                  // → text-3xl

// Weight variants
<Text weight="medium">              // → font-medium
<Title fw="bold">                   // → font-bold (fw is alias)

// Alignment variants
<Text align="center">               // → text-center
<Text ta="right">                   // → text-right (ta is alias)

// Leading variants
<Text leading="tight">              // → leading-tight

// Combined typography
<Title 
  size="2xl" 
  weight="bold" 
  align="center"
  leading="tight"
>                                   // → text-2xl font-bold text-center leading-tight

["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl", "text-3xl", "text-4xl", "text-5xl",
 "font-normal", "font-medium", "font-semibold", "font-bold",
 "text-left", "text-center", "text-right", "text-justify",
 "leading-tight", "leading-normal", "leading-relaxed"]

// Rounded corners
<Card rounded="xl">                 // → rounded-xl
<Button rounded="full">             // → rounded-full
<Badge rounded="md">                // → rounded-md

// Shadows
<Card shadow="lg">                  // → shadow-lg
<Box shadow="md">                   // → shadow-md

// Borders
<Box border="default">              // → border
<Box border="2">                    // → border-2
<Box border="t">                    // → border-t (top only)

// Combined effects
<Card 
  rounded="2xl" 
  shadow="xl" 
  border="default"
  borderColor="border"
>                                   // → rounded-2xl shadow-xl border border-border

// Top border
<Box border="t" border="2">         // → border-t-2

// Bottom border
<Box border="b" border="4">         // → border-b-4

// Left and right
<Box border="l" border="r">         // → border-l border-r

["rounded-none", "rounded-sm", "rounded-md", "rounded-lg", "rounded-xl", "rounded-2xl", "rounded-3xl", "rounded-full",
 "rounded-t-none", "rounded-t-sm", "rounded-t-md", "rounded-t-lg", "rounded-t-xl", "rounded-t-full",
 "rounded-b-none", "rounded-b-sm", "rounded-b-md", "rounded-b-lg", "rounded-b-xl", "rounded-b-full",
 "rounded-l-none", "rounded-l-sm", "rounded-l-md", "rounded-l-lg", "rounded-l-xl", "rounded-l-full",
 "rounded-r-none", "rounded-r-sm", "rounded-r-md", "rounded-r-lg", "rounded-r-xl", "rounded-r-full",
 "shadow-none", "shadow-sm", "shadow-md", "shadow-lg", "shadow-xl", "shadow-2xl", "shadow-inner",
 "border", "border-0", "border-2", "border-4", "border-t", "border-r", "border-b", "border-l",
 "border-t-0", "border-t-2", "border-t-4", "border-b-0", "border-b-2", "border-b-4"]

Output: Tailwind Classes

CVA Engine

CVA Definition

Input: Component Props

Component JSX

p='lg'
rounded='xl'
shadow='md'
bg='card'

cva() function

base: 'transition-all'

variants: {
  p: { lg: 'p-8' },
  rounded: { xl: 'rounded-xl' },
  shadow: { md: 'shadow-md' },
  bg: { card: 'bg-card' }
}

Variant Resolution

Class Merging

Generated className

'transition-all p-8 rounded-xl shadow-md bg-card'

Applied to DOM element

import { cva } from 'class-variance-authority';

export const spacingVariants = cva('', {
  variants: {
    p: {
      none: 'p-0',
      xs: 'p-1',
      sm: 'p-2',
      md: 'p-4',
      lg: 'p-8',
      xl: 'p-12',
      '2xl': 'p-16'
    },
    px: {
      none: 'px-0',
      xs: 'px-1',
      sm: 'px-2',
      md: 'px-4',
      lg: 'px-8',
      xl: 'px-12'
    }
    // ... more spacing variants
  }
});

import { spacingVariants } from '@/core/variants';

// Props are passed to CVA function
const className = spacingVariants({ p: 'lg', px: 'xl' });
// Result: 'p-8 px-12'

Consumers

Output

Extraction Process

Source Files

src/core/variants/
All .ts/.tsx files

CVA Definitions
cva('base', { variants: {...} })

scripts/cva-extractor.ts

@babel/parser
Parse to AST

@babel/traverse
Find cva() calls

Extract classes from:
• Base strings
• Variant objects
• Nested objects
• Arrays

618 unique classes

src/lib/core-classes.json

timestamp: 2025-10-29T12:17:54.882Z

tailwind.config.js
safelist configuration

tw-merge utility
class whitelist

{
  "classes": [
    "absolute",
    "bg-primary",
    "border",
    "flex",
    "gap-4",
    "p-8",
    "rounded-xl",
    "shadow-md",
    // ... 618 total classes
  ],
  "count": 618,
  "timestamp": "2025-10-29T12:17:54.882Z"
}

// tailwind.config.js
const coreClasses = require('./src/lib/core-classes.json');

module.exports = {
  safelist: coreClasses.classes,
  // ... other config
};

Typography Composition

  size='2xl'
  weight='bold'
  align='center'
  leading='tight'
  c='primary'
/>

text-2xl font-bold text-center leading-tight text-primary

Directional Composition

  px='lg'
  py='md'
  mt='xl'
  mb='sm'
/>

px-8 py-4 mt-12 mb-2

Multi-Variant Composition

  p='xl'
  rounded='2xl'
  shadow='lg'
  bg='card'
/>

p-12 rounded-2xl shadow-lg bg-card

Single Variant Application

p-8

// py overrides the vertical portion of p
<Box p="lg" py="xl">
// Result: p-8 py-12
// Tailwind applies: padding: 2rem (from p-8), then padding-top/bottom: 3rem (from py-12)

// className for custom styles not covered by variants
<Card 
  p="lg" 
  rounded="xl" 
  className="hover:scale-105 transition-transform"
>
// Result: p-8 rounded-xl hover:scale-105 transition-transform

Final Component Type

Component Props Interface

Variant Definition

cva('', { variants: {...} })

VariantProps

ComponentPropsWithoutRef<'div'>

SpacingVariantProps
ColorVariantProps
LayoutVariantProps
EffectsVariantProps

Custom component props

type CardProps = 
  BaseProps &
  VariantProps &
  CustomProps

IntelliSense shows:
• All variant options
• Valid values
• Descriptions

// Variant definition with type extraction
import { cva, type VariantProps } from 'class-variance-authority';

const spacingVariants = cva('', {
  variants: {
    p: {
      none: 'p-0',
      xs: 'p-1',
      sm: 'p-2',
      md: 'p-4',
      lg: 'p-8',
      xl: 'p-12'
    }
  }
});

// Extract variant prop types
export type SpacingVariantProps = VariantProps<typeof spacingVariants>;
// Result: { p?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' }

// Component props interface
interface CardProps extends ComponentPropsWithoutRef<'div'>, SpacingVariantProps {
  variant?: 'default' | 'outlined';
}

src/core/variants/
├── spacing.ts          # Padding and margin variants
├── colors.ts           # Background, text, border color variants
├── layout.ts           # Width, height, position variants
├── typography.ts       # Size, weight, align, leading variants
├── effects.ts          # Rounded, shadow, border variants
├── flex.ts             # Flexbox alignment and gap variants
├── grid.ts             # Grid layout variants
└── index.ts            # Exports all variants

// Export variants and utilities from core
export * from './core/variants';

import { 
  spacingVariants, 
  colorVariants, 
  roundedVariants 
} from '@ui8kit/core';

import { Block, Box, Stack } from '@ui8kit/core';

<Block 
  component="section" 
  p="xl" 
  bg="background" 
  rounded="lg"
>
  <Stack gap="md" align="center">
    <Box w="full" h="auto" border="default" rounded="md">
      Content
    </Box>
  </Stack>
</Block>

import { Card, Button, Text } from '@ui8kit/core';

<Card 
  p="lg" 
  rounded="xl" 
  shadow="md" 
  bg="card"
>
  <Card.Header>
    <Text size="xl" weight="bold" c="foreground">
      Title
    </Text>
  </Card.Header>
  <Card.Content>
    <Text size="base" c="muted-foreground">
      Description
    </Text>
  </Card.Content>
  <Card.Footer>
    <Button 
      bg="primary" 
      rounded="md" 
      px="lg" 
      py="md"
    >
      Action
    </Button>
  </Card.Footer>
</Card>

import { DashLayout, Container, LayoutBlock } from '@ui8kit/core';

<DashLayout>
  <Container maxW="6xl" px="lg" py="xl">
    <LayoutBlock 
      layout="grid" 
      gap="lg" 
      p="xl"
      bg="background"
      rounded="lg"
    >
      {/* Grid content */}
    </LayoutBlock>
  </Container>
</DashLayout>