Expert guide for designing, building, and maintaining scalable UI design systems with design tokens, headless primitives, Material Design 3 (M3), Tailwind v4 @theme, and WCAG 2.2 accessibility.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
설치 방법 보기설치하기 전에 에이전트에게 전달되는 지시 내용을 확인할 수 있습니다.
<a name="english"></a>
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.
anti-slop quality standards on component primitives and tokens.<button>, <dialog>, <nav>, <input>).border-border) and directional micro-shadows (shadow-xs). Ban muddy 30px black shadows and ungrounded neon glow orbs.focus-visible:ring-2, loading/skeleton state, and disabled/error styling.tracking-tight), uppercase eyebrows to wide letter-spacing (tracking-wider), and all numeric/counter/price components must enforce tabular-nums.p-[13px]); enforce unified @theme tokens./* 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-canvas: oklch(98.5% 0.005 250); /* L0 Canvas */
--color-surface-card: oklch(100% 0 0); /* L1 Card */
--color-surface-raised: oklch(100% 0 0); /* L2 Popover/Raised */
--color-surface-overlay: oklch(99% 0.005 250); /* L3 Modal Dialog */
--color-surface-2: oklch(97% 0.005 250);
--color-border: oklch(90% 0.01 250);
--color-text: oklch(15% 0.02 250); /* >= 7:1 Contrast */
--color-text-secondary: oklch(45% 0.015 250); /* >= 4.5:1 Contrast */
--color-text-muted: oklch(50% 0.015 250);
--color-destructive: oklch(55% 0.22 25); /* Red */
/* Optical Letter-Spacing */
--tracking-tighter: -0.04em;
--tracking-tight: -0.02em;
--tracking-normal: 0em;
--tracking-wide: 0.025em;
--tracking-wider: 0.05em;
/* --- 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);
}
}
When implementing or adhering to Google Material Design 3 (Material You), strictly apply the 8 foundational pillars and token system:
M3 organizes design tokens into three strict tiers:
md.ref.*): Primitive building blocks storing raw values (e.g. md.ref.palette.primary40: #6750A4).md.sys.*): Context-aware decisions that dynamically adapt between light and dark modes (e.g. md.sys.color.primary, md.sys.elevation.level2, md.sys.shape.corner-large).md.comp.*): Element-specific styling attributes (e.g. md.comp.filled-button.container.color: var(--md-sys-color-primary)).M3 replaces RGB/HSL color matching with the perceptually uniform HCT space. Tone (0 to 100) dictates absolute luminance, mathematically guaranteeing WCAG contrast across all hues:
Dynamic color extraction pipeline from seed color via @material/material-color-utilities:
import { argbFromHex, themeFromSourceColor } from '@material/material-color-utilities';
// Generate 5 core tonal palettes from a single brand seed
const theme = themeFromSourceColor(argbFromHex('#6750A4'));
// Schemes contain full light/dark role maps:
// theme.schemes.light.primary, theme.schemes.dark.primary
Never use static hex colors. Map all elements to semantic M3 color roles:
primary / on-primary (High-emphasis CTA)primary-container / on-primary-container (Medium-high emphasis fill)secondary / on-secondary (Filter chips, secondary elements)secondary-container / on-secondary-container (Active nav pill, subtle highlight)tertiary / on-tertiary (Balanced contrasting accent, creative accents)tertiary-container / on-tertiary-container (Callouts, tags, contextual banners)error / on-error & error-container / on-error-container (Alerts, validation errors)surface-dim (Tone 87 L / Tone 6 D): Background groundingsurface (Tone 98 L / Tone 6 D): Baseline surfacesurface-bright (Tone 98 L / Tone 24 D): High-contrast surfacesurface-container-lowest (Tone 100 L / Tone 4 D): Contained elements on dark canvassurface-container-low (Tone 96 L / Tone 10 D): Contained cards, grouped listssurface-container (Tone 94 L / Tone 12 D): Default cards, dialogs, bottom sheetssurface-container-high (Tone 92 L / Tone 17 D): Floating search bars, action popupssurface-container-highest (Tone 90 L / Tone 22 D): Top-level modal overlaysoutline: High-contrast borders (text field boundaries, unselected buttons).outline-variant: Subtle dividers, table row borders, card outlines.Elevation conveys z-axis separation using surface tinting (primary color blended onto surface) and ambient diffuse shadow:
box-shadow: 0 1px 3px rgba(0,0,0,0.12).box-shadow: 0 2px 6px rgba(0,0,0,0.15).box-shadow: 0 4px 12px rgba(0,0,0,0.18).box-shadow: 0 6px 16px rgba(0,0,0,0.20).box-shadow: 0 8px 24px rgba(0,0,0,0.24).M3 defines 5 type roles in Large, Medium, Small with strict optical sizing and tracking:
display-large (57px/64px -0.25 tracking) | display-medium (45px/52px) | display-small (36px/44px)headline-large (32px/40px) | headline-medium (28px/36px) | headline-small (24px/32px)title-large (22px/28px) | title-medium (16px/24px 0.15 tracking) | title-small (14px/20px 0.1 tracking)body-large (16px/24px 0.5 tracking) | body-medium (14px/20px 0.25 tracking) | body-small (12px/16px 0.4 tracking)label-large (14px/20px 0.1 tracking, weight 500) | label-medium (12px/16px 0.5 tracking) | label-small (11px/16px 0.5 tracking)Corner radius communicates component structure:
corner-none: 0px (Full-bleed images, dividers)corner-extra-small: 4px (Text fields, snackbars, autocomplete)corner-small: 8px (Chips, tooltips)corner-medium: 12px (Cards, compact dialogs)corner-large: 16px (Navigation drawers, modal bottom sheets, standard FABs)corner-extra-large: 28px (Large modal dialogs, date/time pickers)corner-full: 9999px (Pill buttons, badges, active search bar, navigation indicators)M3 adapts navigation and layout structures according to window size classes:
@theme Mapping Architecture@theme {
/* M3 System Color Roles (OKLCH mapping) */
--color-md-sys-primary: oklch(55% 0.22 270);
--color-md-sys-on-primary: oklch(100% 0 0);
--color-md-sys-primary-container: oklch(90% 0.08 270);
--color-md-sys-on-primary-container: oklch(20% 0.12 270);
--color-md-sys-secondary: oklch(58% 0.08 270);
--color-md-sys-on-secondary: oklch(100% 0 0);
--color-md-sys-secondary-container: oklch(92% 0.03 270);
--color-md-sys-on-secondary-container: oklch(22% 0.06 270);
--color-md-sys-surface: oklch(98% 0.005 270);
--color-md-sys-on-surface: oklch(18% 0.015 270);
--color-md-sys-surface-container-low: oklch(96% 0.008 270);
--color-md-sys-surface-container: oklch(94% 0.012 270);
--color-md-sys-surface-container-high: oklch(92% 0.015 270);
--color-md-sys-outline: oklch(55% 0.02 270);
--color-md-sys-outline-variant: oklch(82% 0.015 270);
/* M3 Shapes */
--radius-md-sys-xs: 4px;
--radius-md-sys-sm: 8px;
--radius-md-sys-md: 12px;
--radius-md-sys-lg: 16px;
--radius-md-sys-xl: 28px;
--radius-md-sys-full: 9999px;
/* M3 Elevation Shadows */
--shadow-md-sys-1: 0 1px 3px 1px rgba(0, 0, 0, 0.15), 0 1px 2px 0 rgba(0, 0, 0, 0.30);
--shadow-md-sys-2: 0 2px 6px 2px rgba(0, 0, 0, 0.15), 0 1px 2px 0 rgba(0, 0, 0, 0.30);
--shadow-md-sys-3: 0 4px 8px 3px rgba(0, 0, 0, 0.15), 0 1px 3px 0 rgba(0, 0, 0, 0.30);
}
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 };
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 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 (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>
default, hover, active, focus, disabled, and error.aria-invalid and aria-describedby (React Hook Form + Zod).⌘K command menu via cmdk.<Link viewTransition> for layout morphing.role="navigation" and aria-current="page".shadow-sm); avoid heavy drop shadows in light mode.ring-2).alt text; decorative images have alt="".<label> elements.aria-label or aria-labelledby on icon buttons.<a name="bahasa-indonesia"></a>
Terhubung dan mengorkestrasi skill domain yang relevan seperti anti-slop, brainstorming, zero-to-prod-orchestrator, dan session-memory-manager untuk memastikan eksekusi yang kohesif.
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.
anti-slop pada primitif komponen dan token visual.<button>, <dialog>, <nav>, <input>).border-border) dan micro-shadow terarah (shadow-xs). Dilarang keras bayangan hitam buram 30px dan lingkaran neon mengambang tanpa dasar fisik.tracking-tight), eyebrow menggunakan tracking renggang (tracking-wider), dan semua komponen angka/metrik/harga wajib menerapkan tabular-nums.focus-visible:ring-2, status loading/skeleton, dan status disabled/error.p-[13px]); tegakkan token @theme yang terpadu.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.
Ketika menerapkan atau mengacu pada Google Material Design 3 (Material You), tegakkan 8 pilar fondasi dan sistem token berikut:
M3 mengorganisasi token desain ke dalam tiga hierarki:
md.ref.*): Blok pembangun primitif yang menyimpan nilai mentah (misal md.ref.palette.primary40: #6750A4).md.sys.*): Keputusan desain berbasis konteks yang beradaptasi otomatis antara tema terang/gelap (misal md.sys.color.primary, md.sys.elevation.level2, md.sys.shape.corner-large).md.comp.*): Atribut styling spesifik komponen (misal md.comp.filled-button.container.color: var(--md-sys-color-primary)).M3 menggantikan pencocokan warna RGB/HSL dengan ruang warna HCT (Hue, Chroma, Tone) yang perseptual seragam. Tone (0 hingga 100) menentukan luminansi absolut dan menjamin kepatuhan kontras WCAG secara matematis pada semua rona:
Ekstraksi warna dinamis dari seed color via @material/material-color-utilities:
import { argbFromHex, themeFromSourceColor } from '@material/material-color-utilities';
// Buat 5 palet tonal inti dari satu warna seed brand
const theme = themeFromSourceColor(argbFromHex('#6750A4'));
// Skema menghasilkan peran lengkap untuk mode terang dan gelap:
// theme.schemes.light.primary, theme.schemes.dark.primary
Dilarang menggunakan hex warna statis. Petakan elemen ke peran warna semantik M3:
primary / on-primary (Tombol aksi utama/CTA kontras tinggi)primary-container / on-primary-container (Wadah berbobot visual sedang-tinggi)secondary / on-secondary (Filter chip, elemen aksen sekunder)secondary-container / on-secondary-container (Indikator pil navigasi aktif)tertiary / on-tertiary (Aksen kontras penyeimbang yang kreatif)tertiary-container / on-tertiary-container (Callout, banner kontekstual)error / on-error & error-container / on-error-container (Peringatan & error validasi)surface-dim (Tone 87 L / Tone 6 D): Latar belakang terdalamsurface (Tone 98 L / Tone 6 D): Permukaan dasar aplikasisurface-bright (Tone 98 L / Tone 24 D): Permukaan kontras tinggi di mode gelapsurface-container-lowest (Tone 100 L / Tone 4 D): Wadah terendah pada kanvas gelapsurface-container-low (Tone 96 L / Tone 10 D): Kartu bersarang, pengelompokan listsurface-container (Tone 94 L / Tone 12 D): Wadah kartu default, dialog, bottom sheetsurface-container-high (Tone 92 L / Tone 17 D): Search bar melayang, menu popupsurface-container-highest (Tone 90 L / Tone 22 D): Overlay modal tingkat atasoutline: Batas kontras tinggi (field teks, tombol unselected).outline-variant: Pemisah halus (garis batas kartu, pemisah baris tabel).Elevasi menyampaikan kedalaman sumbu Z menggunakan surface tinting (warna primer yang ditumpangkan di atas surface) dipadukan dengan bayangan difus ambient:
box-shadow: 0 1px 3px rgba(0,0,0,0.12).box-shadow: 0 2px 6px rgba(0,0,0,0.15).box-shadow: 0 4px 12px rgba(0,0,0,0.18).box-shadow: 0 6px 16px rgba(0,0,0,0.20).box-shadow: 0 8px 24px rgba(0,0,0,0.24).M3 mendefinisikan 5 peran tipe dengan ukuran Large, Medium, Small serta tracking presisi:
display-large (57px/64px -0.25 tracking) | display-medium (45px/52px) | display-small (36px/44px)headline-large (32px/40px) | headline-medium (28px/36px) | headline-small (24px/32px)title-large (22px/28px) | title-medium (16px/24px 0.15 tracking) | title-small (14px/20px 0.1 tracking)body-large (16px/24px 0.5 tracking) | body-medium (14px/20px 0.25 tracking) | body-small (12px/16px 0.4 tracking)label-large (14px/20px 0.1 tracking, weight 500) | label-medium (12px/16px 0.5 tracking) | label-small (11px/16px 0.5 tracking)corner-none: 0px (Gambar full-bleed, divider)corner-extra-small: 4px (Text field container, snackbar)corner-small: 8px (Chip, tooltip)corner-medium: 12px (Kartu, dialog kecil)corner-large: 16px (Navigation drawer, modal bottom sheet, FAB standar)corner-extra-large: 28px (Dialog modal penuh, date/time picker)corner-full: 9999px (Tombol bentuk pil, badge, search bar aktif)M3 membagi adaptasi tata letak berdasarkan lebar jendela:
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.
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 (dari tim MUI) adalah alternatif Radix UI untuk 2026 dengan dukungan native React 19. Sepenuhnya tanpa gaya — terapkan className/Tailwind apapun.
default, hover, active, focus, disabled, error). Tampilkan validasi inline on-blur (aria-invalid, aria-describedby via React Hook Form + Zod). Target sentuh minimal 44x44px.⌘K dengan cmdk. Layout responsif (navigasi bawah di mobile, rail di tablet, sidebar penuh di desktop). Transisi halaman halus via <Link viewTransition> di Next.js 15.<label> terkait.anti-slop (ensures zero stubbed components, complete token sets, and 5-state resilience), frontend orchestrators, Tailwind v4, Base UI, and shadcn/ui.아직 리뷰가 없습니다. 사용해 본 소감을 남겨 주세요.
로그인 없이 쓸 수 있습니다. 사용 후기, 질문, 작동하지 않은 환경 등을 편하게 남겨 주세요.
아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.
Expert guide for automated and manual Web Accessibility (a11y) testing — axe-core, Pa11y, Playwright a11y, screen reader testing, and WCAG 2.2 Level AA/AAA compliance / Panduan ahli pengujian aksesibilitas web.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Expert guide for intelligent model cascading and routing — complexity-scored task routing from Flash/Haiku to Sonnet/Opus/Astra, dynamic escalation with quality gates, 40-60% token cost reduction while maintaining output quality / Panduan ahli untuk kaskade dan routing model cerdas — routing tugas berbasis skor kompleksitas dari Flash/Haiku ke Sonnet/Opus/Astra, eskalasi dinamis dengan gerbang kualitas, pengurangan biaya token 40-60% dengan kualitas output terjaga.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Expert guide for Affective Computing, emotional AI, and real-time sentiment analysis through native multimodal tokens (voice intonation and facial micro-expressions) / Panduan ahli komputasi afektif, AI emosional, dan analisis sentimen real-time melalui token multimodal native.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Expert guide for AI-assisted coding workflows — agentic code generation, multi-agent code swarms, self-healing CI/CD, automated PR review, spec-to-code pipelines, codebase knowledge graphs, and human-in-the-loop approval gates / Panduan ahli untuk workflow pengkodean berbasis AI — generasi kode agentic, code swarm multi-agen, CI/CD self-healing, review PR otomatis, pipeline spec-to-code, knowledge graph codebase, dan gate persetujuan human-in-the-loop.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Expert guide for autonomous Machine-to-Machine (M2M) agent settlement, dual-rail fiat & stablecoin micro-clearing, dynamic budget envelopes, and cryptographic agent invoicing / Panduan ahli settlement otonom antar-agen (M2M), kliring mikro dual-rail fiat & stablecoin, pagu anggaran dinamis, dan penagihan agen kriptografis.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Expert guide for long-term episodic memory integration (Mem0 v2, Letta/MemGPT, Zep v2), memory tier architecture, pgvector HNSW storage, and unified context management for autonomous AI agents / Panduan ahli untuk integrasi memori episodik jangka panjang (Mem0 v2, Letta/MemGPT, Zep v2), arsitektur tier memori, penyimpanan pgvector HNSW, dan manajemen konteks terpadu untuk agen AI otonom.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.