slide-overflow-fixer

name: slide-overflow-fixer description: | Fixes overflowing MDX slide content in Amaroad decks while keeping all content inside the inviolable area. Applies layout changes, media resizing, text and spacing tuning, and slide splitting as a last resort. Use when user says "overflow", "clipping", "content does not fit", "ha-mi-dashi", "slide contents are out of bounds", or "fix this slide layout". Key capabilities: prioritized fix strategy (layout > media > spacing > split), screenshot-based before/after verification, heading design preservation, safe-zone padding enforcement, and body text readability floor (1.8rem minimum).

Non-negotiable constraints

1. Do not change heading design.
2. Do not edit heading component implementation:
   • src/components/mdx/typography/Headings.tsx
   • src/components/mdx/typography/Headings.module.css
3. Do not override h1, h2, h3 style in MDX with inline styles.
4. Keep SlideFrame safe-zone paddings unchanged.
5. Keep non-heading text at 1.8rem or larger.
6. Do not use Tailwind utility classes inside slide MDX or src/components/mdx.

Workflow

1. Identify target scope

Collect:

• Deck name
• Slide file(s) under decks/<deck-name>/*.mdx
• Whether overflow appears in viewer, presenter, export, or all of them

Useful commands:

ls decks/<deck-name>/*.mdx | sort -V

2. Confirm overflow and locate the cause

1. Open the target slide in viewer/presenter.
2. Capture before state if needed:

pnpm exec tsx .claude/skills/nanobanana-image/scripts/capture-slide.ts \
  --deck <deck-name> \
  --slide <0-indexed-slide> \
  --output /tmp/<deck-name>-<slide>-before.png

3. Inspect which block causes overflow:

• long text block
• dense multi-column layout
• oversized chart/image/video
• wide table/code block
• large margins/gaps/paddings in custom JSX

3. Apply fixes in this priority order

1. Layout change (highest leverage)
2. Media scaling
3. Non-heading typography/spacing adjustment
4. Content split across slides (last resort, but preferred over unreadable text)

Detailed patterns: references/fix-patterns.md

4. Fix execution rules

• Start with the smallest change that resolves overflow.
• Preserve slide intent and visual hierarchy.
• If one slide remains overcrowded after reasonable tuning, split into 2 slides.
• Keep headings untouched in both style and component mapping.

5. Verify after each edit

Capture after state:

pnpm exec tsx .claude/skills/nanobanana-image/scripts/capture-slide.ts \
  --deck <deck-name> \
  --slide <0-indexed-slide> \
  --output /tmp/<deck-name>-<slide>-after.png

Pass criteria:

• No content is clipped.
• No content extends outside the safe zone.
• No collision with logo/copyright/page number overlays.
• Heading design unchanged.
• Body text remains readable (>= 1.8rem).

6. Report result

Report:

• Updated files
• Which fix pattern was used
• Why that pattern was selected
• Residual risk (if any) and next candidate adjustment

Examples

Example 1: Dense bullet list overflows bottom edge

User says: "Slide 05 content is clipped at the bottom."

Actions:

1. Capture a before screenshot of slide 05.
2. Read the MDX file and identify the overflow cause (12 bullet items in a single column).
3. Apply fix: convert single-column list to a two-column <Columns> layout.
4. Capture an after screenshot and confirm all content is visible within the safe zone.

Result: The 12 items display as two columns of 6, fitting inside the inviolable area with no clipping.

Example 2: Large chart pushes footer content off-slide

User says: "The bar chart on slide 10 collides with the page number overlay."

Actions:

1. Capture before screenshot of slide 10.
2. Identify that the chart container has no data-growable and uses a fixed height of 500px.
3. Apply fix: reduce chart height to 380px and add data-growable so it adapts to remaining space.
4. Capture after screenshot and confirm no collision with overlays.

Result: Chart fits within the content area, page number overlay is unobstructed, and the chart remains readable.

Troubleshooting

Heading style changed after fix

Symptom: After applying overflow fixes, headings look different (font size, weight, or decoration changed). Cause: Inline styles were applied to h1/h2/h3 elements, or heading component CSS was modified. Fix: Revert heading changes. Never override heading styles. Only adjust non-heading content (body text, images, layout, spacing).

Content still clips after reducing font size

Symptom: Text was reduced to 1.6rem but content still overflows. Cause: The minimum font size floor is 1.8rem. Going below this violates readability rules and still does not solve deep overflow. Fix: Do not reduce below 1.8rem. Instead, split the slide into two slides or restructure the layout (e.g., columns, accordion, or tab pattern).

Before/after screenshot capture fails

Symptom: capture-slide.ts returns an error or blank image. Cause: The dev server is not running or the slide index is incorrect (0-indexed). Fix: Start the dev server with pnpm dev, then confirm the correct 0-indexed slide number by counting files in decks/<deck>/*.mdx sorted by name.