slidewire-development

# SlideWire Development Use this skill when working with `wendelladriel/slidewire`: creating new presentations, improving existing decks, adding navigation-friendly structure, or styling slides with themes, text, images, markdown, code, diagrams, fragments, and the first-party presentation UI components. ## Start with the SlideWire workflow Default workflow for a new presentation: 1. Generate the scaffold with `make:slidewire`. 2. Author the deck in a single Blade presentation file. 3. Register the route with `Route::slidewire()`. 4. Refine the deck with themes, transitions, fragments, and supporting components. Use the package command instead of hand-writing the initial file when possible: ```bash php artisan make:slidewire demo/product-launch --title="Product Launch" ``` - Presentations are discovered from `config('slidewire.presentation_roots')`. - By default, files live under `resources/views/pages/slides`. - A presentation key like `demo/product-launch` maps to `resources/views/pages/slides/demo/product-launch.blade.php`. ## Preferred deck structure Each presentation should be a single Blade file with one `<x-slidewire::deck>` containing one or more `<x-slidewire::slide>` components. ```blade <x-slidewire::deck> <x-slidewire::slide class="bg-slate-900 text-white"> <h1 class="text-4xl font-semibold tracking-tight">Product Launch</h1> <p class="text-lg text-slate-300">Opening slide</p> </x-slidewire::slide> <x-slidewire::slide class="bg-white text-slate-900"> <x-slidewire::markdown> ## Metrics - Activation: 62% - Churn: 1.8% </x-slidewire::markdown> </x-slidewire::slide> </x-slidewire::deck> ``` Strong defaults: - Keep one presentation per file. - Use deck-level defaults for repeated settings. - Use slide-level overrides only when a slide should intentionally differ. - Use Tailwind classes for layout, spacing, colors, and typography. ## Tailwind setup SlideWire presentation styling assumes the host Laravel app is using Tailwind CSS. If a project uses the first-party SlideWire UI components like `panel`, `title-slide`, `two-column-slide`, `timeline-slide`, `steps-slide`, or `agenda-slide`, make sure the app's `resources/css/app.css` includes the package sources so Tailwind can generate the needed classes: ```css @import 'tailwindcss'; @source '../views'; @source '../../vendor/wendelladriel/slidewire/resources/views/**/*.blade.php'; @source '../../vendor/wendelladriel/slidewire/src/**/*.php'; @source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php'; ``` Without those `@source` entries, package components may render with missing styles even though the Blade markup is correct. ## Use the right SlideWire components ### Core components - `<x-slidewire::deck>`: presentation wrapper for deck-wide defaults. - `<x-slidewire::slide>`: a single slide, with support for metadata like `theme`, `transition`, `transition-speed`, `auto-slide`, `auto-animate`, and background attributes. - `<x-slidewire::vertical-slide>`: groups slides into a vertical stack inside one horizontal column. - `<x-slidewire::fragment>`: reveals content progressively. - `<x-slidewire::panel>`: reusable modern surface for grouped content, supporting variants like `default`, `elevated`, `outlined`, and `glass`. - `<x-slidewire::title-slide>`: opinionated opening slide for titles, subtitles, overlines, and presenter metadata. - `<x-slidewire::two-column-slide>`: responsive split layout for explanation-plus-supporting-content slides. - `<x-slidewire::media-split-slide>`: media-first split layout with left/right positioning, ratio controls, and optional framed or panel-style media treatment. - `<x-slidewire::timeline-slide>` and `<x-slidewire::timeline-item>`: structured milestone and roadmap layouts. - `<x-slidewire::steps-slide>` and `<x-slidewire::step-item>`: process and rollout layouts with optional auto-numbering. - `<x-slidewire::agenda-slide>` and `<x-slidewire::agenda-item>`: section overview and agenda layouts. - `<x-slidewire::text>`: semantic text wrapper with optional orientation, configured `font` overrides, and component-level animation hooks. - `<x-slidewire::image>`: native image wrapper with component-level animation hooks. - `<x-slidewire::markdown>`: renders markdown and highlighted code fences. - `<x-slidewire::code>`: renders highlighted code blocks directly. - `<x-slidewire::diagram>`: renders Mermaid diagrams. ### When to use each content component - Use `panel` when content needs a polished surface without rebuilding the same rounded, theme-aware wrapper. - Use `title-slide` for opening slides, chapter intros, and title cards. - Use `two-column-slide` for explanatory layouts that pair copy with supporting visuals or code. - Use `media-split-slide` when the visual side should lead the composition and you want built-in media framing controls. - Use `timeline-slide` and `agenda-slide` for milestones, sections, and chapter overviews that need more structure than bullets. - Use `steps-slide` for process, rollout, or tutorial content. - Use `text` for semantic headings, paragraphs, inline text, vertical labels, or reusable animation-ready copy blocks. - Use `image` for native `<img>` output with SlideWire animation metadata. - Use `markdown` for narrative slides, bullets, and mixed prose/code. - Use `code` for tightly controlled code examples or language-specific snippets. - Use `diagram` for flows, architecture, and process explanations. - Use `fragment` for sequential reveals instead of overcrowding one slide. ### Layout component guidance Use the first-party UI components when you want polished slide structure with theme-aware defaults and less repeated Tailwind markup. Recommendations: - Prefer `panel` as the base surface primitive for grouped text, code, media, or mixed content. - Prefer `title-slide` over ad hoc hero markup for opening slides or chapter separators. - Prefer `two-column-slide` for both general split layouts and media-plus-content layouts; frame the visual side with `panel` when needed. - Prefer `media-split-slide` when the deck benefits from a more opinionated media-led split with `plain`, `framed`, or `panel` media presentation. - Prefer `timeline-slide`, `steps-slide`, and `agenda-slide` over plain lists when the sequence or hierarchy matters to the talk. - Still allow local customization through slots and `class` passthrough when a deck needs light visual tailoring. Example: ```blade <x-slidewire::two-column-slide ratio="2:1" gap="xl" align="center"> <x-slot name="left"> <x-slidewire::panel overline="Why SlideWire" title="Presentation-ready layouts" footer="Theme-aware by default" variant="glass" > Build polished decks with reusable surfaces, structured agendas, agenda layouts, and split layouts. </x-slidewire::panel> </x-slot> <x-slot name="right"> <x-slidewire::steps-slide title="Workflow" columns="1" style="cards"> <x-slidewire::step-item title="Plan" description="Choose the right layout for the story." /> <x-slidewire::step-item title="Compose" description="Fill the slots with text, code, or media." /> <x-slidewire::step-item title="Present" description="Keep the deck cohesive across themes." /> </x-slidewire::steps-slide> </x-slot> </x-slidewire::two-column-slide> ``` ### Text component guidance Use `text` when you want semantic text output without hand-writing repeated animation and orientation attributes. Supported attributes: - `type`: `paragraph` (default), `inline`, `heading` - `font`: any configured family from `config('slidewire.fonts')` - `orientation`: `horizontal` (default), `vertical` - `animation` - `animation-speed` - `class` and any other valid HTML attributes for the rendered tag Examples: ```blade <x-slidewire::text type="heading" class="text-5xl font-semibold tracking-tight"> Product Launch </x-slidewire::text> ``` ```blade <x-slidewire::text type="heading" font="Inter" orientation="vertical" animation="slide-up" animation-speed="slow" class="text-4xl" > Launch Day </x-slidewire::text> ``` Recommendations: - Prefer `heading` for prominent slide titles when `h2` semantics make sense. - Prefer `inline` for short labels embedded in richer layouts. - Use `font` for one-off typography changes that should stay within configured presentation fonts. - Use `orientation="vertical"` for side labels or editorial layouts, not long paragraphs. - Fall back to raw HTML when you need fully custom markup. ### Image component guidance Use `image` when you want a normal `<img>` element with the same animation contract as other SlideWire content components. Supported attributes: - all standard image attributes like `src`, `alt`, `class`, `width`, `height`, `loading`, `decoding`, and `fetchpriority` - `animation` - `animation-speed` Example: ```blade <x-slidewire::image src="/images/product-shot.png" alt="Product shot" class="w-72 rounded-2xl shadow-2xl" loading="lazy" animation="pop" animation-speed="default" /> ``` Recommendations: - Always provide meaningful `alt` text unless the image is purely decorative. - Keep sizing intentional with Tailwind classes or width/height attributes. - Use native image attributes directly instead of expecting PHP-side prop mapping. ## Structure slides for presentation flow ### Horizontal and vertical navigation Use regular `<x-slidewire::slide>` elements for left/right progression. Use `<x-slidewire::vertical-slide>` when one topic needs a vertical drill-down: ```blade <x-slidewire::deck> <x-slidewire::slide> <h2>Overview</h2> </x-slidewire::slide> <x-slidewire::vertical-slide> <x-slidewire::slide> <h2>Detail: Top</h2> </x-slidewire::slide> <x-slidewire::slide> <h2>Detail: Bottom</h2> </x-slidewire::slide> </x-slidewire::vertical-slide> </x-slidewire::deck> ``` Behavior to preserve when editing decks: - Left/right moves between horizontal columns. - Up/down moves within a vertical stack. - Space advances linearly through the presentation. - Hash deep links use `#/slide/N` or `#/slide/H/V`. ## Prefer deck defaults, then override intentionally SlideWire resolves runtime settings in this order: ```text slide attribute -> deck attribute -> config('slidewire.slides') ``` Use deck-level attributes for shared presentation behavior: ```blade <x-slidewire::deck theme="black" transition="fade" auto-slide="3000"> <x-slidewire::slide> <h2>Inherits deck defaults</h2> </x-slidewire::slide> <x-slidewire::slide theme="white" transition="zoom"> <h2>Overrides intentionally</h2> </x-slidewire::slide> </x-slidewire::deck> ``` Common deck-level controls: - `theme` - `transition` - `transition-speed` - `transition-duration` - `auto-slide` - `auto-slide-pause-on-interaction` - `show-controls` - `show-progress` - `show-fullscreen-button` - `keyboard` - `touch` - `highlight-theme` ## Make decks visually strong SlideWire is designed to work well with Tailwind and theme presets. ### Theme guidance Built-in themes: - `default` - `black` - `white` - `aurora` - `sunset` - `neon` - `solarized` Use a theme when you want presentation-wide visual consistency. Define custom themes in `config/slidewire.php` with `ThemeConfig` and `ThemeFont` when the deck needs a distinct branded look. ### Background guidance - Use Tailwind classes for solid and gradient backgrounds. - Use slide metadata for image or video backgrounds. - Keep foreground text contrast high against the chosen background. Examples: ```blade <x-slidewire::slide class="bg-gradient-to-br from-blue-900 to-slate-950 text-slate-50"> <h2>Gradient slide</h2> </x-slidewire::slide> ``` ```blade <x-slidewire::slide background-image="https://example.com/bg.jpg" background-size="cover" background-position="center" background-opacity="0.35" > <h2>Image-backed slide</h2> </x-slidewire::slide> ``` ### Typography and font guidance - Theme typography comes from the active `ThemeConfig`. - `text` can override typography per instance with `font` when the family exists in `config('slidewire.fonts')`. - Code highlighting uses `slides.highlight.font` and `slides.highlight.font_size` by default. - Google Fonts configured in `config('slidewire.fonts')` are loaded automatically. - Override code sizing per component with Tailwind classes like `text-sm`, `text-base`, `text-lg`, or `text-xl`. ## Use motion deliberately Supported transition names: - `slide` - `fade` - `zoom` - `convex` - `concave` - `none` Supported transition speeds: - `fast` - `default` - `slow` Recommendations: - Default to one primary transition across the deck. - Use `fade` or `zoom` only when the content change benefits from it. - Use `auto-animate` for before/after or transformation sequences with matching element IDs. - Use `auto-slide` sparingly for timed demos or kiosk-style decks. ### Component-level animations `text` and `image` support element-level entry animations through `animation` and `animation-speed`. Supported names: - `fade`