Palettes

Filament ships with a set of curated palettes, but you can also build your own from scratch, edit them while a show is running, and share them with other performers as a single file.

The first half of this page is for everyone — no code knowledge required. The last section is a compact reference an AI coding assistant can follow if you ask it to generate a palette for you.

[GRAPHIC: Screenshot of the palette switcher on the Player page with the active palette ringed in white and a hover state revealing the pencil and trash icons]

What a palette is

A Filament palette is just an ordered list of colours. That is all. Filament's animations sample colours out of the current palette as they run, so when you change the palette, every animation that uses it instantly re-tints itself to your chosen colours. Same animation, different mood.

A palette has three things:

• A name — what you call it ("Synth Sunset", "Stage 1 Reds", etc.).
• An id — a short machine-readable handle (synth-sunset, stage-1-reds). You almost never see this; Filament generates it from the name.
• A list of colours — 1 to 256 of them, each written as a hex code like #ff5a2a.

You can have a palette with a single colour (handy for solid washes) all the way up to 256 colours for very smooth gradients. Most palettes have between 3 and 8.

Picking a palette during a show

The palette switcher lives inside the Program card on the Player page — the same card where you pick the animation. Click any palette chip and the preview retints immediately. There is no save step; the new palette is active until you pick a different one.

Each chip shows a small gradient of the palette's colours plus its name. The currently active palette has a bright ring around it. If you have more palettes than fit on one row, the strip scrolls horizontally.

Hover (or focus with the keyboard) on a palette chip to reveal two icons:

• Pencil — opens the editor on that palette.
• Trash — deletes it. Only shows up for palettes you created; built-ins cannot be deleted.

At the end of the strip there is a + New chip — click it to create a brand new palette from scratch.

Built-in palettes

Filament ships with twelve curated palettes:

Built-ins always live at the front of the switcher. You cannot edit or delete them, but you can duplicate any of them into a user palette and tweak the copy.

Creating your own palette

1. In the palette switcher, click the + New chip at the end of the strip.
2. The palette editor opens with a blank palette named New palette and a single starter colour.
3. Give it a name in the top field. The id is generated automatically.
4. Add the colours you want (see Editing the colours below).
5. Click Save. The new palette appears in the switcher immediately.

You can re-open the editor any time by hovering the chip and clicking the pencil icon.

Naming tips

• Keep the name short. The switcher truncates long names to fit the chip.
• Use a name that tells you the mood, not the colours — "Cold open" is more useful in a live setting than "Blue thing".
• Names can be up to 64 characters and contain any normal text. No emoji control characters or weird whitespace, but plain Unicode is fine.

Editing the colours

The editor has three areas: the swatch list, the HSV picker, and a paste-in box for hex codes.

[GRAPHIC: Screenshot of the palette editor showing the swatch list on the left, the HSV spectrum on the right with hue slider, and the paste-hex-list box at the bottom]

The swatch list

This is the ordered list of colours that make up your palette.

• Click a swatch to make it the one you are editing. The HSV picker updates to reflect it.
• Drag the ≡ handle to reorder. Order matters — animations sample left to right.
• Click the × to remove a swatch.
• + Add colour appends a new swatch ready to edit.

If you prefer the keyboard, focus a swatch row and press Alt + ↑ or Alt + ↓ to move it.

The HSV picker

• The rainbow strip picks the hue.
• The big square picks how saturated and bright the colour is — drag toward the top-right for vivid, top-left for white, bottom for black.
• The hex field lets you type or paste an exact hex code.

Changes update the swatch live, but the preview window keeps using the saved palette while you edit — that way you can fiddle with a palette during a show without the lights flickering through your half-built ideas. Hit Save when you are ready to commit.

Save vs Cancel

• Save is disabled until the form has a valid name, at least one valid colour, and an actual change.
• Cancel discards the edit. If you have unsaved changes, the editor asks you to confirm.

Paste-in: building from a hex list

The paste box at the bottom of the editor scans anything you paste for hex codes. All of these formats work:

#ff5a2a #ff9153 #ffc564 #ffe2a8
#ff5a2a, #ff9153, #ffc564, #ffe2a8
ff5a2a-ff9153-ffc564-ffe2a8
["#ff5a2a", "#ff9153", "#ffc564", "#ffe2a8"]

A small toggle next to Apply lets you choose whether the pasted colours append to the existing list or replace it.

This is the fastest way to bring in a palette from another tool — Coolors, Adobe Color, a screenshot you ran through a picker, anything.

Duplicating a built-in

Built-in palettes open in read-only mode. The pencil icon still works, but the editor shows a single [ Duplicate ] button instead of normal edit controls. Clicking it creates a copy of the built-in as a brand new user palette that you can rename and recolour.

This is the way to "edit" a built-in: copy it first, then change the copy. The original stays untouched.

Deleting a user palette

Hover (or focus) a user palette in the switcher and click the trash icon. A small inline confirm appears — there is no big modal, but the action is final.

If the palette you are deleting is the one currently driving the preview, Filament falls back to Rainbow automatically. Nothing goes dark.

Built-in palettes never show a trash icon; they cannot be deleted.

Installing a shared palette

1. Open Filament.
2. Drag the .filament-palette file onto the app window.
3. The palette appears in the switcher, ready to use.

It sticks across app restarts.

What if the id is already taken?

• Collision with a built-in — the import is rejected with a clear message. Ask the author to rename their palette; the id has to be different from every built-in.
• Collision with one of your existing user palettes — Filament asks whether you want to Replace it. Cancel leaves your version alone; replace overwrites it.

What if the file is bad?

Malformed files (corrupt JSON, missing fields, invalid hex codes) produce a toast describing exactly what is wrong. Nothing lands on disk in this case; the bad file is ignored.

Palette files are capped at 64 KiB. Anything larger is rejected before Filament even reads it — a normal palette is well under 10 KiB.

Sharing a palette

Right now there is no in-app Export button — exporting a palette is a one-line manual step. Find the palette's palette.json on disk (locations below), copy it somewhere convenient, and rename the copy so it ends in .filament-palette.

On macOS:

cp ~/Library/Application\ Support/Filament/palettes/user/synth-sunset/palette.json \
   ~/Desktop/synth-sunset.filament-palette

That file is what you share. The recipient drags it onto their Filament window.

Where your palettes live on disk

User palettes are stored one folder per palette, each containing a single palette.json file:

You can hand-edit a palette.json if you really want to — but it is almost always faster to use the in-app editor, because Filament validates the file on every load and silently skips any palette that fails validation. If you do edit by hand, the reference card below has the exact schema.

The built-in palettes are not in the user directory — they ship with the app and load from inside the application bundle.

Designing palettes that look good

A few rules of thumb that hold up well in live performance:

• Three to seven colours is the sweet spot for most animations. Fewer and the gradient feels stepped; more and individual colours start to blur together.
• Avoid pure white and pure black unless you specifically want bright flashes or dead patches. LEDs read those literally — pure white is full power, pure black is off.
• Order matters. Most animations sample the palette in order, so a palette that goes dark → mid → bright reads as a wave, while a palette that hops around reads as a flicker.
• Keep two palettes per "look" — a dense, saturated one for energy peaks and a thinner, desaturated cousin for verses. Switch between them by clicking — the animation does not change, only its mood.
• Test on the actual fixture, not just the preview. LED colour reproduction differs from screen colour, especially in the deep blue and pink end.
• Built-ins are reference points, not prison walls. Duplicate one you like, shift its hues a bit, and you have a palette that is yours but still reads like it belongs in Filament.

Troubleshooting

"Palette xxx is not in your library"

You opened a project that refers to a palette id Filament cannot find. This usually means a palette was deleted, or you opened the project on a different machine. Filament falls back to Rainbow and the show keeps running — pick a different palette manually, or re-import the missing one.

A palette I dragged in did not appear

Check that the file extension is exactly .filament-palette. A .json file with the same contents is intentionally rejected so palettes do not get confused with random JSON dragged in by accident. Rename the file and try again.

"Could not read the palette file"

The file is not valid JSON. Open it in a text editor and verify that all keys and colours are quoted and there are no trailing commas. If you are not comfortable doing that, ask the person who sent you the file to re-export it.

"Palette id contains invalid characters"

Ids have to be kebab-case ASCII (^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$). Lower case, digits, hyphens; must start and end with a letter or digit; 2–64 characters. If you are using the in-app editor this is handled automatically — the message usually means you hand-edited a file.

Reference card for AI agents and frameworks

This section is a compact spec for tools generating palette files programmatically. Everything in it is also covered above in prose form.

File format

• File extension: .filament-palette
• Encoding: UTF-8 JSON, top-level object only (arrays at the root are rejected).
• Max file size: 64 KiB (enforced before parsing).
• No multi-palette .filament-palette-pack format.

Schema

{
  "schemaVersion": 1,
  "id": "synth-sunset",
  "label": "Synth Sunset",
  "colors": ["#ff5a2a", "#ff9153", "#ffc564", "#ffe2a8"]
}

Unknown fields are accepted as inert data for forward compatibility; they do not affect runtime behaviour.

Reserved ids

The twelve built-in ids (rainbow, warm, cool, sunset-haze, forest-floor, ocean-deep, synthwave, monochrome, aurora, ember, candy, noir) are reserved. A .filament-palette whose id collides with any of them is rejected at import.

Validation rules

A file is accepted only if every check passes:

1. File size ≤ 64 KiB before reading.
2. Body parses as JSON.
3. Top-level value is an object (not an array, not a scalar).
4. schemaVersion === 1.
5. id is a string and matches the id regex.
6. label is a string, length 1..64 post-trim, no control characters.
7. colors is an array, length 1..256.
8. Every colors[i] matches ^#[0-9a-fA-F]{6}$.
9. id does not collide with a built-in id.
10. On import only: if id matches an existing user palette, the import requires explicit replace confirmation.

A failure surfaces a structured error naming the offending field and the broken rule.

Filesystem layout

$APPDATA/Filament/palettes/
└── user/
    └── <id>/
        └── palette.json

Per-platform $APPDATA:

Each user palette is one directory. The directory name equals the palette's id. The directory contains exactly one file, palette.json, holding the single palette definition. Extra files in the directory are ignored.

Minimal valid file

{
  "schemaVersion": 1,
  "id": "minimal",
  "label": "Minimal",
  "colors": ["#ffffff"]
}

Save as minimal.filament-palette, drop onto Filament, palette appears in the switcher.

Generation guidance

When generating a palette from a description:

• Choose 3–7 colours unless the brief specifically calls for more.
• Pick an id that is descriptive and unique (kebab-case). Do not reuse a built-in id from the reserved list above.
• Order colours so adjacent samples in the list are visually adjacent. Animations sample by index; large hops produce flicker.
• Avoid pure #000000 and pure #ffffff unless the brief asks for hard black-or-white.
• Keep label short — chip width truncates aggressively.
• Output the file as raw JSON; do not wrap it in Markdown fences or include comments. JSON does not allow comments and the file will be rejected.