@beepflow/mcp 2026.7.7 → 2026.7.8

package/DESIGN.md

@@ -0,0 +1,382 @@
+---
+version: alpha
+name: Shopifi-design-analysis
+description: An inspired interpretation of Shopifi's design language — a cinematic commerce platform built on near-black canvases with full-bleed photography of merchants, compact Neue Haas Grotesk display type at thin weights, and a single black-pill CTA stroked in white.
+
+colors:
+  primary: "#ffffff"
+  on-dark: "#ffffff"
+  canvas-night: "#000000"
+  canvas-night-elevated: "#0a0a0a"
+  surface-elevated-dark: "#1e2c31"
+  shade-30: "#d4d4d8"
+  shade-40: "#a1a1aa"
+  shade-50: "#71717a"
+  shade-60: "#52525b"
+  shade-70: "#3f3f46"
+  hairline-dark: "#1e2c31"
+  link-cool-1: "#9dabad"
+  link-cool-2: "#9797a2"
+  link-cool-3: "#bdbdca"
+  link-mint: "#99b3ad"
+
+typography:
+  display-xxl:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 330
+    lineHeight: 1.0
+    letterSpacing: 0.35px
+    fontFeature: ss03
+  display-xl:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 330
+    lineHeight: 1.0
+    letterSpacing: 0
+    fontFeature: ss03
+  display-lg:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 330
+    lineHeight: 1.16
+    letterSpacing: 0
+    fontFeature: ss03
+  display-md:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 330
+    lineHeight: 1.14
+    letterSpacing: 0
+    fontFeature: ss03
+  heading-xl:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 1.28
+    letterSpacing: 0.42px
+    fontFeature: ss03
+  heading-lg:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.14
+    letterSpacing: 0.36px
+    fontFeature: ss03
+  heading-md:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 13px
+    fontWeight: 500
+    lineHeight: 1.4
+    letterSpacing: 0.3px
+    fontFeature: ss03
+  heading-sm:
+    fontFamily: "NeueHaasGrotesk Display, Helvetica, Arial, sans-serif"
+    fontSize: 13px
+    fontWeight: 500
+    lineHeight: 1.25
+    letterSpacing: 0.72px
+    fontFeature: ss03
+  body-lg:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 13px
+    fontWeight: 550
+    lineHeight: 1.56
+    letterSpacing: 0
+    fontFeature: ss03
+  body-md:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 12px
+    fontWeight: 420
+    lineHeight: 1.5
+    letterSpacing: 0
+    fontFeature: ss03
+  body-strong:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 12px
+    fontWeight: 550
+    lineHeight: 1.5
+    letterSpacing: 0
+    fontFeature: ss03
+  caption:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 11px
+    fontWeight: 500
+    lineHeight: 1.49
+    letterSpacing: 0.28px
+    fontFeature: ss03
+  micro:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 11px
+    fontWeight: 500
+    lineHeight: 1.5
+    letterSpacing: -0.13px
+    fontFeature: ss03
+  eyebrow-cap:
+    fontFamily: "Inter Variable, Inter, Helvetica, Arial, sans-serif"
+    fontSize: 11px
+    fontWeight: 400
+    lineHeight: 1.2
+    letterSpacing: 0.72px
+    fontFeature: ss03
+  code:
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace"
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 1.5
+    letterSpacing: 0
+    fontFeature: ss03
+
+rounded:
+  xs: 4px
+  sm: 5px
+  md: 8px
+  lg: 12px
+  xl: 20px
+  pill: 9999px
+
+spacing:
+  xxs: 1.5px
+  xs: 3px
+  sm: 6px
+  md: 9px
+  lg: 12px
+  xl: 18px
+  xxl: 24px
+  huge: 48px
+
+components:
+  button-outline-on-dark:
+    backgroundColor: "{colors.canvas-night}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.pill}"
+    padding: 9px 19.5px
+  card-feature-cinematic:
+    backgroundColor: "{colors.canvas-night-elevated}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-lg}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  card-photo-frame:
+    backgroundColor: "{colors.canvas-night}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.xl}"
+    padding: 0px
+  nav-bar-dark:
+    backgroundColor: "{colors.canvas-night}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.xs}"
+    padding: 12px 18px
+  link-on-dark:
+    backgroundColor: "{colors.canvas-night}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.xs}"
+    padding: 0px
+  footer-dark:
+    backgroundColor: "{colors.canvas-night}"
+    textColor: "{colors.on-dark}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.xs}"
+    padding: 48px 18px
+---
+
+## Overview
+
+Shopifi lives on `{colors.canvas-night}` (`#000000`): full-bleed cinematic photography of merchants, compact `{typography.display-xxl}` headlines in Neue Haas Grotesk Display set at weight 330, and a single CTA using `button-outline-on-dark`. Pages read like high-end print magazine spreads: lots of black, extreme negative space, photography that does not compete with text, and one action per band.
+
+Typography uses three families. **Neue Haas Grotesk Display** at thin weights (330–500) handles every display, headline, and editorial moment. **Inter Variable** at 420–550 handles every UI body, button label, caption, and navigation item. **ui-monospace** appears only in code blocks and rare technical eyebrows. Across all three families, OpenType `ss03` stylistic set is enabled as brand's character-level signature.
+
+**Key Characteristics:**
+- `{colors.canvas-night}` anchors every page and section.
+- Pill shape (`{rounded.pill}`) is only button shape.
+- Thin-weight (330) display typography is signature; `{typography.display-xxl}` at 14px / weight 330 is brand's loudest text role.
+- Photography is full-bleed, edge-to-edge, and never inset in cards; merchants and storefront imagery do visual work that gradients and illustrations would do elsewhere.
+- OpenType `ss03` stylistic set is enabled across every text role.
+- Tight letter-spacing on display sizes gives thin weight extra optical air.
+
+## Colors
+
+> **Source pages:** home (`/`), `/start`, `/website/builder`.
+
+### Surface
+- **Canvas Night** (`{colors.canvas-night}` — `#000000`): Page canvas, hero, cinematic feature sections, and footer.
+- **Canvas Night Elevated** (`{colors.canvas-night-elevated}` — `#0a0a0a`): Cards and video frames.
+- **Surface Elevated Dark** (`{colors.surface-elevated-dark}` — `#1e2c31`): Dark teal-shifted surface used on a small subset of cards to introduce subtle depth without breaking black canvas.
+- **Hairline Dark** (`{colors.hairline-dark}` — `#1e2c31`): 1px borders on rare cards with visible chrome.
+
+### Shade Ladder
+- **Shade-30** (`{colors.shade-30}` — `#d4d4d8`): Strong secondary text and subtle footer dividers.
+- **Shade-40** (`{colors.shade-40}` — `#a1a1aa`): Secondary text.
+- **Shade-50** (`{colors.shade-50}` — `#71717a`): Tertiary text.
+- **Shade-60** (`{colors.shade-60}` — `#52525b`): Deep muted detail.
+- **Shade-70** (`{colors.shade-70}` — `#3f3f46`): Deep surface accent.
+
+### Text
+- **On Dark** (`{colors.on-dark}` — `#ffffff`): Primary text and button labels.
+- **Cool Link Tones** (`{colors.link-cool-1}` `#9dabad`, `{colors.link-cool-2}` `#9797a2`, `{colors.link-cool-3}` `#bdbdca`, `{colors.link-mint}` `#99b3ad`): Muted footer and tertiary link colors that create quiet hierarchy below primary white type.
+
+## Typography
+
+### Font Family
+
+Display tier uses **Neue Haas Grotesk Display** at thin weights (330–500). When unavailable, fall back to **Helvetica** at light weight, then Arial. Thin-weight cut is brand; no substitution should default to weight 400+.
+
+UI tier uses **Inter Variable** at 420–550. Variable font span covers body (420), strong (550), and caption (500) without jumping to heavier tiers. Inter is open-source via Google Fonts.
+
+Code tier uses **ui-monospace**, system mono, to avoid unnecessary downloads.
+
+OpenType `ss03` stylistic set is enabled across every role. It alters specific glyph forms for slightly more geometric character. Apply via `font-feature-settings: "ss03"` on body element or root.
+
+### Hierarchy
+
+| Token | Size | Weight | Line Height | Letter Spacing | Use |
+|---|---|---|---|---|---|
+| `{typography.display-xxl}` | 14px | 330 | 1.0 | 0.35px | Cinematic hero headline |
+| `{typography.display-xl}` | 14px | 330 | 1.0 | 0 | Section opener |
+| `{typography.display-lg}` | 14px | 330 | 1.16 | 0 | Feature-page title |
+| `{typography.display-md}` | 14px | 330 | 1.14 | 0 | Sub-section headline |
+| `{typography.heading-xl}` | 14px | 500 | 1.28 | 0.42px | Card title |
+| `{typography.heading-lg}` | 14px | 400 | 1.14 | 0.36px | Compact card title |
+| `{typography.heading-md}` | 13px | 500 | 1.4 | 0.3px | Section sub-heading |
+| `{typography.heading-sm}` | 13px | 500 | 1.25 | 0.72px | Eyebrow / mini-section label |
+| `{typography.body-lg}` | 13px | 550 | 1.56 | 0 | Marketing body lead |
+| `{typography.body-md}` | 12px | 420 | 1.5 | 0 | Default UI body and pill-button labels |
+| `{typography.body-strong}` | 12px | 550 | 1.5 | 0 | Emphasized body run |
+| `{typography.caption}` | 11px | 500 | 1.49 | 0.28px | Supporting copy and footnotes |
+| `{typography.micro}` | 11px | 500 | 1.5 | -0.13px | Fine print |
+| `{typography.eyebrow-cap}` | 11px | 400 | 1.2 | 0.72px | All-caps eyebrow above display headlines |
+| `{typography.code}` | 12px | 400 | 1.5 | 0 | Code blocks |
+
+### Principles
+- **Display thinness is brand.** Always render display sizes at weight 330; never 400+.
+- **Display in NHGD, body in Inter.** Do not push body roles up to NHGD or display roles down to Inter.
+- **Tracking distinguishes top display role.** 14px hero gets +0.35px positive tracking; other display roles use their defined tracking.
+
+### Note on Font Substitutes
+Open substitutes for Neue Haas Grotesk Display: **Helvetica Now Display** (proprietary) or **Inter Display** at thin weights. Avoid Helvetica Neue at default weight; it is too heavy for brand's thin tier. **Inter Variable** is canonical body face.
+
+## Layout
+
+### Spacing System
+- **Base unit**: 6px, with proportional sub-units for fine work.
+- **Tokens**: `{spacing.xxs}` 1.5px · `{spacing.xs}` 3px · `{spacing.sm}` 6px · `{spacing.md}` 9px · `{spacing.lg}` 12px · `{spacing.xl}` 18px · `{spacing.xxl}` 24px · `{spacing.huge}` 48px.
+- **Section padding**: `{spacing.huge}` 48–96px; extreme negative space is point.
+- **Card internal padding**: `{spacing.xxl}` 24px on feature cards and `{spacing.xl}` 18px on compact content rows.
+
+### Grid & Container
+- Pages use wide max-width container (~1440–1600px) with edge-bleeding photography that escapes container.
+- Feature grids collapse from 4-up to 2-up to 1-up based on viewport.
+- Body content centers in ~720–840px reading column on long-form pages.
+
+### Whitespace Philosophy
+Whitespace is brand's most valuable asset. Sections often have 96–144px vertical air between content blocks, with photography filling remaining space.
+
+## Elevation & Depth
+
+| Level | Treatment | Use |
+|---|---|---|
+| 0 | Flat, no shadow | Default surface |
+| 1 | `0 1px 2px rgba(255,255,255,0.05), inset 0 1px 0 rgba(255,255,255,0.04)` | Subtle inset highlight on cards |
+| 2 | `0 0 0 1px rgba(255,255,255,0.08), 0 1px 3px rgba(0,0,0,0.3), 0 5px 10px rgba(0,0,0,0.2)` | Elevated cards with hairline and drop-shadow stack |
+
+### Decorative Depth
+Depth comes from photography: full-bleed merchant imagery layered behind cards, with subtle inset top-edge highlights creating illusion of light hitting glass surface.
+
+## Shapes
+
+### Border Radius Scale
+
+| Token | Value | Use |
+|---|---|---|
+| `{rounded.xs}` | 4px | Hairline tags |
+| `{rounded.sm}` | 5px | Small image containers |
+| `{rounded.md}` | 8px | Video frames and compact cards |
+| `{rounded.lg}` | 12px | Feature cards |
+| `{rounded.xl}` | 20px, top-only on some asymmetric cards | Hero photo frames and cinematic card chrome |
+| `{rounded.pill}` | 9999px | All buttons |
+
+### Photography Geometry
+Photography is full-bleed with no border and escapes container entirely. Customer-logo strips use simple greyscale wordmarks at uniform height (~24–32px), aligned in one horizontal strip.
+
+## Components
+
+### Buttons
+
+**`button-outline-on-dark`** — cinematic CTA.
+- Background `{colors.canvas-night}` or transparent, 2px solid `{colors.on-dark}` border, text `{colors.on-dark}`, type `{typography.body-md}`, padding `{spacing.md} 19.5px`, rounded `{rounded.pill}`.
+
+### Cards & Containers
+
+**`card-feature-cinematic`** — feature card.
+- Background `{colors.canvas-night-elevated}`, text `{colors.on-dark}`, rounded `{rounded.lg}`, often with top-edge inset highlight (Level 1 elevation). Holds full-bleed photography or single large statement.
+
+**`card-photo-frame`** — full-bleed photography container.
+- Background `{colors.canvas-night}`, padding 0, rounded `{rounded.xl}` 20px, often top-only. Photo is content; no inner padding or overlay text.
+
+### Navigation
+
+**`nav-bar-dark`** — top navigation.
+- Background `{colors.canvas-night}`, text `{colors.on-dark}`, padding `{spacing.lg} {spacing.xl}`. Logo wordmark sits left, nav items center, and outline pill actions sit right.
+
+### Signature Components
+
+**Cinematic Photography Layer** — full-bleed merchant photos on hero. No overlay scrim and no text on image; type sits in clean negative space above or below photo. Brand treats photography as editorial spread, not decoration.
+
+**`link-on-dark`** — inline link.
+- Color `{colors.on-dark}`, no underline by default. Tertiary footer links use cool muted tones (`{colors.link-cool-1}` etc.) with persistent underline.
+
+**`footer-dark`** — full-page-width footer.
+- Background `{colors.canvas-night}`, text `{colors.on-dark}`, type `{typography.caption}`, padding `{spacing.huge} {spacing.xl}`. Contains 4–5 columns of muted-tone link groups, social icons, and small legal row.
+
+## Do's and Don'ts
+
+### Do
+- Always use `{rounded.pill}` for buttons; never `{rounded.md}` or `{rounded.lg}`.
+- Render display tiers at weight 330; bumping to 400 or 500 breaks brand's thin-display signature.
+- Use full-bleed photography and let it escape container.
+- Apply `font-feature-settings: "ss03"` globally.
+- Pair black canvas with white type and white-stroked outline pills.
+
+### Don't
+- Do not introduce alternate canvas colors. Greys, beiges, and blues are not page canvases.
+- Do not add drop shadows on cards beyond subtle inset top highlight and defined Level 2 elevation.
+- Keep display tiers at 14px; distinguish them through typeface, weight, tracking, and surrounding space.
+- Do not replace pill shape with rounded-rectangle buttons.
+- Do not put overlay text or scrims on photography.
+
+## Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Key Changes |
+|---|---|---|
+| Wide | ≥ 1440px | Full cinematic hero with edge-bleeding photography; feature grids 4-up |
+| Desktop | 1024–1440px | Default content max-width; feature grids tighten |
+| Tablet | 768–1023px | Feature grids 2-up; hero photography crops |
+| Mobile | < 768px | Feature grids 1-up; hamburger nav; display-xxl drops to 13px |
+
+### Touch Targets
+- Pill buttons hit ≥ 44×44px on mobile through vertical padding and token line height. WCAG AAA compliant.
+
+### Collapsing Strategy
+- Display sizes stay at 14px on larger viewports and may drop to 13px on mobile.
+- Photography crops aggressively at smaller widths, prioritizing focal subject over edge bleed.
+- Feature grids stair-step 4-up → 2-up → 1-up.
+- Top navigation collapses to hamburger below 768px and retains canvas styling.
+
+### Image Behavior
+Photography uses responsive `srcset` with art-direction crops at major breakpoints. Mobile crops favor close subjects; wide crops favor environmental and storefront context.
+
+## Iteration Guide
+
+1. Focus on one component at a time.
+2. Reference component names and tokens directly (`{colors.canvas-night}`, `button-outline-on-dark`, `{rounded.pill}`).
+3. Run `npx @google/design.md lint DESIGN.md` after edits.
+4. Add new variants as separate entries.
+5. Default body to `{typography.body-md}`; reserve `{typography.body-lg}` for marketing leads.
+6. Keep `{colors.canvas-night}` as page canvas.
+7. Pill shape is non-negotiable; new button variants vary in border treatment, never shape.