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

How to — add a theme preset

Curated theme presets live in dropafinder-app-nextjs/src/components/finders/v2/appearanceThemes.ts. Adding one is a frontend-only change — no backend or widget deploy required.

Step 1 — Understand the preset structure

Each preset is created by createThemePreset(), which calls buildThemePreset(overrides) from finderBuilderConfig.ts. buildThemePreset starts with the default “Signal” color system and applies the overrides you provide.

The createThemePreset() signature:

createThemePreset(
  key: string,                    // unique slug, lowercase-kebab
  label: string,                  // displayed in the theme picker
  description: string,            // short label shown below the preset name
  personality: string,            // one-line brand personality descriptor
  category: AppearanceThemeCategory,  // 'Light' | 'Bold' | 'Dark' | 'Warm'
  dot: string,                    // hex color for the swatch dot
  overrides: Partial<ColorSystem> // any color keys that differ from Signal defaults
)

The overrides object accepts any subset of the color keys defined in buildThemePreset(). Keys not included in overrides fall through to the Signal defaults.

Step 2 — Choose the color key set

The full set of color keys (from buildThemePreset in finderBuilderConfig.ts):

background, borderColor,
buttonSearchBackground, buttonSearchBackgroundHover, buttonSearchText,
buttonRefinementsBackground, buttonRefinementsBackgroundHover, buttonRefinementsText,
buttonRefinementsApplyBackground, buttonRefinementsApplyBackgroundHover, buttonRefinementsApplyText,
buttonRefinementsCloseBackground, buttonRefinementsCloseBackgroundHover, buttonRefinementsCloseText,
buttonDirectionsBackground, buttonDirectionsBackgroundHover, buttonDirectionsText,
locationBackground, locationBackgroundHover,
locationTextHeading, locationTextAddress, locationTextFields, locationTextDistance,
tagBackground, tagText,
markerColor,
inputBackground, inputText, inputPlaceholder

You don’t need to override every key — only the ones that differ from the Signal base. For a new light theme, typically override: background, borderColor, buttonSearch*, buttonRefinements*, buttonDirections*, locationBackgroundHover, locationTextDistance, tagBackground, tagText, markerColor.

Step 3 — Add the preset to APPEARANCE_THEME_PRESETS

Open dropafinder-app-nextjs/src/components/finders/v2/appearanceThemes.ts and scroll to APPEARANCE_THEME_PRESETS (line 421). Add a new createThemePreset() call at the end of the array (or within the appropriate category group if the array is ordered by category):

export const APPEARANCE_THEME_PRESETS: AppearanceThemePreset[] = [
  // ...existing presets...
 
  createThemePreset(
    'verdant',
    'Verdant',
    'Forest green and sage system',
    'Grounded and organic, suited to nature and outdoor brands.',
    'Light',            // AppearanceThemeCategory
    '#2D6A4F',          // dot hex — use the dominant accent color
    {
      background: '#F2F7F4',
      buttonSearchBackground: '#2D6A4F',
      buttonSearchBackgroundHover: '#235940',
      buttonRefinementsBackground: '#E4F0EA',
      buttonRefinementsBackgroundHover: '#D2E8DA',
      buttonRefinementsText: '#1E5A40',
      buttonRefinementsApplyBackground: '#2D6A4F',
      buttonRefinementsApplyBackgroundHover: '#235940',
      buttonDirectionsBackground: '#2D6A4F',
      buttonDirectionsBackgroundHover: '#235940',
      locationBackgroundHover: '#EAF5EE',
      locationTextDistance: '#2D6A4F',
      tagBackground: '#D3EBD9',
      tagText: '#1E5A40',
      borderColor: '#C3DECA',
      markerColor: '#2D6A4F',
    }
  ),
];

Step 4 — Check the category

AppearanceThemeCategory is 'Light' | 'Bold' | 'Dark' | 'Warm'. The theme picker groups presets by category, so pick the one that fits:

CategoryCharacter
LightWhite/light-grey backgrounds, pastel accents
BoldHigh-contrast, saturated primary colors
DarkDark background, light text
WarmAmber/rust/cream color family

Step 5 — Verify accessibility

The getThemeAccessibilitySummary() and getContrastReport() helpers in appearanceThemes.ts calculate WCAG contrast ratios for the audited color pairs (listing text on listing card, search button text on button background, etc.).

Manually verify the critical pairs before shipping:

  1. Search button text on search button background → minimum ratio 4.5:1 (AA)
  2. Listing heading text on listing card → 4.5:1 (AA)
  3. Listing address text on listing card → 4.5:1 (AA)
  4. Tag text on tag background → 4.5:1 (AA)

Use any online contrast checker (e.g., WebAIM Contrast Checker ) to verify each pair. All audited pairs must pass AA. AAA is preferred for body text.

⚠️ Warning: Shipping a preset that fails WCAG AA on its primary text pairs creates an accessibility regression for every customer who applies it. Verify before merging.

Step 6 — Visual QA in the builder

  1. Start the dashboard locally (npm run dev in dropafinder-app-nextjs).
  2. Open a Finder, go to the Finder Builder, and navigate to the Theme section.
  3. Find your new preset in the picker. The dot color should render as the swatch.
  4. Apply the preset. Confirm the Live Preview rail reflects all color changes.
  5. Confirm the builder’s color editor shows the overridden values correctly.

Step 7 — Deploy

A theme preset change is dashboard-only — no backend or widget changes needed:

cd "/Users/codydavis/Local Sites/dropafinder-app-nextjs"
git push origin main

Vercel auto-deploys. Verify the new preset appears in the theme picker in production.

Where to next

Concepts