Skip to main content

Vision-First Palette Generator

The Vision-First Palette Generator (internally "VF Palette") lets a shopper upload inspiration photos and get back an AI-generated color palette matched against the real Shopify color catalog, with a one-click path to shop bridesmaid swatches in those colors.

Do not confuse this with the Party Planner manual color palette picker (ColorPaletteQuestion, the event color palette editor, swatch bundles) β€” see Party Planner. That feature lets a party owner hand-pick colors from the catalog during onboarding; this feature lets anyone generate a palette from photos. They are unrelated flows that happen to feed into the same catalog color data and the same swatch-shopping PLP.


How It Works

What the shopper sees​

The generator is a Builder.io-authored component ("Color Palette Generator") placed on the Swatch Landing Pages (e.g. /pages/swatch-color-palettes). It shows a title, body copy, and an upload control:

  1. The shopper uploads 1–3 inspiration photos (e.g. a wedding mood board, a flower arrangement, a venue photo).
  2. Clicking "Create my palette" sends the photos off for analysis. A loading state is shown.
  3. A modal opens automatically with the generated palette: a short two-word name, a one-sentence description, and a grid of 6–8 color swatches, all selected by default.
  4. The shopper can deselect colors they don't want.
  5. "Shop Matching Swatches" takes them to the bridesmaid color-swatches PLP, pre-filtered to the selected colors, with a tooltip explaining the shop has been filtered to their selections.

The palette can be reopened later via a "View Palette" affordance without re-running the analysis.

Where the colors come from​

The AI (Gemini) only identifies raw perceived colors in the photos β€” it does not know Birdy Grey's catalog. A separate server-side step snaps those raw colors onto the nearest real colors in the live Shopify color catalog, so every swatch shown is always a color the shopper can actually buy. This split is deliberate: the vision model and the catalog-matching logic can be swapped or tuned independently.


Technical Reference

Entry point (Builder.io)​

  • app/builder/registry/ColorPaletteGenerator/wrapper.tsx registers the component (registryName 'Color Palette Generator') for Builder content. It reads csrfToken off the root loader and passes CMS-authored title, bodyText, showNewIcon straight through as props.

UI component​

app/components/ColorPaletteGenerator/colorPaletteGenerator.component.tsx

  • Client-side image upload: up to 3 images, at least 1 required; shows preview thumbnails with remove buttons.
  • Publishes analytics on upload/remove via Hydrogen's useAnalytics(): CustomVisionFirstPaletteAnalyticsEvents.VF_UPLOAD_CTA_CLICK / VF_REMOVE_CTA_CLICK (app/components/GoogleTagManager/enums.ts).
  • handleGenerate on submit:
    1. Downscales each image client-side to ~1024px JPEG (downscaleImage, app/lib/gemini/utils.ts) before upload, to bound payload size.
    2. POSTs a multipart FormData to POST /api/analyzeImageColors, with a CSRF header.
    3. Stores the resulting GeneratedPalette in state; a ref tracks the false→true transition of "generation complete" so the result modal auto-opens exactly once per generation (not on every re-render).
  • Inline error states use shared copy from app/lib/colorPalette/analyzeErrors.ts (ANALYZE_GENERIC_ERROR_MESSAGE, ANALYZE_LOCAL_DECODE_ERROR_MESSAGE).
  • No variant prop exists anymore β€” the single B-style layout is now inlined directly in the component's JSX return (dark-cream background, polaroid placeholder, "New" badge, info tooltip about photo privacy/terms).

Server endpoint​

app/routes/api.analyzeImageColors.tsx (action only):

  1. Validates CSRF token, GEMINI_API_KEY presence, file count (≀3), per-file size (≀3MB), and MIME type (image/jpeg|png|webp|heif).
  2. Hashes the uploaded image set (SHA-256) to build a cache key, and reads/writes through context.withCache at CacheStrategy.slower β€” an identical set of images reuses a cached result and skips calling Gemini again.
  3. Calls Gemini (gemini-2.5-flash-lite) via generateContentWithRetry (app/lib/gemini/helpers.server.ts, shared with the separate virtual try-on feature in try-on.server.ts). The system prompt asks for 8–12 raw perceived hex codes focused on clothing (ignoring backgrounds), plus a two-word name and a one-sentence description.
  4. Maps those raw hexes onto the live Shopify color catalog server-side: matchHexesToCatalog / buildCatalog (app/components/ColorPalette/colorMatch.ts) against getCatalogColors (app/lib/catalog/colors.server.ts), trimming the result to COLORS_PER_PALETTE (6–8) final catalog-matched colors.
  5. Returns GeneratedPalette = { name?, description?, colors: MatchedColor[] }.

Result modal​

app/components/ColorPalette/colorPalette.component.tsx

  • Renders the palette name/description and a selectable swatch grid (all selected by default).
  • Publishes VF_SELECTED_COLOR / VF_DESELECTED_COLOR / VF_PALETTE_GENERATED / VF_SWATCH_PLP_CTA_CLICK (CustomVisionFirstPaletteAnalyticsEvents).
  • "Shop Matching Swatches" navigates to AppRoutes.BRIDESMAID_COLOR_SWATCHES with filter.tags_color_bar=<color name> repeated per selected color, plus utm_source=COLOR_PALETTE β€” the same UTM-driven "pre-filtered" tooltip mechanism used elsewhere on the PLP (see Party Planner event-color shopping links for the equivalent pattern).

Supporting libraries​

FilePurpose
app/lib/gemini/utils.tsClient-side image downscale / readAsDataUrl helpers
app/lib/gemini/helpers.server.tsShared Gemini call/retry/error-response helpers (also used by virtual try-on)
app/lib/colorPalette/analyzeErrors.tsShared error-code enum and user-facing messages
app/components/ColorPalette/colorMatch.tsHex-to-catalog matching logic
app/lib/catalog/colors.server.tsShared color-catalog fetch, also used by Party Planner