Advanced Workflow

Relevant source files

Purpose and Scope

This document covers non-standard scenarios where the 15 composite UI components from src/components/ui/ are insufficient for your use case. You will learn how to compose the five core primitives (Block, Box, Grid, Flex, Stack) from src/core/ui/ to build custom interfaces. For typical component usage with ready-made composites, see Basic Workflow. For general usage guidelines and patterns, see Best Practices. Sources: .devin/wiki.json191-198 src/components/GUIDE_CREATE_FORM.md1-10

When to Use Advanced Workflow

The library provides 15 composite components that cover ~80% of common UI scenarios. However, certain elements are intentionally absent from the library:

Missing Component Type	Reason for Absence	Advanced Solution
Form elements (Form, Label, Input)	HTML semantics vary widely	Compose `Block` + `Box` with `component` prop
Select dropdowns	Requires complex state management	Use `Box component="select"` with variants
Custom interactive widgets	Application-specific logic	Build with primitives + variants
Non-standard layouts	Unique structural requirements	Compose `Grid`, `Flex`, `Stack` directly

Decision Tree: Basic vs Advanced Workflow

Yes

No

Yes

No

Yes

No

Need UI element

Component exists in
src/components/ui/?

Use composite component
(Button, Card, Badge)

Standard HTML element
with styling?

Use Block/Box
with component prop

Complex layout
structure?

Compose Grid/Flex/Stack
with primitives

Build custom component
from primitives

Basic Workflow (5.1)

Advanced Workflow (5.2)

Sources: src/components/README.md1-8 src/components/GUIDE_CREATE_FORM.md5-10

Building Forms with Block and Box

The library does not include dedicated Form, Label, or Input components. Instead, use the polymorphic component prop on Block and Box to render semantic HTML elements with the full variant system.

Component Prop Pattern

The component prop transforms primitives into any HTML element while maintaining type-safe variant props:

Variant Props

Rendered Elements

component prop

Primitive Components

applies to

applies to

applies to

applies to

Block
(semantic container)

Box
(flexible primitive)

component='form'

component='label'

component='input'

component='textarea'

component='select'

<form>

<label>

<input>

<textarea>

<select>

p, m, px, py, etc

w, h, maxW, minH

rounded, border, shadow

bg, c, borderColor

Sources: src/components/GUIDE_CREATE_FORM.md7-9

Form Structure Pattern

Use Block with component="form" as the form wrapper, applying layout and styling variants: Form Container Structure:

Element	Component	Props	Purpose
Form wrapper	`<Block component="form">`	`w`, `maxW`, `p`, `rounded`, `shadow`, `bg`	Semantic form container with layout
Field groups	`<Block>`	`w="full"`, `className="space-y-2"`	Vertical field spacing
Labels	`<Box component="label">`	`c`, `className="text-sm font-medium"`	Accessible field labels
Inputs	`<Box component="input">`	`w="full"`, `p`, `rounded`, `border`, `borderColor`	Form input fields
Textareas	`<Box component="textarea">`	`w="full"`, `p`, `rounded`, `border`, `minH`	Multi-line text input
Submit button	`<Button>`	`w="full"`, `size`, `variant`	Form submission

Example form structure (see src/components/GUIDE_CREATE_FORM.md14-32):

<Block 
  component="form"
  w="full"
  maxW="md"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  {/* Form fields */}
</Block>

Sources: src/components/GUIDE_CREATE_FORM.md11-33

Input Field Patterns

All input types use Box with component="input" and standard HTML attributes: Text Input (src/components/GUIDE_CREATE_FORM.md37-50):

<Box 
  component="input"
  type="text"
  placeholder="Enter your name"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>

Input with Focus States (src/components/GUIDE_CREATE_FORM.md54-67):

<Box 
  component="input"
  type="text"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  bg="white"
  c="gray-900"
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>

Password Input (src/components/GUIDE_CREATE_FORM.md70-82):

<Box 
  component="input"
  type="password"
  placeholder="Password"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>

Number Input with Constraints (src/components/GUIDE_CREATE_FORM.md84-97):

<Box 
  component="input"
  type="number"
  placeholder="Age"
  w="full"
  p="md"
  rounded="md"
  border="default"
  min={0}
  max={120}
/>

Sources: src/components/GUIDE_CREATE_FORM.md35-97

Textarea Fields

Use Box with component="textarea" for multi-line text input: Basic Textarea (src/components/GUIDE_CREATE_FORM.md99-115):

<Box 
  component="textarea"
  rows={4}
  placeholder="Enter your message"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
  className="resize-none"
/>

Textarea with Minimum Height (src/components/GUIDE_CREATE_FORM.md117-129):

<Box 
  component="textarea"
  placeholder="Description"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  minH="32"
  className="resize-y"
/>

Sources: src/components/GUIDE_CREATE_FORM.md99-129

Complete Form Example

Contact Form Architecture:

Block component='form'
onSubmit handler
Layout: w='full' maxW='lg' p='lg'
Style: rounded='lg' shadow='lg' bg='white'

Block (Name field group)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='text' name='name' required
w='full' p='md' rounded='md'
border='default' borderColor='gray-300'

Block (Email field group)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='email' name='email' required
w='full' p='md' rounded='md'

Block (Message field group)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='textarea'
rows=5 name='message' required
w='full' p='md' minH='32'
resize-none focus:ring-2

Button type='submit'
w='full' size='lg' variant='default'

Full implementation at src/components/GUIDE_CREATE_FORM.md134-226 Key patterns:

Form event handling: onSubmit prop on form Block
Field structure: Block wrapper → label → input in each group
Spacing: className="space-y-6" on form, className="space-y-2" on field groups
Validation: required attribute on inputs
Focus states: Combine variants with className for focus rings

Sources: src/components/GUIDE_CREATE_FORM.md131-226

Multi-Column Form Layout

For complex forms, use Box with grid display (src/components/GUIDE_CREATE_FORM.md228-277):

<Block 
  component="form"
  w="full"
  maxW="2xl"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  <Box 
    display="grid" 
    className="grid-cols-1 md:grid-cols-2 gap-6"
  >
    {/* First Name field */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        First Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>

    {/* Last Name field */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        Last Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>
  </Box>
</Block>

Sources: src/components/GUIDE_CREATE_FORM.md228-277

Form Validation Pattern

Build reusable validated input components (src/components/GUIDE_CREATE_FORM.md311-339):

function ValidatedInput({ error, label, ...props }) {
  return (
    <Block w="full" className="space-y-2">
      <Box component="label" c="gray-700" className="text-sm font-medium">
        {label}
      </Box>
      <Box 
        component="input"
        w="full"
        p="md"
        rounded="md"
        border="default"
        borderColor={error ? "red-500" : "gray-300"}
        bg={error ? "red-50" : "white"}
        className={error ? "focus:ring-red-500" : "focus:ring-blue-500"}
        {...props}
      />
      {error && (
        <Box c="red-600" className="text-sm">
          {error}
        </Box>
      )}
    </Block>
  );
}

Pattern breakdown:

Conditional borderColor and bg based on error state
Dynamic focus ring colors via className
Error message display with Box for text color
Props spreading with {...props} for HTML attributes

Sources: src/components/GUIDE_CREATE_FORM.md311-339

Available Variant Props for Primitives

All primitives support the 12 CVA variant categories. Key variants for form building:

Spacing Variants

Prop	Values	Purpose
`p`, `px`, `py`, `pt`, `pb`, `pl`, `pr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`	Padding control
`m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto`	Margin control

Layout Variants

Prop	Values	Purpose
`w`	`auto`, `full`, `screen`, `fit`, `min`, `max`, `1/2`, `1/3`, etc.	Width control
`h`	`auto`, `full`, `screen`, `fit`, `min`, `max`	Height control
`minH`	Numeric values like `"32"`, `"64"`	Minimum height (useful for textareas)
`maxW`	`xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, etc.	Maximum width (useful for centered forms)
`display`	`block`, `flex`, `grid`, `inline`, `none`	Display type

Border & Style Variants

Prop	Values	Purpose
`border`	`none`, `default`, `2`, `4`, `8`	Border width
`borderColor`	All design system colors	Border color
`rounded`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`	Border radius
`shadow`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`	Box shadow

Color Variants

Prop	Values	Purpose
`bg`	All design system colors (e.g., `white`, `card`, `gray-50`)	Background color
`c`	All design system colors (e.g., `gray-700`, `red-600`)	Text color

Sources: src/components/GUIDE_CREATE_FORM.md279-301 src/components/README.md205-222

Best Practices for Advanced Composition

Form Field Guidelines

Always set w="full" on input fields for consistent width (src/components/GUIDE_CREATE_FORM.md304)
Use Block for form structure (form element, field groups) (src/components/GUIDE_CREATE_FORM.md305)
Use Box for actual inputs (input, textarea, select) (src/components/GUIDE_CREATE_FORM.md306)
Combine variant props with Tailwind classes for focus states (src/components/GUIDE_CREATE_FORM.md307)
Use minH for textarea instead of fixed height (src/components/GUIDE_CREATE_FORM.md308)
Apply className="resize-none" to prevent textarea resizing if needed (src/components/GUIDE_CREATE_FORM.md309)

Variant + ClassName Hybrid Pattern

The variant system covers ~80% of styling needs. For remaining 20%, combine variants with className:

<Box 
  component="input"
  // Variants cover structure
  w="full"
  p="md"
  rounded="md"
  border="default"
  bg="white"
  // className covers interactive states
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>

When to use className:

Interactive states (:hover, :focus, :active)
Pseudo-elements (:before, :after)
Complex animations
Grid/flex utilities not covered by variants
Responsive breakpoints beyond variant system

Sources: src/components/GUIDE_CREATE_FORM.md302-310 src/components/README.md237-244

Custom Component Composition

Building Reusable Composites

When you need the same pattern repeatedly, extract it into a custom component: Pattern: Labeled Input Field

controls

displays

renders

Custom ValidatedInput Component

Block wrapper
w='full' space-y-2

Box component='label'
c='gray-700'
text-sm font-medium

Box component='input'
w='full' p='md'
rounded='md' border='default'
Conditional: borderColor, bg

Box (conditional render)
c='red-600' text-sm
Displays error message

Props:
- error (string | undefined)
- label (string)
- ...props (HTML attributes)

Implementation approach:

Accept variant props and HTML attributes via props spreading
Handle conditional logic (error states, validation)
Maintain accessibility (label associations, ARIA attributes)
Return primitive composition (Block + Box)

Sources: src/components/GUIDE_CREATE_FORM.md311-339

Non-Form Custom Scenarios

Custom Interactive Widgets: When building application-specific widgets (sliders, pickers, custom controls):

Start with Box or Block as container
Apply semantic component prop (<Box component="button"> for clickable elements)
Use variant props for layout and styling
Add event handlers (onClick, onChange, etc.)
Combine with className for complex interactions

Custom Layout Structures: For unique layout requirements not covered by DashLayout, LayoutBlock, or SplitBlock:

Compose Grid, Flex, or Stack from src/core/ui/
Apply layout variants (cols, gap, align, justify)
Nest primitives for hierarchical structure
Use Block with component="section"/component="aside" for semantic markup

Sources: src/components/README.md237-244 .devin/wiki.json191-198

Comparison: Basic vs Advanced Workflow

When to use each approach:

Advanced Workflow (5.2)

Basic Workflow (5.1)

Yes

No

Ready-made components exist

Card, Button, Badge,
Title, Text, Image, Icon

Use composite components
from src/components/ui/

Example:
<Card p='lg' rounded='xl'>

Custom requirements

Form elements, custom widgets,
unique layouts

Compose primitives
from src/core/ui/

Example:
<Block component='form'>
<Box component='input'/>

Component exists
in library?

Capability matrix:

Feature	Basic Workflow	Advanced Workflow
Development speed	Fast (pre-built components)	Moderate (manual composition)
Flexibility	Limited to component props	Full control via primitives
Code maintenance	Easier (fewer components)	More complex (more code)
Type safety	Full (composite component types)	Full (primitive component types)
Variant support	Via prop forwarding	Direct application
Semantic HTML	Predefined structure	Full control via `component` prop
Best for	Standard UI patterns	Custom/unique requirements

Sources: src/components/README.md1-19 src/components/GUIDE_CREATE_FORM.md1-10

Summary

The advanced workflow enables building custom interfaces when the 15 composite components are insufficient:

Forms: Compose Block + Box with component prop for form elements, labels, and inputs
Custom widgets: Use primitives with semantic component props and variant system
Unique layouts: Compose Grid, Flex, Stack for structural requirements
Hybrid approach: Combine variant props (~80% coverage) with className for edge cases

For standard scenarios with existing components, use Basic Workflow. For general guidelines, see Best Practices. Sources: src/components/GUIDE_CREATE_FORM.md341-347 .devin/wiki.json191-198

Getting started

Architecture

Components

Development Guide

Advanced Workflow

Advanced Workflow

Purpose and Scope

When to Use Advanced Workflow

Building Forms with Block and Box

Component Prop Pattern

Form Structure Pattern

Input Field Patterns

Textarea Fields

Complete Form Example

Multi-Column Form Layout

Form Validation Pattern

Available Variant Props for Primitives

Spacing Variants

Layout Variants

Border & Style Variants

Color Variants

Best Practices for Advanced Composition

Form Field Guidelines

Variant + ClassName Hybrid Pattern

Custom Component Composition

Building Reusable Composites

Non-Form Custom Scenarios

Comparison: Basic vs Advanced Workflow

Summary

​Advanced Workflow

​Purpose and Scope

​When to Use Advanced Workflow

​Building Forms with Block and Box

​Component Prop Pattern

​Form Structure Pattern

​Input Field Patterns

​Textarea Fields

​Complete Form Example

​Multi-Column Form Layout

​Form Validation Pattern

​Available Variant Props for Primitives

​Spacing Variants

​Layout Variants

​Border & Style Variants

​Color Variants

​Best Practices for Advanced Composition

​Form Field Guidelines

​Variant + ClassName Hybrid Pattern

​Custom Component Composition

​Building Reusable Composites

​Non-Form Custom Scenarios

​Comparison: Basic vs Advanced Workflow

​Summary

Advanced Workflow

Purpose and Scope

When to Use Advanced Workflow

Building Forms with Block and Box

Component Prop Pattern

Form Structure Pattern

Input Field Patterns

Textarea Fields

Complete Form Example

Multi-Column Form Layout

Form Validation Pattern

Available Variant Props for Primitives

Spacing Variants

Layout Variants

Border & Style Variants

Color Variants

Best Practices for Advanced Composition

Form Field Guidelines

Variant + ClassName Hybrid Pattern

Custom Component Composition

Building Reusable Composites

Non-Form Custom Scenarios

Comparison: Basic vs Advanced Workflow

Summary