Viewer Design Craft — Visual Excellence Standards
Extracted from Vercel Web Interface Guidelines, Designing Beautiful Websites (Tristan Manchester), and UI/UX Pro Max. Adapted for GatorSquare Studio viewer context.
When to Use
Every time you touch viewer CSS, gallery HTML, or any user-facing surface. This is not optional reference — it's the quality floor.
The Standard
Make the next action obvious. Build from user goals upward. Systemise visuals. Validate early.
The question is never "does it work?" The question is: would someone screenshot this and share it?
Design Philosophy (from Anthropic frontend-design)
Reject generic. Commit to a BOLD aesthetic direction.
Every project gets an intentional aesthetic — not a template. Before touching CSS, choose a tone:
- Brutally minimal, maximalist, retro-futuristic, organic, luxury, editorial, brutalist, art deco, industrial/utilitarian
The key is intentionality, not intensity. Both bold maximalism and refined minimalism succeed when executed with clear conceptual direction.
Typography: Avoid generic choices (Inter for everything). Select distinctive display fonts paired with refined body. Characterful > safe.
Color: Dominant colors with sharp accents outperform timid palettes. Use CSS variables. Create atmosphere through contextual backgrounds, not solid colors.
Motion: Prioritize high-impact moments — one well-orchestrated page entrance with staggered reveals — over scattered micro-interactions.
Anti-patterns: Overused fonts, cliched color schemes (purple gradients), predictable layouts, cookie-cutter patterns. If it looks like every other AI-generated site, it's wrong.
From Stitch (Google Labs): Use evocative color names, not generic ("Ocean-deep Cerulean" not "blue"). Describe geometry in physical terms ("Pill-shaped" not "border-radius: 20px"). Design documentation should convey character and context.
Design Token System
Spacing Scale (px) — pick from this, no ad-hoc values
0, 4, 8, 12, 16, 24, 32, 48, 64, 96, 128
- Inside-group spacing < between-group spacing (this creates visual grouping)
- The 8px grid is the foundation. Everything aligns to multiples of 8.
Typography Scale
| Size | Role | Line-height |
|---|
| 12px / 0.75rem | Caption, metadata, panel count | 1.4 |
| 14px / 0.875rem | Small body, labels, tags | 1.5 |
| 16px / 1rem | Body default | 1.6 |
| 20px / 1.25rem | Subheading, scene title | 1.5 |
| 24px / 1.5rem | h3, section header | 1.4 |
| 30px / 1.875rem | h2, intro subtitle | 1.3 |
| 40px / 2.5rem | h1, intro title | 1.2 |
Rules:
- Body line-height: 1.5–1.7 for readability
- Line length: 45–80 characters (the 10-word rule)
- Use weight/color/spacing before inventing new sizes
font-variant-numeric: tabular-nums for any numbers/coststext-wrap: balance on headings to prevent orphan words
Color Architecture
- Define shades upfront (100–900), never ad-hoc lightens/darkens
- One primary accent per style (brass for default, crimson for dossier, gold for picture-book)
- Semantic accents: success (green), warning (amber), error (red)
- Contrast minimum: 4.5:1 for normal text, 3:1 for large text (WCAG AA)
- Consistent color temperature — warm greys OR cool greys, never mixed
Shadow / Elevation
Level 0: Flat (default cards)
Level 1: 0 1px 3px rgba(0,0,0,0.12) — subtle lift (gallery cards)
Level 2: 0 4px 16px rgba(0,0,0,0.15) — popovers, dialogue boxes
Level 3: 0 8px 32px rgba(0,0,0,0.2) — modals, review panel
Level 4: 0 16px 48px rgba(0,0,0,0.25) — overlays, focus states
CSS Rules (Non-Negotiable)
Transitions
/* NEVER this: */
transition: all 0.3s ease;
/* ALWAYS list properties explicitly: */
transition: opacity 0.3s ease, transform 0.3s ease;
- Only animate
transform and opacity (compositor-friendly, no layout thrash)
- Set correct
transform-origin for every animation
- Duration: 150–300ms for interactions, 400–800ms for page transitions
- Honor
prefers-reduced-motion — provide reduced variant or disable
Layout
- Flex/grid preferred over absolute positioning when possible
- No layout reads in render (
getBoundingClientRect, offsetHeight)
overflow-x: hidden on body to prevent unwanted horizontal scroll- Scrollable containers:
scrollbar-width: thin + scrollbar-color
Images
- Always set
width and height attributes (prevents CLS)
object-fit: contain for illustrations, cover for atmospheric photos- Never stretch low-res images — if 512px, constrain to natural size
Focus & Interaction
- All interactive elements need visible focus:
focus-visible ring
- Never
outline: none without replacement
- Touch targets: minimum 44x44px
touch-action: manipulation (prevents double-tap delay)
Viewer-Specific Patterns
Gallery Cards
Must have:
├─ Hero image or typographic fallback (NEVER broken image placeholder)
├─ Hover effect: translateY(-4px) + shadow lift (Level 2 → Level 3)
├─ Title: readable, not truncated. Max 2 lines with line-clamp
├─ Subtitle: the hook — 0.75+ opacity, not invisible
├─ Tags: 2-3 max visible, overflow hidden
├─ NO production data (cost, panel count) on gallery-facing cards
└─ Transition: transform 0.2s ease, box-shadow 0.2s ease
Intro Screens
Must convey:
├─ The MOOD of the content (dark = serious, cream = gentle, black = cinematic)
├─ Title hierarchy: title > subtitle > action button > metadata
├─ Production data (cost, panel count) hidden or extremely subtle
├─ "Begin" button is the clear primary action
└─ Brand label ("GATORSQUARE STUDIO") subtle, not competing with title
Reading Experience
Every moment transition must feel intentional:
├─ Image crossfade: 0.6–0.8s with ease-out (not linear)
├─ Text entrance: slight translateY + opacity fade (not instant)
├─ Scene number: ambient background element, not UI noise
├─ Speaker badge: hidden when show_speaker_badge is false — ENFORCED
├─ Typewriter: delightful under 100 chars, skip over 300 chars
└─ Progress bar: nearly invisible, just enough to orient
Text-Only Content
When there are no images:
├─ Text IS the visual — typography carries everything
├─ Full viewport width, generous padding (5-6rem sides)
├─ Two-column for dense content (column-count: 2, column-gap: 4rem)
├─ Markdown must render as HTML (bold, tables, code blocks, headers)
├─ Scrollable — overflow-y: auto on the container
├─ Scene numbers as large faint background elements
└─ Pull quotes, section breaks, accent lines for visual rhythm
Dialogue / Picture Book
Text OVER the image, not beside it:
├─ Floating dialogue box: rounded, semi-transparent, backdrop-blur
├─ Centered at bottom of viewport
├─ Warm cream for children's content, dark glass for noir
├─ Large text (1.5rem+), generous line-height
├─ No avatar, no speaker label for narrator-only
└─ The box should feel like part of the illustration
| Anti-Pattern | Why It's Wrong | Fix |
|---|
transition: all | Layout thrash, unpredictable | List specific properties |
| Broken image placeholder | Looks like an error | Typographic fallback card |
| "$0.00" on gallery card | Screams "this was free" | Hide or gate behind debug param |
Raw markdown **text** | Literal asterisks on screen | Parse markdown to HTML |
| Text in 40% side panel when no image | Half the screen wasted | Full-width typographic layout |
| Same visual treatment for all projects | AI slop signal | Content-adaptive styles |
| NARRATOR badge on pure-narrator | UI noise, chat-app feel | Hide when show_speaker_badge: false |
| Typewriter on 400-word blocks | 15-second wait to read | Instant render over threshold |
outline: none without focus-visible | Accessibility violation | Add visible focus ring |
| Hard color splits (solid panel edge) | Cheap, presentational | Gradient bleed between zones |
Before-and-After Verification Protocol
EVERY CSS change requires this:
1. BEFORE: Take mental snapshot of current state
2. CHANGE: Make the CSS edit
3. AFTER: Refresh and compare
4. ASK: Is this actually better? Not different — BETTER.
5. If worse or uncertain → REVERT IMMEDIATELY
6. If better → keep and document what improved
Never ship CSS changes without visual verification. Code that looks correct in the editor can look terrible in the browser. The browser is the only judge.
The Taste Test
Before declaring any viewer work complete, answer these:
- Would you screenshot this and post it on Twitter/X?
- Does every project look DIFFERENT from each other?
- Could this be mistaken for a generic template? If yes — not done.
- Is there anything on screen that makes you wince? Fix it.
- Show it to someone who doesn't know what GatorSquare is — do they say "that looks nice"?
If you can't answer yes to all five, keep working.