marketplaces/DESIGN.md

---
name: Marketplaces Platform
description: Config-driven multi-tenant marketplace platform — quiet chrome, tenant-led storefronts.
colors:
  primary: "#497671"
  primary-hover: "#3d635f"
  secondary: "#a1b4b5"
  secondary-hover: "#8da3a4"
  accent: "#a7ceca"
  accent-hover: "#91b9b5"
  text-primary: "#1e3c38"
  text-secondary: "#667a77"
  text-light: "#828e8d"
  bg-primary: "#ffffff"
  bg-secondary: "#f5f5f5"
  bg-tertiary: "#f0f0f0"
  border: "#d3dad9"
  border-dark: "#677b78"
  success: "#10b981"
  warning: "#f59e0b"
  error: "#ef4444"
  info: "#3b82f6"
typography:
  display:
    fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
    fontSize: "clamp(2rem, 4vw, 2.75rem)"
    fontWeight: 700
    lineHeight: 1.25
    letterSpacing: "normal"
  headline:
    fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
    fontSize: "clamp(1.5rem, 3vw, 2rem)"
    fontWeight: 700
    lineHeight: 1.25
    letterSpacing: "normal"
  title:
    fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
    fontSize: "1.125rem"
    fontWeight: 600
    lineHeight: 1.3
    letterSpacing: "normal"
  body:
    fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
    fontSize: "1rem"
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: "normal"
  label:
    fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
    fontSize: "0.7rem"
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: "0.4px"
rounded:
  sm: "8px"
  md: "12px"
  lg: "13px"
  xl: "22px"
  field: "10px"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "32px"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    rounded: "{rounded.md}"
    padding: "0.625rem 1rem"
  button-primary-hover:
    backgroundColor: "{colors.primary-hover}"
    textColor: "#ffffff"
    rounded: "{rounded.md}"
  button-secondary:
    backgroundColor: "{colors.secondary}"
    textColor: "#ffffff"
    rounded: "{rounded.md}"
    padding: "0.625rem 1rem"
  button-ghost:
    backgroundColor: "transparent"
    textColor: "{colors.text-primary}"
    rounded: "{rounded.md}"
    padding: "0.625rem 1rem"
  card:
    backgroundColor: "{colors.bg-primary}"
    rounded: "{rounded.md}"
    padding: "16px"
  input:
    backgroundColor: "{colors.bg-primary}"
    textColor: "{colors.text-primary}"
    rounded: "{rounded.field}"
    padding: "10px 12px"
  badge:
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: "2px 8px"
---

# Design System: Marketplaces Platform

## 1. Overview

**Creative North Star: "The Operator's Workbench"**

This is a tool before it is a brand. The platform chrome — the Project Editor, the Admin backoffice, the shared UI primitives — is a dependable workbench an operator returns to session after session to build and run a marketplace. It rewards precision and speed: state is always legible (draft vs published, saved vs unsaved, safe vs destructive), controls map visibly to what they change, and nothing on screen competes with the work. The palette is a calm Muted Pine teal-green, warm enough to feel like commerce, quiet enough to disappear behind a tenant's own theme.

The system is deliberately configuration-first. Every storefront is themed per tenant from a runtime `bootstrap.json`, so the platform's own identity stays neutral by design — the tenant's colors, type, and layout carry the storefront's character, and the workbench chrome recedes. Where components do appear, they are tactile and confident: solid fills, decisive hover lift, honest disabled and error states. Depth is real but restrained — surfaces sit on soft tonal shadows at rest, and structural elevation is reserved for things that genuinely float (modals, dropdowns, the save bar).

This system explicitly rejects three looks. It is **not dated enterprise admin** — no cluttered gray dashboards, no tiny dense tables, no 2010-era Bootstrap backoffice. It is **not a generic AI-SaaS template** — no cream/violet gradient landings, no hero-metric card rows, no tracked-uppercase eyebrows on every section, no identical icon-heading-text grids. It is **not a consumer toy** — no bubbly rounded-everything, no mascots, no candy colors, no gamified UI.

**Key Characteristics:**
- Quiet, neutral chrome so per-tenant themes lead the storefront.
- Muted Pine teal-green primary; retail-warm but low-drama.
- Tactile, confident components with decisive states.
- Legible state above decoration in every tool surface.
- WCAG 2.2 AA; contrast holds across tenant themes, not just the default.

## 2. Colors

A grounded teal-green core over cool near-white neutrals; retail warmth without shouting. The tokens below are the canonical Dexar theme — the platform default. Tenant themes (Lavero, Novo, and future tenants) override these same CSS custom properties, so components must consume the variables, never hardcode hex (ADR-008).

### Primary
- **Muted Pine** (#497671): The core brand teal-green. Primary buttons, active nav, focus outlines, links, key accents. On hover it deepens to **Pine Deep** (#3d635f). Grounded and natural — the color of the workbench itself.

### Secondary
- **Sage Grey** (#a1b4b5): Muted blue-grey-green for secondary actions and supporting surfaces; hover **Sage Grey Deep** (#8da3a4). Quieter than primary, never competes.

### Tertiary
- **Pale Mint** (#a7ceca): Soft light accent (#91b9b5 on hover) for gentle highlights, hero gradient stops, and low-emphasis fills.

### Neutral
- **Deep Pine Ink** (#1e3c38): Primary text. Tinted toward the brand hue, not pure black — carries 4.5:1+ on white.
- **Muted Pine Grey** (#667a77): Secondary text, captions, field descriptions.
- **Faint Pine Grey** (#828e8d): Light/tertiary text, placeholders — reserve for large or non-essential text.
- **White** (#ffffff): Primary surface (cards, inputs, panels).
- **Soft Grey** (#f5f5f5): App background, secondary surface.
- **Faint Grey** (#f0f0f0): Tertiary surface, subtle fills.
- **Divider Grey** (#d3dad9): Borders, dividers, input strokes.
- **Border Deep** (#677b78): Stronger borders where a divider needs weight.

### Status
- **Success** (#10b981), **Warning** (#f59e0b), **Error** (#ef4444), **Info** (#3b82f6): Standard semantic set, consistent across all themes. Error text darkens to #991b1b on light backgrounds for AA.

### Named Rules
**The Quiet Chrome Rule.** The platform's own surfaces stay neutral so tenant themes carry storefront identity. Never introduce a platform-branded color that would fight a tenant's palette.

**The Variable-Only Rule.** Components and widgets consume CSS custom properties (`--primary-color`, `--text-primary`, `--border-color`) only. A hardcoded hex in a component is a bug (ADR-008) — it breaks per-tenant theming.

## 3. Typography

**Display / Body Font:** DM Sans (with `-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif` fallback)
**Label Font:** DM Sans (same family, tracked and uppercased for badges)

**Character:** One family, four weights (400/500/600/700). DM Sans is a low-contrast geometric-humanist sans — clean, legible at dense sizes, neutral enough to sit behind tenant content. Hierarchy comes from weight and size, never a second display face.

### Hierarchy
- **Display** (700, clamp(2rem, 4vw, 2.75rem), 1.25): Page-level headings, storefront hero titles. Never exceeds ~2.75rem — the workbench does not shout.
- **Headline** (700, clamp(1.5rem, 3vw, 2rem), 1.25): Section headings, admin page titles.
- **Title** (600, 1.125rem, 1.3): Card titles, editor section labels, form group headings.
- **Body** (400, 1rem, 1.6): Default reading text. Cap prose at 65–75ch.
- **Label** (600, 0.7rem, 1.4, letter-spacing 0.4px, uppercase): Badges and tags only — the one place tracked uppercase is legitimate.

### Named Rules
**The One Family Rule.** DM Sans in multiple weights carries the entire system. Do not pair a second sans; do not add a display serif. Contrast is weight and size.

**The Uppercase-Is-Earned Rule.** Tracked uppercase lives on badges/tags exclusively. It is forbidden as a section eyebrow — that is a named anti-reference.

## 4. Elevation

A hybrid: soft tonal shadows give resting surfaces gentle separation from the background, while structural elevation is reserved for elements that genuinely float — modals, dropdowns, the sticky save bar. On top of that, interactive surfaces lift on hover (a 1–2px translate plus a stronger shadow). Depth is present and purposeful, never heavy.

### Shadow Vocabulary
- **shadow-sm** (`0 2px 8px rgba(0,0,0,0.1)`): Resting cards, inputs, low panels. The default ambient layer.
- **shadow-md** (`0 4px 12px rgba(0,0,0,0.15)`): Hover state for cards and buttons; raised toolbars.
- **shadow-lg** (`0 12px 32px rgba(73,118,113,0.2)`): Structural float — modals, dropdowns, popovers, the save bar. Tinted with the brand hue.

### Named Rules
**The Lift-on-Intent Rule.** Resting surfaces carry at most `shadow-sm`. `shadow-md` is a response to hover/focus; `shadow-lg` means the element floats above the page. Never use `shadow-lg` as decoration on a static card.

## 5. Components

### Buttons
- **Shape:** Gently curved (12px radius, `{rounded.md}`); editor action buttons use 10px (`{rounded.field}`).
- **Primary:** Muted Pine fill (#497671), white text, padding `0.625rem 1rem`, weight 600–700. Tactile and confident.
- **Hover / Focus:** Background deepens to #3d635f, `translateY(-1px)` lift with `shadow-sm`; focus-visible shows a 2px Muted Pine outline offset 2px. `:active` returns to `translateY(0)`.
- **Secondary:** Sage Grey (#a1b4b5) fill, white text; hover #8da3a4.
- **Ghost:** Transparent, Deep Pine Ink text, Divider Grey border; hover fills `rgba(73,118,113,0.08)` and border shifts to Muted Pine.
- **Disabled:** `opacity: 0.6`, no lift, no shadow, `cursor: not-allowed`.

### Cards / Containers
- **Corner Style:** 12px (`{rounded.md}`).
- **Background:** White (#ffffff) on Soft Grey (#f5f5f5) page.
- **Border:** 1px Divider Grey (#d3dad9).
- **Shadow Strategy:** `shadow-sm` at rest → `shadow-md` on hover with `translateY(-2px)` (product cards add a subtle `scale(1.01)`). See Elevation.
- **Internal Padding:** 16px (`{spacing.md}`).
- **Nested cards:** Editor sub-cards use `#fbfcfc` fill with the same 12px radius and 1px border.

### Inputs / Fields
- **Style:** White fill, 1px Divider Grey border, 10px radius (`{rounded.field}`), padding `10px 12px`, inherits body font.
- **Focus:** 2px Muted Pine focus-visible outline, offset 2px (global rule).
- **Field description:** 12px, Muted Pine Grey (#667a77), sits under the label at weight 400.
- **Error:** Error text #991b1b; color input controls get a 44px min-height touch target.

### Navigation
- Neutral chrome, DM Sans, weight 600 for active items. Default text is Deep Pine Ink; active/hover carries Muted Pine. Header uses a low-tint `--bg-header` wash (brand hue at ~10% alpha). Mobile collapses to a menu; `body.platform-menu-open` locks scroll.

### Badges & Tags (signature)
- **Badge:** Uppercase Label type (0.7rem, 600, 0.4px tracking), white text, 8px radius, `2px 8px` padding, solid semantic fills (new #4caf50, sale #f44336, hot #ff5722, limited #ff9800, bestseller #2196f3, featured #607d8b). Absolutely-positioned overlay top-left on product media.
- **Tag:** Pill (12px radius), Muted Pine text on `rgba(73,118,113,0.08)` fill with a faint brand border. Low-emphasis metadata.

### Save Bar (signature)
- Sticky, structurally elevated (`shadow-lg`), always states current state (unsaved changes / saving / published). The clearest expression of the Operator's Workbench: the operator always knows where the work stands.

## 6. Do's and Don'ts

### Do:
- **Do** consume theme CSS custom properties (`--primary-color`, `--text-primary`, `--border-color`) — never hardcode hex in a component (ADR-008).
- **Do** keep platform chrome neutral so tenant themes lead the storefront (The Quiet Chrome Rule).
- **Do** carry hierarchy with DM Sans weight and size; one family only.
- **Do** keep resting surfaces on `shadow-sm`; reserve `shadow-lg` for genuinely floating elements.
- **Do** make state unambiguous — draft vs published, saved vs unsaved, safe vs destructive — in every tool surface.
- **Do** give every hover/transform a `prefers-reduced-motion: reduce` fallback (handled globally in `styles.scss`).
- **Do** hold 4.5:1 body-text contrast across every tenant theme, not just Dexar.

### Don't:
- **Don't** ship dated enterprise admin: no cluttered gray dashboards, tiny dense tables, or 2010-era Bootstrap backoffice.
- **Don't** ship generic AI-SaaS template: no cream/violet gradient landings, hero-metric card rows, tracked-uppercase eyebrows on every section, or identical icon-heading-text card grids.
- **Don't** ship consumer-toy UI: no bubbly rounded-everything, mascots, candy colors, or gamified surfaces.
- **Don't** use tracked uppercase anywhere except badges/tags (The Uppercase-Is-Earned Rule).
- **Don't** exceed ~2.75rem on display headings — the workbench does not shout.
- **Don't** add a second type family or a display serif.
- **Don't** let platform-branded color fight a tenant's palette.