shadcn/ui: Komponen Copy-Paste sebagai Sebuah Arsitektur

Setiap beberapa tahun sebuah component library merilis versi besar, dan setiap tim yang bergantung padanya mewarisi sore yang sama: membaca changelog, menulis ulang theme override, lalu menyadari tombol yang tidak pernah disentuh kini tampil bergeser dua piksel. Itulah biaya dari menginstal keputusan desain orang lain sebagai dependensi.

shadcn/ui mengambil posisi yang berbeda. Alih-alih mengirimkan paket yang diimpor, ia memberikan kode sumber asli setiap komponen dan membiarkan sebuah CLI menyalin kode itu langsung ke repositori kita sendiri. Hasilnya bukan sekadar library yang lebih ringkas, melainkan arsitektur yang sepenuhnya berbeda, dibangun di atas primitive Radix UI untuk perilaku komponen dan token Tailwind CSS untuk theming, dan ini mengubah cara sebuah design system berkembang seiring bertambahnya ukuran codebase.

Bukan Component Library, Melainkan Model Distribusi

Dokumentasi shadcn/ui menyatakan posisinya secara terang-terangan: ini bukan component library, ini adalah cara membangun component library milik kita sendiri. Menjalankan perintah add pada CLI tidak menambahkan entri di package.json yang mengarah ke bundel terkompilasi. Perintah itu menulis sebuah file TypeScript biasa ke folder components kita, sepenuhnya dapat dibaca, sepenuhnya milik kita, tanpa versi yang perlu dilacak dan tanpa kotak hitam yang harus dilawan ketika kebutuhan desain tidak sesuai dengan asumsi library tersebut.

Library tradisional seperti Material UI atau Ant Design menyelesaikan masalah yang berbeda: perilaku yang konsisten di antara ribuan pengguna, dicapai lewat prop API dan objek theme yang harus tetap backward compatible. Batasan backward compatibility itu justru yang membuat proses upgrade menyakitkan. shadcn/ui menghindari batasan tersebut dengan tidak pernah menjanjikan kompatibilitas sejak awal, karena setelah langkah penyalinan tidak ada lagi paket bersama yang perlu dijaga kompatibilitasnya.

• Kode terbuka: komponen mendarat sebagai file sumber biasa di bawah components/ui, sehingga editor, linter, atau alat code review apa pun memperlakukannya seperti bagian lain dari codebase, bukan seperti keluaran node_modules yang tertutup.
• Tidak ada versi yang perlu dilawan: kode dibekukan pada saat kita menyalinnya. Rilis shadcn/ui di masa depan tidak bisa diam-diam mengubah tampilan tombol kita, karena tombol itu bukan lagi tombol milik shadcn/ui.
• Komposisi lebih dulu: setiap primitive memakai konvensi yang dapat diprediksi, prop asChild untuk polimorfisme dan class-variance-authority untuk variant, sehingga begitu tim memahami satu komponen, komponen lain terasa serupa saat dibaca.

Dibangun di Atas Primitive Radix untuk Aksesibilitas

Logika interaksi adalah bagian tersulit dari sebuah komponen, bukan gaya visualnya. Radix UI Primitives menyediakan logika itu sebagai building block yang tidak berstyle namun aksesibel, mengikuti pola penulisan WAI-ARIA, menangani navigasi keyboard, penjebakan fokus di dalam dialog, dan peran yang benar untuk pembaca layar. shadcn/ui membungkus setiap primitive Radix dengan utility class Tailwind, sehingga pekerjaan aksesibilitas diwariskan bukan diimplementasikan ulang, sementara lapisan visualnya tetap sepenuhnya dapat diedit.

Tombol di bawah ini menunjukkan pola tersebut dalam skala kecil. Ia tidak langsung terhubung ke primitive Radix, tetapi memperlihatkan dua elemen yang selalu menjadi sandaran setiap komponen shadcn/ui: Slot dari Radix, yang memungkinkan komponen dirender sebagai elemen bawaan yang berbeda tanpa node pembungkus tambahan, dan class-variance-authority, yang mengubah prop variant menjadi lookup bertipe dari string class Tailwind, bukan sekumpulan ekspresi kondisional.

// components/ui/button.tsx (installed via CLI, then edited freely)
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border border-input bg-background hover:bg-accent",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp className={cn(buttonVariants({ variant, size, className }))} {...props} />
  )
}

export { Button, buttonVariants }

Karena file ini berada di repositori kita, menambahkan variant baru, misalnya kombinasi destructive-outline yang tidak pernah dirilis desain aslinya, hanyalah sebuah edit lokal dan pull request, bukan feature request ke roadmap orang lain. Hal yang sama berlaku untuk menghapus dependensi yang tidak diinginkan: buang class-variance-authority dan tulis langsung string class jika tim lebih menyukai lebih sedikit bagian yang bergerak.

Theming dengan CSS Variable dan Design Token

Komponen shadcn/ui tidak pernah menulis kode warna hex secara langsung. Setiap properti visual melewati sekumpulan kecil CSS variable, background, foreground, primary, primary foreground, dan beberapa lainnya, dinyatakan sebagai triple HSL agar bisa dirujuk di dalam fungsi warna Tailwind. Konfigurasi Tailwind kemudian memetakan class seperti bg-primary ke hsl(var(--primary)), yang berarti nama class yang sama menghasilkan piksel berbeda tergantung variable mana yang sedang aktif.

/* app/globals.css — tokens consumed by every shadcn/ui component */
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 240 5.9% 10%;
  --primary-foreground: 0 0% 98%;
  --radius: 0.5rem;
}

.dark {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
  --primary: 0 0% 98%;
  --primary-foreground: 240 5.9% 10%;
}

Lapisan indireksi tunggal itulah yang membuat rebranding tetap dapat dikelola dalam skala besar. Mengubah warna aksen sebuah produk berarti mengedit satu CSS variable sekali saja, bukan mencari kode hex yang tercecer di setiap file komponen. Mode gelap bekerja dengan cara yang sama: mengaktifkan class dark pada elemen html menukar set variable yang aktif, dan setiap komponen yang sudah membaca var(--background) otomatis mendapat palet baru tanpa perubahan kode di tingkat komponen.

Apa yang Sebenarnya Dikorbankan

Perbandingan yang jujur terhadap model dependensi tradisional bukanlah soal pakai library atau tidak, melainkan siapa yang menanggung biaya pemeliharaan dan ke mana bobot bundel itu mengalir. Tabel di bawah membandingkan tiga dimensi yang paling relevan dalam praktik.

Konsekuensinya, tanggung jawab pemeliharaan berpindah dari maintainer library ke tim kita sendiri. Perbaikan terkait keamanan pada Radix tetap datang lewat package manager kita, tetapi perbaikan pada kode wrapper milik shadcn/ui sendiri harus diterapkan secara manual, file demi file, di setiap komponen tempat kode itu disalin. Itu harga yang wajar untuk tim dengan disiplin code review dan pemilik design system yang jelas, sekaligus risiko nyata bagi proyek solo yang tidak memiliki keduanya.

Alur Kerja Praktis untuk Mengembangkan Design System

Kepemilikan copy-paste hanya tetap terkelola bila tim memperlakukan kode yang disalin dengan disiplin yang sama seperti internal library lainnya. Beberapa kebiasaan berikut mencegahnya berubah menjadi drift yang tidak terkendali di puluhan komponen.

1. Instal setiap primitive sekali lewat CLI ke components/ui dan perlakukan folder itu sebagai scaffolding hasil generate, model mental yang sama seperti output codegen yang boleh diedit tangan tapi tidak diformat ulang secara sembarangan.
2. Bungkus primitive yang sudah terinstal dalam lapisan aplikasi terpisah untuk prop dan copy yang spesifik produk, sehingga kebutuhan satu halaman marketing tidak pernah memaksa perubahan pada primitive bersama yang juga dirender oleh semua layar lain.
3. Simpan seluruh design token dalam satu file CSS dan dokumentasikan arti setiap nama variable, sehingga komponen baru selalu menyusun dari palet yang sama, bukan memunculkan corak warna yang sedikit berbeda dari warna yang sudah ada.
4. Tambahkan poin checklist code review, atau aturan lint ringan, yang menandai edit langsung di dalam components/ui, sehingga perubahan pada primitive bersama selalu menjadi keputusan sengaja yang dibuat oleh seseorang yang bertanggung jawab atas design system, bukan efek samping tidak sengaja dari sebuah feature branch.

Kapan Kepemilikan Copy-Paste Tepat, dan Kapan Tidak

Arsitektur ini adalah trade-off yang nyata, bukan opsi yang selalu lebih baik, dan lebih cocok untuk beberapa situasi dibanding yang lain.

• Cocok: tim produk yang mengharapkan kustomisasi visual yang dalam dan berkelanjutan serta sudah memiliki pemilik design system yang mereview setiap perubahan komponen.
• Cocok: organisasi yang merilis beberapa aplikasi serupa yang bisa berbagi satu registry komponen internal daripada menduplikasi upaya di setiap repositori.
• Kurang cocok: tim yang membutuhkan perbaikan keamanan atau aksesibilitas menyebar ke setiap aplikasi konsumen begitu dirilis di hulu, karena library berbasis dependensi menghantarkannya lewat kenaikan versi sederhana, sementara kode yang disalin membutuhkan penerapan manual di setiap repositori.

Dalam praktiknya, kebanyakan tim produk berada di tengah-tengah: mereka menyalin primitive shadcn/ui demi kendali penuh atas lapisan visual, sambil tetap menarik Radix UI sendiri sebagai dependensi npm yang sesungguhnya untuk logika interaksi yang kritis bagi aksesibilitas di baliknya. Kepemilikan di tempat kustomisasi penting, dependensi di tempat kebenaran perilaku penting.