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

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.

• 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