design-system-architect

Design System Architect (2026 Edition — shadcn/ui Registry)

English | Bahasa Indonesia

English

Description

Expert guide for building and maintaining scalable UI design systems. Covers design tokens with OKLCH and Tailwind v4 @theme, Material Design 3 (M3) integration, 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.
• Applying Material Design 3 (M3) principles (https://m3.material.io/).
• 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)

/* 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 */

  /* --- Fluid Typography (clamp) --- */
  --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", ui-monospace, monospace;
  --font-size-xs:   clamp(0.7rem, 0.17vi + 0.66rem, 0.75rem);
  --font-size-sm:   clamp(0.8rem, 0.17vi + 0.76rem, 0.875rem);
  --font-size-base: clamp(0.9rem, 0.17vi + 0.86rem, 1rem);
  --font-size-lg:   clamp(1rem, 0.17vi + 0.96rem, 1.125rem);
  --font-size-xl:   clamp(1.1rem, 0.34vi + 1.02rem, 1.25rem);
  --font-size-2xl:  clamp(1.2rem, 0.69vi + 1.03rem, 1.5rem);
  --font-size-3xl:  clamp(1.5rem, 0.86vi + 1.29rem, 1.875rem);
  --font-size-4xl:  clamp(1.8rem, 1.03vi + 1.54rem, 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);
  }
}