W4C UI

Design system Waste4Change: token warna, komponen Vue, dan pedoman pemakaian untuk project Nuxt. Dengan ini, project baru bisa langsung fokus ke fitur tanpa membuat ulang tombol, input, dan modal.

Lihat komponen Token warna

Instalasi

Untuk project Nuxt 4 baru.

  1. 1

    Hubungkan ke registry

    Package ini private dan tinggal di GitLab Package Registry, bukan di npmjs. Baris pertama masuk ke repo project. Tokennya disimpan di ~/.npmrc, di luar repo, supaya tidak ikut ter-commit; buat di GitLab lewat Preferences > Access tokens dengan scope read_api saja.

    .npmrc
    @waste4change:registry=https://gitlab.com/api/v4/projects/w4c-tech%2Fui/packages/npm/
    ~/.npmrc
    //gitlab.com/api/v4/projects/w4c-tech%2Fui/packages/npm/:_authToken=TOKEN_KAMU
  2. 2

    Tambahkan package

    Versi yang terpasang mengikuti tag rilis di repo design system.

    bash
    bun add @waste4change/ui
  3. 3

    Extend di nuxt.config.ts

    Layer ini sudah memasang Tailwind v4, ikon Iconify lewat W4cIcon (@nuxt/icon), dan font Nunito (@nuxt/fonts). Tidak perlu dipasang lagi.

    nuxt.config.ts
    export default defineNuxtConfig({
      extends: ['@waste4change/ui'],
      css: ['~/assets/css/main.css'],
    })
  4. 4

    Import di CSS utama

    Satu baris ini sudah memuat Tailwind dan token W4C, jadi token warna langsung bisa dipakai sebagai class (bg-primary, text-content-muted, dan seterusnya). Jangan tambahkan @import 'tailwindcss' lagi.

    app/assets/css/main.css
    @import '@waste4change/ui';
  5. 5

    Pakai komponennya

    Semua komponen memakai prefix W4c dan langsung tersedia tanpa import.

    vue
    <W4cButton icon="lucide:save" @click="save">
      Simpan
    </W4cButton>

Di CI project pemakai

Pipeline project pemakai juga butuh token sendiri. CI_JOB_TOKEN milik satu project tidak otomatis boleh membaca registry project lain, jadi cara paling sederhana adalah satu group access token Waste4Change dengan scope read_api, disimpan sebagai CI variable bertipe masked.

bash
# Di before_script pipeline project pemakai.
# W4C_REGISTRY_TOKEN disimpan sebagai CI variable bertipe masked.
echo "//gitlab.com/api/v4/projects/w4c-tech%2Fui/packages/npm/:_authToken=${W4C_REGISTRY_TOKEN}" >> ~/.npmrc
bun install --frozen-lockfile

Dark mode

Token otomatis berganti saat elemen <html> punya class dark. Cara paling mudah memasang class itu adalah dengan @nuxtjs/color-mode:

nuxt.config.ts
// bun add -D @nuxtjs/color-mode
export default defineNuxtConfig({
  extends: ['@waste4change/ui'],
  modules: ['@nuxtjs/color-mode'],
  colorMode: { classSuffix: '' },
})

Konvensi

  • Semua komponen memakai prefix W4c. Boleh ditulis PascalCase (<W4cButton>) atau kebab-case (<w4c-button>). Pilih salah satu dan pakai konsisten dalam satu project.
  • Warna diatur lewat prop color (primary, neutral, success, warning, danger). Hindari class warna langsung.
  • class pada komponen hanya untuk tata letak: margin, lebar, posisi.
  • Untuk halaman sendiri, pakai token semantik seperti bg-surface, text-content-muted, dan border-border, bukan bg-white atau text-gray-500. Dengan begitu dark mode ikut benar.

Untuk AI agent

Banyak MVP di W4C dibuat dengan bantuan AI, dan agent yang tidak tahu library ini akan mengarang komponennya sendiri. Tiga berkas dibuat untuk mencegah itu:

  • /llms.txt — seluruh halaman dokumentasi sebagai satu berkas teks. Dibuat dari navigasi situs ini, jadi halaman baru langsung ikut terdaftar.
  • /llms-full.txt — API lengkap setiap komponen dalam satu berkas: 51 komponen, 482 prop, 43 event, dan 107 slot, dengan tipe, nilai bawaan, dan keterangannya. Dibaca langsung dari sumber komponen oleh bun run api, jadi tidak bisa ketinggalan dari kodenya. Satu kali fetch menggantikan membuka seluruh halaman komponen.
  • AGENTS.md ikut terkirim bersama paketnya, di node_modules/@waste4change/ui/AGENTS.md: aturan keras, daftar komponen, tabel “pakai ini, bukan itu”, dan kesalahan yang paling sering terjadi.

Arahkan agent ke ketiganya di awal pekerjaan — misalnya lewat CLAUDE.md atau AGENTS.md milik project itu sendiri.