# Materials MVP — Product overview

**Version:** 0.1

A materials and design catalogue that turns **colour-led discovery** into **qualified enquiries** for suppliers and designers.

Buyers browse anonymously. Suppliers and designers manage catalogue and leads in a shared admin panel. Ranking is driven by **colour science** (CIELAB / CIEDE2000), not by an LLM guessing “similar products.” Matches are **explainable** (signature glance, pins, honest %), and photo-match uploads are **ephemeral** — images are not stored.

---

## Why it matters (USP)

**Now**

- **Match by colour, not keywords.** Upload a site or mood photo (or open a material) and get scientifically ranked finishes — similar, complementary, analogous, and product lanes.
- **Explainable, honest scores.** Match % reflects real colour distance; a signature glance and key-colour pins make ranking inspectable. Featured placement can change *order*, not inflate the number.
- **From inspiration to lead.** Shortlist materials and design looks (including AI finish previews), share deeplinks with clients, then submit one structured enquiry with a durable snapshot.
- **Two-sided platform.** Suppliers self-serve their materials and collections; designers curate looks; both get role-scoped leads from the same funnel.
- **Monetization-ready attention.** Featured boost already reshapes discovery; analytics and CPV/CPC/CPL are a natural upgrade path.
- **Privacy-minded matching.** Photo-match images are processed ephemerally for trust with trade and consumer buyers alike.

**Planned**

- **Vibe search & match.** Full material semantics unlock style-language discovery (“Japandi — clean but fun, with some pop”), blended with colour ranking / photo match.
- **Shareable mood boards.** Synced shortlists → named boards with **PDF / share packages** for clients and project teams (beyond today’s single look / AI-preview deeplinks).

**One-line:** Colour discovery → confident shortlist → structured lead → monetizable attention.

### Not just another…

| Alternative | Gap | Materials MVP |
|-------------|-----|----------------|
| Mood boards / Pinterest | Inspiration without trade leads or SKU truth | Colour-ranked catalogue → enquiry with snapshot |
| Keyword / faceted search alone | Misses “what pairs with this wall” | Lab / CIEDE2000 similarity + harmony lanes |
| Generic “AI interior” apps | Black-box looks, weak supplier routing | Deterministic colour engine + AI beside it (preview, semantics, planned vibe search & match) |

---

## Who uses it

| Role | What they do |
|------|----------------|
| **Buyer** (architect, designer, fit-out, homeowner) | Browse, photo-match, shortlist, share looks, enquire — no account required |
| **Supplier** | Self-serve own profile, materials, and collections; see enquiries that include their products |
| **Designer** | Curate looks and finishes; see enquiries on their designs |
| **Admin** | Full catalogue, colour tools, photo-match analytics, AI settings |

A future **client** (logged-in buyer) role is seeded but not exposed yet.

---

## How people use it

- **On site (trade):** Architect photographs a wall or joinery → photo match → shortlist finishes → enquire for quote — before leaving the meeting.
- **At home (consumer):** Homeowner explores a Japandi-leaning look → swaps finishes → AI preview → shares the link → enquires when ready (vibe search & match planned to meet them earlier in that journey).
- **Supplier launch:** Brand features a new SKU → lane and catalogue boost lift visibility → colour-demand analytics show what buyers are matching → path to paid CPV/CPC later.

---

## Buyer journey

```mermaid
flowchart LR
  browse[Browse_filter_photoMatch]
  shortlist[Shortlist]
  customize[Customize_AI_preview]
  enquire[Submit_enquiry]
  inbox[Supplier_designer_inbox]
  browse --> shortlist --> customize --> enquire --> inbox
```

1. **Catalogue** — search and filter (category, finish, application, colour family, supplier); **grid or mosaic** merchandising; featured / newest sorts. Trade buyers can open **collections** (series with inherited characteristics), not only single SKUs.
2. **Photo match** — upload a mood or site photo; multi-lane colour rank; key-colour pins; inspectable signature glance. Uploads are not retained.
3. **Material detail** — specs, palette, supplier + **collection** context, suggested **lanes** of related finishes.
4. **Designs** — curated looks; colour-suggested alternatives; region swaps; optional **AI finish preview**; **shareable deeplinks** for finish groups and AI looks (sales-assist / client review).
5. **Shortlist → enquire** — review selections; contact fields; **intent is inferred automatically** (quote, sample when enabled, design as-shown, design with swaps, or general contact) — no confusing intent dropdown. Buyer gets a reference id.

**Today’s limits (honest):** shortlist is device-local (no login sync); suppliers are not emailed on submit (they check the admin inbox); sample-request UI is built but off by default; no cart or PDF mood boards yet.

### Try it on a running instance

1. `/` — filters, mosaic layout, **Photo match**  
2. Open a material — lanes + collection/supplier links  
3. `/designs` — customize, AI preview, copy a share link  
4. `/enquiry` — review shortlist and submit  

Hub and this overview: `/docs` · `/docs/0.1`

---

## Discovery engine

Discovery is a **deterministic colour pipeline**, not generative search. Images become perceptual colour models; candidates are scored with published colour-difference maths; results are organised into **lanes**. Generative AI is not in this loop.

```mermaid
flowchart LR
  img[Image]
  extract[Extract_CIELAB_signature]
  harm[Derive_harmony_targets]
  fam[Assign_colour_families]
  score[Score_similarity_and_fitness]
  lanes[Lane_results]
  img --> extract --> harm
  extract --> fam
  extract --> score
  harm --> score
  score --> lanes
```

### Why Lab and CIEDE2000

RGB/hex are poor proxies for “how different do these look.” The pipeline uses **CIELAB**, then **CIEDE2000** (ΔE₀₀) — the industry-standard perceptual difference. Finishes that look close in a room still rank close; vivid accents are not treated like large quiet neutrals.

### Colour signature

Each published material (and design cover) gets a stored **signature**: weighted Lab palette (coverage matters), contrast / texture cues, and optional nominal brand colour merged without wiping photographic truth. Design covers use the same model so looks drive suggestions like materials do.

### Similarity, harmony, families

- **Similarity** — palette-aware ΔE → absolute **match %** (calibrated; not forced to look like 98% on card one). Photo match can weight **salience** so small vivid accents punch above quiet walls. Lane label: **Similar colours** — finishes closest to the overall mix (or a focused hue chip).
- **Harmony** — from up to two chromatic hue anchors in the signature, the engine derives **colour-wheel targets**, then ranks catalogue candidates on **fitness** to that relationship (hue / lightness / saturation / neutrality blend) — not “more of the same.”
- **Families** — nearest of a fixed Lab family set for simple filter chips.

#### Colour-theory / harmony lanes

These are the pairing intents buyers see as Match-type tabs (wording matches the product UI):

| Lane | Intent |
|------|--------|
| **Similar colours** | Closest to this overall colour mix (ΔE similarity; optional per-hue focus) |
| **Complementary** | Opposite on the wheel — bold, punchy pairing |
| **Analogous** | Neighbouring hues — soft, cohesive feel |
| **Triadic** | Three evenly spaced accents — lively, balanced scheme |
| **Split complementary** | Near-opposite accents — contrast with a little less clash |
| **Neutrals** (`neutral_pair` on materials) | Calm, quiet partners for a colourful anchor |

**Photo match** adds two live-only tabs on top of the same idea:

| Lane | Intent |
|------|--------|
| **Neutral** | Quiet greiges / soft neutrals that ground the uploaded scene (grounding lane, not a wheel target) |
| **Tetradic (square)** | Four evenly spaced colours — rich, structured palette |

Pinning one or two **key colours** in photo match rebuilds harmony targets from those anchors without re-uploading.

#### Product / surface lanes (material PDP)

Same Match-type chrome, different job — surface and assortment relationships:

| Lane | Intent |
|------|--------|
| **Tonal match** | Same lightness band; hue can wander a little |
| **Colour pop** | Bolder / brighter accents to lift a quieter surface |
| **Texture twin** | Similar grain and touch; colour can differ |
| **Same collection** | More finishes from this collection |
| **Contrast pair** | Clearly lighter or darker partners |

(Directional lighter/darker variants exist in the computed blob for internal use; public tabs focus on the rows above.)

### Photo match and lanes

**Photo match (live):** ephemeral upload → extract → **Similar** + harmony tabs (Complementary, Analogous, Neutral, Triadic, Split complementary, Tetradic) → pins + signature glance + palette-focus chips on Similar.

**Material PDP:** precomputed colour-theory tabs (Similar through Neutrals) **plus** product/surface tabs (Tonal match through Contrast pair). Strict criteria first; a softer second pass can fill thin lanes (muted “closest in this type”).

**Design show:** colour / harmony suggestions from the cover signature (live scorer; same Match-type idea as photo match — not the full product-lane set).

| Signal | Role |
|--------|------|
| **Absolute %** | Honest fitness across the library |
| **Relative strength bar** | Hierarchy *within* the current lane |

**Featured** is a read-time layer: diverse, visually interesting picks; up to **two** featured candidates already in a lane’s pool may be prepended — visibility without rewriting science (wedge for paid boost / CPV / CPC).

| Surface | Behaviour |
|---------|-----------|
| Catalogue | Families, taxonomy, mosaic / featured merchandising |
| Photo match | Live multi-lane rank + pins + glance (no image retention) |
| Material PDP | Precomputed lanes; collection context |
| Design show | Cover-signature suggestions + shareable AI / group links |
| Admin / supplier | Extract, lanes, analytics; suppliers edit own catalogue |

---

## AI layer

Colour ranking stays deterministic. AI sits **beside** that engine: meaning, finish visualisation, and — next — **vibe search & match**.

### Today

**1. Design photo semantics (ops)** — vision reads a cover → regions, brief cues, style hints, material candidates. Speeds curation; does not replace Lab signatures.

**2. Finish preview (buyer)** — image-edit applies shortlisted finishes on a look; async generate, poll, **shareable link**; shortlist into enquiry. “See it on the scene,” not catalogue rank.

**3. Provider registry** — OpenAI / Gemini configurable so models can change without rewriting flows.

### Planned — material semantics and vibe search & match

Extend semantic enrichment from designs to **materials** (style, mood, materiality, room fit, trend labels) beside the Lab signature. That unlocks **vibe search & match**:

> “Japandi — clean but fun, with some pop.”

| Layer | Role |
|-------|------|
| **Colour science** | Exact / harmony match from photo or swatch |
| **Material semantics** | Style and mood language |
| **Blend rank** | Vibe relevance × colour fitness (still respects pins / photo) |

Type a vibe, pick chips, or mix with photo match — results stay explainable (tags + colour score).

Also planned: enquiry summaries, NL front door into vibe + colour, upload auto-tagging, abuse controls on public preview.

---

## Lead gen

```mermaid
flowchart LR
  public[Public_catalogue]
  shortlist[Shortlist]
  form[Enquiry_form]
  db[Durable_snapshot]
  inbox[Role_scoped_inbox]
  public --> shortlist --> form --> db --> inbox
```

Contact fields plus a **durable snapshot** of materials, design groups, swaps, and preview context — still meaningful if catalogue content changes later. Intent is **server-inferred** from shortlist shape.

- **Suppliers** see only enquiries that include **their** materials.
- **Designers** see only enquiries on **their** designs.
- One enquiry can touch multiple parties; each inbox is **scoped** (peers’ lines are not dumped into someone else’s view).
- Status: new → replied → ongoing → resolved → archived in-panel.

Public **supplier pages** (bio, site, materials); designs show designer name (full public designer profiles later). Suppliers already **self-serve** catalogue CRUD for their own records — this is a working portal, not a static brochure.

---

## Analytics and how to add value

### Already in place

- Photo-match funnel (upload, pin, click, shortlist, failure)
- Daily **colour-demand** rollups
- Finish-preview operational events

**Flywheel:** more matches → clearer colour demand → better assortment / merchandising advice for suppliers → stickier catalogue and stronger case for paid attention.

### Highest-leverage improvements

| Direction | Partner value |
|-----------|----------------|
| **Full funnel analytics** | Impression → match → PDP → shortlist → enquiry |
| **Featured → paid boost** | Caps + disclosure; keep scores honest |
| **CPV → CPC → CPL** | Views → clicks → attributed leads |
| **Colour demand insights** | Stock / merchandize; B2C trend content |
| **Lead notify + CRM** | Email/webhook; HubSpot / Salesforce |
| **Buyer accounts & mood boards** | Synced shortlists; named boards; PDF / share packages; softer CTAs |
| **Sample logistics** | Sample intent end-to-end |
| **AI inbox + vibe search & match** | Summaries; NL / vibe blended with colour |

Commercial path: **featured (now) → measurable boost → CPV/CPC → CPL**, with analytics proving ROI.

---

## B2B and B2C

One catalogue today; positioning can split later without rebuilding discovery.

- **B2B:** specs, collections, supplier pages, quote enquiries, designer curation, self-serve portals → SLA inboxes, RFQ depth, CRM, paid leads.
- **B2C:** photo match + AI “see it on the look” + share links → accounts, **mood boards / PDF packages**, retail fulfilment, vibe + trend surfaces.

---

## Roadmap levers

Intentional MVP boundaries — each extends something already shipped:

- Email / SMS on new enquiry  
- Monetized leads marketplace and self-serve boost budgets  
- Buyer login, synced shortlists, **shareable mood boards**, PDF packages  
- Full BI beyond photo-match analytics  
- Public designer profile pages  
- Full material semantics + **vibe search & match** (see AI layer)  

---

## Bottom line

Materials MVP is a **colour-native materials marketplace spine**: explainable scientific discovery, design-led inspiration with AI preview and share loops (and planned vibe search & match), supplier/designer self-serve, and structured two-sided lead capture — with a clear path to analytics-backed monetization (featured → CPV/CPC/CPL).