7.9 KiB
DESIGN.md
Purpose
This document defines the visual design system, interaction principles, component expectations, and UI constraints for the collectibles platform.
The platform is category-independent and must support Pokémon, sports cards, comics, figures, sealed products, and future collectible categories without requiring a redesign.
When implementation details are ambiguous, prioritize:
Collectible
↓
Important Data
↓
Application Branding
The collectible and its data are always more important than the application itself.
Core Design Principles
The application should be:
- Minimal
- Clean
- Information-dense without clutter
- Accessible
- Responsive
- Consistent
- Component-driven
- Collector-focused
- Mobile-first
- Category-independent
The experience should feel:
- Premium
- Modern
- Precise
- Fast
- Purpose-built for collectors
Avoid:
- Generic SaaS styling
- Excessive decoration
- Rainbow UI design
- Marketplace-branded interfaces
- Gaming-style visual overload
Visual Direction
Theme
Monochrome + Electric Cobalt
Primary brand color:
#1769FF
Use Electric Cobalt for:
- Brand identity
- Focus states
- Selection states
- Interactive controls
- Navigation highlights
Do NOT use Electric Cobalt for:
- Prices
- Marketplace values
- Condition indicators
- Generic status indicators
Typography
Primary UI Font
Manrope
Used for:
- Navigation
- Forms
- Tables
- Metadata
- Prices
- Statuses
- Body copy
Display Font
Space Grotesk
Used for:
- Page titles
- Section headings
- Collectible names
- Display typography
Numeric Presentation
Use tabular numerals for:
- Prices
- Quantities
- Grades
- Market values
Color System
Brand
Electric Cobalt
#1769FF
Semantic Colors
Success:
#12A150
Warning:
#D88A00
Danger:
#E5484D
Information:
#1683C4
Rules:
- Never rely on color alone.
- Pair color with labels, icons, or text.
- Maintain WCAG 2.2 AA contrast compliance.
Controlled Luminescence
Glow is a branding tool.
Glow should be used sparingly.
Allowed:
- Focus
- Selection
- Primary action emphasis
Avoid:
- Constant glowing interfaces
- Price glow
- Status glow
- Decorative glow
Users may choose:
- Standard
- Reduced
- Off
Disabling glow must never remove focus visibility.
Spacing System
Use an 8px spacing system.
4
8
12
16
24
32
48
64
96
Avoid arbitrary spacing values.
Shape Language
Use controlled geometry.
Radius scale:
4px
6px
8px
12px
16px
Full
Default card radius:
12px
The mobile Add button is intentionally circular.
Layout Philosophy
Browsing
Collection browsing should feel spacious and visual.
Management
Inventory management should feel efficient and information-dense.
Rule:
Browsing breathes. Managing is efficient.
Responsive Design
Mobile is a first-class platform.
Do not design desktop first and collapse later.
Primary breakpoints:
640
768
1024
1280
1536
All major workflows must be usable on mobile.
Navigation
Use adaptive navigation.
Desktop:
- Sidebar navigation
Mobile:
- Bottom navigation
- Prominent circular Add action
The Add action is a signature interaction.
Component Architecture
Build reusable Vue components.
Examples:
- SearchBar
- CollectibleCard
- InventoryGroup
- InventoryCopyRow
- PriceDisplay
- ConditionBadge
- StatusBadge
- ImageGallery
- FilterPanel
- SortControl
- Modal
- Dialog
- BottomSheet
- FormField
- ValidationMessage
- DataTable
- EmptyState
- LoadingState
- ErrorState
- ActivityTimeline
- MarketValue
- MarketplaceSource
- TaskProgress
Rules:
- Single responsibility
- Reusable
- Accessible
- Domain logic belongs outside components
- Components consume semantic tokens, not raw colors
Collectible Presentation
Image Treatment
Use a gallery/museum presentation style.
Rules:
- Preserve aspect ratio
- Use contain by default
- Avoid unnecessary cropping
- Neutral image stages
- No cobalt image backgrounds
- No artificial image enhancements
Collectibles are the visual hero.
Card Structure
Default hierarchy:
- Image
- Name
- Identity metadata
- Condition / Grade
- Price
- Status
Cards should adapt to context rather than forcing a single universal layout.
Detail Pages
Use a hybrid detail page.
Primary section:
- Images
- Identity
- Price
- Condition
- Status
- Primary actions
Secondary sections:
- Overview
- Market
- Copies
- Listings
- Activity
Prices
Prices are important but not the hero.
Rules:
- Use tabular numerals
- Distinguish actual vs market values
- Distinguish source values vs converted values
- Do not make all prices green
Market Data
The system must support:
- Reference values
- Marketplace values
- Data freshness
- Provenance
- Mapping confidence
Users must be able to understand:
- Where a value came from
- When it was updated
- Whether it was calculated or imported
Condition, Grade, and Status
These are separate concepts.
Condition:
- Near Mint
- Lightly Played
- etc.
Grade:
- Certification provider
- Grade
- Certification number
Status:
- Inventory status
- Listing status
- Workflow status
Do not merge these concepts.
Collectible vs Physical Copy
The system distinguishes:
Collectible Identity
What the item is.
Physical Copy
The specific owned instance.
Copy-specific data includes:
- Condition
- Grade
- Images
- Acquisition data
- Storage
- Listings
- Notes
Never collapse meaningful copies into quantity-only inventory.
Multiple Copies
Default view:
Grouped by collectible
Users may switch to:
Individual copies
Both modes must be supported.
Category Hierarchy
Hierarchy is category-defined.
Examples:
- Set
- Series
- Product
- Issue
Do not hard-code Pokémon-specific concepts.
Collection Organization
Treat these separately:
Physical Location
Always private.
Examples:
- Binder
- Shelf
- Cabinet
- Vault
User Collections
Curated groupings.
A copy may belong to multiple collections.
Tags
Flexible labels.
Saved Views
Saved filters/configurations.
Search
Support:
- Global search
- Identification search
- Marketplace mapping search
Global search includes archived items.
Architecture should support future command-style search.
Forms
Rules:
- Persistent labels
- Progressive validation
- Progressive disclosure
- Draft protection
- Mobile-friendly inputs
Avoid placeholder-only forms.
Feedback States
Support:
- Loading
- Success
- Warning
- Error
- Empty
Use:
- Skeletons
- Toasts
- Inline validation
- Progress indicators
Avoid excessive animations.
Motion
Motion should communicate:
- Responsiveness
- Hierarchy
- State changes
Not decoration.
Target timing:
80–350ms
Respect reduced-motion preferences.
Accessibility
Minimum standard:
WCAG 2.2 AA
Requirements:
- Keyboard navigation
- Visible focus states
- Screen-reader support
- 44x44 touch targets
- No color-only meaning
- Reduced motion support
Accessibility is part of component acceptance criteria.
Privacy
Default:
Private
Visibility options:
- Private
- Public
- Custom
Provide:
- Public preview
- Visibility summaries
- Explicit visibility decisions
Storage locations must never be public.
Future Considerations
Architect so future support is possible for:
- Wishlist
- Price alerts
- Additional marketplaces
- Search commands
- Dashboard customization
Do not implement these unless specifically planned.
Implementation Rule
When generating UI:
- Use semantic tokens.
- Preserve the collectible → data → branding hierarchy.
- Favor reusable components.
- Prioritize mobile usability.
- Maintain accessibility.
- Keep the interface visually restrained.
- Let collectibles remain the visual focus.