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:
- The shopper uploads 1β3 inspiration photos (e.g. a wedding mood board, a flower arrangement, a venue photo).
- Clicking "Create my palette" sends the photos off for analysis. A loading state is shown.
- 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.
- The shopper can deselect colors they don't want.
- "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.tsxregisters the component (registryName'Color Palette Generator') for Builder content. It readscsrfTokenoff the root loader and passes CMS-authoredtitle,bodyText,showNewIconstraight 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). handleGenerateon submit:- Downscales each image client-side to ~1024px JPEG (
downscaleImage,app/lib/gemini/utils.ts) before upload, to bound payload size. - POSTs a multipart
FormDatatoPOST /api/analyzeImageColors, with a CSRF header. - Stores the resulting
GeneratedPalettein 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).
- Downscales each image client-side to ~1024px JPEG (
- Inline error states use shared copy from
app/lib/colorPalette/analyzeErrors.ts(ANALYZE_GENERIC_ERROR_MESSAGE,ANALYZE_LOCAL_DECODE_ERROR_MESSAGE). - No
variantprop 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):
- Validates CSRF token,
GEMINI_API_KEYpresence, file count (β€3), per-file size (β€3MB), and MIME type (image/jpeg|png|webp|heif). - Hashes the uploaded image set (SHA-256) to build a cache key, and reads/writes through
context.withCacheatCacheStrategy.slowerβ an identical set of images reuses a cached result and skips calling Gemini again. - Calls Gemini (
gemini-2.5-flash-lite) viagenerateContentWithRetry(app/lib/gemini/helpers.server.ts, shared with the separate virtual try-on feature intry-on.server.ts). The system prompt asks for 8β12 raw perceived hex codes focused on clothing (ignoring backgrounds), plus a two-wordnameand a one-sentencedescription. - Maps those raw hexes onto the live Shopify color catalog server-side:
matchHexesToCatalog/buildCatalog(app/components/ColorPalette/colorMatch.ts) againstgetCatalogColors(app/lib/catalog/colors.server.ts), trimming the result toCOLORS_PER_PALETTE(6β8) final catalog-matched colors. - 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_SWATCHESwithfilter.tags_color_bar=<color name>repeated per selected color, plusutm_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β
| File | Purpose |
|---|---|
app/lib/gemini/utils.ts | Client-side image downscale / readAsDataUrl helpers |
app/lib/gemini/helpers.server.ts | Shared Gemini call/retry/error-response helpers (also used by virtual try-on) |
app/lib/colorPalette/analyzeErrors.ts | Shared error-code enum and user-facing messages |
app/components/ColorPalette/colorMatch.ts | Hex-to-catalog matching logic |
app/lib/catalog/colors.server.ts | Shared color-catalog fetch, also used by Party Planner |