# Theme

Một theme là ba lựa chọn trong một file seed. Bộ tạo theme suy ra mọi màu, bo góc và vòng focus cho chế độ tối và sáng từ đó, nên bạn không bao giờ phải ghi đè từng token.

## Seed

`npx werewolf-ui init` tạo `tokens/seed.json` với giá trị mặc định bên dưới. Sau đó chỉ lệnh theme thay đổi file này.

| Lựa chọn | Giá trị | Thay đổi gì | Mặc định |
| --- | --- | --- | --- |
| `accent` | Mã hex 3 hoặc 6 ký tự | Các token accent, vòng focus, và sắc độ của màu xám khi độ ám xám lớn hơn 0 | `#111111` |
| `gray-tint` | 0 đến 1 | Mức sắc accent mà nền, chữ, icon và viền trung tính nhận vào | `0` |
| `radius-base` | `sharp`, `default`, `round`, `pill`, hoặc giá trị px | Mọi bo góc | `default` |

```json
{
  "seed": {
    "accent": { "$type": "color", "$value": "#111111" },
    "gray-tint": { "$type": "number", "$value": 0 },
    "radius-base": { "$type": "string", "$value": "default" }
  }
}
```

## Xem thử trên site này

Mở panel Giao diện trên header và chọn accent, độ ám xám và bo góc. Mọi trang docs, kể cả component, cập nhật ngay. Nút Copy lệnh cho bạn lệnh theme tương ứng để chạy trong app.

## Áp dụng vào app

Lệnh theme cập nhật seed và tạo lại `styles/werewolf.css` cùng lúc. Truyền lựa chọn nào cũng được; lựa chọn không truyền giữ nguyên. Cả hai chế độ phải qua mọi kiểm tra tương phản trước khi ghi, nên theme lỗi sẽ không làm hỏng theme hiện tại.

```bash
npx werewolf-ui theme --accent "<hex>"
npx werewolf-ui theme --gray-tint 0.25 --radius-base round
npx werewolf-ui theme --radius-base 6px
```

Nếu bạn đã tự sửa stylesheet được tạo, lệnh sẽ báo xung đột thay vì ghi đè. Xem lại file, rồi truyền đường dẫn của nó vào `--overwrite`.

## Accent hoạt động thế nào

Accent dành cho hành động chính, lựa chọn, link và focus, không dùng để trang trí hay tô nền lớn. Khi accent quá tối hoặc quá sáng để đạt 3:1 trên nền trang ở một chế độ, bộ tạo theme chỉnh nó cho chế độ đó. Màu mặc định `#111111` giữ nguyên ở chế độ sáng và thành gần trắng ở chế độ tối, chữ trên nó được chọn theo độ tương phản. Vì accent tối lúc đó trùng màu chữ chính, link luôn có gạch chân.

## Các mức bo góc

Mỗi mức đặt bốn bậc. Giá trị px `N` cho `N` với element, `N + 4` với container và `N + 8` với page, bậc inner tối đa 6px.

| Mức | `radius-inner` | `radius-element` | `radius-container` | `radius-page` |
| --- | --- | --- | --- | --- |
| `sharp` | 2px | 4px | 6px | 8px |
| `default` | 4px | 8px | 12px | 16px |
| `round` | 6px | 12px | 16px | 20px |
| `pill` | 6px | full | 20px | 28px |

## Chế độ tối và sáng

Mặc định là tối trên `:root`. `data-theme="light"` trên một phần tử chuyển nó và mọi thứ bên trong sang sáng; `data-theme="dark"` chuyển lại. Việc nhớ lựa chọn của người xem do code app của bạn đảm nhận.

## Kích thước cảm ứng

Stylesheet kết thúc bằng một khối `@media (pointer: coarse)` nâng chiều cao control, vùng chạm và cỡ chữ input trên màn hình cảm ứng. Nó theo thiết bị nhập, không theo chiều rộng màn hình, nên iPad dùng trackpad vẫn giữ kích thước chuột. Bạn không cần tự viết media query cho kích thước.

## Xuất token sang nền tảng khác

Xuất token của app đã khởi tạo vào một thư mục bên trong app. Mỗi lần xuất ghi `json/dark.json` và `json/light.json`, cộng file của một nền tảng: `web/` (CSS và theme Tailwind), `ios/` (SwiftUI) hoặc `android/` (Compose). Chạy lệnh một lần cho mỗi nền tảng. File native dùng kích thước cảm ứng và chỉ chứa token; component native dự kiến có ở v2.

```bash
npx werewolf-ui tokens build --out exported-tokens
npx werewolf-ui tokens build --platform ios --out exported-tokens
npx werewolf-ui tokens build --platform android --out exported-tokens
```

## Không dùng CLI

Trong panel Giao diện, Copy CSS hoặc Tải werewolf.css cho bạn stylesheet theo lựa chọn; thay `styles/werewolf.css` bằng file đó. Chỉ cần theme mặc định thì [tải tokens.css](https://www.werewolf-ui.dev/tokens.css). Stylesheet bạn tự thay được tính là chỉnh sửa của bạn, nên lần chạy `theme` sau sẽ cần `--overwrite`.