---
id: AGD-0002
ticket: palette-management-in-studio
title: Palette Management in Studio
status: open
created: 2026-03-26
resolved:
decision:
tags:
  - studio
  - legacy-import
  - palette-management
  - tile-bank
  - packer-boundary
---

## Pain

Studio already has a retained agenda for palette management in the `tile bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.

Without importing it into `discussion/`, the canonical discussion surface would lose the still-open Studio question about:

- how candidate palettes are presented;
- how `1..64` palette capacity is enforced and explained;
- how preview and selection behave inside the asset workflow;
- how Studio UX stays separate from packer-owned extraction, validation, identity, and persistence.

## Context

Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md`

Domain owner: `docs/studio`
Cross-domain impact: `docs/packer`

The retained agenda is intentionally scoped to `tile bank`.

The imported context keeps the same baseline:

- every `*.png` input of a tile bank is one tile;
- each tile yields one extracted palette during cache construction;
- developers may also work with favorite palettes and asset palettes;
- each bank may integrate at most `64` palettes;
- each palette contains `16` colors with a default color-key baseline;
- Studio owns curation UX, while packer remains authoritative for extraction, identity, validation, and persistence.

The current UI shape already converged on:

- a left-side transfer list for candidate and selected palettes;
- custom palette rendering with swatches and source indicators;
- a right-side preview panel with tile/file selector, tile preview, and applied palette strip.

## Open Questions

- [ ] How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources?
- [ ] Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission?
- [ ] What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination?
- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
- [ ] Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives?
- [ ] Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management?

## Options

### Option A - Automatic Integration
- **Approach:** Treat extracted tile palettes as implicit inputs and integrate them automatically without explicit user curation.
- **Pro:** Lowest immediate UX cost.
- **Con:** Hides palette-budget reasoning, weakens deliberate composition, and makes source distinctions harder to understand.
- **Maintainability:** Weak. It pushes important bank rules into implicit behavior.

### Option B - Asset-Scoped Curated Selection
- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence.
- **Pro:** Matches the concrete `tile bank` workflow and keeps authority boundaries clear.
- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics.
- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them.

### Option C - Studio-Owned Palette Library
- **Approach:** Treat palettes as a broader Studio-owned library/workspace with direct local editing and persistence behavior.
- **Pro:** Potentially flexible for future palette-heavy features.
- **Con:** Duplicates packer ownership and risks creating a second authority for bank composition.
- **Maintainability:** Weak. It expands Studio responsibility before the persistence contract is closed.

## Discussion

The imported agenda keeps the original recommendation intact: palette management should be first-class for `tile bank`, but Studio must not become the persistence authority.

That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely:

- candidate aggregation from multiple sources;
- clear source and identity display;
- explicit `1..64` capacity feedback;
- a preview model that stays tied to the selected bank palettes;
- a boundary between `tile bank`-specific UX and reusable Studio primitives.

The retained source already converged on a pragmatic first wave:

- transfer-list selection on the left;
- palette-focused preview on the right;
- first selected palette as default preview;
- clicking on a selected palette changes the previewed palette;
- removing the current preview palette falls back to the first remaining selected palette.

## Resolution

Recommended direction: adopt **Option B**.

The imported agenda preserves the retained Studio direction:

1. palette management belongs to the `tile bank` asset workflow;
2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes;
3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range;
4. the right-side preview panel stays tied to the current selected palette set;
5. packer remains authoritative for extraction, identity, validation, and persistence;
6. broader standalone palette-authoring workflows remain deferred.

Next step suggestion: convert this imported agenda into a decision that closes the ownership boundary, candidate-source model, first-wave transfer-list UX, preview behavior, and reusable-vs-family-specific primitive boundary.
