hxdeck Presentation Framework
Relevant source files
The following files were used as context for generating this wiki page:
The hxdeck Presentation Framework is an independent UI system within the HXLoLi project designed to create and manage structured, themeable presentations. It functions as a standalone system that avoids direct references to the main blog components or styles, allowing for modular deployment and theme switching without affecting core content layout.
Sources: src/hxdeck/index.ts:1-12, src/hxdeck/Demo.tsx:1-5
System Architecture
The framework utilizes a layered architecture to separate visual style from functional logic. This modularity ensures that components consume design tokens rather than hardcoded styles.
Architectural Layers
| Layer | Component Focus | Description |
|---|---|---|
| Theme Layer | theme/ | Manages token contracts and theme implementations. |
| Runtime Layer | Deck | Handles navigation, keyboard/mouse events, and slide transitions. |
| UI Layer | ui | Provides layout primitives, content blocks, and image containers. |
| Data Layer | charts | Integrates Recharts for pie, line, and bar charts. |
| Code Layer | code | Provides static syntax highlighting with VS Code color schemes. |
| Skin Layer | meme | Manages mascots, textures, and theme-specific assets. |
Sources: src/hxdeck/index.ts:3-12
Component Relationship Flow
The following diagram illustrates the relationship between the runtime Deck and its child components.
This diagram shows how the Deck provides a context that child components consume to maintain visual consistency.
Sources: src/hxdeck/index.ts, src/hxdeck/Deck.tsx
Theming System
The theme system uses a "Port and Adapter" pattern where UI components depend on a token contract (DeckTheme).
Design Tokens
Themes are defined by several interfaces that control every aspect of the presentation:
- DeckColors: Defines semantic colors such as
primary,surface,bg, and state colors (success,warn,danger). - DeckScale: Manages fluid scaling for typography and spacing using
clamp()to ensure readability across different screen sizes. - DeckShape: Controls border radius, widths, and effects like
shadowandglow. - DeckMotion: Configures transition ease and stagger timings.
Sources: src/hxdeck/theme/types.ts:15-120
Theme Registration and Selection
Themes are registered in a central registry and can be dynamically switched. The themeToVars function compiles these tokens into CSS variables prefixed with --hxd-*.
export function themeToVars(theme: DeckTheme): Record<string, string> {
const vars: Record<string, string> = {};
for (const [k, v] of Object.entries(theme.colors)) vars[`--hxd-color-${kebab(k)}`] = v;
for (const [k, v] of Object.entries(theme.shape)) vars[`--hxd-shape-${kebab(k)}`] = v;
// ... additional token mappings
return vars;
}
Sources: src/hxdeck/theme/types.ts:156-170, src/hxdeck/index.ts:25-27
Runtime and Navigation
The Deck component serves as the presentation engine, managing state and user interactions.
Core Logic
- Slide Management: Slide indices are managed via state, supporting direct jumps via URL parameters (e.g.,
?page=N). - Event Handling: The framework captures mouse wheel scrolls, keyboard arrows (Up/Down/PageUp/PageDown), and touch gestures to trigger slide transitions.
- Responsive Scaling: Presentations are designed on a fixed 1600x900 canvas, which is then scaled to fit the container or viewport.
Sources: src/hxdeck/Deck.tsx, src/hxdeck/Demo.tsx:39-44, src/hxdeck/theme/types.ts:133-138
Navigation Interaction
This diagram describes the loop between user input, internal state updates, and external URL synchronization.
Sources: src/hxdeck/Deck.tsx, src/hxdeck/Demo.tsx:39-44
UI and Visualization Components
hxdeck provides a library of pre-built components that automatically adapt to the active theme.
Layout and Content Blocks
- PageHeader: Standardizes the opening structure of each slide.
- Split & Columns: Layout primitives for 1:1, proportional, or multi-column layouts.
- Bullets & Steps: For ordered or unordered text content.
- Callout & Quote: For highlighted warnings, tips, or citations.
Sources: src/hxdeck/index.ts:42-55, src/hxdeck/Demo.tsx:64-90
Data and Technical Visualization
- Charts: Includes
PieChartBlock,LineChartBlock, andBarChartBlockbased on Recharts. - Diagram: Supports architectural and workflow diagrams. These diagrams use inline SVGs that respond to theme variables, allowing them to change colors dynamically when the theme is switched.
- CodeBlock: Renders code with VS Code-style highlighting and supports diff views (
CodeDiff).
Sources: src/hxdeck/index.ts:58-69, src/hxdeck/Demo.tsx:109-125
Theme Editor
The framework includes a ThemeEditor that allows for real-time visual editing of theme tokens.
Editor Features
- Element Selection: Users click directly on canvas elements (Mascots, Cards, Titles) to edit their specific properties.
- Asset Management: Supports uploading and positioning mascots and textures via data URLs.
- Serialization: Themes can be serialized, downloaded as YAML/JSON, and loaded back into the framework.
- Instant Preview: Changes to colors or spacing are reflected immediately in the rendered Deck instance within the editor.
Sources: src/hxdeck/ThemeEditor.tsx:28-60, src/hxdeck/index.ts:72-76
Editor Logic Flow
The editor simplifies theme creation by mapping visual elements to their corresponding design tokens.
Sources: src/hxdeck/ThemeEditor.tsx:75-100
Summary
The hxdeck Presentation Framework provides a robust, token-driven environment for creating technical presentations within the HXLoLi ecosystem. By decoupling logic from style through a comprehensive theme contract and providing specialized components for data and code visualization, it enables developers to produce high-quality, interactive slides that maintain consistent visual identity across different themes.