Core Components

Relevant source files

Purpose and Scope

This document covers the five foundational primitives in Layer 1 of the architecture: Block, Box, Grid, Flex, and Stack. These components serve as the building blocks for all higher-level UI components and layouts in the library. They provide direct access to the CVA variant system and implement fundamental React patterns including forwardRef, TypeScript type composition, and HTML attribute forwarding. For documentation on composite components that extend these primitives (Button, Card, etc.), see UI Components. For variant system details, see Variant System. Sources: README.md81-103 .devin/wiki.json56-63

Architectural Role

Core components form the foundation of the three-layer architecture. They are the only components that directly apply the CVA variant system and render semantic HTML5 elements. All Layer 2 components (UI Components) and Layer 3 components (Layouts) ultimately compose or extend these five primitives.

Output

React Patterns

CVA Variant System

Layer 1: Core Components (This Document)

Block
component='section' | 'article' | 'nav' | etc.
data-class='block'

Box
component='div' | 'span' | any ElementType
data-class='box'

Grid
CSS Grid layout
cols, rows, gap props

Flex
Flexbox layout
direction, align, justify props

Stack
Vertical/horizontal stacking
gap, direction props

class-variance-authority
Variant resolution

spacingVariants()
p, m, px, py, etc.

colorVariants()
bg, c, borderColor

layoutVariants()
w, h, minH, position

roundedVariants()
rounded

shadowVariants()
shadow

borderVariants()
border, borderTop, etc.

forwardRef()
Ref forwarding to DOM

TypeScript interfaces
HTMLAttributes + VariantProps

...props
HTML attribute forwarding

Semantic HTML5
section, article, nav, header, footer

data-class attributes
DOM targeting

Tailwind CSS classes
Applied to className

Sources: README.md62-103 src/components/ui/Block/Block.tsx1-88

The Five Core Primitives

Overview Table

Component	Primary Purpose	Semantic HTML Support	Key Variants	Default Width
`Block`	Semantic block containers	section, article, nav, header, footer, aside, main, div	spacing, color, layout, rounded, shadow, border	`w='full'`
`Box`	Generic flexible container	Any `ElementType` (div, span, p, etc.)	spacing, color, layout	No default
`Grid`	CSS Grid layouts	div with `display: grid`	spacing, layout, cols, rows, gap	No default
`Flex`	Flexbox layouts	div with `display: flex`	spacing, layout, direction, align, justify	No default
`Stack`	Vertical/horizontal stacking	div with flexbox stacking	spacing, gap, direction	No default

Sources: README.md81-103

Fundamental React Patterns

forwardRef Implementation

All core components implement forwardRef to expose the underlying DOM element reference to parent components. This enables imperative DOM operations and integration with third-party libraries.

ref={blockRef}

ref forwarding

blockRef.current?.scrollIntoView()

Parent Component
const blockRef = useRef(null)

Block
forwardRef

DOM Element
section | article | nav | etc.

Example structure from Block component: src/components/ui/Block/Block.tsx33-36

export const Block = forwardRef<HTMLElement, BlockProps>(
  ({ children, className, component, variant = 'div', ...props }, ref) => {
    // Component implementation
  }
);

Sources: src/components/ui/Block/Block.tsx33-86

TypeScript Type Composition

Core components compose multiple TypeScript interfaces to achieve type safety across HTML attributes, variant props, and custom component props.

extends

extends

extends

Pick<..., 'w' | 'h' | 'minH' | 'position'>

extends

extends

extends

includes

BlockProps
Component-specific interface

React.HTMLAttributes
Standard HTML attributes

VariantSpacingProps
p, px, py, pt, pb, pl, pr
m, mx, my, mt, mb, ml, mr

ColorProps
bg, c, borderColor

VariantLayoutProps
w, h, minH, maxW, position

RoundedProps
rounded

ShadowProps
shadow

BorderProps
border, borderTop, etc.

Custom Props
children: ReactNode
component?: ElementType
variant?: 'section' | 'article' | ...

Type composition pattern from Block: src/components/ui/Block/Block.tsx20-31

export interface BlockProps 
  extends React.HTMLAttributes<HTMLElement>,
    VariantSpacingProps,
    ColorProps,
    Pick<VariantLayoutProps, 'w' | 'h' | 'minH' | 'position'>,
    RoundedProps,
    ShadowProps,
    BorderProps {
  children: ReactNode;
  component?: ElementType;
  variant?: 'section' | 'main' | 'nav' | 'article' | 'header' | 'footer' | 'aside' | 'div';
}

Sources: src/components/ui/Block/Block.tsx20-31

Prop Destructuring and HTML Attribute Forwarding

Core components destructure variant props explicitly and forward remaining HTML attributes to the underlying DOM element using the spread operator (...props).

Incoming Props
p='lg', onClick, data-testid, etc.

Destructured Variant Props
p, px, py, m, bg, c, w, h, rounded, shadow, border

Rest Props (...props)
onClick, data-testid, aria-label, etc.

Variant Functions
spacingVariants({ p, px, py, ... })
colorVariants({ bg, c })
layoutVariants({ w, h })

className prop
cn(variants, custom className)

Base Component
Block/Box/Grid/Flex/Stack

Rendered DOM Element
with className + ...props

Prop destructuring pattern from Block: src/components/ui/Block/Block.tsx34-61

({ 
  children, 
  className,
  component,
  variant = 'div',
  // Spacing props
  p, px, py, pt, pb, pl, pr,
  m, mx, my, mt, mb, ml, mr,
  // Color props
  bg, c, borderColor,
  // Layout props
  w = 'full', h, minH, position,
  // Visual props
  rounded, shadow,
  // Border props
  border, borderTop, borderBottom, borderLeft, borderRight,
  ...props  // Remaining HTML attributes
}, ref)

Sources: src/components/ui/Block/Block.tsx34-86

Component-Specific Features

Block: Semantic HTML Container

Block is designed for semantic block-level elements. It defaults to w='full' (full width) and provides a variant prop for selecting semantic HTML5 elements. Key characteristics:

Semantic element selection via variant prop
Full width by default (w='full')
Supports all spacing, color, layout, rounded, shadow, and border variants
Uses data-class="block" for DOM targeting

Element type resolution: src/components/ui/Block/Block.tsx62-68

// Use variant as component if no component is explicitly provided
const elementType = component || variant;

return (
  <BaseBlock
    ref={ref}
    component={elementType}
    data-class="block"

Usage examples:

// Renders as <section> with full width
<Block variant="section" p="lg" rounded="xl">
  Section content
</Block>

// Renders as <nav> with custom background
<Block variant="nav" bg="primary" c="white">
  Navigation links
</Block>

// Override with custom component
<Block component="article" p="md">
  Article content
</Block>

Sources: src/components/ui/Block/Block.tsx1-88 README.md85-87

Box: Flexible Generic Container

Box is the most flexible primitive, accepting any ElementType via the component prop. It has no default width and minimal defaults, making it suitable for inline and custom layouts. Key characteristics:

Accepts any React ElementType (div, span, p, a, button, custom components)
No default width or height
Supports spacing, color, and layout variants
Uses data-class="box" for DOM targeting

Usage examples:

// Renders as <div>
<Box p="md" bg="card">
  Generic container
</Box>

// Renders as <span> (inline)
<Box component="span" c="primary" weight="bold">
  Inline text
</Box>

// Renders as custom element
<Box component="input" w="full" p="sm" border="default" />

Sources: README.md85 src/components/ui/Box/index.ts1

Grid: CSS Grid Layout

Grid provides CSS Grid layout capabilities with props for columns, rows, and gap. Key characteristics:

display: grid applied by default
cols prop for column count
rows prop for row count
gap prop for grid spacing
Supports spacing and layout variants

Usage examples:

// 2-column grid with gap
<Grid cols={2} gap="md" p="lg">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
  <Box>Item 3</Box>
  <Box>Item 4</Box>
</Grid>

// 3-column responsive grid
<Grid cols={3} gap="lg" w="full">
  {items.map(item => <Card key={item.id}>{item.name}</Card>)}
</Grid>

Sources: README.md88

Flex: Flexbox Layout

Flex provides Flexbox layout capabilities with props for direction, alignment, and justification. Key characteristics:

display: flex applied by default
direction prop for flex-direction
align prop for align-items
justify prop for justify-content
Supports spacing and layout variants

Usage examples:

// Horizontal flex with centered items
<Flex direction="row" align="center" justify="between" p="md">
  <Text>Left content</Text>
  <Button>Right action</Button>
</Flex>

// Vertical flex
<Flex direction="column" gap="md">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Flex>

Sources: README.md88

Stack: Simplified Stacking

Stack is a specialized flex container for vertical or horizontal stacking with consistent gap spacing. Key characteristics:

Simplified API compared to Flex
direction prop: ‘vertical’ (default) or ‘horizontal’
gap prop for spacing between children
Automatic flex layout

Usage examples:

// Vertical stack (default)
<Stack gap="md" p="lg">
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</Stack>

// Horizontal stack
<Stack direction="horizontal" gap="sm">
  <Button>Cancel</Button>
  <Button variant="primary">Submit</Button>
</Stack>

Sources: README.md89

Variant Application Pattern

Core components apply variants using the cn() utility function, which merges variant-generated classes with custom className props using tw-merge for conflict resolution.

validated by

Variant Props
p='lg', bg='card', rounded='xl'

Variant Functions
spacingVariants({ p: 'lg' })
colorVariants({ bg: 'card' })
roundedVariants({ rounded: 'xl' })

Generated Classes
'p-8' (from p='lg')
'bg-card' (from bg='card')
'rounded-xl' (from rounded='xl')

Custom className
(optional user override)

cn() utility
tw-merge for conflict resolution

Final className
Applied to component

core-classes.json
618 class whitelist
Prevents Tailwind purging

Application pattern from Block: src/components/ui/Block/Block.tsx70-79

className={cn(
  // Apply variants
  spacingVariants({ p, px, py, pt, pb, pl, pr, m, mx, my, mt, mb, ml, mr }),
  colorVariants({ bg, c, borderColor }),
  layoutVariants({ w, h, minH, position }),
  roundedVariants({ rounded }),
  shadowVariants({ shadow }),
  borderVariants({ border, borderTop, borderBottom, borderLeft, borderRight }),
  className  // User's custom className (if provided)
)}

Sources: src/components/ui/Block/Block.tsx70-79

Import and Export Pattern

Core components follow a consistent import/export structure for tree-shaking and type safety.

Component File Structure

Each core component has a dedicated directory with two files:

src/core/ui/Block/
├── Block.tsx          # Component implementation
└── index.ts           # Public exports

Import Pattern in Component Files

src/components/ui/Block/Block.tsx3-18

import {
  Block as BaseBlock,           // Base component from core
  spacingVariants,              // Variant functions
  colorVariants,
  layoutVariants,
  roundedVariants,
  shadowVariants,
  borderVariants,
  type VariantSpacingProps,     // TypeScript types
  type ColorProps,
  type VariantLayoutProps,
  type RoundedProps,
  type ShadowProps,
  type BorderProps,
  cn                            // Utility function
} from "@ui8kit/core";

Export Pattern in Index Files

src/components/ui/Box/index.ts1

export { Box, type BoxProps } from "./Box";

Export structure:

Named export for component
Named export for TypeScript props interface using type keyword
No default exports (enforces consistent import syntax)

Sources: src/components/ui/Block/Block.tsx1-18 src/components/ui/Box/index.ts1

data-class Attributes

All core components include a data-class attribute for consistent DOM targeting in tests, CSS selectors, and debugging tools.

Block
data-class='block'

Box
data-class='box'

Grid
data-class='grid'

Flex
data-class='flex'

Stack
data-class='stack'

DOM Queries
document.querySelector('[data-class=block]')
screen.getByTestId('block')

CSS Selectors
[data-class='block'] { ... }

Browser DevTools
Filter by data-class

Usage from Block component: src/components/ui/Block/Block.tsx69

data-class="block"

Consumer testing example:

// React Testing Library
const blockElement = screen.getByTestId('block');

// Direct DOM query
const allBlocks = document.querySelectorAll('[data-class="block"]');

// Cypress
cy.get('[data-class="block"]').should('exist');

Sources: src/components/ui/Block/Block.tsx69

displayName Convention

All core components set displayName for improved debugging experience in React DevTools and error messages. src/components/ui/Block/Block.tsx88

Block.displayName = "Block";

Benefits:

Clear component names in React DevTools component tree
Improved error stack traces
Better debugging with React.StrictMode warnings

Sources: src/components/ui/Block/Block.tsx88

Relationship with Higher Layers

Core components serve as the foundation for Layer 2 (UI Components) and Layer 3 (Layouts). Higher-level components either extend core components with additional props or compose multiple core components together.

Layer 1: Core Components

Layer 2: UI Components

Layer 3: Layouts

uses

uses

uses

uses

uses

uses

extends

extends

uses

DashLayout
Composes: Container, Grid, Flex

LayoutBlock
Uses: Grid or Flex

SplitBlock
Uses: Container

Card
Extends: Block
Forwards variant props

Button
Extends: Box
Adds button-specific variants

Container
Uses: Block
Adds max-width logic

Block
Direct variant application

Box
Direct variant application

Grid
Direct variant application

Flex
Direct variant application

Stack
Direct variant application

Extension pattern (Card extends Block):

// Card component internally uses Block
<Block
  component="div"
  data-class="card"
  className={cn(cardVariants({ variant }), className)}
  {...variantProps}  // Forwards spacing, color, layout props
>
  {children}
</Block>

Composition pattern (DashLayout uses Grid):

// DashLayout composes multiple core components
<Block component="div" className="dashboard-layout">
  <Grid cols={12} gap="md">
    <Block component="aside" className="sidebar">
      {sidebar}
    </Block>
    <Block component="main" className="content">
      {children}
    </Block>
  </Grid>
</Block>

Sources: README.md62-168

Summary

Core components implement five fundamental patterns:

forwardRef - Expose DOM references to parent components
Type Composition - Combine React.HTMLAttributes with variant prop types
Prop Destructuring - Extract variant props and forward HTML attributes
Variant Application - Apply CVA variants via cn() utility
Semantic HTML - Render appropriate HTML5 elements via component prop

These patterns enable:

Type-safe component APIs with full TypeScript inference
Direct access to the variant system without prop forwarding overhead
Flexible semantic HTML structure for accessibility
Consistent DOM targeting via data-class attributes
Clean React DevTools debugging with displayName

All higher-level components in the library either extend or compose these five primitives, ensuring architectural consistency throughout the system. Sources: README.md62-103 src/components/ui/Block/Block.tsx1-88 .devin/wiki.json56-63

Getting started

Architecture

Components

Development Guide

Core Components Architecture

Core Components

Purpose and Scope

Architectural Role

The Five Core Primitives

Overview Table

Fundamental React Patterns

forwardRef Implementation

TypeScript Type Composition

Prop Destructuring and HTML Attribute Forwarding

Component-Specific Features

Block: Semantic HTML Container

Box: Flexible Generic Container

Grid: CSS Grid Layout

Flex: Flexbox Layout

Stack: Simplified Stacking

Variant Application Pattern

Import and Export Pattern

Component File Structure

Import Pattern in Component Files

Export Pattern in Index Files

data-class Attributes

displayName Convention

Relationship with Higher Layers

Summary

​Core Components

​Purpose and Scope

​Architectural Role

​The Five Core Primitives

​Overview Table

​Fundamental React Patterns

​forwardRef Implementation

​TypeScript Type Composition

​Prop Destructuring and HTML Attribute Forwarding

​Component-Specific Features

​Block: Semantic HTML Container

​Box: Flexible Generic Container

​Grid: CSS Grid Layout

​Flex: Flexbox Layout

​Stack: Simplified Stacking

​Variant Application Pattern

​Import and Export Pattern

​Component File Structure

​Import Pattern in Component Files

​Export Pattern in Index Files

​data-class Attributes

​displayName Convention

​Relationship with Higher Layers

​Summary

Core Components

Purpose and Scope

Architectural Role

The Five Core Primitives

Overview Table

Fundamental React Patterns

forwardRef Implementation

TypeScript Type Composition

Prop Destructuring and HTML Attribute Forwarding

Component-Specific Features

Block: Semantic HTML Container

Box: Flexible Generic Container

Grid: CSS Grid Layout

Flex: Flexbox Layout

Stack: Simplified Stacking

Variant Application Pattern

Import and Export Pattern

Component File Structure

Import Pattern in Component Files

Export Pattern in Index Files

data-class Attributes

displayName Convention

Relationship with Higher Layers

Summary