These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content
CustomizationCustom colors

Custom colors

When a curated theme is close-but-not-quite, override individual color tokens. The live WCAG checker keeps you honest — every change is contrast-audited against the visitor experience.

For the curated themes themselves, see Themes. For the broader customization context, see the Customization guide.

When to use Custom colors

Reach for Custom colors when:

  • A specific brand color is non-negotiable (your CTA button has to be exactly your hex)
  • You’ve picked a theme that’s 90% right and one or two tokens are wrong
  • You want to test an alternative color treatment quickly without committing

Skip Custom colors when:

  • You’re tempted to override more than ~5 tokens (start from a different theme instead)
  • You’re guessing at colors (try the curated themes first; they cover most use cases)
  • You’re not sure which token controls what (read the token list below first)

How to open Custom colors

In the Finder Builder, on the Theme & colors page:

  1. Look at the Theme summary card at the top
  2. Click Customize (next to Change theme)
  3. The Custom colors panel expands below

🟡 [SCREENSHOT: Theme summary card with the “Customize” button highlighted, and the Custom colors panel expanded below showing several color tokens with overridden values.]

What you can override

Custom colors lets you set values for every token a theme defines. Tokens are grouped by visual area:

Surfaces

  • Body background — the widget’s outermost container
  • Panel background — list panel and detail panel
  • Card background — individual location cards in the list

Text

  • Primary text — location titles, primary labels
  • Secondary text — addresses, metadata
  • Muted text — placeholders, low-emphasis hints

Buttons

  • Primary button background — search button and primary CTAs
  • Primary button text — text on the primary button
  • Secondary button background — secondary actions
  • Secondary button text — text on secondary buttons

Inputs

  • Input background
  • Input border
  • Input text
  • Placeholder text

Filters & tags

  • Filter chip background (default state)
  • Filter chip background (active state)
  • Tag pill background
  • Tag pill text

Map

  • Marker fill
  • Marker stroke
  • Cluster background (when many markers cluster at low zoom)

Misc

  • Border — generic divider color
  • Focus ring — keyboard focus indicator

🔴 [NEEDS CLARIFICATION: Confirm the exact final list of overridable tokens against the current appearanceThemes.ts token map. The list above reflects the standard set surfaced in the digest; the production UI may expose a subset or additional tokens.]

How to change a color

Click any token’s swatch to open the color picker. The picker offers:

  • Hex input — type or paste any 6-digit hex code
  • Eyedropper — pick a color from anywhere on your screen (browser support varies)
  • Recent / suggested swatches — quick re-pick of recently used colors

🟡 [SCREENSHOT: Color picker open over a token’s swatch, showing the hex input populated with a brand color and the contrast preview underneath.]

Changes apply to the Live Preview immediately. To revert a single token to its theme default, click the Reset icon next to that token. To reset everything back to the active theme, use Reset all at the bottom of the panel.

The live WCAG checker

The moment you change a color, the WCAG status pill next to the Theme summary updates:

  • 🟢 Passes WCAG 2.1 AA — every audited color pair meets contrast threshold
  • 🟡 N pairs below AA — review — at least one pair is below threshold

Click the pill to open the Contrast report drawer.

🟡 [SCREENSHOT: Theme summary header showing the WCAG status pill in amber state, with “3 pairs below AA — review” text and a click affordance.]

What the report drawer shows

For every color pair the widget renders (button text on button background, body text on body background, etc.), the drawer lists:

  • The two colors in question (with mini swatches)
  • The current contrast ratio (e.g., 3.2:1)
  • The WCAG threshold for that pair (4.5:1 for body text, 3:1 for large text and UI)
  • A Reset to preset action that restores just that pair (one or both tokens) back to the active theme’s defaults

🟡 [SCREENSHOT: Contrast report drawer open, listing three failing pairs grouped by audit area (search button, location card, filter chip). Each row shows the two swatches, the ratio, the target, and the Reset action.]

What gets audited

Every meaningful pair in the visitor-facing widget. This includes:

  • All text colors against their immediate background
  • Button text against button background, in default and hover states
  • Focus ring against the surrounding container
  • Filter chip text against active and inactive backgrounds
  • Tag pill text against tag pill background
  • Marker fill against typical map tile color (this audit uses a representative tile color, not your specific provider’s exact tiles)

Pairs that aren’t visually adjacent (e.g., body text vs. tag background, when they never sit next to each other) are not audited.

Working with brand colors

A common workflow: your brand’s CTA color is a saturated red. The default theme’s button-on-button-background passes WCAG; once you swap the button background to your red, the default white-on-red text might or might not pass depending on the exact red.

The right move:

  1. Override the button background to your brand red
  2. Watch the status pill — if it goes amber, open the report
  3. The report tells you whether to lighten/darken the red, or whether to flip the button text from white to a darker color
  4. Apply the suggested fix or pick a slightly different shade of red

This is iterative; expect 2–3 small adjustments to land at a brand-faithful, accessible result.

💡 Tip: If you can’t make a brand color work without breaking contrast, the brand color is probably the wrong tool for that token. Use it as an accent (focus ring, marker fill) rather than a surface (button background, panel background) and the contrast problems usually disappear.

Edge cases and limitations

  • Themes win when you switch. Switching to a different curated theme keeps your custom overrides — they don’t reset automatically. Use “Reset all” first if you want a clean theme.
  • Map provider tiles aren’t customizable. The map’s tile colors come from the provider, not your theme. A near-white widget on a dark satellite map will look strange.
  • Per-state colors are limited. Hover and active states for buttons derive from the base color via fixed rules; you can’t independently set them.
  • Per-finder, not per-workspace. Custom colors apply to one Finder. To reuse the same palette, duplicate the finder or set the same colors manually.

🔴 [NEEDS CLARIFICATION: Is there a “save as theme” / “share palette” feature? Useful for agencies maintaining many similar finders.]

Where to next

Authorized URLsLanguage & copy