Slide-by-Slide Design Protocol

What this file covers: Per-slide design protocol, slide structure, what each slide contains, generation modes.

Per-Slide Protocol (MANDATORY for EVERY Slide)

Step 1: Announce Checkpoint

Before writing each slide section, announce what you're about to do:

SLIDE ID: [slide-id] — [Type Name]
Action: generate-new
Layout: [full-width | two-column | centered] | Components: [list of TSX patterns used]

Example announcements:

SLIDE ID: "step-1" — Step 1 Question + CFU
Action: generate-new
Layout: centered | Components: TitleZone, ContentBox, CfuAnswerCard

SLIDE ID: "problem-setup" — Problem Setup
Action: generate-new
Layout: two-column | Components: TitleZone, ContentBox, SVG visual
Graph: Use graph patterns → modify for X_MAX=10, Y_MAX=100

Step 2: Determine Slide Type and Layout

CFU and Answer are separate slide IDs, not same-position overlays. Each step produces three slide IDs: "step-N", "step-N-cfu", and "step-N-answer".

The Duplication Test (MOST IMPORTANT LAYOUT DECISION)

This test is the #1 priority when choosing a layout. Every two-column slide must pass this test.

Before choosing two-column, ask: "Would I say the same thing on both sides?"

Example of duplication (BAD - use centered instead):

LEFT COLUMN               RIGHT COLUMN
"Meaning 1: How many      [Box: "Meaning 1:
slices per group?"         How many in each group?"]
"Meaning 2: How many      [Box: "Meaning 2:
groups?"                   How many groups?"]

This duplicates. The visual boxes say the same thing as the text. Use centered and let the diagram speak for itself with a brief subtitle.

Note: The number of step slides varies (S = 2-5 steps, default 3). Let S = number of steps.

Example with 3 steps (default): Slide IDs are "title", "problem-setup", "step-1", "step-1-cfu", "step-1-answer", "step-2", "step-2-cfu", "step-2-answer", "step-3", "step-3-cfu", "step-3-answer", "practice-1", "practice-2".

Layout Selection (step and practice slides):

For two-column layout (text + visual side-by-side):

• Left: Main content (36-48px) + Problem reminder at bottom left corner (max 15 words)
• Right: SVG visual or diagram
• Left and right must show DIFFERENT content
• Problem reminder uses ProblemReminder component

For centered layout (stacked hero content):

• Main: Large equation/diagram centered (hero element)
• Support: Brief text below (optional)
• Use when the diagram IS the teaching, not just supporting it

See styling/layout-presets.md for layout dimensions and examples.

Note: Practice problems appear in TWO places:

1. Practice slides (Preview): One problem per slide for whiteboard work (NO answers shown)
2. Printable: Both problems with space for written work + answer key

Step 3: Add CfuAnswerCard (Separate Slide IDs)

CFU and Answer are revealed via separate slide IDs, NOT same-position overlays. Each step gets its own CfuAnswerCard component with two controlling slide IDs.

Add a CfuAnswerCard for each step (steps 1 through S):

<CfuAnswerCard
  showCfu={show("step-1-cfu")}
  showAnswer={show("step-1-answer")}
  question="Why did I [VERB] first?"
  answer="Because [explanation in 25 words or fewer]."
/>

How progressive reveal works:

• On slide ID "step-1": Step 1 content appears. CfuAnswerCard is hidden.
• On slide ID "step-1-cfu": CFU question is revealed (yellow card). Step 1 content remains visible.
• On slide ID "step-1-answer": Answer is revealed (green card). CFU remains visible. Step 1 content remains visible.
• On slide ID "step-2": Step 2 content appears. All previous content (step-1, its CFU, its answer) remains visible.

The show() predicate is monotonic. Once show("step-1") returns true, it stays true on all subsequent slides.

Step 4: Compose Slides

For ALL slides in the deck visual:

1. ANNOUNCE checkpoint to user (plain text)
2. CHOOSE LAYOUT — use the duplication test to pick the best layout for this content
3. DESIGN the slide — use TSX component patterns and adapt freely:
   • TitleZone: Badge ("STEP N: [VERB]") + Title + optional Subtitle
   • ContentBox: Main text content (instructions, questions, explanations)
   • CfuAnswerCard: CFU and Answer with separate slide IDs
   • ProblemReminder: Condensed problem summary (max 15 words)
   • SVG visual: Graph or diagram (if visual slide)
4. ADD data-element-id attributes on <g> groups for fixture visibility testing
5. WRAP progressive elements in <Animated> components:

   <Animated segment="step-1" isVisible={s => show(s)} entrance="fade">
     {/* Step 1 content */}
   </Animated>
   

6. IF Visual Type = "coordinate-graph": Read technical-specs/svg-workflow.md FIRST
7. IF Visual Type = "diagram" (non-graph SVG): Read analysis/diagram-patterns.md FIRST
   • Includes: tape diagrams, hanger diagrams, double number lines, input-output tables, area models
   • Based on Illustrative Mathematics (IM) curriculum representations
8. VERIFY the pre-flight checklist (see checklists/pre-flight.md)

Step 5: Practice Problem Slides

For Practice slides ("practice-1" and "practice-2"), use the Problem Setup as a template but:

• Change title zone to: "PRACTICE PROBLEM [1/2]: [Scenario Name] [Icon]"
• Use the appropriate scenario's graphPlan/diagramEvolution:
  • "practice-1": Use scenarios[1] (Scenario 2)
  • "practice-2": Use scenarios[2] (Scenario 3)
• Include "Your Task:" section prominently with the question to solve
• NO CfuAnswerCard - students work independently on whiteboards
• Keep the same layout style as the worked example (two-column or centered)

Step 6: Generate Lesson Summary

After the printable is complete, generate a one-page lesson summary.

This is a printable reference card that students can use to quickly recall the main idea from this lesson. Use lesson-summary-snippet.html as the template.

Content to include:

1. Header: "LESSON SUMMARY" badge + lesson title + Grade/Unit/Lesson
2. Big Idea (hero section): Large, prominent statement from strategyDefinition.bigIdea
3. Strategy Steps: Numbered list of all moves (2-5, verb + description) from strategyDefinition.moves
4. Visual Reference (ALWAYS include):
   • For coordinate graph lessons: Small labeled graph showing the key concept (use Scenario 1's graphPlan, scaled down)
   • For diagram lessons: Simplified version of the diagram type
   • For text/table lessons: Compact worked example showing the strategy applied
5. Remember: 1-2 sentence key takeaway synthesized from learningGoals

Requirements:

• Single print-page div (one page, 8.5in x 11in)
• Uses Times New Roman font (matches printable worksheet)
• Must include print-page CSS class for print detection
• Keep it scannable - a student should grasp the key idea at a glance
• Visual should fit in ~40% of the page width

Visual Type Reference

Your visual type was determined in Phase 1. Here's what each requires:

Text-only:

• No graphics - pure text/equation problems
• Use ContentBox patterns only

HTML table:

• Simple data tables with highlighting
• Use <table> with inline styles inside SVG <foreignObject> or as a TSX component
• See ContentBox examples for table patterns

SVG visual (ALL other graphics):

• Coordinate planes and graphs
• Hanger diagrams and balance problems
• Geometric shapes and diagrams
• Number lines and bar models
• Any custom visual representation (coins, objects, arrays)

For SVG visuals:

1. Read technical-specs/svg-workflow.md for coordinate graphs
2. Read analysis/diagram-patterns.md for other diagram types
3. Wrap distinct element groups in <g data-element-id="..."> for fixture visibility testing

Using the Correct GRAPH PLAN

CRITICAL: Use EACH SCENARIO'S graphPlan, NOT the mastery check's graphPlan.

The mastery check (problemAnalysis.graphPlan) is for the student's exit ticket/assessment - it is NEVER shown in these slides. Each scenario has its own numbers/context, so each needs its own graphPlan:

Each GRAPH PLAN contains the semantic decisions for that scenario:

• Equations with correct slope/y-intercept for that scenario's numbers
• Scale (X_MAX, Y_MAX) appropriate for that scenario's values
• Line endpoints (startPoint, endPoint) calculated for that scenario
• keyPoints with correct coordinates for that scenario
• Annotations type and position

You MUST implement exactly what each scenario's GRAPH PLAN specifies. Do NOT use the mastery check's graphPlan. Do NOT recalculate or change the scale.

Context-Aware Generation Modes

Mode: Full (Default)

Generate the complete deck visual from scratch (contract.ts, visual.tsx, contract.test.ts).

Mode: Continue

Resume from where generation was interrupted.

• DO NOT regenerate completed slide sections
• Match style of existing slides exactly
• Start from next slide ID

Mode: Update

Regenerate only specific slide sections with targeted changes.

• Modify ONLY the slide IDs marked for update
• Maintain same structure as existing slides
• Keep existing data-element-id values stable

Output Format

The deck visual must:

• Be a valid React TSX component
• Render a 640x360 SVG viewport
• Use SlideSystem.show(activeSlideId) for progressive reveal
• Include data-element-id on <g> groups for fixture testing
• Use <Animated> components for entrance animations
• Use CfuAnswerCard with separate showCfu and showAnswer props

NEVER include in the visual component:

• Raw HTML documents or <!DOCTYPE html>
• Inline <script> tags or event handlers
• Direct DOM manipulation