---
name: theme-select
description: Rank or combine complete visual themes from a project brief while exposing fit scores, source choices, and style conflicts.
---

# Theme selection

Use when choosing a whole visual direction or combining theme traits. Do not use for palette math alone (`color`) or for tokens alone (`design-tokens`).

## Procedure

1. Read the project brief. Run `scripts/theme_pick.py` to rank three themes with a scoring breakdown and reasons.
2. If the user is choosing, present three to five options with name, one-line mood, and a short palette description; use the decision protocol. If deciding, record the selected theme and rationale as an agent decision.
3. For a blend, select structure from A, color from B, and effects from C. Run `scripts/theme_blend.py`; review warnings and unresolved conflicts before accepting the result.
4. Validate the chosen theme against `schemas/theme.schema.json`, then pass its seed, harmony, and neutral tint to `color` and `design-tokens`.

## Inputs and outputs

- Inputs: validated `brief.json` and complete theme JSON files.
- Outputs: a deterministic top-three ranking or schema-validated merged theme with color contrast audit.
- Scripts read and write local files only; existing output paths require `--force` before replacement.

## Reference routing

| Need | Load |
|---|---|
| Score interpretation and tie-breaking | [picker scoring](references/scoring.md) |
| Known conflicts and blend resolution | [blend rules](references/blend-rules.md) |

## CLI

```bash
python skills/theme-select/scripts/theme_pick.py .narmaforge/project/brief.json
python skills/theme-select/scripts/theme_blend.py --a A.json --b B.json --c C.json --output merged-theme.json
```