# Theming Guide — Tera Beauty SDK

The editor's entire UI palette is exposed as **`beauty_*` color tokens**. There is no theming API
and no builder for colors — you re-theme purely by **resource override**:

> Declare a color with the **same token name** in your app's `res/values/colors.xml`. Android's
> resource merger lets the **app value win** over the library value. Nothing else is required.

This guide lists **all 37 overridable tokens** (the complete set the SDK ships — nothing else is
themeable via colors), grouped by component, plus the rules for rebrand / light / dark.

---

## 1. The fastest path — rebrand (4 tokens)

Most apps only need to change the brand accent. Put this in `app/src/main/res/values/colors.xml`:

```xml
<color name="beauty_primary">#FF4081</color>               <!-- Save button + selected tool -->
<color name="beauty_primary_variant">#FF7AA8</color>
<color name="beauty_accent_gradient_start">#FF4081</color> <!-- selected-state gradient start -->
<color name="beauty_accent_gradient_end">#FF9AC0</color>   <!-- selected-state gradient end -->
```

`beauty_tool_selected` references `beauty_primary` inside the SDK, so the selected-tool tint follows
your primary automatically.

---

## 2. Complete override block — all 37 tokens

Copy this whole block into `app/src/main/res/values/colors.xml` and edit the values you want. Every
token the SDK exposes is here, at its **default** value — anything you leave unchanged keeps the SDK
default, anything you edit wins at merge time. (You never need to declare a token you aren't
changing; this block is just the exhaustive starting point.)

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>

    <!-- ===== Brand (4) ===== -->
    <color name="beauty_primary">#0A68FF</color>
    <color name="beauty_primary_variant">#3B86FF</color>
    <color name="beauty_accent_gradient_start">#1A7DFF</color>
    <color name="beauty_accent_gradient_end">#39A2FF</color>

    <!-- ===== Base (9) ===== -->
    <color name="beauty_bg_screen">#131315</color>
    <color name="beauty_bg_panel">#111111</color>
    <color name="beauty_bg_toolbar">#0F0F10</color>
    <color name="beauty_text_primary">#FFFFFFFF</color>
    <color name="beauty_text_secondary">#A3FFFFFF</color>
    <color name="beauty_icon_tint">#FFFFFFFF</color>
    <color name="beauty_icon_tint_unselected">#D9D8DC</color>
    <color name="beauty_divider">#1FFFFFFF</color>
    <color name="beauty_scrim">#73000000</color>

    <!-- ===== Tool bar (1) — references beauty_primary by default ===== -->
    <color name="beauty_tool_selected">@color/beauty_primary</color>

    <!-- ===== Dialog (3) ===== -->
    <color name="beauty_dialog_bg">#1D1D1D</color>
    <color name="beauty_dialog_danger">#FF453A</color>
    <color name="beauty_dialog_btn_neutral">#1FFFFFFF</color>

    <!-- ===== Confirm bar (1) ===== -->
    <color name="beauty_confirm_bar_bg">#0DFFFFFF</color>

    <!-- ===== Makeup (1) ===== -->
    <color name="beauty_makeup_name_unselected">#E0FFFFFF</color>

    <!-- ===== Slider (5) ===== -->
    <color name="beauty_slider_inactive">#5EFFFFFF</color>
    <color name="beauty_slider_active">#FFFFFFFF</color>
    <color name="beauty_slider_thumb_halo">#4DFFFFFF</color>
    <color name="beauty_slider_pill_bg">#5E000000</color>
    <color name="beauty_slider_pill_text">#FFFFFFFF</color>

    <!-- ===== Compare — over-photo, keep default (1) ===== -->
    <color name="beauty_compare_bg">#5E000000</color>

    <!-- ===== Face bracket — over-photo, keep default (1) ===== -->
    <color name="beauty_face_bracket_selected">#00FF00</color>

    <!-- ===== Crop — over-photo, keep default (4) ===== -->
    <color name="beauty_crop_frame">#CCFFFFFF</color>
    <color name="beauty_crop_grid">#99FFFFFF</color>
    <color name="beauty_crop_corner">#FFFFFFFF</color>
    <color name="beauty_crop_mask">#80000000</color>

    <!-- ===== Body gizmo — over-photo, keep default (7) ===== -->
    <color name="beauty_body_scrim">#6B000000</color>
    <color name="beauty_body_line">#FFFFFFFF</color>
    <color name="beauty_body_connector">#E6FFFFFF</color>
    <color name="beauty_body_connector_shadow">#47000000</color>
    <color name="beauty_body_handle_fill">#CCFFFFFF</color>
    <color name="beauty_body_handle_border">#1F000000</color>
    <color name="beauty_body_label_text">#FFFFFFFF</color>

</resources>
```

**Count by group:** Brand 4 · Base 9 · Tool bar 1 · Dialog 3 · Confirm bar 1 · Makeup 1 · Slider 5 ·
Compare 1 · Face bracket 1 · Crop 4 · Body gizmo 7 = **37 total.**

> The 13 over-photo tokens (Compare 1 + Face bracket 1 + Crop 4 + Body gizmo 7) render on top of the
> user's photo — leave them at defaults unless you have a reason (see §4).

---

## 3. Full token reference

These are the SDK defaults (a dark palette). Override any subset by name.

### Brand
| Token | Default | Role |
|---|---|---|
| `beauty_primary` | `#0A68FF` | Save button, selected tool |
| `beauty_primary_variant` | `#3B86FF` | Lighter brand shade |
| `beauty_accent_gradient_start` | `#1A7DFF` | Selected-state gradient start |
| `beauty_accent_gradient_end` | `#39A2FF` | Selected-state gradient end |

### Base (screen / panels / text / icons)
| Token | Default | Role |
|---|---|---|
| `beauty_bg_screen` | `#131315` | Editor background (also drives the GL canvas clear + status bar) |
| `beauty_bg_panel` | `#111111` | Tool panels / sheets |
| `beauty_bg_toolbar` | `#0F0F10` | Bottom tool bar (drives status-bar icon contrast) |
| `beauty_text_primary` | `#FFFFFFFF` | Primary text |
| `beauty_text_secondary` | `#A3FFFFFF` | Secondary text |
| `beauty_icon_tint` | `#FFFFFFFF` | Selected/active icon tint |
| `beauty_icon_tint_unselected` | `#D9D8DC` | Unselected icon tint |
| `beauty_divider` | `#1FFFFFFF` | Dividers |
| `beauty_scrim` | `#73000000` | Modal scrim |

### Tool bar
| Token | Default | Role |
|---|---|---|
| `beauty_tool_selected` | `@color/beauty_primary` | Selected tool tint (follows `beauty_primary`) |

### Dialog
| Token | Default | Role |
|---|---|---|
| `beauty_dialog_bg` | `#1D1D1D` | Dialog background |
| `beauty_dialog_danger` | `#FF453A` | Destructive action (e.g. Discard) |
| `beauty_dialog_btn_neutral` | `#1FFFFFFF` | Neutral button background |

### Confirm bar
| Token | Default | Role |
|---|---|---|
| `beauty_confirm_bar_bg` | `#0DFFFFFF` | Apply/Cancel bar background |

### Makeup
| Token | Default | Role |
|---|---|---|
| `beauty_makeup_name_unselected` | `#E0FFFFFF` | Unselected makeup style label |

### Slider
| Token | Default | Role |
|---|---|---|
| `beauty_slider_inactive` | `#5EFFFFFF` | Track (inactive) |
| `beauty_slider_active` | `#FFFFFFFF` | Track (active) |
| `beauty_slider_thumb_halo` | `#4DFFFFFF` | Thumb halo |
| `beauty_slider_pill_bg` | `#5E000000` | Value pill background |
| `beauty_slider_pill_text` | `#FFFFFFFF` | Value pill text |

### Compare (over-photo)
| Token | Default | Role |
|---|---|---|
| `beauty_compare_bg` | `#5E000000` | "Before/After" badge background |

### Face bracket (over-photo)
| Token | Default | Role |
|---|---|---|
| `beauty_face_bracket_selected` | `#00FF00` | Selected-face bracket |

### Crop (over-photo)
| Token | Default | Role |
|---|---|---|
| `beauty_crop_frame` | `#CCFFFFFF` | Crop frame |
| `beauty_crop_grid` | `#99FFFFFF` | Rule-of-thirds grid |
| `beauty_crop_corner` | `#FFFFFFFF` | Corner handles |
| `beauty_crop_mask` | `#80000000` | Dimmed outside-crop mask |

### Body gizmo (over-photo)
| Token | Default | Role |
|---|---|---|
| `beauty_body_scrim` | `#6B000000` | Gizmo scrim |
| `beauty_body_line` | `#FFFFFFFF` | Guide line |
| `beauty_body_connector` | `#E6FFFFFF` | Connector |
| `beauty_body_connector_shadow` | `#47000000` | Connector shadow |
| `beauty_body_handle_fill` | `#CCFFFFFF` | Handle fill |
| `beauty_body_handle_border` | `#1F000000` | Handle border |
| `beauty_body_label_text` | `#FFFFFFFF` | Handle label text |

---

## 4. Building a light theme

Override the **Base group** to light values. Text/icon tokens go dark, backgrounds go light:

```xml
<!-- Backgrounds → light -->
<color name="beauty_bg_screen">#FFFFFF</color>
<color name="beauty_bg_panel">#F5F5F5</color>
<color name="beauty_bg_toolbar">#FFFFFF</color>
<!-- Text / icons → dark -->
<color name="beauty_text_primary">#FF1A1A1A</color>
<color name="beauty_text_secondary">#CC1A1A1A</color>
<color name="beauty_icon_tint">#FF1A1A1A</color>
<color name="beauty_icon_tint_unselected">#FF666666</color>
<color name="beauty_divider">#1F000000</color>
```

The GL canvas clear color and status-bar icon contrast follow `beauty_bg_screen` /
`beauty_bg_toolbar` **automatically** — you do not set them separately.

> **Leave the over-photo tokens at their defaults** (Compare, Crop, Face bracket, Body gizmo).
> They render *on top of the user's image*, not on your panels, and the defaults are tuned to stay
> legible on any photo. Overriding them to "match your light theme" usually makes them disappear on
> bright photos.

---

## 5. Light / Dark mode (`ThemeMode`)

The editor **ships both palettes**: light in `res/values/colors.xml`, dark in
`res/values-night/colors.xml` (the SDK default look). **Which one renders is chosen at runtime**, by
`setThemeMode(...)` — *not* by the device, unless you pick `SYSTEM`:

```kotlin
BeautyEditorOptions.Builder()
    .setThemeMode(ThemeMode.DARK)   // DARK (default) | LIGHT | SYSTEM
    .build()
```

| Mode | Palette used |
|---|---|
| `DARK` (default) | `values-night/` — original look; existing integrations unchanged. |
| `LIGHT` | `values/` |
| `SYSTEM` | follows the device's day/night setting |

To recolor a mode, override the `beauty_*` tokens **in the folder for that mode**: `res/values/` for
light, `res/values-night/` for dark. Brand tokens (§2) are the same in both palettes → put them in
**both** files. Base tokens (§3) differ per palette → set them in the folder you're theming.

> **Upgrading a fixed-dark integration:** the dark tokens moved from `values/` to `values-night/`. If
> you previously overrode `beauty_*` in `res/values/colors.xml` to theme the (then dark-only) editor,
> **move those overrides to `res/values-night/colors.xml`** so they still apply under the default
> `ThemeMode.DARK`. Otherwise your dark overrides would only show under `LIGHT`.

---

## 6. Icons

Vector icons (`ic_*.xml`) **bake their color into the drawable**, so they are not covered by color
tokens. To rebrand an icon, override the **drawable by the same name** in your app's
`res/drawable/`. Common names: `ic_edit_face`, `ic_edit_body`, `ic_edit_make_up`,
`ic_edit_retouch`, `ic_edit_crop`, `ic_edit_adjust`.

---

## 7. What is NOT themeable

- **Algorithmic colors** — ML mask colors, per-pixel math, and default makeup **product colors** are
  intentionally fixed (they must be product-accurate); they are not tokenized.
- Anything not listed in §2 / §3.

---

## 8. Checklist

- [ ] Mode chosen via `setThemeMode(...)` (default `DARK`).
- [ ] Brand tokens overridden (`beauty_primary` + variant + 2 gradient stops) in **both** `values/` and `values-night/`.
- [ ] Base group overridden in the folder(s) for the mode(s) you ship; over-photo tokens left at defaults.
- [ ] Migrating from fixed-dark: old `values/` overrides moved to `values-night/`.
- [ ] No accidental drawable name collisions with SDK `ic_*` / `img_make_up_*`.