DESIGN_COMPONENT_SPECS

BuyWhere Design System — Core UI Component Specs

Version: 1.0
Status: Draft
Parent: BUY-2100 (Design System Definition)
Last Updated: April 2026

Overview

This document defines specifications for core UI primitives in the BuyWhere design system. These components are the building blocks for all product-facing interfaces—agent dashboards, merchant portals, and consumer-facing views.

1. Button Component

1.1 Button Variants

Primary Button

The main call-to-action. Used for primary user actions.

Property	Value
Background	`#0066FF`
Text	`#FFFFFF`
Hover	`#0052CC`
Active	`#004099`
Disabled	`#E5E7EB` bg, `#9CA3AF` text
Border-radius	`6px`
Font	Inter 500, 14px
Height	40px (default), 32px (small), 48px (large)
Padding	0 20px
Min-width	80px
Transition	100ms ease-out

Secondary Button

For secondary actions. Appears alongside primary buttons.

Property	Value
Background	transparent
Border	1px solid `#E5E7EB`
Text	`#374151`
Hover	background `#F9FAFB`
Active	background `#E5E7EB`
Disabled	`#F3F4F6` bg, `#9CA3AF` text
Border-radius	`6px`
Font	Inter 500, 14px
Height	40px (default), 32px (small), 48px (large)
Padding	0 20px

Ghost Button

Minimal action button. Used in toolbars, cards, and inline contexts.

Property	Value
Background	transparent
Text	`#0066FF`
Hover	background `#E8F1FF`
Active	background `#D1E3FF`
Disabled	`#9CA3AF` text, no hover
Border-radius	`6px`
Font	Inter 500, 14px
Height	32px (compact), 40px (default)
Padding	0 12px

Danger Button

For destructive actions (delete, remove).

Property	Value
Background	`#EF4444`
Text	`#FFFFFF`
Hover	`#DC2626`
Active	`#B91C1C`
Border-radius	`6px`
Font	Inter 500, 14px
Height	40px
Padding	0 20px

1.2 Button States

State	Visual Change
Default	Base variant styles
Hover	Darken background 10%, cursor pointer
Active/Pressed	Darken background 20%, scale(0.98)
Focus	3px ring `rgba(0,102,255,0.3)`, offset 1px
Disabled	Gray background, muted text, cursor not-allowed
Loading	Opacity 0.7, spinner icon replaces text/icon, pointer-events none

1.3 Button Sizes

Size	Height	Padding	Font	Use Case
Small (sm)	32px	0 12px	13px	Inline actions, table rows
Medium (md)	40px	0 20px	14px	Default, forms, cards
Large (lg)	48px	0 24px	16px	Hero sections, prominent CTAs

1.4 Button with Icon

Icon size: 16px (sm), 18px (md), 20px (lg)
Icon gap from text: 8px
Icon-only button: 32px × 32px (sm), 40px × 40px (md)
Icon-only border-radius: 50% or 6px

2. Product Card Component

2.1 Product Card Anatomy

┌─────────────────────────────────────────┐
│  [Merchant Badge]              [Image]   │
│                                  1:1     │
│                                  aspect  │
├─────────────────────────────────────────┤
│  Brand Name (caption, muted)            │
│  Product Title (h4, 2 lines max)        │
│  ★★★★☆ 4.2 (1,234)                      │
│                                         │
│  $129.00                    [Buy Btn]   │
│  ↘ Price trend indicator if available  │
└─────────────────────────────────────────┘

2.2 Product Card Specifications

Container

Property	Value
Width	100% (fluid in grid)
Min-width	160px
Max-width	280px
Background	`#FFFFFF`
Border	1px solid `#E5E7EB`
Border-radius	`8px`
Padding	12px
Shadow	none (flat)
Hover border	`#0066FF`
Transition	150ms ease-out

Image Area

Property	Value
Aspect ratio	1:1 (square)
Object-fit	cover
Border-radius	`6px`
Background	`#F9FAFB`
Placeholder	Shimmer animation
Error state	Generic product icon
Min-height	160px

Merchant Badge

Property	Value
Position	Top-left of image
Background	Platform color or `#374151`
Text	`#FFFFFF`, Inter 500, 10px, uppercase
Padding	2px 6px
Border-radius	`4px`
Platform colors	Shopee `#EE4D2D`, Lazada `#0F1470`, Amazon `#FF9900`, generic `#6B7280`

Brand Name

Property	Value
Font	Inter 500, 12px
Color	`#6B7280`
Text transform	uppercase
Letter spacing	0.05em
Margin	0

Product Title

Property	Value
Font	Inter 600, 14px
Color	`#0A0E1A`
Line-height	20px
Max lines	2
Overflow	ellipsis
Margin	4px 0 0 0

Rating Display

Property	Value
Star color	`#F59E0B` (filled), `#E5E7EB` (empty)
Font	Inter 500, 12px
Text color	`#374151`
Format	★★★★☆ 4.2 (1,234)
Margin	6px 0 0 0

Price Display

Property	Value
Font	Inter 700, 18px
Color	`#0A0E1A`
Currency symbol	Before amount
Original price	Inter 400, 13px, `#9CA3AF`, strikethrough
Price trend	Icon + text, 12px, green (↓) / red (↑) / gray (→)

Buy/Action Button

Property	Value
Variant	Ghost or Primary
Size	Small (32px height)
Full width	Yes, in card footer
Icon	external-link or shopping-cart

2.3 Product Card States

State	Visual Change
Default	Base styles
Hover	Border `#0066FF`, slight shadow `0 4px 12px rgba(0,102,255,0.1)`
Loading	Skeleton shimmer on image and text areas
Out of Stock	Image opacity 0.6, "Out of Stock" overlay badge, button disabled
Price Unavailable	Price shows "Check site", button text "View"

2.4 Product Card Variants

Compact Card (List View)

Horizontal layout: image left (80px × 80px), details right
Padding reduced to 8px
Title single line

Comparison Card

Larger image (120px × 120px)
Extended details: shipping cost, delivery time
"Best Value" / "Fastest Shipping" highlight badges

Search Result Card

Includes confidence score indicator
Source attribution visible
"Add to compare" checkbox

3. Input Fields

3.1 Text Input

Property	Value
Background	`#FFFFFF`
Border	1px solid `#E5E7EB`
Border-radius	`6px`
Height	40px
Padding	0 12px
Font	Inter 400, 14px
Color	`#0A0E1A`
Placeholder	`#9CA3AF`
Focus	border `#0066FF`, box-shadow `0 0 0 3px rgba(0,102,255,0.1)`
Disabled	background `#F9FAFB`, text `#9CA3AF`
Error	border `#EF4444`, box-shadow `0 0 0 3px rgba(239,68,68,0.1)`
Transition	100ms ease-out

3.2 Search Input

Property	Value
Background	`#F9FAFB`
Border	1px solid `#E5E7EB`
Border-radius	`20px` (pill shape)
Height	40px
Padding	0 16px 0 40px (icon space)
Font	Inter 400, 14px
Icon	Search icon left, 18px, `#6B7280`
Clear button	Right side, appears when text present
Focus	background `#FFFFFF`, border `#0066FF`

3.3 Filter Input (Dropdown Select)

Property	Value
Background	`#FFFFFF`
Border	1px solid `#E5E7EB`
Border-radius	`6px`
Height	40px
Padding	0 32px 0 12px
Font	Inter 400, 14px
Chevron icon	Right, `#6B7280`
Focus	border `#0066FF`
Open state	Dropdown max-height 300px, scrollable

3.4 Range Slider (Price Filter)

Property	Value
Track	4px height, `#E5E7EB` background
Fill	`#0066FF`
Thumb	18px circle, `#0066FF`, white border
Thumb hover	scale(1.1)
Value display	Above thumb, Inter 500, 12px

3.5 Checkbox & Toggle

Checkbox

Property	Value
Size	18px × 18px
Border-radius	`4px`
Border	2px `#E5E7EB`
Checked bg	`#0066FF`
Checked icon	White checkmark, 12px
Focus	ring `rgba(0,102,255,0.3)`

Toggle Switch

Property	Value
Width	40px
Height	22px
Track off	`#E5E7EB`
Track on	`#0066FF`
Thumb	18px circle, white
Transition	200ms ease-out

3.6 Form Field States

State	Visual Change
Default	Base styles
Hover	Border `#9CA3AF`
Focus	Border `#0066FF`, blue ring
Disabled	Gray background, no interactions
Error	Red border, red ring, error message below
Success	Green border, green checkmark icon

3.7 Form Layout

Property	Value
Label	Inter 500, 14px, `#374151`, margin-bottom 6px
Helper text	Inter 400, 12px, `#6B7280`, margin-top 4px
Error message	Inter 400, 12px, `#EF4444`, margin-top 4px
Field gap	16px (space-4)
Section gap	32px (space-8)

4. Typography Tokens

4.1 Type Scale

Token	Size	Line Height	Weight	Tracking	Use
`display`	48px	56px	700	-0.02em	Hero headlines
`h1`	36px	44px	700	-0.01em	Page titles
`h2`	28px	36px	600	0	Section headers
`h3`	22px	30px	600	0	Subsection headers
`h4`	18px	26px	600	0	Card titles, component headers
`body-lg`	18px	28px	400	0	Hero body text
`body`	16px	24px	400	0	Body text
`body-sm`	14px	20px	400	0	Secondary descriptions
`caption`	12px	16px	500	0.02em	Labels, badges
`code`	14px	22px	400	0	Code blocks (monospace)

4.2 Color Tokens

Token	Light Mode	Dark Mode	Use
`text-primary`	`#0A0E1A`	`#F9FAFB`	Headlines, primary text
`text-secondary`	`#374151`	`#D1D5DB`	Body text
`text-muted`	`#6B7280`	`#9CA3AF`	Captions, metadata
`text-disabled`	`#9CA3AF`	`#6B7280`	Disabled states
`text-inverse`	`#FFFFFF`	`#0A0E1A`	Text on dark backgrounds
`text-link`	`#0066FF`	`#4D94FF`	Links, interactive text
`text-success`	`#10B981`	`#34D399`	Success messages
`text-warning`	`#F59E0B`	`#FBBF24`	Warning messages
`text-error`	`#EF4444`	`#F87171`	Error messages

4.3 Semantic Tokens

Token	Light Mode	Dark Mode	Use
`bg-primary`	`#FFFFFF`	`#0F0F1A`	Page background
`bg-secondary`	`#F9FAFB`	`#1A1A2E`	Card backgrounds
`bg-hover`	`#F3F4F6`	`#252540`	Hover states
`bg-active`	`#E5E7EB`	`#2D2D44`	Active/pressed states
`border-default`	`#E5E7EB`	`#2D2D44`	Default borders
`border-strong`	`#D1D5DB`	`#4B5563`	Emphasized borders
`accent`	`#0066FF`	`#4D94FF`	Primary accent
`accent-hover`	`#0052CC`	`#3B82F6`	Accent hover state
`accent-muted`	`#E8F1FF`	`#1E3A5F`	Accent backgrounds

5. CSS Variable Reference

:root {
  /* Colors - Light Mode */
  --color-primary: #0066FF;
  --color-primary-hover: #0052CC;
  --color-primary-active: #004099;
  --color-navy: #0A0E1A;
  --color-white: #FFFFFF;
  
  /* Semantic Colors */
  --color-success: #10B981;
  --color-warning: #F59E0B;
  --color-error: #EF4444;
  --color-info: #3B82F6;
  
  /* Neutral Colors */
  --color-gray-50: #F9FAFB;
  --color-gray-100: #F3F4F6;
  --color-gray-200: #E5E7EB;
  --color-gray-300: #D1D5DB;
  --color-gray-400: #9CA3AF;
  --color-gray-500: #6B7280;
  --color-gray-600: #374151;
  --color-gray-700: #1F2937;
  --color-gray-800: #111827;
  --color-gray-900: #0A0E1A;
  
  /* Text Colors */
  --text-primary: var(--color-gray-900);
  --text-secondary: var(--color-gray-600);
  --text-muted: var(--color-gray-500);
  --text-disabled: var(--color-gray-400);
  --text-inverse: var(--color-white);
  --text-link: var(--color-primary);
  
  /* Background Colors */
  --bg-primary: var(--color-white);
  --bg-secondary: var(--color-gray-50);
  --bg-hover: var(--color-gray-100);
  --bg-active: var(--color-gray-200);
  
  /* Border Colors */
  --border-default: var(--color-gray-200);
  --border-strong: var(--color-gray-300);
  
  /* Platform Brand Colors */
  --platform-shopee: #EE4D2D;
  --platform-lazada: #0F1470;
  --platform-amazon: #FF9900;
  --platform-qoo10: #5C2D91;
  --platform-generic: #6B7280;
  
  /* Spacing (4px base) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  --space-20: 80px;
  
  /* Border Radius */
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 8px;
  --radius-xl: 12px;
  --radius-full: 9999px;
  
  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
  --shadow-card-hover: 0 4px 12px rgba(0, 102, 255, 0.1);
  
  /* Typography */
  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', Consolas, monospace;
  
  /* Font Sizes */
  --text-xs: 12px;
  --text-sm: 14px;
  --text-base: 16px;
  --text-lg: 18px;
  --text-xl: 22px;
  --text-2xl: 28px;
  --text-3xl: 36px;
  --text-4xl: 48px;
  
  /* Font Weights */
  --font-normal: 400;
  --font-medium: 500;
  --font-semibold: 600;
  --font-bold: 700;
  
  /* Transitions */
  --transition-fast: 100ms ease-out;
  --transition-base: 200ms ease-out;
  --transition-slow: 300ms ease-out;
  
  /* Z-Index Scale */
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-modal-backdrop: 300;
  --z-modal: 400;
  --z-tooltip: 500;
}

6. Accessibility Requirements

All components must meet WCAG 2.1 AA standards:

Minimum 4.5:1 contrast ratio for normal text
Minimum 3:1 contrast ratio for large text (18px+ or 14px bold+)
Focus indicators visible on all interactive elements
Keyboard navigation support (Tab, Enter, Space, Escape)
ARIA labels on icon-only buttons
Form inputs associated with labels
Error messages linked to inputs via aria-describedby
Loading states announced via aria-live
Reduced motion respected via prefers-reduced-motion

7. Component Checklist

Before shipping any component, verify:

All variants implemented (primary, secondary, ghost, danger)
All states handled (default, hover, active, focus, disabled, loading)
All sizes implemented (sm, md, lg where applicable)
Dark mode support
RTL support (for future localization)
Keyboard accessible
Screen reader tested
Touch targets minimum 44px × 44px on mobile
Performance: no layout shift on load (CLS)
Animation respects prefers-reduced-motion

This document is part of the BuyWhere design system. Coordinate updates with the Head of Design (Iris). For implementation questions, tag the engineering team.