beam-ai-team/beam-figma-to-html-slides

Beam Figma To HTML Slides

Overview

Use this skill to turn Beam Figma slide sources into editable HTML decks quickly and with high fidelity. Treat Figma as the visual source of truth, HTML as the editable template target, and the Beam design pack as the repeated design system.

For any real conversion, read references/conversion-playbook.md before editing. Use scripts/audit-html-deck.mjs after building or changing a deck, and scripts/build-source-comparison.mjs after rendering QA images.

Safety Contract

Require explicit user approval before publishing, sending, or committing converted customer-facing decks. Download only approved Figma assets, keep local asset paths portable, and record provenance for exported images and any simplifications.

Required Workflow

1. Establish the source set.

   • Identify the Figma file, page, section, and frame/node IDs.
   • Rename or record frames with human slide names when needed.
   • Capture slide-level references: frame ID, title, screenshot/source preview, and intended template role.

2. Extract before rebuilding.

   • Default to Figma get_design_context for each selected node when available; it returns coordinates, text, image asset URLs, and useful generated code in one pass.
   • Use Figma dev data when available: frame size, top/side padding, text sizes, card coordinates, fills, images, radii, strokes, effects, and component names.
   • Measure at source scale first. Most Beam slides are 1920x1080; the HTML prototype is usually 1600x900, so multiply Figma coordinates by 0.833333.
   • Do not start by inventing a generic Beam-dark layout. Preserve the source composition unless there is a specific reason to simplify.

3. Decide image vs HTML early.

   • Export from Figma when the object is a photo, product screenshot, background texture, complex rendered visual, logo strip, map, or high-fidelity diagram that carries meaning.
   • Rebuild in HTML when the object is text, headings, cards, bullets, metrics, tags, tables, simple charts, journey cards, pricing cards, or simple diagrams.
   • Split the difference when needed: keep the shell, title, labels, and captions editable; use an image only for the inner product/media crop.
   • If an image is blurry, content-light, or only decorative, rebuild or replace it rather than locking poor source quality into the template.
   • Download meaningful Figma MCP asset URLs immediately into the deck assets/ folder. Do not leave figma.com/api/mcp/asset URLs in production HTML because they expire.

4. Build the HTML deck.

   • Use a fixed 16:9 stage, usually 1600x900, with source-equivalent 80px padding.
   • Reuse the Beam dark background recipe unless the source slide has a meaningful exported background.
   • Keep titles, labels, cards, metrics, bullets, CTA bars, and most diagrams editable.
   • Use local assets only. Store assets next to the rebuild with provenance and crop intent.
   • Keep layouts stable: fixed card dimensions, explicit grids, and content zones that do not shift when copy changes.

5. Simplify only when necessary.

   • Simplify if exact fidelity depends on unsupported primitives, a source element is redundant, the source is too noisy for a reusable template, or the detail would become brittle in editable HTML.
   • Preserve the hierarchy and visual anchor even when simplifying.
   • Record every meaningful simplification in the conversion audit.
   • Do not simplify merely because a layout is harder to implement.

6. QA and iterate.

   • Run the audit script against the deck directory.
   • Render every slide to PNG and a contact sheet.
   • Build a side-by-side source comparison sheet.
   • Compare against Figma previews side by side before promotion.
   • Iterate on spacing, background, typography, asset crops, and vertical centering until the deck feels like the Figma source, not a generic dark-card rebuild.

Beam Defaults

• Source slide: 1920x1080.
• HTML prototype: 1600x900.
• Source padding: 100px; prototype padding: 80px.
• Customer-facing body/card copy minimum: 18px source, 15px prototype.
• Captions minimum: 12px prototype.
• Micro-labels minimum: 11px prototype.
• Font stack: Satoshi, Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif.
• Font weights must preserve Figma style names: Regular 400, Medium 500, Semi Bold/Semibold 600, Bold 700, Black 900. Do not collapse Black into Bold, and avoid fuzzy weights like 720 or 780 unless the source explicitly requires optical compensation and the audit explains why.
• Default background: match the Figma Background component: black base, centered blurred blue gradient layer, no visible grid. At source scale this is a 2341px wide layer over a 1920x1080 slide, blur(2px), vertical gradient from rgba(51,119,255,0) to rgba(51,119,255,.38), plus inset bottom glow 0 -48px 128px rgba(142,161,255,.4). At 1600x900 prototype scale, use about 1951px layer width and 0 -40px 107px inset glow. Some slides intentionally start the glow lower, around 53.7% source height.
• Default output files: index.html, manifest.json, conversion-audit.md, assets/, and qa/.

Audit Requirements

Every rebuild must leave a short audit that names:

• Figma file/page/section/frame IDs used.
• Which slide templates were rebuilt.
• Which elements are editable HTML.
• Which elements remain Figma-exported images.
• Which simplifications were made and why.
• Which Prism or Beam designer primitives are missing.
• Which QA checks were run and where the contact sheet lives.

Tool Notes

• When interacting with Figma through MCP, load and follow the Figma figma-use skill before any use_figma call.
• Prefer Figma node exports or dev measurements over screenshot guessing.
• If Figma access is unavailable, use screenshots as temporary references and mark the fidelity as provisional in the audit.
• If a slide becomes visually crowded while preserving source detail, choose one of three explicit outcomes: export more inner visual assets, split the slide into two templates, or simplify with an audit note. Do not silently shrink text below the minimum.