Ark UI Headless Components: Unstyled Building Blocks

The Design System That Saved Our Sanity

Building components from scratch nearly killed our team. Then we discovered this approach.

Table of Contents

• Why Design Systems Matter
• Core Concepts
• 5 Implementation Patterns
• Accessibility First
• Performance Considerations
• Team Workflow
• Migration Strategy
• FAQ
• Best Practices

Why Design Systems Matter in 2026

Consistency isn't optional anymore.

The Cost of Inconsistency

// Before: Every button different
<button className="bg-blue-500 px-4 py-2">One</button>
<button style={{background: 'blue', padding: 10}}>Two</button>
<div onClick={...} className="custom-btn">Three</div>

The Solution

// After: Consistent system
import { Button } from '@/components';

<Button variant="primary">Consistent</Button>
<Button variant="secondary">Everywhere</Button>

Business Impact

Teams ship 3x faster with fewer bugs.

Core Concepts

Understanding the foundation.

Component Architecture

// Well-structured component
import { forwardRef } from 'react';

interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={`btn-${variant} btn-${size}`}
        {...props}
      >
        {children}
      </button>
    );
  }
);

Design Tokens

Colors, spacing, typography as code.

Composition Patterns

Build complex UIs from simple parts.

Pattern 1: Type-Safe Variants

CVA Pattern

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

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground',
        destructive: 'bg-destructive text-destructive-foreground',
        outline: 'border border-input bg-background',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
      }
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    }
  }
);

interface ButtonProps extends VariantProps<typeof buttonVariants> {
  children: React.ReactNode;
}

export function Button({ variant, size, children }: ButtonProps) {
  return (
    <button className={buttonVariants({ variant, size })}>
      {children}
    </button>
  );
}

Type Safety Benefits

Catch errors at compile time.

Pattern 2: Compound Components

Advanced Composition

// Flexible API
import { createContext, useContext } from 'react';

const SelectContext = createContext<{
  value: string;
  onChange: (value: string) => void;
}>(null!);

export function Select({ value, onChange, children }) {
  return (
    <SelectContext.Provider value={{ value, onChange }}>
      <div className="select-wrapper">{children}</div>
    </SelectContext.Provider>
  );
}

Select.Trigger = function Trigger({ children }) {
  return <button className="select-trigger">{children}</button>;
};

Select.Content = function Content({ children }) {
  return <div className="select-content">{children}</div>;
};

Select.Item = function Item({ value, children }) {
  const { onChange } = useContext(SelectContext);
  return (
    <div onClick={() => onChange(value)}>
      {children}
    </div>
  );
};

// Usage
<Select value={selected} onChange={setSelected}>
  <Select.Trigger>Choose option</Select.Trigger>
  <Select.Content>
    <Select.Item value="1">Option 1</Select.Item>
    <Select.Item value="2">Option 2</Select.Item>
  </Select.Content>
</Select>

Flexibility

Users compose as needed.

Pattern 3: Accessibility

ARIA Patterns

// Accessible by default
import { useId } from 'react';

export function Input({ label, error, ...props }) {
  const id = useId();
  const errorId = `${id}-error`;

  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input
        id={id}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
        {...props}
      />
      {error && (
        <span id={errorId} role="alert">
          {error}
        </span>
      )}
    </div>
  );
}

Keyboard Navigation

Support all interactions.

Screen Reader Support

Test with real assistive tech.

Pattern 4: Dark Mode

CSS Variables

/* Theme tokens */
:root {
  --color-bg: white;
  --color-text: black;
}

[data-theme="dark"] {
  --color-bg: black;
  --color-text: white;
}

.component {
  background: var(--color-bg);
  color: var(--color-text);
}

React Implementation

// Theme provider
import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext<{
  theme: 'light' | 'dark';
  toggle: () => void;
}>(null!);

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  const toggle = () => {
    setTheme(t => t === 'light' ? 'dark' : 'light');
    document.documentElement.dataset.theme = theme;
  };

  return (
    <ThemeContext.Provider value={{ theme, toggle }}>
      {children}
    </ThemeContext.Provider>
  );
}

Pattern 5: Animation

Framer Motion

// Smooth transitions
import { motion } from 'framer-motion';

export function Modal({ isOpen, children }) {
  return (
    <motion.div
      initial={{ opacity: 0, scale: 0.95 }}
      animate={{ opacity: isOpen ? 1 : 0, scale: isOpen ? 1 : 0.95 }}
      transition={{ duration: 0.2 }}
    >
      {children}
    </motion.div>
  );
}

Performance

Use GPU-accelerated properties.

Performance Benchmarks

Team Workflow

Component Development

1. Design in Figma
2. Implement with tokens
3. Add accessibility
4. Write tests
5. Document usage

Code Review Checklist

• [ ] Accessible
• [ ] Responsive
• [ ] Dark mode works
• [ ] Tests pass
• [ ] Documented

Migration Strategy

Phase 1: Setup

Install dependencies and configure.

Phase 2: Core Components

Button, Input, Select first.

Phase 3: Complex Components

Modal, Dropdown, DatePicker next.

Phase 4: Migration

Replace old components gradually.

FAQ

Q1: Build or buy components?

Headless libraries + your styling = best balance.

Q2: How to ensure consistency?

Design tokens + automated tests.

Q3: Accessibility requirements?

WCAG 2.1 AA minimum standard.

Q4: Dark mode support?

CSS variables make it easy.

Q5: Performance impact?

Properly tree-shaken, minimal overhead.

Best Practices

Documentation

// Document components clearly
/**
 * Button component with multiple variants
 * 
 * @example
 * <Button variant="primary" size="lg">
 *   Click me
 * </Button>
 */
export function Button(props: ButtonProps) {
  // Implementation
}

Testing

Test accessibility and interactions.

Versioning

Semantic versioning for updates.

Conclusion

Design systems are infrastructure.

Key takeaways:

• Start with tokens
• Build accessible first
• Document everything
• Test thoroughly
• Iterate based on usage

Invest in your component library.

Resources:

• Component Examples
• Accessibility Guides
• Design Token Systems
• Testing Strategies

Next Steps:

1. Audit current components
2. Define design tokens
3. Build core components
4. Add accessibility
5. Document patterns

Build UI that scales.