fragginwagon/pokemon-inventory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
pokemon-inventory/docs/DESIGN.md
T

7.9 KiB
Raw Permalink Blame History

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:

  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:

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:

  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.
Reference in New Issue View Git Blame Copy Permalink