# Menambah produk

> Buat tema terang dan gelap untuk produk Sosialoka baru dari warna logonya dengan satu perintah, dan pakai tema netral untuk layar yang bukan milik produk mana pun.

Setiap brand tercatat satu kali, di `tokens/brands.json`. Build token, registry, paket Flutter, dan situs ini membaca daftar itu, jadi produk baru cukup butuh satu perintah, logonya, dan beberapa baris dokumentasi.

## Sebelum mulai

- **Warna logo** dalam format `#RRGGBB`. Warna ini langsung jadi `primary` di mode terang: primary sebuah produk selalu warna logonya.
- **File logo**, satu untuk latar terang dan satu untuk latar gelap, dalam SVG atau PNG.
- **Id**: huruf kecil dan angka, misalnya `lokaticket`. Id ini jadi nilai `data-brand`, nama file tema, dan nilai enum Flutter, jadi tentukan sekali saja.

## 1. Buat temanya

Di repositori design system:

```bash
pnpm new-brand lokaticket --name "Loka Ticket" --logo "#B83A0B" --summary "Ticketing for music events."
```

Perintah ini menulis `tokens/themes/lokaticket-light.tokens.json` dan `lokaticket-dark.tokens.json`, menambahkan produknya ke `tokens/brands.json`, lalu menjalankan cek kontras untuk dua tema baru itu.

| Opsi | Untuk |
| --- | --- |
| `--name` | Nama produk seperti yang dibaca orang. Wajib. |
| `--logo` | Warna logo. Wajib. |
| `--summary` | Satu baris berbahasa Inggris tentang fungsi produknya. Wajib. |
| `--secondary` | Warna logo kedua, untuk gradien dan hero login. |
| `--dark-primary` | `primary` di mode gelap, kalau hasil turunannya kurang cocok dengan logonya. |
| `--font` | Font display untuk momen brand. Default-nya Plus Jakarta Sans. |
| `--fallback` | `sans-serif` atau `serif`, setelah font display. |
| `--sample` | Kalimat contoh dalam font display di halaman Brand. Tulis seperti kalimat di hero login. |

## Cara warnanya dibuat

| Token | Terang | Gelap |
| --- | --- | --- |
| `primary` | Warna logo | Warna logo, dicerahkan sampai teks gelap terbaca di atasnya |
| `primary-foreground` | Putih atau tinta gelap, mana yang terbaca di warna logo dan di hover-nya | Tinta gelap |
| `background`, `card`, `muted`, `border` | Hampir putih, dengan sedikit rona logo | Hampir hitam, dengan sedikit rona logo |
| `foreground`, `muted-foreground`, `input` | Digeser sampai mencapai 4.5:1, atau 3:1 untuk `input` | Sama |
| `primary-soft`, `primary-text` | Rona pucat, dan warna logo yang digelapkan sampai terbaca sebagai teks | Rona gelap, dan versi terang warna logo |
| `chart-1` | Warna logo, digelapkan hanya kalau perlu untuk mencapai 3:1 | Warna logo, dicerahkan hanya kalau perlu |
| `brand-*` | Warna logo, sama di kedua mode | Sama |

Logo abu-abu menghasilkan neutral abu-abu, karena ronanya tidak pernah lebih berwarna dari logonya. Hasilnya titik awal: buka file temanya, ubah yang terasa kurang pas dengan produknya, lalu jalankan `pnpm check`, yang menjaga setiap pasangan warna di kontras yang dibutuhkan.

### Kalau cek kontras melaporkan pasangan

Beberapa warna logo, seperti pink atau jingga terang, tidak bisa memuat teks putih maupun gelap di 4.5:1. Perintahnya tetap memakai warna logo dan menampilkan pasangan itu. Jangan ganti `primary` sendiri: tanyakan ke pemilik design system. Pasangan itu bisa diterima sebagai pengecualian di `packages/tokens/src/contrast.ts`, seperti jingga Cover Clearance, atau primary-nya diganti.

## 2. Tambahkan logonya

Simpan file-nya di `site/public/brand/` dan daftarkan di entri produknya di `tokens/brands.json`:

```json
"logos": [
  { "variant": "light-ground", "file": "lokaticket.svg", "alt": "Loka Ticket logo, for light grounds" },
  { "variant": "dark-ground", "file": "lokaticket-white.svg", "alt": "Loka Ticket logo, white, for dark grounds" }
]
```

Halaman Brand menampilkannya di grid logo, dan contoh font ikut memakai font display serta kalimat contohnya.

## 3. Muat font display baru

Kalau font display-nya belum dimuat situs, tambahkan paket `@fontsource-variable`-nya ke `site/` dan impor di `FontSpecimen.astro` serta `block-preview.css`. Produk memuat font-nya sendiri.

## 4. Tambahkan produknya ke dokumentasi

- Di halaman [Brand](https://design.sosialoka.tech/id/brand/), satu bagian berisi token brand produknya: `<TokenTable group="brand" theme="lokaticket-light" />`.
- Di beranda, satu baris di daftar produk.
- Di `site/public/AGENTS.md`, id-nya di daftar `data-brand`.

Tulis setiap perubahan dalam bahasa Inggris dan bahasa Indonesia, di bawah `id/`.

## 5. Cek dan commit

Jalankan `pnpm check`. Perintah ini membangun ulang semua yang membaca daftar brand:

- `sosialoka.css` dengan `[data-brand="lokaticket"]` untuk mode terang dan gelap
- tema registry `theme-lokaticket.json` untuk React dan Vue
- nilai enum Flutter `SosialokaBrand.lokaticket` di `tokens.g.dart`
- pemilih brand di situs ini dan daftar tema di server MCP

Commit file tema, `tokens/brands.json`, logo, dan `flutter/lib/src/generated/tokens.g.dart`. Setelah itu produknya memasang tema seperti produk lain:

```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-lokaticket.json
```

```dart
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.lokaticket, Brightness.light));
```

## Tema netral

`neutral` adalah tema grafit: permukaan abu-abu, `primary` hampir hitam di mode terang dan abu-abu terang di mode gelap. Tema ini bukan milik produk mana pun. Pakai untuk:

- pekerjaan vendor atau partner yang dimulai sebelum brand produknya ditetapkan
- tool internal dan prototipe
- layar yang melayani beberapa produk sekaligus

Produk yang sudah punya logo pakai temanya sendiri. Tema netral dipasang dan diganti seperti tema lain:

```html
<html data-brand="neutral" data-theme="dark">
```

```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-neutral.json
```

```dart
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.neutral, Brightness.light));
```
