feat: migrate visual fixtures to storybook

2026-09-08 21:43:26 -04:00
parent 41efdfe041
commit f7534d901b
69 changed files with 62947 additions and 589 deletions
@@ -1,43 +1,679 @@
-# Design System Direction
+# DESIGN.md

-## Principles
+## Purpose

- Minimal
- Clean
- Information-dense without clutter
- Accessible
- Responsive
- Consistent
- Component-driven
+This document defines the visual design system, interaction principles, component expectations, and UI constraints for the collectibles platform.

-## Component architecture
+The platform is category-independent and must support Pokémon, sports cards, comics, figures, sealed products, and future collectible categories without requiring a redesign.

-Build atomic/reusable Vue components.
+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
- ProductCard
- InventoryGroup
- InventoryCopyRow
- PriceDisplay
- ConditionBadge
- StatusBadge
- ImageGallery
- FilterPanel
- SortControl
- Modal/Dialog
- FormField
- ValidationMessage
- DataTable
- EmptyState
- LoadingState
- ErrorState
- ActivityTimeline

-Components should have clear responsibilities and avoid embedding domain business rules.
+* SearchBar
+* CollectibleCard
+* InventoryGroup
+* InventoryCopyRow
+* PriceDisplay
+* ConditionBadge
+* StatusBadge
+* ImageGallery
+* FilterPanel
+* SortControl
+* Modal
+* Dialog
+* BottomSheet
+* FormField
+* ValidationMessage
+* DataTable
+* EmptyState
+* LoadingState
+* ErrorState
+* ActivityTimeline
+* MarketValue
+* MarketplaceSource
+* TaskProgress

-## Visual decisions
+Rules:

-Exact color palette, typography, spacing tokens, and final visual styling can evolve during implementation, but must preserve accessibility and the documented information hierarchy.
+* Single responsibility
+* Reusable
+* Accessible
+* Domain logic belongs outside components
+* Components consume semantic tokens, not raw colors

-No color-only indication of state or condition.
+---
+
+# 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.
@@ -100,6 +100,7 @@ docker context use orbstack
 - The web catalog now provides keyboard-accessible listing cards with stable `/listings/:id` links, a public listing detail page, and service-level detail loading/error handling.
 - Catalog search and pagination are synchronized to the browser URL (`q` and `page`) with accessible previous/next controls; the web port `5173` is declared in the project port registry.
 - The web catalog includes a stable `/products/:slug` product detail route with API-backed loading, not-found/error states, and semantic product facts.
+- The visual design foundation is centralized in web tokens with light/dark/system runtime theme support; the fixture composition has moved to Storybook at port `6006` with the accessibility addon and component stories for available, pending, and sold states.
 - `ImageStorage`, traversal-safe local storage, multipart upload transport, and binary signature validation are implemented; derivative processing remains.
 - Derivative orchestration now defines thumbnail, medium, and large WebP storage outputs behind an injected renderer; the concrete worker-backed renderer remains.
 - The worker owns an image derivative job runner with explicit processing, completion, and failure outcomes; queue transport and persistent job records remain.