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);
  }
}

Material Design 3 (M3) Integration

When requested to follow Material Design 3 (https://m3.material.io/), implement the following M3 token principles in your design system:

1. Color Roles: Map Tailwind colors to M3 roles (Primary, Secondary, Tertiary, Error, Surface, Outline). Implement On-* colors for text/icons on top of those roles, and *-Container / On-*-Container for lower emphasis. Support Dynamic Color if applicable.
2. Typography Scale: Use M3 naming conventions: Display, Headline, Title, Body, Label (each with Large, Medium, Small sizes).
3. Elevation & Surface: Use M3 Elevation levels (0 to 5) implemented via subtle shadows and surface tint colors, not just heavy drop shadows.
4. Shapes: Map --radius-* to M3 shape families: None, Extra Small, Small, Medium, Large, Extra Large, Full.

Component Architecture

Headless + Styled Pattern (Base UI 1.x / Radix UI)

Use headless primitives for accessibility, apply styles via Tailwind + CVA:

// 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<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => (
    <button
      ref={ref}
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  )
);
Button.displayName = 'Button';

export { Button, buttonVariants };

Component Layout (Container Queries over Media Queries)

Avoid @media queries for internal component styling. Use CSS Container Queries (@container) so components respond to their wrapper, not the viewport. This makes components truly reusable anywhere.

// Example of a container-aware component using Tailwind v4
<div className="@container">
  <div className="flex flex-col @md:flex-row gap-4">
    <div className="p-4 bg-surface rounded-xl">Fluid Card</div>
  </div>
</div>

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:

// 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))" }
            }
          }
        }
      }
    }
  ]
}

# 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:

import { Dialog, Button, Select } from '@base-ui-components/react';

// Fully unstyled — apply any className/Tailwind styles
<Dialog.Root>
  <Dialog.Trigger render={<Button />}>Open Dialog</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50 animate-fade-in" />
    <Dialog.Popup className="fixed inset-0 m-auto h-fit max-w-md rounded-xl bg-surface p-6 shadow-xl animate-slide-up">
      <Dialog.Title className="text-lg font-semibold">Title</Dialog.Title>
      <Dialog.Close className="absolute right-4 top-4">✕</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

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 <label> elements.
• Keyboard navigation works for all interactions (Tab, Enter, Space, Escape, Arrow keys).
• aria-label or aria-labelledby on icon buttons.
• Modals trap focus and restore it on close.
• No content relies on color alone to convey information.
• Touch targets ≥ 24×24px (WCAG 2.2 new requirement).

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti brainstorming, zero-to-prod-orchestrator, dan project-context-mapper untuk memastikan eksekusi yang kohesif.

Deskripsi

Panduan ahli untuk membangun dan memelihara design system UI yang skalabel. Mencakup design token dengan OKLCH dan @theme Tailwind v4, primitif komponen headless (Radix UI, Base UI 1.x), registry shadcn/ui untuk distribusi library komponen, CVA untuk varian type-safe, dan kepatuhan aksesibilitas WCAG 2.2.

Kondisi Pemicu

• Membangun library komponen UI bersama dari awal.
• Menyiapkan design token (warna, tipografi, spacing) dengan Tailwind v4.
• Menerapkan prinsip Material Design 3 (M3) (https://m3.material.io/).
• Menggunakan primitif headless (Radix UI, Base UI 1.x) dengan styling kustom.
• Mendistribusikan komponen via format registry shadcn/ui.
• Mengaudit library komponen untuk kepatuhan aksesibilitas WCAG 2.2.

Fondasi Design Token (Tailwind v4 + OKLCH)

Definisikan semua token di CSS menggunakan direktif @theme. Gunakan warna OKLCH untuk tampilan P3 wide-gamut. Definisikan token semantik (--color-primary, --color-surface, --color-border) yang secara otomatis beradaptasi antara mode terang/gelap melalui @variant dark.

Integrasi Material Design 3 (M3)

Jika diminta mengikuti Material Design 3 (https://m3.material.io/), terapkan prinsip token M3 berikut:

1. Peran Warna (Color Roles): Petakan warna ke peran M3 (Primary, Secondary, Tertiary, Error, Surface, Outline). Gunakan warna On-* untuk teks di atasnya, dan *-Container / On-*-Container untuk penekanan lebih rendah.
2. Skala Tipografi: Gunakan penamaan M3: Display, Headline, Title, Body, Label (dengan ukuran Large, Medium, Small).
3. Elevasi & Permukaan: Gunakan tingkat Elevasi M3 (0 hingga 5) melalui bayangan halus dan warna tint permukaan (surface tint).
4. Bentuk (Shapes): Petakan --radius-* ke keluarga bentuk M3: None, Extra Small, Small, Medium, Large, Extra Large, Full.

Arsitektur Komponen

Gunakan pola Headless + Styled: primitif headless (Base UI/Radix) untuk aksesibilitas, gaya melalui Tailwind + CVA (class-variance-authority) untuk varian type-safe.

Container Queries (@container): DILARANG keras menggunakan @media query (misal md:, lg:) untuk layout di dalam sebuah komponen. Gunakan Container Queries (@md:, @lg:) agar komponen dapat menyesuaikan diri dengan lebar pembungkusnya, bukan lebar layar secara keseluruhan. Ini membuat komponen Anda 100% reusable.

Registry shadcn/ui — Komponen yang Dapat Didistribusikan (2026)

shadcn/ui v2 memperkenalkan sistem registry — distribusikan komponen Anda sebagai library yang dapat dibagikan sehingga orang lain dapat menginstalnya dengan npx shadcn add [url] [komponen].

Base UI 1.x — Primitif Aksesibilitas Tanpa Gaya

Base UI (dari tim MUI) adalah alternatif Radix UI untuk 2026 dengan dukungan native React 19. Sepenuhnya tanpa gaya — terapkan className/Tailwind apapun.

Checklist Aksesibilitas WCAG 2.2

• Semua elemen interaktif memiliki indikator fokus yang terlihat.
• Kontras warna ≥ 4.5:1 (teks), ≥ 3:1 (komponen UI).
• Semua input form memiliki elemen <label> terkait.
• Navigasi keyboard berfungsi untuk semua interaksi.
• Modal menjebak fokus dan memulihkannya saat ditutup.
• Target sentuh ≥ 24×24px (persyaratan baru WCAG 2.2).

Orchestration & Integration

• Integrates with frontend orchestrators, Tailwind v4, Base UI, and shadcn/ui.