# 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.