BuyWhere Brand Style Guide

Version: 1.0
Status: Draft
Last Updated: April 2026

---

1. Brand Overview

1.1 Brand Personality

BuyWhere — the agent-native product catalog API for AI commerce.

• Core Value: Making product discovery instant, reliable, and agent-friendly
• Voice: Confident, technical, helpful—not marketing-speak
• Tone: Professional but approachable; precise but not cold
• Positioning: Infrastructure for AI agents, built by engineers who understand agents

1.2 Brand Mission

To be the definitive product catalog API that powers AI shopping agents across Southeast Asia and globally.

---

2. Logo System

2.1 Primary Logo

The BuyWhere wordmark combined with a location pin / search hybrid icon.

[Icon] BuyWhere

Clear Space: Minimum padding = height of the "B" on all sides
Minimum Size: 24px height for digital, 10mm for print

2.2 Icon-Only Variant

For favicons, app icons, and contexts where wordmark is unnecessary.

[Pin icon only]

Usage: Favicons, social media, app store icons, documentation headers

2.3 Logo Variations

2.4 Logo Don'ts

• Do not stretch or distort the logo
• Do not change the icon-to-wordmark ratio
• Do not add shadows, gradients, or effects
• Do not place on backgrounds that reduce contrast below 4.5:1
• Do not use outdated logo versions
• Do not recreate the logo from scratch

2.5 Color Logo Treatments

Light Backgrounds: Full color (blue icon + dark text)
Dark Backgrounds: White monochrome or full color with white icon
Accent Uses: The blue (#0066FF) can be used as a standalone brand accent

---

3. Color Palette

3.1 Primary Colors

3.2 Secondary Colors

3.3 Semantic Colors

3.4 Dark Mode Palette

3.5 Color Contrast

All text combinations meet WCAG 2.1 AA standards (4.5:1 for normal text, 3:1 for large text):

---

4. Typography

4.1 Font Families

Primary (Headlines & Body): Inter

• Google Fonts: Inter (weights: 400, 500, 600, 700)
• Fallback: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif

Monospace (Code & Technical): JetBrains Mono

• Google Fonts: JetBrains Mono (weights: 400, 500)
• Fallback: "SF Mono", "Fira Code", Consolas, monospace

Display (Hero Headlines): Inter with increased weight (700-800) and optical sizing

4.2 Type Scale

Display:   48px / 56px line-height / -0.02em tracking / 700 weight
H1:        36px / 44px line-height / -0.01em tracking / 700 weight
H2:        28px / 36px line-height / 0 / 600 weight
H3:        22px / 30px line-height / 0 / 600 weight
H4:        18px / 26px line-height / 0 / 600 weight
Body LG:   18px / 28px line-height / 0 / 400 weight
Body:      16px / 24px line-height / 0 / 400 weight
Body SM:   14px / 20px line-height / 0 / 400 weight
Caption:   12px / 16px line-height / 0.02em tracking / 500 weight
Code:      14px / 22px line-height / 0 / 400 weight (monospace)

4.3 Type Styles

Display — Hero sections, marketing landing pages

BuyWhere: The API for AI Commerce
Font: Inter 700, 48px

H1 — Page titles, major section headers

Getting Started with BuyWhere
Font: Inter 700, 36px

H2 — Section headers within pages

Authentication
Font: Inter 600, 28px

H3 — Subsection headers

Rate Limits
Font: Inter 600, 22px

H4 — Component headers, card titles

Endpoint Card
Font: Inter 600, 18px

Body Large — Hero body text, marketing copy

Build AI shopping agents that search, compare, and buy
Font: Inter 400, 18px

Body — Standard body text, descriptions

The Products API provides access to BuyWhere's catalog...
Font: Inter 400, 16px

Body Small — Secondary descriptions, metadata

Last updated: April 15, 2026
Font: Inter 400, 14px

Caption — Labels, badges, timestamps

PRO  |  REQUIRED  |  v2
Font: Inter 500, 12px

Code — Code blocks, technical content

curl -X GET "https://api.buywhere.ai/v1/products"
Font: JetBrains Mono 400, 14px

4.4 Line Length

• Optimal reading width: 65-75 characters
• Maximum body text width: 720px
• Maximum full-width content: 1200px

---

5. Iconography System

5.1 Icon Style

Library: Lucide Icons (open-source, consistent stroke weight)
Stroke Weight: 1.5px (standard), 2px (emphasis)
Corner Radius: 2px (slightly rounded, modern)
Optical Size: 24px default, 16px for inline, 32px for featured

5.2 Icon Usage

5.3 Icon Don'ts

• Do not mix icon libraries with different stroke weights
• Do not use filled icons alongside outlined icons
• Do not stretch or scale icons non-uniformly
• Do not use icons as decorative elements without purpose

---

6. Spacing System

6.1 Base Unit

4px — All spacing is a multiple of 4

6.2 Spacing Scale

6.3 Component Spacing

---

7. Layout Grid

7.1 Page Grid

Mobile (<640px):     1 column, 16px gutters
Tablet (640-1024px): 2 columns, 24px gutters, max 720px centered
Desktop (>1024px):   12-column grid, 24px gutters, max 1200px centered

7.2 Sidebar + Content Layout

Desktop:
┌──────────┬─────────────────────────────────────────────────┐
│ Sidebar  │ Content                                          │
│ 260px    │ max-width 900px, centered in remaining space    │
│ fixed    │                                                  │
├──────────┼─────────────────────────────────────────────────┤

Tablet:
┌──────────┬─────────────────────────────────────────────────┐
│ Sidebar  │ Content                                          │
│ 240px    │ fluid, max 720px                                │
│ overlay  │                                                  │
└──────────┴─────────────────────────────────────────────────┘

Mobile:
┌─────────────────────────────────────────────────────────────┐
│ Content (hamburger → sidebar overlay)                      │
│ full-width, 16px padding                                   │
└─────────────────────────────────────────────────────────────┘

7.3 Content Rhythm

• H1: 48px margin-top (space-12)
• H2: 32px margin-top (space-8)
• H3: 24px margin-top (space-6)
• Paragraph: 16px margin-bottom (space-4)
• Lists: 12px between items (space-3)
• Code blocks: 16px margin-top/bottom (space-4)
• Cards: 16px gap between cards (space-4)

---

8. Component Styling

8.1 Buttons

Primary Button

• Background: #0066FF
• Text: #FFFFFF
• Hover: #0052CC
• Active: #004099
• Border-radius: 6px
• Font: Inter 500, 14px
• Height: 40px
• Padding: 0 20px

Secondary Button

• Background: transparent
• Border: 1px solid #E5E7EB
• Text: #374151
• Hover: background #F9FAFB
• Border-radius: 6px

Ghost Button

• Background: transparent
• Text: #0066FF
• Hover: background #E8F1FF
• Border-radius: 6px

Disabled Button

• Background: #E5E7EB
• Text: #9CA3AF
• Cursor: not-allowed

8.2 Input Fields

• Background: #FFFFFF
• Border: 1px solid #E5E7EB
• Border-radius: 6px
• Height: 40px
• Padding: 0 12px
• Font: Inter 400, 14px
• Focus: border-color #0066FF, box-shadow 0 0 0 3px rgba(0,102,255,0.1)

8.3 Cards

• Background: #FFFFFF
• Border: 1px solid #E5E7EB
• Border-radius: 8px
• Padding: 16px
• Shadow: none (flat) or 0 1px 3px rgba(0,0,0,0.1) for elevated
• Hover (if interactive): border-color #0066FF

8.4 Badges

Method Badges

• GET: green background #D1FAE5, text #065F46
• POST: blue background #DBEAFE, text #1E40AF
• PATCH: amber background #FEF3C7, text #92400E
• DELETE: red background #FEE2E2, text #991B1B
• Font: JetBrains Mono 500, 12px
• Border-radius: 4px
• Padding: 2px 6px

Status Badges

• NEW: purple background #F3E8FF, text #6B21A8
• BETA: amber background #FEF3C7, text #92400E
• DEPRECATED: gray background #F3F4F6, text #6B7280
• Font: Inter 500, 11px uppercase

8.5 Tables

• Header: background #F9FAFB, font-weight 600
• Row: border-bottom 1px solid #E5E7EB
• Row hover: background #F9FAFB
• Cell padding: 8px 12px
• Border-collapse: collapse

---

9. Animation & Motion

9.1 Timing

9.2 Easing

• Default: cubic-bezier(0.4, 0, 0.2, 1) — ease-out for most transitions
• Entrance: cubic-bezier(0, 0, 0.2, 1) — decelerate
• Exit: cubic-bezier(0.4, 0, 1, 1) — accelerate
• Bounce: cubic-bezier(0.34, 1.56, 0.64, 1) — slight overshoot

9.3 Motion Don'ts

• Do not animate layout shifts ( CLS impact)
• Do not use motion for motion's sake
• Do not exceed 300ms for simple interactions
• Do respect prefers-reduced-motion

---

10. Dark Mode Implementation

10.1 CSS Variables

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --bg-card: #ffffff;
  --bg-hover: #f3f4f6;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
  --accent: #0066ff;
}

[data-theme="dark"] {
  --bg-primary: #0f0f1a;
  --bg-secondary: #1a1a2e;
  --bg-card: #1a1a2e;
  --bg-hover: #252540;
  --text-primary: #f9fafb;
  --text-secondary: #9ca3af;
  --border: #2d2d44;
  --accent: #4d94ff;
}

10.2 Toggle Behavior

• Initial state: respect prefers-color-scheme
• User toggle: persist to localStorage
• Transition: 200ms ease for color properties

---

11. Responsive Breakpoints

---

12. Accessibility Checklist

• All text meets 4.5:1 contrast ratio
• Focus states visible on all interactive elements
• Keyboard navigation for all features
• Skip to main content link
• ARIA labels on icon-only buttons
• Reduced motion respected
• Semantic HTML structure
• Form labels associated with inputs

---

This brand style guide is a living document. For updates, coordinate with the Head of Design (Iris).