680 lines
7.9 KiB
Markdown
680 lines
7.9 KiB
Markdown
# 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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
#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
|
||
|
||
```text
|
||
Manrope
|
||
```
|
||
|
||
Used for:
|
||
|
||
* Navigation
|
||
* Forms
|
||
* Tables
|
||
* Metadata
|
||
* Prices
|
||
* Statuses
|
||
* Body copy
|
||
|
||
## Display Font
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
Electric Cobalt
|
||
#1769FF
|
||
```
|
||
|
||
## Semantic Colors
|
||
|
||
Success:
|
||
|
||
```text
|
||
#12A150
|
||
```
|
||
|
||
Warning:
|
||
|
||
```text
|
||
#D88A00
|
||
```
|
||
|
||
Danger:
|
||
|
||
```text
|
||
#E5484D
|
||
```
|
||
|
||
Information:
|
||
|
||
```text
|
||
#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.
|
||
|
||
```text
|
||
4
|
||
8
|
||
12
|
||
16
|
||
24
|
||
32
|
||
48
|
||
64
|
||
96
|
||
```
|
||
|
||
Avoid arbitrary spacing values.
|
||
|
||
---
|
||
|
||
# Shape Language
|
||
|
||
Use controlled geometry.
|
||
|
||
Radius scale:
|
||
|
||
```text
|
||
4px
|
||
6px
|
||
8px
|
||
12px
|
||
16px
|
||
Full
|
||
```
|
||
|
||
Default card radius:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
1. Image
|
||
2. Name
|
||
3. Identity metadata
|
||
4. Condition / Grade
|
||
5. Price
|
||
6. 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:
|
||
|
||
```text
|
||
Grouped by collectible
|
||
```
|
||
|
||
Users may switch to:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
80–350ms
|
||
```
|
||
|
||
Respect reduced-motion preferences.
|
||
|
||
---
|
||
|
||
# Accessibility
|
||
|
||
Minimum standard:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
1. Use semantic tokens.
|
||
2. Preserve the collectible → data → branding hierarchy.
|
||
3. Favor reusable components.
|
||
4. Prioritize mobile usability.
|
||
5. Maintain accessibility.
|
||
6. Keep the interface visually restrained.
|
||
7. Let collectibles remain the visual focus.
|