# Palette guidelines

A palette is a named triple of three colour tokens (`--c-bg`, `--c-mid`, `--c-acc`) that the patterns and heroes galleries paint with. This document is the rule sheet for adding a new one.

## The contract

Every palette has:

| Field | Type | What it is |
|---|---|---|
| `id` | kebab-case slug | Stable identifier. Used in the URL hash, the GitHub issue title for voting, and as a CSS data attribute. Examples: `brand`, `drive-sales`, `acquire-users`. |
| `name` | short title-case string | Human-readable name shown on the gallery card. Examples: `Buzzvil brand`, `Drive Sales`, `Acquire Users`. |
| `type` | one of `brand-anchor`, `customer-experiment`, `pillar` | Tells the gallery how to badge the card. See **Types** below. |
| `use` | string | Where the palette is intended to be used. Either a route (`/solutions/drive-sales`) or a surface description (`Landing, How We Work, brand-anchor surfaces`). |
| `bg` `mid` `acc` | hex strings | The three colour tokens. `bg` is the largest area / lowest visual energy; `mid` carries the bulk shapes; `acc` is the smallest / brightest hit. Same role split as the pattern contract. |
| `sources` | sentence | Where the colours came from. For customer experiments: the partner brands. For brand-anchor: the design library tokens. For pillars: the single-anchor hue concept. |

## Types

### `brand-anchor`

Buzzvil's own brand palette, used on surfaces where the page is "Buzzvil itself" rather than a specific solution. Examples: the landing hero, the how-we-work culture page, the monetize surface (which is publisher-anchored to Buzzvil's red).

The brand palette is **not fully locked yet**. It follows the chameleon logic in [design.buzzvil.com](https://design.buzzvil.com)'s brand guidelines — Buzzvil adapts its hue to context while keeping the same structural rhythm. When in doubt, check there. When still in doubt, ask Max.

### `customer-experiment`

The current hypothesis being tested on every Solution surface: pull the palette from the **major key partner brand colours** in that solution. A CMO landing on Drive Sales sees Naver green, Olive Young olive, Musinsa black answering them in the visual language they already trust. The pattern composition stays the same; only the tokens swap.

**This is a hypothesis, not a decision.** The whole point of letting the canvas swap palettes quickly is so we can compare side by side and pick a direction with evidence rather than taste.

When proposing a customer-experiment palette:
- Source from the **top 3 partner brands** in that solution
- Order: pick one to be `bg` (lowest visual energy in the trio), one to be `mid` (bulk), one to be `acc` (smallest, brightest)
- Document the partners in `sources`

### `pillar`

A single-anchor hue carried across a How-It-Works pillar surface. Reach gets a deep-blue family, Interaction gets amber, Reward gets green. The three tokens are tonal variants of the same hue (deep / mid / light), not three separate hues.

## How to add a palette

1. Fork or branch this repo.
2. Copy [`palettes/_template.html`](./_template.html) to understand the shape of a palette entry.
3. Edit [`palettes/palettes.js`](./palettes.js) and add a new object to the `PALETTES` array, fitting the contract above.
4. Open a PR. The Pages workflow deploys a preview so you (and the reviewer) can see the palette in the gallery before merge. The new palette automatically becomes available in the patterns and heroes palette switchers.

Reviewer (Max) merges if the palette reads cleanly on the comp-squares preview, fits the chameleon rule for its declared type, and isn't a near-duplicate of an existing palette.

## Naming

- **id** is kebab-case, all lowercase, no spaces.
- **name** is title-case, human-readable. Match the route name if there is one (`Drive Sales`, not `drive-sales`).
- For customer-experiment palettes named after a solution, the id is the solution slug (e.g. `drive-sales`). For pillar palettes, the id is the pillar slug (e.g. `reach`).
- Avoid colour-descriptive ids (`warm-orange`, `dark-blue`). The id should describe the **role**, not the colour. The colour can change later if we re-pick partners; the role doesn't.

## What we're looking for

Good additions:
- New partner-combination experiments on existing solution surfaces (e.g. swap one partner for a different anchor brand and compare)
- Pillar palettes for surfaces that don't have one yet
- Seasonal or campaign palettes for time-bound surfaces (the trio should still source from a real concept, not "things I think look nice")

Avoid:
- Anything that lifts colours from non-partner sources without a documented use-case (`sources` should be a sentence, not a guess)
- Near-duplicates of existing palettes (a 5% hue shift on Drive Sales isn't a new palette, it's a tweak — PR the existing entry)
- Palettes that fail the identity test on `comp-squares` (if the largest shape disappears against the background, the `bg`/`mid` split is wrong)

## The PR

When you open a PR, the template will pre-fill a checklist. Before merging, the palette lives on a deploy preview. Reviewer walks it across the three pages (palettes / patterns / heroes), gives notes if any, or merges. Once merged, the palette is in the switcher on every page.