whatisthatbook-design-guidelines.md

Design Guidelines

Theme: Vintage Bookshop

WhatIsThatBook uses a vintage bookshop aesthetic — warm, nostalgic, and inviting. The design evokes the feeling of browsing dusty shelves in a cozy indie bookstore and discovering forgotten treasures.

Color Palette

All colors are defined as CSS variables in src/app.css using OKLCH color space:

Variable	Hex Approx	Usage
--book-cream	#faf7f2	Primary background
--book-paper	#f5f0e6	Card backgrounds, secondary surfaces
--book-ink	#2d2319	Primary text
--book-ink-light	#5c4a3d	Secondary text
--book-ink-muted	#8a7d72	Muted text, hints, placeholders
--book-spine	#8b3a3a	Primary accent (burgundy), CTAs
--book-spine-hover	#6d2d2d	Hover states for primary buttons
--book-gold	#b8860b	Highlights, ratings, decorative
--book-sage	#6b8e6b	Success states, match indicators
--book-rust	#a65d3f	Secondary accent
--book-border	—	Warm border color

Typography

Variable	Value	Usage
--font-display	'Playfair Display', Georgia, serif	Headlines, book titles
--font-body	'Source Serif 4', Georgia, serif	Body text, descriptions
--font-ui	'DM Sans', system-ui, sans-serif	Buttons, labels, small text

Utility classes:

• .font-display — Display/headline typography
• .font-body — Body text typography
• .font-ui — UI element typography
• .book-title — Elegant serif with tight tracking for titles
• .book-body — Readable serif for body content
• .book-ui — Clean sans-serif for UI elements
• .book-muted — Muted text style
• .book-quote — Italic serif for quotes/inspirations

shadcn Component Variants

IMPORTANT: When adding new shadcn components, always add book variants to maintain design consistency. See existing components for reference.

Button

<script>
	import { Button } from '$lib/components/ui/button';
</script>

<!-- Primary action (burgundy) -->
<Button variant="book">Find My Book</Button>

<!-- Secondary action (outlined) -->
<Button variant="book-outline">View Details</Button>

<!-- Tertiary action (ghost) -->
<Button variant="book-ghost">Cancel</Button>

<!-- Special highlight (gold) -->
<Button variant="book-gold">Premium Feature</Button>

Card

<script>
	import * as Card from '$lib/components/ui/card';
</script>

<!-- Standard book card -->
<Card.Root variant="book">Card content</Card.Root>

<!-- Card with hover lift effect (for interactive cards) -->
<Card.Root variant="book-hover">Interactive card content</Card.Root>

Input

<script>
	import { Input } from '$lib/components/ui/input';
</script>

<!-- Book-styled input -->
<Input variant="book" placeholder="Search..." />

Adding New shadcn Components

When installing a new shadcn component:

1. Install the component: bunx shadcn-svelte@latest add [component]
2. Add book variant(s) using tailwind-variants (tv)
3. Export the variant type and variants function from the index file
4. Document the new variants in this file

Example pattern for adding variants:

<script lang="ts" module>
	import { type VariantProps, tv } from 'tailwind-variants';

	export const componentVariants = tv({
		base: '/* base styles */',
		variants: {
			variant: {
				default: '/* default styles */',
				book: 'bg-book-paper border-book-border text-book-ink /* book theme styles */'
			}
		},
		defaultVariants: {
			variant: 'default'
		}
	});

	export type ComponentVariant = VariantProps<typeof componentVariants>['variant'];
</script>

Decorative Elements

Dividers

<!-- Ornamental divider -->
<div class="book-divider">
	<span class="text-book-gold">✦</span>
</div>

Surface with texture

<!-- Background with subtle texture -->
<div class="book-surface rounded-xl p-6">Background section</div>

Decorative symbols

Symbol	Usage
✦	Section dividers, footer
❧	Alternative divider
""	Quotation styling
★	Ratings (gold color)

Animation

Utility classes:

• .animate-fade-in-up — Fade in from below (0.5s)
• .animate-fade-in — Simple fade in (0.4s)
• .animate-scale-in — Scale up from 95% (0.3s)

Stagger delays:

• .delay-100 through .delay-500 — For staggered animations

Example usage:

<div class="animate-fade-in-up opacity-0">First element</div>
<div class="animate-fade-in-up opacity-0 delay-100">Second element (100ms delay)</div>

Component Patterns

Section Headers

<div class="mb-16 text-center">
	<div class="book-divider mx-auto mb-6 max-w-xs">
		<span class="text-book-gold">✦</span>
	</div>
	<h2 class="book-title mb-4 text-3xl text-book-ink md:text-4xl">Section Title</h2>
	<p class="book-body mx-auto max-w-2xl text-lg text-book-ink-light">Section description text</p>
</div>

Quote/Inspiration Cards

<Card.Root variant="book-hover" class="group relative p-6">
	<!-- Decorative quote mark -->
	<div class="font-display absolute -top-2 -left-1 text-6xl text-book-gold/20 select-none">"</div>
	<blockquote class="relative">
		<p class="book-quote text-book-ink-light">Quote text here...</p>
	</blockquote>
	<div class="mt-4">
		<span class="book-ui rounded-full bg-book-spine/10 px-3 py-1 text-xs text-book-spine">
			Category
		</span>
	</div>
</Card.Root>

Book Cards

• Use Card.Root variant="book-hover" for interactive cards
• Cover images with spine shadow effect
• Serif font for book titles (.book-title)
• Gold stars for ratings (text-book-gold)
• Sage green for match percentage badges

Icons

Use Lucide icons from @lucide/svelte:

• BookOpen — Book-related actions
• Search — Search functionality
• ExternalLink — External links
• Sparkles — AI/magic features
• CheckCircle — Success/completion

Dark Mode

Dark mode variables are defined in src/app.css under the .dark class. The palette inverts to warm dark tones while maintaining the vintage aesthetic.

Accessibility

• Maintain WCAG 2.1 AA contrast ratios
• Use book-ink on book-cream/paper for sufficient contrast
• Focus states use --book-gold ring color
• Interactive elements have clear hover/focus states

Language/Copy

Use warm, book-related vocabulary:

• "Find" instead of "search"
• "Discover" instead of "results"
• "Remember" instead of "recall"
• "Forgotten favorites" for rediscovered books
• "Book lovers" for users

whatisthatbook-extraordinary-design.md

Extraordinary Design Philosophy

A guide for creating memorable, distinctive UI that breaks from convention while remaining functional.

Core Principle

Don't design interfaces. Design experiences that happen to be interfaces.

Most websites look the same because designers ask "what do other websites do?" Instead, ask: "What real-world experience does this feel like?"

The WhatIsThatBook Approach

1. Find the Physical Metaphor

Before designing any component, identify a real-world object that matches your brand:

Instead of...	Think...
Navigation menu	Bookshelf with book spines
Mobile drawer	Library card catalog
Buttons	Bookmarks, stamps, wax seals
Cards	Index cards, book covers
Loading states	Page turning, bookmark sliding
Empty states	Empty shelf, blank journal page

2. Make It Interactive Like the Real Thing

Once you have the metaphor, ask: "How would I interact with the real object?"

Book spine navigation:

• Real: Pull book from shelf, tilt to see cover
• Digital: Hover lifts book, rotates to reveal cover with horizontal text

Card catalog:

• Real: Pull open drawer, flip through cards
• Digital: Slide-out panel, cards with colored tabs

3. The "Push It" Test

After your first design, ask: "Is this what most websites do?"

If yes, push further:

❌ Horizontal nav with text links
↓ push
⚠️ Styled tabs with hover effects
↓ push again
✅ Book spines that pull out and rotate to reveal covers

4. Micro-Interactions That Delight

Every interaction is an opportunity:

• Hover: Don't just change color. Move, tilt, lift, glow.
• Click: Provide satisfying feedback. A book being pulled, a stamp pressing down.
• Transitions: Things don't just appear/disappear. They slide, fade, rotate with purpose.

5. Details That Nobody Asked For

These make the difference between "nice" and "memorable":

• Gold foil dots on book spines
• Decorative ✦ flourishes
• "Est. 2025" like a real shop sign
• "Happy reading" in the mobile menu footer
• Texture lines that suggest aged paper
• Inner shadows that create depth

Nobody will consciously notice these. Everyone will feel them.

Practical Framework

When designing a new component:

1. Name the metaphor: "This isn't a modal, it's a **_**"
2. Sketch the real thing: How does it look? How does it move?
3. Identify interaction points: What do you touch? What responds?
4. Add unnecessary details: What would a craftsman add that a factory wouldn't?
5. Test the "screenshot test": If someone sees a screenshot, will they remember it?

Examples

Navigation (What We Built)

Metaphor: Bookshelf with books
Interaction: Pull book → tilt to see cover
Details: Spine texture, gold foil, bookend, shelf edge shadow
Result: Memorable, on-brand, still perfectly functional

Future Ideas

Search input:

• Metaphor: Library request slip
• Interaction: Writing on aged paper, submit stamps it
• Details: Faded lines, pencil texture, ink stamp animation

Results list:

• Metaphor: Stack of recommended books from librarian
• Interaction: Books slide in one by one, can be "picked up"
• Details: Slight rotation variety, shadow underneath, dog-eared pages

404 page:

• Metaphor: Lost in the stacks
• Interaction: Towering bookshelves, wrong aisle
• Details: Dust particles, dim lighting, "ask the librarian" link

Loading state:

• Metaphor: Flipping through pages to find the right one
• Interaction: Animated page flip
• Details: Paper sound effect (optional), page corner curl

Anti-Patterns

Things that kill extraordinary design:

• "Users expect..." — Users expect to accomplish their goal. How you get them there is your creative space.
• "Keep it simple" — Simple doesn't mean boring. A book spine is simpler than a hamburger menu icon (it's literally a rectangle).
• "We don't have time" — Extraordinary often takes the same code as ordinary, just different CSS values.
• "It's not accessible" — Extraordinary and accessible aren't opposites. Our book spines are just links with creative styling.

The Feeling Test

When someone uses your interface, they should feel something specific.

WhatIsThatBook should feel like:

• Walking into a cozy indie bookshop
• The smell of old pages
• A knowledgeable friend who loves books
• Discovery and nostalgia
• Warmth, not clinical efficiency

Every design decision should be tested against this feeling.

---

"The details are not the details. They make the design." — Charles Eames