# DESIGN.md — bloom.medusajs.com

## 1. Visual Theme & Atmosphere

Bloom by Medusa is a developer-oriented e-commerce showcase with a refined commerce aesthetic — clean, modern, and trust-building. The visual language is that of a well-funded DTC brand: white surfaces, zinc typography, subtle borders, and a single deep shadow for elevation. The atmosphere is "premium e-commerce storefront that developers would be proud to ship." It's neither corporate nor playful — it occupies the confident middle ground that serious product companies aim for.

## 2. Color Palette & Roles

| Role | Value | Notes |
|------|-------|-------|
| Body text / primary | `rgb(24, 24, 27)` | Zinc-900 — near-black, warm-tinted |
| Border / dividers | `rgb(228, 228, 231)` | Zinc-200 — whisper-light separators |
| Header surface | `rgb(255, 255, 255)` | Pure white — fixed/sticky header base |
| Button text (secondary) | `rgb(82, 82, 91)` | Zinc-600 — muted interactive state |
| White surfaces | `rgb(255, 255, 255)` | Product cards, base layer |
| Dark surfaces | `rgb(39, 39, 42)`, `rgb(24, 24, 27)` | Section variants, dark CTAs |

The palette is a monochromatic zinc scale — no hues, no saturation. This is intentional: the product photography and brand content are the color. The UI recedes to give products room to breathe.

## 3. Typography Rules

**Typeface**: `Inter` — the industry-standard for readable UI. Falls back through `-apple-system` and `system-ui`.

| Selector | Size | Weight | Notes |
|----------|------|--------|-------|
| h1 | 18px | 500 | Surprisingly restrained — medium, not dominant |
| body | 16px | 400 | Comfortable baseline |

- Line height for h1 is 28.8px (1.6x) — generous for readability.
- No letter-spacing manipulation — Inter's default spacing is respected.
- Weight 500 (medium) for headings signals restraint: this design doesn't shout.
- **What's absent**: no expressive display fonts, no condensed variants, no large-scale typographic gestures. Typography is pure utility.

## 4. Component Stylings

- **Header**: white background, zinc borders — always visible, always grounded.
- **Buttons**: transparent background with zinc-600 text and zinc-200 border — ghost style by default.
- **Cards**: white (`rgb(255,255,255)`) with a nuanced depth shadow.
- **Shadow**: `rgba(50, 50, 93, 0.25) 0px 13px 27px -5px, rgba(0, 0, 0, 0.3) 0px 8px 16px -8px` — a compound shadow creating a realistic lifted card feel without being dramatic.
- **Dark sections**: `rgb(39,39,42)` and `rgb(24,24,27)` backgrounds for footer or promotional blocks.

## 5. Layout Principles

- Body and section elements have zero default margin/padding — a clean slate for custom grid.
- The layout follows a classic e-commerce pattern: sticky header, grid-based product listing, editorial sections.
- Zinc-200 borders define content zones without adding visual weight.
- No detected animations — the layout is static and performant.

## 6. Depth & Elevation

The compound shadow is the site's primary elevation mechanism: `rgba(50,50,93,0.25) 0px 13px 27px -5px` handles ambient depth while `rgba(0,0,0,0.3) 0px 8px 16px -8px` adds a close-contact shadow. This technique creates cards that feel realistically lifted from the page — not a flat design, but subtly physical. The two-layer shadow is a widely-recognized premium e-commerce pattern popularized by Stripe's own design system.

## 7. Do's and Don'ts

**Do:**
- Let Inter do its job at 16px/400 — don't reach for custom weights or tracking.
- Use zinc-200 (`rgb(228,228,231)`) for all borders and dividers — consistent and light.
- Apply the compound shadow to product cards and elevated UI surfaces.
- Contrast white cards against a near-black section (`rgb(24,24,27)`) for impact.

**Don't:**
- Add color accents — this palette's power is its chromatic restraint.
- Use font weights above 600 — medium (500) is the ceiling here.
- Create borders with heavy colors — zinc-200 only.
- Add more than two layers of shadow — the compound shadow is precise.

## 8. Responsive Behavior

- Sticky header at `rgb(255,255,255)` works at all widths — always legible.
- Card grids likely collapse from 3-column to 2-column to 1-column — standard e-commerce responsive pattern.
- 18px h1 is effectively body-scale — this is a UI-first heading scale, not editorial.
- Ghost buttons scale gracefully at any width with text-only resize.

## 9. Agent Prompt Guide

> Build a premium e-commerce UI in the style of Bloom by Medusa: zinc monochrome palette (`rgb(24,24,27)` text, `rgb(228,228,231)` borders, white surfaces), Inter typeface at 500/400 weights, white sticky header, ghost-style buttons, compound elevation shadow (`rgba(50,50,93,0.25) 0px 13px 27px -5px, rgba(0,0,0,0.3) 0px 8px 16px -8px`) on cards. No color accents — product imagery provides all hue.

*Generated by Sparkbites — extracted from live CSS analysis*