@damarkuncoro/agnostic-ui-theme

Tujuan paket ini adalah mendefinisikan “tema” sebagai sekumpulan token yang netral terhadap framework maupun library UI. Tema memetakan varian dan ukuran komponen ke token desain (warna, tipografi, spacing, radius), bukan ke kelas CSS spesifik. Ini mematuhi SRP, DRY, KISS, YAGNI dan mengikuti arsitektur Core yang independen.

Konsep Utama

• Tema adalah kontrak token: tidak ada class Tailwind, tidak ada DOM, tidak ada CSS. Hanya string token yang dapat diinterpretasi oleh layer lain.
• Variants dan sizes ditentukan per komponen. Contoh untuk Button:
  • variants: primary, secondary, success, warning, danger, ghost, link
  • sizes: xs, sm, md, lg, xl
• Setiap varian dan ukuran memetakan ke token seperti color.primary, space.4, font.base, radius.md, dsb.

API

• Ekspor utama:
  • defaultButtonTheme mendefinisikan token untuk varian/ukuran tombol.
  • UiButtonTheme, UiButtonVariantTokens, UiButtonSizeTokens sebagai tipe.
• Lokasi sumber:
  • packages/agnostic-ui-theme/src/ui/button/ui-button.theme.ts
  • packages/agnostic-ui-theme/src/ui/button/ui-button.types.ts
  • packages/agnostic-ui-theme/src/index.ts

Contoh struktur tema tombol:

// packages/agnostic-ui-theme/src/ui/button/ui-button.theme.ts:5
export const defaultButtonTheme: UiButtonTheme = {
  variants: {
    primary: { bg: 'color.primary', text: 'color.onPrimary', hoverBg: 'color.primary.hover' },
    secondary: { bg: 'color.secondary', text: 'color.onSecondary', hoverBg: 'color.secondary.hover' },
    success: { bg: 'color.success', text: 'color.onSuccess', hoverBg: 'color.success.hover' },
    warning: { bg: 'color.warning', text: 'color.onWarning', hoverBg: 'color.warning.hover' },
    danger: { bg: 'color.danger', text: 'color.onDanger', hoverBg: 'color.danger.hover' },
    ghost: { bg: 'color.transparent', text: 'color.onGhost', hoverBg: 'color.transparent.hover' },
    link: { bg: 'color.transparent', text: 'color.onLink', hoverBg: 'color.transparent.hover' }
  },
  sizes: {
    xs: { px: 'space.2', py: 'space.1', font: 'font.sm', radius: 'radius.sm' },
    sm: { px: 'space.3', py: 'space.1', font: 'font.sm', radius: 'radius.sm' },
    md: { px: 'space.4', py: 'space.2', font: 'font.base', radius: 'radius.md' },
    lg: { px: 'space.5', py: 'space.3', font: 'font.lg', radius: 'radius.lg' },
    xl: { px: 'space.6', py: 'space.4', font: 'font.lg', radius: 'radius.lg' }
  }
}

Instalasi & Import

Monorepo sudah memetakan alias ke source melalui tsconfig.base.json.

// Impor tema tombol dan tipe
import { defaultButtonTheme, type UiButtonTheme } from '@damarkuncoro/agnostic-ui-theme'

Tema menggunakan kontrak:

import { UI_BUTTON_SIZES, UI_BUTTON_VARIANTS } from '@damarkuncoro/contracts'

Build & Test

• Build:

pnpm --filter @damarkuncoro/agnostic-ui-theme build

• Test:

pnpm --filter @damarkuncoro/agnostic-ui-theme test

Hubungan dengan Paket Lain

• contracts: mendefinisikan enumerasi dan tipe publik untuk varian/ukuran (UI Contract).
• skin: menerjemahkan token tema menjadi implementasi visual (kelas CSS/Tailwind).
• base, react, vue: menggunakan kontrak dan skin untuk merender komponen.

Extensibility

• Tambah tema baru: definisikan objek UiButtonTheme lain, tetap gunakan kunci token yang konsisten (color.*, space.*, dll).
• Ubah tema default: override defaultButtonTheme pada aplikasi Anda lalu injeksikan melalui layer yang membutuhkan.

Prinsip Desain

• Core, tanpa dependensi pada UI lib.
• SOLID: tema untuk satu komponen berada di modulnya sendiri.
• Composition over Inheritance: komponen mengonsumsi token; skin mengkomposisi kelas dari token dan utilitas.