Media framework

Interactive Workshops

Foundation source: `contexts/design-foundations-system.html`.

Foundation source: contexts/design-foundations-system.html.

System Waterfall

Apply in order: update ledger, foundation context, tokens and brand systems, media framework, channel data, this workshop sheet, workshop style template, starter implementation, browser QA. Workshop code uses rem and tokens; px appears only as viewport review labels or external asset coordinates.

Requirement

Interactive workshops govern presenter-led browser experiences that combine slide storytelling, live capture, editable state, export, localization, and optional prepared facilitator narration.

Constraints

INTO Consulting only.
Warm Light is the default working surface.
Blueprint Dark is reserved for covers, pauses, section breaks, command surfaces, and high-contrast focus moments.
Use Newsreader, Lexend, and IBM Plex Mono only.
Petrol marks action, current path, selected slide, and primary affordance.
Saffron marks caution, milestone, comparison, and chart signal only.
The artifact must be static/local-first unless the project explicitly requires a live service.
Content, interface strings, seed data, voiceover scripts, and export labels must be separate so late localization does not leave English fragments.

Bet

The useful form is neither a deck nor a dashboard. It is a compact presentation shell wrapped around working surfaces. This costs more structure than a one-off slide app, but it prevents future builds from oscillating between static slides and boxed admin screens.

Failure Modes

A workshop becomes a dashboard with too many cards, badges, and metadata fields.
A workshop becomes a static deck and loses live state, export, accessibility, or recovery behavior.
Negative rules such as “no boxes” leave agents without replacement patterns.
Facilitator narration, localization, and generated files become runtime dependencies instead of prepared content.
GSAP is used for page-load theatre instead of clarifying state.
Display/H1 type is too large or thick for a working room.
Slide content uses complex custom geometry when a calm two-column slide would be clearer.
Accent color is applied to too many items and competes with the primary button.
Visible meta commentary tells the room how the artifact works instead of what executives need to decide.
Analytical slides default to text when a chart, table, screenshot, schematic, timeline, or decision surface would make the point faster.
Charts or diagrams lack source, method, quantified basis, direction, or visible relationship logic.

When To Use

Use this medium when the artifact has all three conditions:

A facilitator or presenter controls the room.
Participants or the operator capture decisions, inputs, votes, owners, or next actions.
The output needs export, reset, or recovery after the session.

Use media/decks.md instead when the surface is read-only. Use media/web-apps.md instead when the product is a persistent app with normal navigation, accounts, permissions, and record lifecycle as the primary job.

Surface Contract

Default browser target:

Desktop review: 1366 x 768.
Mobile review: 390 x 844.
Surface: Warm Light for working slides.
Cover and pause slides: full-viewport Blueprint Dark or photo overlay.
Top chrome: compact, 3.5rem desktop and 3rem mobile.
Bottom pager: compact, 4rem desktop and 3.5rem mobile.
Content track height: 100svh - top chrome - bottom pager.
Desktop safe area: 3.5rem default, 3rem minimum.
Mobile safe area: 1.25rem default, 1rem minimum.
Content max width: 73.75rem unless a full-width evidence row is required.
Default working slide layout: one or two columns. Left column carries label, title, body, source, or action. Right column carries proof, activity, decision, or facilitator script controls.
Activity slides may scroll inside the activity surface only.
Do not put a full-width Blueprint Dark slide inside Warm Light margins.

Typography And Spacing

Use brand/typography-spacing-system.md and brand/layout-composition-system.md.

Newsreader 400 is the default for slide titles. Do not use heavy bold.
Working slide H1: 2.5-3.5rem. Above 4rem is a defect unless the slide is a cover, pause, section break, or quote.
Cover title: 3.25-4.5rem. Bigger titles require a documented reason.
Body: 1-1.125rem, Lexend 300, 35-56 character line length where possible.
Label to title: 0.75-1rem.
Title to body: 1.25-1.75rem.
Body to action row: 1.75-2.25rem.
Body to exhibit or activity: 2-3rem.
Major section pause: 4-6rem.
Use the 0.25rem micro baseline for type alignment and the 0.5rem structural baseline for layout spacing. No arbitrary gaps when a token exists.
Use letter-spacing 0 by default; never use negative tracking. Mono labels get rhythm from wording, separators, and placement.
Use italics only for one short heading phrase on covers, pauses, or quotes. Do not use italics in controls, labels, data, or body emphasis.

Treat these as default values, not inspiration. If the slide feels messy, reduce scale and columns before adding another visual device.

Reading, Chunking, And Bento

Use vertical/layer-cake scanning for working slides and mobile workshop views. Use Z-pattern only for sparse covers, pauses, and final decision screens.
F-pattern scanning means the slide has become unstructured prose. Add headings, bullets, exhibits, or split the slide.
Keep visible choices in meaningful groups of roughly 3-6 when recall is required. Do not blindly cap navigation or menus at seven when recognition and structure make more options usable.
Bento is allowed only for peer choice modules or one dominant proof/activity with supporting modules. It is banned as decorative dashboard clutter or nested cards.

Executive Composition

The first meaningful line should be the conclusion, recommendation, or decision question unless the slide is explicitly a capture surface.
Every visible phrase must answer what changed, why it matters, what decision is needed, what evidence proves it, or what action follows.
Remove visible meta commentary from the primary path. Facilitator notes, voiceover scripts, AI narration state, internal mode labels, and build commentary belong in the drawer, voiceover files, notes, export detail, or appendix.
Related controls, labels, evidence, sources, and actions sit closer together than unrelated groups.
Analytical slides choose the dominant visual before prose: chart, table, screenshot, schematic, timeline, owner/action/date strip, two-axis board, or known/assumed/missing/next board.
Charts must expose conclusion, unit, period, population or denominator, source, method or calculation basis, and assumption/caveat when relevant.
Diagrams must explain a real workflow, system, dependency, ownership model, architecture, or evidence chain.

Required Rhythm

Every workshop flow uses this sequence:

cover -> proof -> reframe -> instruction -> activity -> decision -> export

The sequence may repeat by section. Do not expose a permanent agenda rail by default. Let the slide own the room; expose section navigation through the bottom pager, a command menu, or a facilitator drawer.

Named Primitives

Primitive	Job	Rule
`PresentationShell`	Owns viewport, chrome, pager, keyboard handling, and print mode.	No sidebar. No dashboard frame.
`SlideFrame`	Gives each slide a theme, safe area, title, and content track.	One dominant argument or working task.
`CoverPause`	Creates full-bleed recognition or reset moments.	Blueprint Dark or photo overlay; no Warm Light margin.
`ProofExhibit`	Shows evidence before asking for input.	Conclusion title, source note, direct labels.
`ReframeSlide`	Changes the room’s mental model.	Narrow prose, one strong claim, recovery space.
`ExerciseInstruction`	Explains the current task.	Verb first, timebox, input rule, output rule.
`ActivitySurface`	Captures live inputs or decisions.	Use positive alternatives below before cards.
`DecisionGate`	Converts discussion into an owner, action, date, or approval.	Primary action is petrol; alternatives are secondary or quiet.
`BottomSlidePager`	Shows progress and nearby navigation.	44px touch targets where touch is likely.
`FacilitatorDrawer`	Holds notes, script, timing, and reset/export controls.	Drawer, not permanent rail.
`ExportSheet`	Produces PDF/JSON/Markdown output.	Shows scope, generated time, and sensitivity note.
`FacilitatorScript`	Plays prepared narration or script.	Static audio first; browser speech last. Use human-facing labels such as Facilitator Script.

Activity Surface Patterns

Use these instead of generic card grids:

Open decision list: one column, owner/action/date inline, no enclosure.
Hairline board: related items separated by lines, not boxes.
Direct-label exhibit: evidence figure with labels on the figure itself.
Shortlist rail: 3-5 options in a horizontal or vertical rail with a current selection rule.
Two-axis placement board: explicit axes and draggable or keyboard-movable items; static fallback as a table.
Known / assumed / missing / next board: four named lanes with short entries.
Owner / action / date strip: compact commitment row below a decision.
Single-question capture: one prompt, one input, one visible next action.

Cards are allowed only for discrete peer choices, participant records, or final exported decision summaries. Avoid nested cards.

Button Contract

Workshop buttons use brand/button-system.md v2.

Primary: one petrol action per slide or surface.
Secondary: hairline or pale surface.
Quiet: text or icon plus text.
Glass: dark/photo cover controls only.
Icon-only: familiar commands only, with accessible label and tooltip.
Split: default action plus separate menu for alternate actions.
Destructive: reset/delete only, with confirmation path.
Loading: used for export, audio generation, import, or save.
Permission-disabled: visible disabled control with a reason.
Button content: label first, optional trailing icon second. Use inline-flex row anatomy with left-aligned text. Do not stack icon above text.
Button label floor: 0.875rem default, 0.8125rem compact. If a label does not fit, shorten the label, widen the control, or split the action.

Minimum touch target is 2.75rem for presenter controls and mobile. Compact 2rem controls are allowed only for dense desktop toolbars.

Color discipline:

One petrol-filled primary button per slide or surface.
Pager items, slide thumbnails, tabs, shortlist options, and agenda rows use petrol text, rail, outline, underline, or soft surface before fill.
Current items must not look like extra primary CTAs.
Saffron never styles ordinary buttons, tabs, or selected states.

State And Export Model

Every workshop starter defines:

Seed content: immutable slide and exercise defaults.
Mutable session state: participant inputs, decisions, votes, owners, notes, current slide, language, and audio state.
Persistence: versioned localStorage key with schema version.
Reset: requires confirmation and never overwrites live data silently.
Import: validates schema, shows preview, and rejects unknown versions.
Export: supports JSON and Markdown by default; PDF/print uses print CSS.
Print: hides chrome, keeps activity outputs readable, and reveals source or script only when opted in.

Localization Contract

Use separate files:

content/workshop.en.json
content/workshop.fr.json
content/voiceover.en.md
content/voiceover.fr.md
src/data/*.ts only for behavior, IDs, and non-copy seed records.

Do not store interface copy in components when localization is required. Do not translate stable IDs, placeholder tokens, filenames, or data keys.

Voiceover And Facilitator Script

Per-slide audio is a content surface.

Stable narration key: sectionId.pageId.
Markdown is the script source.
Audio manifest maps narration keys to static generated files.
Static generated files are preferred.
Local neural TTS is an acceptable preparation step.
Browser speech is fallback only.
No live remote TTS dependency during client sessions.
Controls: play, pause, restart, progress, language state, and unavailable state.
Every generated file needs provenance: source script, language, voice, generator, date, and reviewer.

Motion And GSAP

Motion must enact meaning.

Allowed GSAP jobs:

Slide entrance when it establishes hierarchy.
Proof exhibit reveal.
Timeline or Gantt bar fill.
Drawer or sheet transition.
Decision lock-in.
AI stream settling into review state.
Audio progress and playhead.
Command palette entrance.

Required implementation:

Use @gsap/react useGSAP in React starters.
Scope animations to a ref.
Use gsap.matchMedia() for viewport and prefers-reduced-motion.
Revert or clean up on unmount.
Provide a static final state.
Do not use GSAP for routine button hover or focus states; CSS owns those.