Yes

No

Yes

No

Yes

No

Grid layout

Flex layout

Stack items

Generic

Need to render UI element

Building page
structure or
dashboard?

Need pre-styled
component with
variants?

Need semantic
HTML element?

Need layout
control?

Use DashLayout
src/layouts/DashLayout.tsx

Use LayoutBlock
src/layouts/LayoutBlock.tsx

Use SplitBlock
src/layouts/SplitBlock.tsx

Use UI Component
Button, Card, Badge, etc.
src/components/ui/

Use Block
with component prop
src/core/ui/Block.tsx

Use Box
generic container
src/core/ui/Box.tsx

Use Grid
src/core/ui/Grid.tsx

Use Flex
src/core/ui/Flex.tsx

Use Stack
src/core/ui/Stack.tsx

// ✅ Good: Use UI component for common elements
<Button variant="primary" size="lg" p="md" rounded="lg">
  Submit
</Button>

// ❌ Bad: Recreating UI component with primitives
<Box 
  component="button" 
  className="inline-flex items-center justify-center bg-primary text-primary-foreground..."
>
  Submit
</Box>

// ✅ Good: DashLayout for dashboard structure
<DashLayout 
  sidebar={<NavigationSidebar />}
  header={<DashboardHeader />}
>
  <Container>
    <Card p="lg">Content</Card>
  </Container>
</DashLayout>

// ❌ Bad: Manual layout reconstruction
<Box className="flex min-h-screen">
  <Box className="w-64 border-r">
    <NavigationSidebar />
  </Box>
  {/* Complex manual layout logic */}
</Box>

Developer writes JSX

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

class-variance-authority
Resolves variants to classes

core-classes.json
618 validated classes

Tailwind CSS
Applies utility classes

Rendered DOM
with semantic elements

// ✅ Good: Compose variants for complex styling
<Card 
  p="xl" 
  rounded="2xl" 
  shadow="lg"
  bg="card"
  border="default"
  w="full"
  maxW="2xl"
  mx="auto"
>
  Content
</Card>

// ❌ Bad: Using className for variant-covered styles
<Card className="p-12 rounded-2xl shadow-lg bg-card border w-full max-w-2xl mx-auto">
  Content
</Card>

// ⚠️ Acceptable: className for the 20% edge cases
<Card 
  p="xl" 
  rounded="2xl"
  className="animate-pulse hover:scale-105 transition-transform"
>
  Custom animation
</Card>

// ✅ Good: Use className for animations
<Box 
  p="lg" 
  rounded="xl"
  className="hover:scale-105 transition-transform duration-200"
>
  Interactive element
</Box>

// ✅ Good: Use className for pseudo-classes
<Button 
  variant="primary" 
  size="md"
  className="focus-visible:ring-2 focus-visible:ring-offset-2"
>
  Accessible button
</Button>

Yes

No

Yes

No

Yes

No

Yes

No

Yes

No

Yes

No

Yes

No

Rendering content

Navigation menu
or links?

Self-contained
syndicated content?

Thematic
grouping?

Tangentially
related content?

Introductory
content?

Footer content?

Main content
area?

Block component='nav'

Block component='article'

Block component='section'

Block component='aside'

Block component='header'

Block component='footer'

Block component='main'

Box
generic container

// ✅ Good: Semantic page structure
<Block component="main" py="xl">
  <Block component="section" py="lg">
    <Container>
      <Block component="header" mb="lg">
        <Title order={1}>Page Title</Title>
      </Block>
      <Block component="article">
        <Text>Article content...</Text>
      </Block>
    </Container>
  </Block>
</Block>

// ❌ Bad: Generic divs everywhere
<Box py="xl">
  <Box py="lg">
    <Container>
      <Box mb="lg">
        <Title order={1}>Page Title</Title>
      </Box>
      <Box>
        <Text>Article content...</Text>
      </Box>
    </Container>
  </Box>
</Box>

// ✅ Good: Navigation with semantic nav element
<Block component="nav" p="md" bg="background" border="default">
  <Stack gap="sm">
    <a href="/">Home</a>
    <a href="/about">About</a>
  </Stack>
</Block>

// ✅ Good: Proper heading hierarchy
<Block component="article">
  <Title order={1}>Main Title</Title>
  <Title order={2}>Section Title</Title>
  <Title order={3}>Subsection Title</Title>
</Block>

// ✅ Good: Accessible button
<Button 
  variant="primary" 
  size="md"
  aria-label="Submit form"
  className="focus-visible:ring-2 focus-visible:ring-primary"
>
  Submit
</Button>

// ✅ Good: Accessible image
<Image 
  src="/product.jpg"
  alt="Blue running shoes with white stripes"
  rounded="lg"
/>

// ✅ Good: Accessible navigation
<Block component="nav" aria-label="Main navigation">
  <Stack gap="md" role="list">
    <a href="/" role="listitem">Home</a>
    <a href="/about" role="listitem">About</a>
  </Stack>
</Block>

// ❌ Bad: Non-semantic interactive element
<Box 
  onClick={handleClick}
  className="cursor-pointer"
>
  Click me
</Box>

// ✅ Good: Use Button component
<Button onClick={handleClick}>
  Click me
</Button>

// ✅ Good: Accessible form with semantic structure
<Block component="form" onSubmit={handleSubmit}>
  <Stack gap="md">
    <Box>
      <Text as="label" htmlFor="email" weight="medium" mb="xs">
        Email
      </Text>
      <Box
        component="input"
        id="email"
        type="email"
        aria-required="true"
        aria-describedby="email-error"
        p="sm"
        rounded="md"
        border="default"
        w="full"
      />
      <Text id="email-error" size="sm" c="destructive" mt="xs">
        {emailError}
      </Text>
    </Box>
    
    <Button type="submit" variant="primary">
      Submit
    </Button>
  </Stack>
</Block>

// ✅ Good: Compose components naturally
<Card p="lg" rounded="xl">
  <Card.Header>
    <Title order={2}>Product</Title>
  </Card.Header>
  <Card.Content>
    <Stack gap="md">
      <Image src="/product.jpg" alt="Product" />
      <Text>Description</Text>
    </Stack>
  </Card.Content>
  <Card.Footer>
    <Button variant="primary">Buy Now</Button>
  </Card.Footer>
</Card>

// ❌ Bad: Excessive prop drilling
<ProductCard
  title="Product"
  imageSrc="/product.jpg"
  imageAlt="Product"
  description="Description"
  buttonText="Buy Now"
  buttonVariant="primary"
  cardPadding="lg"
  cardRounded="xl"
/>

import { memo } from 'react';

// ✅ Good: Memoize expensive list items
const ProductCard = memo(({ product }) => (
  <Card p="md" rounded="lg">
    <Card.Content>
      <Stack gap="sm">
        <Image src={product.image} alt={product.name} />
        <Text>{product.name}</Text>
        <Text size="sm" c="muted-foreground">
          ${product.price}
        </Text>
      </Stack>
    </Card.Content>
  </Card>
));

// ✅ Good: Use forwardRef for ref forwarding
import { forwardRef } from 'react';

const CustomInput = forwardRef((props, ref) => (
  <Box
    component="input"
    ref={ref}
    p="sm"
    rounded="md"
    border="default"
    {...props}
  />
));

// ✅ Good: Use primitive values as dependencies
const [count, setCount] = useState(0);

useEffect(() => {
  // Effect logic
}, [count]);

// ❌ Bad: Object/array dependencies cause unnecessary re-renders
const config = { theme: 'dark' };

useEffect(() => {
  // This runs on every render
}, [config]);

// ✅ Good: Extract primitive values
const theme = config.theme;

useEffect(() => {
  // This runs only when theme changes
}, [theme]);

Pattern 4: Children Composition

Stack

Child component 1

Child component 2

Child component 3

Pattern 3: Content Hooks

LayoutBlock

beforeContent function

content function

afterContent function

Pattern 2: Prop Forwarding

Button
extends BaseButton

spacingVariants
roundedVariants
shadowVariants

Pattern 1: Compound Components

Card

Card.Header

Card.Content

Card.Footer

// ✅ Good: Flexible card composition
<Card p="lg" rounded="xl" shadow="md">
  <Card.Header>
    <Card.Title>Title</Card.Title>
    <Card.Description>Description</Card.Description>
  </Card.Header>
  <Card.Content>
    <Stack gap="md">
      {/* Content */}
    </Stack>
  </Card.Content>
  <Card.Footer>
    <Group gap="md" justify="end">
      <Button variant="secondary">Cancel</Button>
      <Button variant="primary">Save</Button>
    </Group>
  </Card.Footer>
</Card>

// ✅ Good: Optional parts
<Card p="lg">
  <Card.Content>
    {/* Only content, no header/footer */}
  </Card.Content>
</Card>

// ✅ Good: Button with forwarded spacing and visual variants
<Button 
  variant="primary"
  size="lg"
  p="md"        // From spacingVariants
  rounded="lg"  // From roundedVariants
  shadow="sm"   // From shadowVariants
>
  Click me
</Button>

// ✅ Good: Card with forwarded layout variants
<Card
  p="xl"         // From spacingVariants
  rounded="2xl"  // From roundedVariants
  shadow="lg"    // From shadowVariants
  w="full"       // From layoutVariants
  maxW="2xl"     // From layoutVariants
  mx="auto"      // From spacingVariants
>
  Content
</Card>

// ✅ Good: LayoutBlock with content hooks
<LayoutBlock
  layout="grid"
  cols={3}
  gap="lg"
  contentHooks={{
    beforeContent: () => (
      <Block component="header" mb="lg">
        <Title order={1}>Page Title</Title>
      </Block>
    ),
    content: () => products.map(product => (
      <Card key={product.id} p="md">
        {/* Product card */}
      </Card>
    )),
    afterContent: () => (
      <Block component="footer" mt="lg">
        <Button>Load More</Button>
      </Block>
    )
  }}
/>

// ❌ Bad: Using className for variant-covered styles
<Card className="p-12 rounded-2xl shadow-lg bg-card w-full max-w-2xl">
  Content
</Card>

// ✅ Good: Use variants
<Card p="xl" rounded="2xl" shadow="lg" bg="card" w="full" maxW="2xl">
  Content
</Card>

// ❌ Bad: Generic divs for navigation
<Box className="nav-container">
  <Box className="nav-item">Home</Box>
  <Box className="nav-item">About</Box>
</Box>

// ✅ Good: Semantic navigation
<Block component="nav" aria-label="Main navigation">
  <Stack gap="md" component="ul" role="list">
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </Stack>
</Block>

// ❌ Bad: Recreating Button component
const CustomButton = ({ children, ...props }) => (
  <Box
    component="button"
    className="inline-flex items-center justify-center rounded-md px-4 py-2 bg-primary text-white"
    {...props}
  >
    {children}
  </Box>
);

// ✅ Good: Extend existing Button
import { Button } from '@ui8kit/core';

const CustomButton = ({ children, ...props }) => (
  <Button 
    variant="primary" 
    size="md"
    className="custom-animation" // Only add custom styles
    {...props}
  >
    {children}
  </Button>
);

// ❌ Bad: Unnecessary wrapper nesting
<Box>
  <Box>
    <Box>
      <Box>
        <Text>Content</Text>
      </Box>
    </Box>
  </Box>
</Box>

// ✅ Good: Minimal nesting
<Box>
  <Text>Content</Text>
</Box>

// ✅ Good: Use Stack for spacing instead of wrappers
<Stack gap="md">
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</Stack>

// ❌ Bad: Custom selectors without data-class
<Card className="my-custom-card">
  <div className="my-custom-header">Header</div>
</Card>

// ✅ Good: Use data-class attributes for targeting
<Card data-class="product-card">
  <Card.Header data-class="product-card-header">
    Header
  </Card.Header>
</Card>

// In CSS or testing:
// [data-class="product-card"] { ... }
// screen.getByTestId('product-card')