@troshab/slidev-theme-troshab 0.1.0

package/CLAUDE.md

@@ -0,0 +1,537 @@
+# slidev-theme-troshab
+
+> **This file must be written in English only.**
+
+Minimal universal Slidev theme with flexible layouts and a library of ready-made slides.
+
+---
+
+## Development Rules
+
+### Styling Principles
+
+1. **All styling via CSS classes** — never use inline styles (`style="..."`)
+2. **Semantic class names** — classes should describe component purpose, not appearance
+   - Good: `.btn-primary`, `.link-button`, `.card-metric`
+   - Bad: `.text-white`, `.bg-blue-500` (only use utility classes from UnoCSS when necessary)
+3. **All custom classes in `styles/base.css`** — component styles must be centralized
+4. **Type-specific variations** — use modifier classes like `.block-info`, `.block-warning`
+5. **Dark theme support** — use `color-mix(in srgb, var(--color-X) N%, transparent)` instead of `.dark` overrides; CSS variables auto-adapt
+
+### File Organization
+
+- `styles/colors.css` — color variables only (no component styles) **← SOURCE OF TRUTH**
+- `styles/base.css` — typography, spacing, and component styles
+- `styles/motion.css` — motion system (transitions, animations, v-click)
+- `uno.config.ts` — grid utilities and UnoCSS configuration
+- `setup/mermaid.ts` — Mermaid theme configuration (reads CSS variables at runtime)
+- `setup/shiki.ts` — Shiki syntax highlighting theme + lang-label transformer
+- `composables/useColors.ts` — shared color types and CSS var maps (single source of truth)
+
+### Component Documentation Sync
+
+> Component docs live in the plugin skill directory: `~/troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/`
+
+- Every component in `components/` has a matching `.md` in `plugin/components/{Name}.md`
+- The layout has `plugin/layouts/slide.md` with full mode/prop/slot documentation
+- **When creating or modifying a component:** update (or create) the corresponding `.md` in the plugin skill directory
+- **When deleting a component:** delete its `.md` from the plugin skill directory
+- MD files use a standard format: `# Name`, `## Props` (table), `## Slots` (table, if any), `## Usage` (examples), `## Notes` (gotchas, if any)
+
+### Slide Numbering
+
+- Slides in `example_slides/` use 3-digit prefix: `001-name.md`, `002-name.md`, ...
+- When adding or removing slides, **renumber all subsequent files** to maintain continuous sequence
+- Update `example_content.md` to match the new file names
+- 4 sections: Layouts (003-023), Components (024-075), Addons (076-079), Theme Features (080-092), Q&A (093)
+
+---
+
+## Project Structure
+
+```
+slidev-theme-troshab/
+├── package.json
+├── uno.config.ts          # UnoCSS: grid, utilities
+├── styles/
+│   ├── index.css          # CSS entry point (auto-detected by Slidev)
+│   ├── base.css           # Typography, spacing, component styles
+│   ├── colors.css         # Color system (light/dark) ← SOURCE OF TRUTH
+│   └── motion.css         # Motion system (transitions, animations)
+├── setup/
+│   ├── main.ts            # App setup (image preloading)
+│   ├── mermaid.ts         # Mermaid theme (reads CSS vars at runtime)
+│   └── shiki.ts           # Shiki syntax highlighting
+├── composables/
+│   └── useColors.ts       # Shared color types + CSS var maps
+├── fonts/                 # IBM Plex Sans/Mono (woff2)
+├── layouts/               # 1 universal layout (slide.vue)
+├── components/            # 11 primitives + 26 widgets
+├── snippets/              # Code snippets for import demos
+├── example_content.md     # 92 slides (all content, no theme config)
+├── example_white.md       # Light theme wrapper (src: example_content.md)
+├── example_dark.md        # Dark theme wrapper (src: example_content.md)
+└── slides-export/         # Visual testing reference
+    ├── white/             # Light theme PNG exports
+    └── black/             # Dark theme PNG exports
+```
+
+---
+
+## Development Servers
+
+```bash
+npx slidev example_dark.md --port 30303    # Dark: http://localhost:30303
+npx slidev example_white.md --port 31313   # Light: http://localhost:31313
+```
+
+---
+
+## Visual Testing
+
+```bash
+npx slidev export example_white.md --format png --output ./slides-export/white
+npx slidev export example_dark.md --format png --output ./slides-export/black
+```
+
+## THE UNIVERSAL LAYOUT
+
+See @../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/layouts/slide.md for full documentation (modes, props, slots, background slots, edge-to-edge rules).
+
+All slides use `layout: slide` with `mode: fullscreen | split | columns` (default: columns).
+
+---
+
+## INCLUDED ADDONS
+
+### Preload Images
+
+Automatic image preloading. Config: `preloadImages: { enabled: true, ahead: 3 }` in frontmatter. Strategy: preload current + ahead slides on startup, then background-load the rest.
+
+### Asciinema
+
+Terminal recordings: `<Asciinema src="/casts/demo.cast" :rows="24" :cols="80" autoplay />`. Props: `src` (required), `rows`, `cols`, `autoplay`, `loop`, `speed`.
+
+### FancyArrow
+
+Hand-drawn arrows: `<FancyArrow x1="100" y1="100" x2="300" y2="200" color="red" :width="3" />`. Props: `x1/y1/x2/y2` (required), `color`, `width`, `two-way`.
+
+---
+
+## PRIMITIVE COMPONENTS (10)
+
+Semantic building blocks. Full API (props, slots, usage) in `plugin/components/{Name}.md`.
+
+| Component | Description |
+|-----------|-------------|
+| Background | Bg slot wrapper: color, gradient, image, overlay (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Background.md) |
+| StyledText | Universal text: heading/block/inline, color, spoiler v-click (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/StyledText.md) |
+| Image | Content image with caption, border, sizing (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Image.md) |
+| Icon | Phosphor icon with size and color (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Icon.md) |
+| Metric | KPI display with count-up animation (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Metric.md) |
+| PersonCard | Speaker/member card with avatar (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/PersonCard.md) |
+| Iframe | External content embed (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Iframe.md) |
+| ColorSwatch | Theme color display with resolved value (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/ColorSwatch.md) |
+| StyledList | Themed list markers (check/arrow/star/number) (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/StyledList.md) |
+| CodeHighlight | Syntax-highlighted code block (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/CodeHighlight.md) |
+
+---
+
+## WIDGET COMPONENTS (26)
+
+Full API (props, slots, usage) in `plugin/components/{Name}.md`.
+
+| Component | Description |
+|-----------|-------------|
+| Stepper | Steps/timeline/progress with dots/numbers/arrows (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Stepper.md) |
+| Callout | Admonition: info, tip, warning, danger, note (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Callout.md) |
+| Card / CardGrid | Feature cards in responsive grid (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Card.md, @components/CardGrid.md) |
+| QRCode | Theme-aware SVG QR code (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/QRCode.md) |
+| Tags | Tag pills (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Tags.md) |
+| Progress | Presentation progress bar (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Progress.md) |
+| SpeechBubble | Speech/thought bubbles (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/SpeechBubble.md) |
+| Conversation | iMessage-style chat with v-click (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Conversation.md) |
+| DeviceMockup | Device frames: iPhone, MacBook, browser, tablet (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/DeviceMockup.md) |
+| Countdown | Animated timer with v-click (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Countdown.md) |
+| AnimatedCounter | Count-up number animation (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/AnimatedCounter.md) |
+| Typewriter | Text typing animation (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Typewriter.md) |
+| Confetti | Celebration particles for bg slot (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Confetti.md) |
+| ImageCompare | Before/after image slider (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/ImageCompare.md) |
+| CodeDiff | Code comparison: split or unified (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/CodeDiff.md) |
+| Testimonial | Customer quote card with rating (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Testimonial.md) |
+| QuoteBlock | Large centered quote (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/QuoteBlock.md) |
+| Funnel | Conversion funnel (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Funnel.md) |
+| Pyramid | Hierarchical levels (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Pyramid.md) |
+| PricingTable | Pricing tier cards (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/PricingTable.md) |
+| MatrixGrid | 2x2 quadrant grid (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/MatrixGrid.md) |
+| SwotGrid | SWOT analysis (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/SwotGrid.md) |
+| CaseStudy | Multi-section case study (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/CaseStudy.md) |
+| Definition | Term definition card (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/Definition.md) |
+| MermaidChart | Mermaid diagram wrapper (@../troshab-own-claude-code/plugins/troshab-own/skills/slidev-visualise-content/components/MermaidChart.md) |
+
+---
+
+## MERMAID DIAGRAMS
+
+Theme automatically applies matching colors via `setup/mermaid.ts` (reads CSS vars at runtime). Theme detection happens at page load — toggle requires reload.
+
+### Rules
+
+1. **Short labels** — max 8-10 chars per node
+2. **Limit nodes** — max 6-8 for flowcharts
+3. **No titles in xychart** — causes overflow
+4. **Use abbreviations** — `LB` not `Load Balancer`
+
+### Limits by type
+
+- **Flowchart:** max 8 nodes, 2-8 char labels, use `TD` or `LR`
+- **XY Chart:** no `title`, max 6-8 x-axis labels (3-char), short y-axis label
+- **Sequence:** max 4 participants (2-6 chars), max 6-8 messages
+- **Pie:** max 5 segments, max 12-char labels
+
+If too complex: split slides, use `cols: 2`, create external SVG, or simplify.
+
+---
+
+## CODE BLOCKS
+
+### Limits to Avoid Overflow
+
+| Context | Max lines | Max width |
+|---------|-----------|-----------|
+| Full-width slide (1 col) | 12-15 lines | 80 chars |
+| Two-column (`cols: 2`) | 8-10 lines | 40 chars |
+| Inline with text | 6-8 lines | 60 chars |
+
+### Best Practices
+
+1. **Remove comments** — `// Usage`, `// Example` take space
+2. **Shorten error messages** — `throw new Error('HTTP error')` not full status
+3. **Omit obvious types** — TypeScript can infer many types
+4. **Split long code** — use multiple slides or `cols: 2` for before/after
+5. **Use highlights** — `{1,3-5}` to focus on key lines instead of showing all
+
+---
+
+## SLIDE EXAMPLES
+
+### Cover / section divider
+
+```md
+---
+layout: slide
+mode: fullscreen
+---
+
+::bg::
+<Background :gradient="'section'" />
+
+::default::
+# Section Title
+```
+
+### Image with overlay
+
+```md
+---
+layout: slide
+mode: fullscreen
+---
+
+::bg::
+<Background src="/hero.jpg" bgOverlay="dark" />
+
+::default::
+# Title Over Image
+```
+
+### Two columns
+
+```md
+---
+layout: slide
+cols: 2
+---
+
+# Title
+
+::col1::
+Left content
+
+::col2::
+Right content
+```
+
+### Split with image
+
+```md
+---
+layout: slide
+mode: split
+split: [5, 7]
+---
+
+::left-bg::
+<Background src="/photo.jpg" />
+
+::right::
+# Content
+```
+
+### Simple text
+
+```md
+---
+layout: slide
+---
+
+# Title
+
+Content here
+```
+
+---
+
+## V-CLICK AUTO-INTEGRATION
+
+Components can auto-register with Slidev's click system so users don't need `<v-click>` wrappers or `clicks:` frontmatter. The slide's total clicks are computed dynamically from all registered elements.
+
+### How it works
+
+Inject `$$slidev-clicks-context` (a `Ref<ClicksContext>`). On mount, call `ctx.calculate('+1')` to claim the next click slot, then `ctx.register(el, info)` to register. On unmount, call `ctx.unregister(el)`.
+
+**ClicksContext API** (from `@slidev/client/composables/useClicks.ts`):
+- `ctx.calculate(at)` - returns `ClicksInfo` with `{ start, end, max, delta, isActive, isCurrent }`. `at` values: `'+1'` (relative next), `'+2'`, or absolute number `0`, `1`, `2`.
+- `ctx.register(el, info)` - registers element in click system. `el` = DOM element (used as Map key). Must be called in `onMounted` (before parent slide's `isMounted`).
+- `ctx.unregister(el)` - removes element from click system.
+- `ctx.current` - current click index (reactive getter, clamped to `[clicksStart, total]`).
+- `ctx.total` - max click index (dynamically computed from all registered elements' `max` values).
+- `info.isActive` - `computed(() => current >= start)` - tracks forward/backward.
+- `info.isCurrent` - `computed(() => current === start)` - true only at exact click.
+
+### Pattern for auto v-click components
+
+```typescript
+const rootEl = ref<HTMLElement | null>(null)
+const clicksContext = inject<Ref<any>>('$$slidev-clicks-context', ref(null))
+
+onMounted(() => {
+  const ctx = clicksContext.value
+  if (ctx?.calculate && rootEl.value) {
+    const info = ctx.calculate('+1')       // Claim next click slot
+    if (info) {
+      ctx.register(rootEl.value, info)
+      // IMPORTANT: watchEffect MUST be inside onMounted — info is not reactive,
+      // so a watchEffect created before onMounted would never re-run.
+      // info.isActive is a computed ref that tracks forward/backward navigation.
+      watchEffect(() => {
+        isRevealed.value = info.isActive.value
+      })
+    }
+  }
+})
+
+onUnmounted(() => {
+  if (clicksContext.value?.unregister && rootEl.value)
+    clicksContext.value.unregister(rootEl.value)
+})
+```
+
+### `at` prop pattern (explicit click index)
+
+For components with `at` prop (AnimatedCounter, Countdown, Confetti, ImageCompare, Metric):
+
+```typescript
+const clicksContext = inject<Ref<{current: number}>>('$$slidev-clicks-context', ref({current: 0}))
+
+// Watch click counter manually
+watch(() => clicksContext.value.current, (cur) => {
+  if (cur >= props.at && !hasTriggered) trigger()
+  if (cur < props.at && hasTriggered) reset()
+})
+```
+
+### Components with v-click integration
+
+| Component | Type | Behavior |
+|-----------|------|----------|
+| StyledText (spoiler) | Auto `+1` | Registers next click, blurs/unblurs |
+| AnimatedCounter | `at` prop (0) | Count-up on click, reset on backward |
+| Countdown | `at` prop (-1) | Start timer on click |
+| Confetti | `at` prop (0) | Fire particles on click |
+| ImageCompare | `at` prop (-1) | Animate slider on click |
+| Metric | Pass-through | Forwards `at` to AnimatedCounter |
+
+---
+
+## UnoCSS Utilities
+
+Theme includes:
+- 12-column grid (`col-span-3` ... `col-span-9`)
+- Semantic aliases (`is-half`, `is-one-third`, `is-two-thirds`, `is-one-quarter`, `is-three-quarters`)
+- Styles for Block/Theorem components
+
+---
+
+## When to Use Which Mode + Component
+
+| Situation | Mode | Component |
+|-----------|------|-----------|
+| Regular slide with text/list | columns (default) | — |
+| Title/cover slide | fullscreen | `<StyledText tag="h1">` + `<StyledText color="secondary">` |
+| Section divider | fullscreen | `<Background :gradient="'section'">` in ::bg:: |
+| Centered statement | fullscreen | `<StyledText tag="h1" align="center">` |
+| Quote | fullscreen | `<QuoteBlock>` |
+| Large number/KPI | fullscreen | `<Metric size="lg" gradient>` |
+| Hero with background image | fullscreen | `<Background src="..." bgOverlay="dark">` |
+| Full-screen iframe/media | fullscreen | `padding: false` |
+| Image + text side by side | split | `<Background>` in bg slot |
+| Before/after comparison | split | `colAlign: center` prop |
+| Two columns | columns | `cols: 2` |
+| Three columns | columns | `cols: 3` |
+| Four columns | columns | `cols: 4` |
+| Meeting agenda | columns | `<StyledList marker="number">` |
+| Key takeaways | columns | `<StyledList marker="check" color="success">` |
+| Styled bullet points | columns | `<StyledList marker="arrow">` |
+| Content with footnotes | columns | `footnote: true` prop |
+| Speaker introduction | columns | `<PersonCard>` |
+| Team members grid | columns | `<PersonCard size="sm">` in grid |
+| KPIs dashboard | columns | `<Metric>` components |
+| Pricing table | columns | `<PricingTable>` |
+| Customer testimonial | fullscreen | `<Testimonial variant="featured">` |
+| Chat dialog, Q&A | columns | `<Conversation>` |
+| Call to action | fullscreen | `<StyledText tag="h1">` + `<StyledText>` |
+| Case study | columns | `<CaseStudy>` |
+| Step-by-step workflow | columns | `<Stepper variant="numbers">` |
+| Project milestones | columns | `<Stepper variant="dots" direction="vertical">` |
+| Sales/conversion funnel | columns | `<Funnel>` |
+| Hierarchical pyramid | columns | `<Pyramid>` |
+| SWOT analysis | columns | `<SwotGrid>` |
+| Impact/effort matrix | columns | `<MatrixGrid>` |
+| Key insight, focus point | fullscreen | `<StyledText tag="h1" color="primary">` |
+| Term definition | columns | `<Definition>` |
+| Bibliography/references | columns | `<StyledList indent="hanging">` |
+| Attribution credits | columns | `<StyledList marker="none" columns="2">` |
+| Q&A, thank you | fullscreen | `<StyledText tag="h1" align="center">` |
+| Mermaid diagrams (all types) | any | `<MermaidChart type="...">` wrapper with ` ```mermaid ` inside |
+
+---
+
+## TYPOGRAPHY
+
+### Fonts
+
+| Role | Font | Weights |
+|------|------|---------|
+| Text + headings | **IBM Plex Sans** | 400, 500, 600, 700 |
+| Code | **IBM Plex Mono** | 400, 500 |
+
+### Font Sizes (4 variables)
+
+`--font-size-h1`: 57px, `--font-size-h2`: 43px (also h3), `--font-size-base`: 24px, `--font-size-small`: 18px (captions, labels, code)
+
+### Formatting Rules
+
+- **Alignment:** left for multi-line text, center only for single-line headings
+- **Italic:** only for book titles/terms, NOT for emphasis
+- **ALL CAPS:** only for short labels
+- **Underline:** only for links
+- **Justified text:** forbidden
+- **Light/thin weights:** forbidden (fade on projector)
+
+### Accessibility
+
+- Contrast ratio >= 4.5:1 for all text (AA), target 7:1 (AAA)
+- WCAG 2.2 keyboard focus styles (3px primary outline)
+- BDA-compliant spacing: word-spacing 0.08em, letter-spacing 0.02em (4.0x ratio, BDA min 3.5x)
+- Safe zone: 5% padding on all sides (`--safe-inset-x`, `--safe-inset-y`)
+
+---
+
+## COLORS
+
+**Source of truth:** `styles/colors.css`. Shared types in `composables/useColors.ts`.
+
+### Architecture (3-layer Dracula/Alucard palette)
+
+1. **Layer 1 (Palette):** `--color-{family}-{shade}` in `:root` — ONLY place hex values exist. 11 families (drac-bg, drac-fg, alu-bg, drac-comment, drac-cyan, drac-green, drac-orange, drac-pink, drac-purple, drac-red, drac-yellow) x 11 shades. Generated via `scripts/generate-palette.mjs` (OKLCH shade ramps).
+2. **Layer 2 (Semantic):** `--color-primary: var(--color-drac-purple-700)` — only `var()` refs to palette.
+3. **Layer 3 (Usage):** Components use ONLY semantic vars. NO hex anywhere in components/slides.
+
+### Key principles
+
+- Light (Alucard): alu-bg-50 bg, drac-fg-900 text, drac-purple-700 primary, drac-pink-700 accent
+- Dark (Dracula): drac-bg-900 bg, drac-fg-50 text, drac-cyan-300 primary, drac-purple-200 accent
+- Tint vars (`--color-X-tint`) use opaque palette shades, NOT `color-mix()`
+- `color-mix()` ONLY for true alpha: shadows, image overlays
+- Every `--color-{name}` has matching `--color-{name}-foreground` for readable text
+- Borders: light drac-comment-500/600, dark drac-comment-300/200 (all 3:1+ non-text contrast)
+- Chart palette: 8 colors per theme with varied shade levels for grayscale spread
+- Components accepting colors use semantic names (primary, success, accent) mapped to `--color-{name}`
+- 5 audits: contrast, shiki, chart, typography, integrity — all must exit 0
+
+### Gradient system
+
+**CSS vars** (defined in `colors.css`): `--gradient-{color}` for each semantic color + accent. Primary is a special cross-color gradient (purple→pink); others go from `--color-{name}` to `--color-{name}-fade`.
+
+**JS utility** (in `composables/useColors.ts`): `gradientVar` map (`Record<ExtendedColor, string>`). Components use it instead of building template literals:
+
+```typescript
+import { gradientVar } from '../composables/useColors'
+// In component: gradientVar[props.color]  →  'var(--gradient-primary)'
+```
+
+**Pattern for components with `color` prop + gradient:**
+- Inline style sets a CSS custom property: `:style="{ '--metric-gradient': gradientVar[color] }"`
+- CSS uses it with fallback: `background: var(--metric-gradient, var(--gradient-primary))`
+- Components without `color` prop use `var(--gradient-primary)` directly in CSS (decorative)
+
+---
+
+## MOTION SYSTEM
+
+**Source of truth:** `styles/motion.css`. Tokens based on IBM Carbon.
+
+### Design Principles
+
+1. Motion explains, not decorates — animations show causality
+2. 1-2 properties max — only `opacity + transform` (GPU-friendly)
+3. Exit faster than enter (~20% shorter)
+4. Desktop prefers shorter (150-300ms typical)
+5. Stagger <= 6 items (longer lists skip stagger)
+6. Reduced motion: WCAG 2.1 via `prefers-reduced-motion` (currently TODO)
+
+### Motion Modes
+
+| Mode | Class | Duration | Use |
+|------|-------|----------|-----|
+| Calm | (default) | 240ms | Standard presentations |
+| Crisp | `motion-crisp` | 150ms | Technical demos |
+| Expressive | `motion-expressive` | 400ms | Creative presentations |
+
+### Slide Transitions
+
+Content slides use `slide-left` (page-turn), accent slides use `fade`. Set global default in first slide's frontmatter (`transition: slide-left`), override per slide.
+
+Available: `slide-left`, `slide-right`, `slide-up`, `slide-down`, `fade`, `none`.
+
+### v-click Reveal Styles
+
+Default = fade + rise. Override per slide: `reveal-fade` (opacity only), `reveal-slide` (from right), `reveal-pop` (scale up). Theme auto-detects content type (code/tables = fade, lists = slide from left, large text = pop).
+
+### Entrance Animations
+
+Automatic per layout — headings fall from above, content rises from below, two columns slide from opposite sides, grids rise together. No configuration needed.
+
+---
+
+## ICONS
+
+Phosphor Icons via Iconify (`@iconify-json/ph`). Use via `<Icon>` component:
+
+```md
+<Icon name="ph-check-circle" size="xl" color="success" />
+<Icon name="ph-github-logo-bold" />
+```
+
+Weight suffixes: (none) = regular, `-bold`, `-fill`, `-duotone`, `-thin`, `-light`.

package/LICENSE

@@ -0,0 +1,134 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all your
+licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only distribute the
+software according to [Distribution License](#distribution-license)
+and make changes or new works based on the software according
+to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software. Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright (c) 2024-2026 troshab
+> (https://github.com/troshab)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, or
+becomes able to license, that you would infringe by using
+the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or
+religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any
+of your licenses to anyone else, or prevent the licensor
+from granting licenses to anyone else. These terms do not
+imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes
+or contributes to infringement of any patent, your patent
+license for the software granted under these terms ends
+immediately. If your company makes such a claim, your
+patent license ends immediately for work on behalf of your
+company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the
+software not covered by your licenses, your licenses can
+nonetheless continue if you come into full compliance with
+these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice. Otherwise,
+all your licenses end immediately.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be
+liable to you for any damages arising out of these terms or
+the use or nature of the software, under any kind of legal
+claim.
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor
+makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control
+of, or are under common control with that organization.
+Control means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise. Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for
+the software under these terms.
+
+**Use** means anything you do with the software requiring
+one of your licenses.