Slide Deck Builder — Technical Instructions

slide-guidelines.md

1. Tech Stack

2. Project Structure

slides/
├── index.html
├── package.json
├── vite.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── public/
│   └── images/          # All slide images go here
├── src/
│   ├── main.tsx
│   ├── App.tsx          # Slide deck shell, navigation, keyboard controls
│   ├── index.css        # Tailwind imports + custom fonts + base styles
│   ├── slides/
│   │   ├── index.ts     # Export ordered array of all slides
│   │   ├── 01-intro.tsx
│   │   ├── 02-problem.tsx
│   │   └── ...          # One file per slide or small group of related slides
│   ├── components/
│   │   ├── SlideLayout.tsx      # Shared slide wrapper (scaling, padding, background)
│   │   ├── AnimatedText.tsx     # Reusable text entrance animations
│   │   ├── Chart.tsx            # Recharts wrapper
│   │   ├── ImageSlide.tsx       # Image display component
│   │   ├── InteractiveBlock.tsx # For custom interactive UI per slide
│   │   └── ...
│   └── lib/
│       ├── animations.ts    # Shared Framer Motion variants and transitions
│       ├── theme.ts         # Color palette, font sizes, spacing tokens
│       └── useSlideScale.ts # Hook for viewport-fitting scale

3. Style Discovery — Mood & Presets

Step 1: Ask the User for Mood

Step 2: Pick a Style Preset

Dark Presets

#1a1a1a

#FF5722

#0a0a0a

#4361ee

#0066ff

#1a1a2e

#d4ff00

#0f0f0f

#d4a574

#e8b4b8

Light Presets

#f8f6f1

#2d2d2d

#c8d9e6

#faf9f7

#f5f3ee

#1a1a1a

#e8d4c0

#ff3300

Specialty Presets

#0a0f1c

#00ffcc

#ff00aa

#0d1117

#39d353

#faf9f7

#1a1a1a

#c41e3a

Step 3: Apply the Preset

src/lib/theme.ts

src/index.css

• All colors from the preset
• Font families loaded from Google Fonts or Fontshare
• CSS variables for backgrounds, accents, text colors
• Use the preset's signature elements in at least the title slide and section transitions

4. Design System — Anti AI-Slop Rules

Typography

• Use the font pairing from your chosen preset. Load from Google Fonts or Fontshare via

  @import

  in CSS.
• No more than 2 font families.
• Headlines: large and bold. Body text: scarce.
• Never center-align body paragraphs. Left-align or use deliberate layout.
• ALL font sizes must use

  clamp(min, preferred, max)

  — never fixed px/rem for text. This ensures readability across viewport sizes.

/* Example clamp values */
--title-size: clamp(2rem, 6vw, 5rem);
--subtitle-size: clamp(0.875rem, 2vw, 1.25rem);
--body-size: clamp(0.75rem, 1.2vw, 1rem);

Color & Backgrounds

• Commit fully to your preset's palette. Define as CSS custom properties.
• Create atmosphere, not flat colors. Layer CSS gradients for depth instead of a single solid background color:

/* Layered gradient for depth */
background:
  radial-gradient(ellipse at 20% 80%, rgba(120, 0, 255, 0.15) 0%, transparent 50%),
  radial-gradient(ellipse at 80% 20%, rgba(0, 255, 200, 0.1) 0%, transparent 50%),
  var(--bg-primary);

/* Subtle grid pattern for structure */
background-image:
  linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
  linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
background-size: 50px 50px;

• Dominant colors with sharp accents outperform timid, evenly-distributed palettes.

Layout — Scaled Slide Container

• The slide is a fixed 1280×720px container scaled via CSS

  transform: scale()

  to fit the viewport (like reveal.js). All content is authored at 1280×720 and uniformly scaled.
• Because of transform scaling, Tailwind's rem-based spacing appears smaller on screen. For any element that needs visible padding (cards, chips, buttons with backgrounds), use inline

  style={{}}

  with px values instead of Tailwind padding classes.
• Minimum padding for elements with a background:

  style={{ padding: '20px 48px' }}

  for horizontal chips,

  style={{ padding: '24px 32px' }}

  for content cards,

  style={{ padding: '16px 32px' }}

  for buttons.
• Generous whitespace. Content should breathe.
• Max 60% of the slide area should contain content. The rest is intentional empty space.
• Use CSS Grid or Flexbox. Avoid absolute positioning unless for decorative elements.
• The

  SlideLayout

  component handles the scaling + centering.

Content Density Limits (NON-NEGOTIABLE)

Visual Rules — Backgrounds & Borders

• Do NOT wrap text content in background cards. Let text sit directly on the slide background. Use spacing and typography for hierarchy, not boxes.
• No nested backgrounds. Never put one colored box inside another.
• When an element MUST have a background (interactive buttons, chips, tags): use

  bg-white/5

  with

  border border-white/10

  — never solid surface colors.
• Borders must be subtle. Use

  border-l border-muted/20

  for left accents, never

  border-l-2

  . Use

  border border-white/10

  for containers.
• No drop shadows unless it's a hard shadow (offset, no blur) as a specific design choice.
• No rounded-full badges with gradient backgrounds.
• No decorative blobs, waves, or mesh gradients.
• Geometric accents are OK: lines, dots, simple shapes.

DO NOT USE — Banned AI Patterns

#6366f1

What Makes It NOT Feel AI-Slop

• Asymmetric layouts (not everything centered in a stack)
• Oversized typography for emphasis
• Deliberate use of negative space
• Content that has opinion and edge, not generic filler
• Consistent but not monotonous — vary slide layouts across the deck
• Real images and data, not placeholder illustrations
• Surprise the viewer — make at least 1-2 unexpected layout choices per deck

5. Animation — Feeling-Driven Motion

Match Animation to Mood

Framer Motion Defaults

• Default duration: 0.4–0.6s. Avoid animations longer than 0.8s (unless cinematic mood).
• Default easing:

  [0.25, 0.1, 0.25, 1]

  (smooth deceleration, equivalent to

  ease-out-expo

  )
• Stagger children by 0.08–0.12s, not more

Slide Transitions

• Use

  AnimatePresence

  with

  mode="wait"

  for slide changes
• Slide enter: fade in + subtle translateY (20px) or translateX (30px)
• Slide exit: fade out quickly (0.2s)
• Do not use 3D transforms, rotations, or scale bounces for slide transitions

Content Animations (within a slide)

• Headline: fade in + translateY, arrives first
• Supporting content: staggered fade in after headline
• Charts/images: fade in + subtle scale from 0.95 to 1
• Use

  variants

  pattern for orchestrated animations:

const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: { staggerChildren: 0.1 }
  }
};

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0, transition: { duration: 0.5, ease: [0.25, 0.1, 0.25, 1] } }
};

Progressive Reveal

• Some slides should reveal content in steps (click to advance within a slide)
• Track a

  step

  state per slide when needed
• Animate items in/out based on current step
• Show a subtle progress indicator (dots or a thin bar) when a slide has multiple steps

What NOT to Do

• No

  spring

  with high bounce (underdamped springs look toyish)
• No

  rotate

  animations on text
• No continuous looping animations (except very subtle pulsing on interactive elements)
• No parallax scrolling within slides
• No animation on every single element — some things should just be there
• One well-orchestrated entrance per slide beats scattered micro-interactions

prefers-reduced-motion

Support

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const item = prefersReducedMotion
  ? { hidden: { opacity: 0 }, show: { opacity: 1 } }
  : { hidden: { opacity: 0, y: 20 }, show: { opacity: 1, y: 0, transition: { duration: 0.5 } } };

6. Slide Types & Components

Title Slide

• Oversized headline using

  clamp(2.5rem, 6vw, 5rem)

• Optional subtitle
• Optional date or presenter name
• Minimal, dramatic layout
• Use preset's signature element (colored card, split panel, geometric shape, etc.)

Content Slide (Text)

• Headline + 2–5 short bullet points or a short paragraph
• Bullets should animate in with stagger
• Left-aligned text, right side can have supporting visual
• Max 4-6 bullets. Exceeds? Split into two slides.

Image Slide

• Full-bleed or large contained image
• Images are placed in

  public/images/

  by the user
• Reference as

  /images/filename.ext

• Image max-height: 60% of slide height (432px at 720px)
• Support caption text below or overlaid with semi-transparent background
• Lazy load images

Chart Slide

• Use Recharts (BarChart, LineChart, PieChart, AreaChart)
• Style charts to match the deck theme — custom colors from preset, no default Recharts styling
• Animate chart entrance with Framer Motion wrapper
• Include clear labels and a headline

Comparison Slide

• Side-by-side or before/after layout
• Use a clear visual separator (accent line, not a heavy border)
• Animate left then right panel

Quote / Callout Slide

• Large text using

  clamp(1.5rem, 3vw, 2.5rem)

  , centered or left-aligned
• Accent color or background
• Attribution below in smaller text
• Max 3 lines for the quote.

Interactive Slide

• For slides that need custom UI (polls, toggles, demos, games)
• Build as self-contained components with local state
• Add

  data-interactive

  attribute to prevent accidental slide navigation on click
• Add clear visual affordance that something is interactive (hover states, cursor)

Link References

• External URLs: render as styled links that open in new tab (

  target="_blank"

  )
• Local folder links: render as

  file:///

  protocol links with a folder icon
• Style links distinctly — underline + accent color, not default blue

7. Navigation & Controls

• Keyboard: Right arrow / Space / Enter = next, Left arrow = previous
• Click/Tap: Click right half = next, click left half = previous (skip elements with

  data-interactive

  ,

  button

  ,

  input

  )
• Progress bar: Thin bar at bottom showing position in deck
• Slide counter: Small "3 / 28" indicator in bottom-right corner
• Support

  step

  sub-navigation within slides before advancing to next slide
• Escape key: Toggle overview mode (grid of slide thumbnails) — nice to have, not required for v1

8. Content Guidelines

slide-guidelines.md

• Problem → Discussion → Concept → Example → Takeaway cycle
• One idea per slide
• Visual-first, minimal text
• Short headlines (6–8 words)
• Progressive reveal for complex information
• 60-70% visual slides, 10-15% charts/diagrams, 15-20% text explanation

9. Build & Run

npm create vite@latest . -- --template react-ts  # Only if starting fresh
npm install
npm run dev

npm run dev

10. Quality Checklist

• npm run dev

  starts without errors
• TypeScript compiles cleanly (

  npx tsc --noEmit

  )

• npx vite build

  succeeds
• All animations are smooth at 60fps
• Slides fit within 1280×720 — no content overflow, no scrolling
• Content density within limits per slide type
• No placeholder text like "Lorem ipsum" or "Your content here"
• Color palette is consistent and matches chosen preset
• Fonts are loading correctly from Google Fonts / Fontshare
• Images referenced in slides exist in

  public/images/

• Interactive elements have hover/focus states
• Navigation works: keyboard, click, and progress bar are in sync
• No text content wrapped in background cards — text sits on slide directly
• No nested backgrounds (box inside box)
• All elements with backgrounds have generous padding via inline `style={{}}``, not Tailwind classes
• Borders are subtle —

  border-white/10

  ,

  border-muted/20

  , never solid surface colors
• All font sizes use

  clamp()

  — no fixed px/rem for text
• Backgrounds have depth — layered gradients or patterns, not flat solid colors

11. Workflow

1. Ask the user for mood and content — what feeling? What topic? How many modules?
2. Pick a style preset — suggest 2-3 based on mood, let user choose
3. Scaffold the app — set up Vite, Tailwind, Framer Motion, project structure, theme from preset, shared components
4. Build slides in batches — implement 5–10 slides at a time, then ask for review
5. Iterate — adjust based on feedback
6. Images — when a slide needs an image, tell the user what image is needed and where to place it (

   public/images/

   ). Use a visible placeholder with the filename so they know what's missing.