---
name: design-system-architect
description: "Expert guide for designing, building, and maintaining scalable UI design systems with design tokens, headless primitives (Radix/Base UI), Tailwind v4 @theme, and WCAG 2.2 accessibility in English and Indonesian."
author: "Roedy Rustam"
---
# Design System Architect (2026 Edition — shadcn/ui Registry)
[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
---
## English
### Description
Expert guide for building and maintaining scalable UI design systems. Covers design tokens with OKLCH and Tailwind v4 `@theme`, headless component primitives (Radix UI, **Base UI 1.x**), **shadcn/ui registry** for distributable component libraries, CVA for type-safe variants, and WCAG 2.2 accessibility compliance.
### Trigger Conditions
- Building a shared UI component library from scratch.
- Setting up design tokens (colors, typography, spacing) with Tailwind v4.
- Using headless primitives (Radix UI, Base UI 1.x) with custom styling.
- Distributing components via the **shadcn/ui registry** format.
- Auditing a component library for WCAG 2.2 accessibility compliance.
### Design Token Foundation (Tailwind v4 + OKLCH)
```css
/* packages/ui/src/tokens.css */
@import "tailwindcss";
@theme {
/* --- Color System (OKLCH for wide-gamut P3 displays) --- */
/* Brand */
--color-brand-50: oklch(97% 0.015 250);
--color-brand-100: oklch(93% 0.04 250);
--color-brand-500: oklch(55% 0.22 250);
--color-brand-700: oklch(40% 0.18 250);
--color-brand-900: oklch(20% 0.10 250);
/* Semantic (maps to brand in light/dark automatically) */
--color-primary: var(--color-brand-500);
--color-primary-fg: oklch(100% 0 0); /* White */
--color-surface: oklch(100% 0 0); /* White */
--color-surface-2: oklch(97% 0.005 250);
--color-border: oklch(90% 0.01 250);
--color-text: oklch(15% 0.02 250);
--color-text-muted: oklch(50% 0.015 250);
--color-destructive: oklch(55% 0.22 25); /* Red */
/* --- Typography --- */
--font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
--font-mono: "JetBrains Mono", "Fira Code", ui-monospace, monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;
/* --- Spacing & Radius --- */
--radius-sm: 0.25rem;
--radius-md: 0.5rem;
--radius-lg: 0.75rem;
--radius-xl: 1rem;
--radius-full: 9999px;
/* --- Animation --- */
--animate-fade-in: fade-in 0.2s ease-out;
--animate-slide-up: slide-up 0.3s cubic-bezier(0.16, 1, 0.3, 1);
--animate-scale-in: scale-in 0.2s ease-out;
}
/* Dark mode tokens */
@variant dark {
:root {
--color-surface: oklch(10% 0.015 250);
--color-surface-2: oklch(15% 0.015 250);
--color-border: oklch(25% 0.02 250);
--color-text: oklch(95% 0.005 250);
--color-text-muted: oklch(60% 0.01 250);
}
}
```
### Component Architecture
#### Headless + Styled Pattern (Base UI 1.x / Radix UI)
Use headless primitives for accessibility, apply styles via Tailwind + CVA:
```typescript
// packages/ui/src/button.tsx
import * as React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
// Base styles
'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-500 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 select-none',
{
variants: {
variant: {
default: 'bg-primary text-primary-fg shadow-sm hover:brightness-110 active:brightness-90',
secondary: 'bg-surface-2 text-text border border-border hover:bg-surface hover:border-brand-300',
destructive: 'bg-destructive text-white hover:brightness-110',
ghost: 'hover:bg-surface-2 text-text',
link: 'text-primary underline-offset-4 hover:underline p-0 h-auto',
},
size: {
sm: 'h-8 px-3 text-xs',
md: 'h-9 px-4 text-sm',
lg: 'h-11 px-6 text-base',
icon: 'h-9 w-9',
},
},
defaultVariants: { variant: 'default', size: 'md' },
}
);
export interface ButtonProps
extends React.ButtonHTMLAttributes,
VariantProps {
asChild?: boolean;
}
const Button = React.forwardRef(
({ className, variant, size, ...props }, ref) => (
)
);
Button.displayName = 'Button';
export { Button, buttonVariants };
```
### shadcn/ui Registry — Distributable Components (2026)
shadcn/ui v2 introduces a **registry** system — distribute your components as a shareable library that others can `npx shadcn add` into their projects:
```json
// registry.json — defines your component library
{
"$schema": "https://ui.shadcn.com/schema/registry.json",
"name": "my-ui",
"homepage": "https://ui.myapp.com",
"items": [
{
"name": "button",
"type": "registry:ui",
"title": "Button",
"description": "Multi-variant button component with CVA",
"files": [
{ "path": "registry/ui/button.tsx", "type": "registry:ui" }
],
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": { "primary": "hsl(var(--primary))" }
}
}
}
}
}
]
}
```
```bash
# Users install your components directly
npx shadcn add https://ui.myapp.com/registry.json button
npx shadcn add https://ui.myapp.com/registry.json card dialog
```
### Base UI 1.x — Unstyled Accessibility Primitives
Base UI (from MUI team) is the 2026 alternative to Radix UI with React 19 native support:
```typescript
import { Dialog, Button, Select } from '@base-ui-components/react';
// Fully unstyled — apply any className/Tailwind styles
}>Open Dialog
Title
✕
```
### WCAG 2.2 Accessibility Checklist
- [ ] All interactive elements have visible focus indicators (`ring-2`).
- [ ] Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text / UI components).
- [ ] All images have `alt` text; decorative images have `alt=""`.
- [ ] All form inputs have associated `