@honeydeck/honeydeck 0.1.2 → 0.2.0

package/AGENTS.md

@@ -18,8 +18,7 @@ From repo root:
 npm -w @honeydeck/honeydeck run dev
 npm -w @honeydeck/honeydeck run test
 npm -w @honeydeck/honeydeck run typecheck
-npm -w @honeydeck/honeydeck run build
 npm -w @honeydeck/honeydeck run pack:dry-run
 ```
 
-For full monorepo gates use root workspace scripts: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, and `npm run pack:dry-run`.
+For full monorepo gates use root workspace scripts: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, and `npm run pack:dry-run`. Root `npm run build` runs only workspaces that define a build script.

package/DEVELOPMENT.md

@@ -87,7 +87,6 @@ npx playwright install chromium
 
 | Script | Purpose |
 |--------|---------|
-| `npm run build` | Run the package TypeScript build gate |
 | `npm run dev` | Run source CLI against starter template deck |
 | `npm run dev:init` | Run source CLI against starter template deck |
 | `npm run format` | Format/lint with Biome and write fixes |
@@ -114,7 +113,6 @@ npm run format
 npm run lint
 npm run typecheck
 npm test
-npm run build
 npm run pack:dry-run
 ```
 

package/Readme.md

@@ -19,13 +19,12 @@ Decks are plain MDX files separated into slides with `---`; see the first deck e
 ## Documentation
 
 - [Getting started](docs/getting-started.md) - first deck, first commands, and the shortest path to presenting
-- [Next steps](docs/next-steps.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
+- [Deeper dive](docs/deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
 - [Slides](docs/slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](docs/configuration.md) - deck-level and slide-level frontmatter
 - [Steps and reveals](docs/steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
 - [Components](docs/components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
-- [Kits](docs/kits.md) - themes, layout sets, Tailwind tokens, and third-party kits
-- [Kit authoring](docs/kit-authoring.md) - layout maps, layout props, demos, and design tokens for kit authors
+- [Customization](docs/customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](docs/navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](docs/mobile.md) - mobile controls, touch gestures, and pinch zoom
 - [Presenter mode](docs/presenter-mode.md) - notes, presenter window, sync, and mobile behavior

package/SPEC.md

@@ -42,7 +42,7 @@ The Honeydeck specification is distributed:
 - `react`, `react-dom`, and Tailwind are peer dependencies of `honeydeck`.
 - Honeydeck wires the Tailwind Vite plugin internally, but Tailwind/theme CSS is only loaded when user-authored CSS imports it; generated projects install `tailwindcss` and import `./styles.css` from `deck.mdx`.
 - Generated projects use compatible semver ranges for React, Tailwind, TypeScript, and types.
-- Published third-party kits are plain npm packages; supported runtime ranges are managed by package metadata, not by a Honeydeck-specific mechanism.
+- Custom themes, layouts, and components are plain CSS/TypeScript modules; installed-package usage is handled by standard package metadata rather than by a Honeydeck-specific mechanism.
 - Icons come from `lucide-react` and must use suffixed `...Icon` component exports (for example `ChevronLeftIcon`), not inline SVG path helpers, emoji glyphs, or unsuffixed aliases.
 
 ---
@@ -59,7 +59,7 @@ The Honeydeck specification is distributed:
 | Runtime | [`src/runtime/SPEC.md`](src/runtime/SPEC.md) | timeline semantics, keyboard/touch navigation, SPA/build behavior, runtime errors |
 | Runtime components | [`src/runtime/components/SPEC.md`](src/runtime/components/SPEC.md) | `Reveal`, `RevealGroup`, `TimelineSteps`, `ListStyle`, `Keyboard`, `BrowserFrame`, `Notes` |
 | Runtime views | [`src/runtime/views/SPEC.md`](src/runtime/views/SPEC.md) | presenter mode, overview mode, theme/layout/component reference pages |
-| Layouts and kits | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | kit model, built-in layouts, layout props, demos, layout resolution |
+| Layouts and customization | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | custom theme/layout/component model, built-in layouts, layout props, demos, layout resolution |
 | Theme | [`src/theme/SPEC.md`](src/theme/SPEC.md) | design tokens, base theme CSS, Tailwind mapping, color mode behavior |
 | Public exports | [`src/SPEC.md`](src/SPEC.md) | import paths and public TypeScript types |
 | Public release governance | Repository root `.github/SPEC.md` | protected branch, CI checks, PR title contract, publishing automation; repository-only, not shipped in the npm package |
@@ -80,7 +80,7 @@ The Honeydeck specification is distributed:
 Honeydeck prioritizes:
 
 1. **Zero to presenting** — a plain `deck.mdx` works with built-in layouts, even before CSS is imported.
-2. **Progressive power** — add explicit CSS imports, React, custom layout maps, and kits as needed.
+2. **Progressive power** — add explicit CSS imports, React components, and custom layout maps as needed.
 3. **Explicit composition** — see imports and configuration; no user-content auto-discovery and no automatic theme CSS injection.
 4. **Presentation-native** — timeline, steps, presenter mode, runtime reference pages, and PDF export built in.
 5. **Fun** — starter sparkle button, tasteful CLI output, playful defaults.

package/docs/customization.md

@@ -0,0 +1,413 @@
+# Customization
+
+Honeydeck starts with built-in layouts and a small base theme. Customize only what you need: CSS tokens, React components, or a layout map.
+
+## Mental model
+
+| Concern | What you write | How you use it |
+|---------|----------------|----------------|
+| Theme | CSS files with Honeydeck tokens and Tailwind utilities | import CSS from `deck.mdx` or from another CSS file |
+| Components | React components | import them in MDX |
+| Layouts | React layout components in a layout map | set `layouts:` in deck frontmatter, then choose `layout:` per slide |
+
+All references are explicit. Local files and installed packages work the same way: import the module you want.
+
+## Start with CSS
+
+The starter deck imports `./styles.css` from `deck.mdx`:
+
+```mdx
+import './styles.css'
+
+# Hello world
+```
+
+A typical styles file imports Tailwind and the Honeydeck base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+```
+
+Override tokens after the base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+
+:root {
+  --honeydeck-primary: oklch(55% 0.25 280);
+  --honeydeck-font-heading: "Playfair Display", serif;
+  --honeydeck-border-radius: 1rem;
+}
+```
+
+Target light and dark modes when needed:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+}
+
+[data-honeydeck-color-mode="dark"] {
+  --honeydeck-primary: oklch(70% 0.2 250);
+}
+```
+
+## Bundled themes and layouts
+
+The default visual style is clean black, white, and grey:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+```
+
+`@honeydeck/honeydeck/themes/clean.css` is available as an optional named clean layer.
+
+The Bee theme adds the original playful palette:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+@import "@honeydeck/honeydeck/themes/bee.css";
+```
+
+Use the matching Bee layout set when you want Bee slide chrome too:
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts/bee"
+---
+```
+
+The default clean layout set is available through either path:
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts"
+---
+```
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts/clean"
+---
+```
+
+## Tailwind token utilities
+
+Honeydeck maps theme tokens to Tailwind utilities:
+
+```mdx
+<div className="rounded-honeydeck border border-border bg-surface p-6 text-surface-foreground">
+  Styled with Honeydeck tokens.
+</div>
+```
+
+Useful color utilities include `primary`, `primary-foreground`, `accent`, `accent-foreground`, `background`, `foreground`, `surface`, `surface-foreground`, and `border`.
+
+## Design tokens
+
+Themes provide CSS custom properties. Colors derive from a primary using `oklch` relative color syntax, with separate values for light and dark modes:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+  --honeydeck-background: oklch(from var(--honeydeck-primary) 98% 0.01 h);
+  --honeydeck-foreground: oklch(from var(--honeydeck-primary) 15% 0.02 h);
+  --honeydeck-surface: oklch(from var(--honeydeck-primary) 94% 0.02 h);
+}
+```
+
+| Token | Purpose |
+|-------|---------|
+| `--honeydeck-primary` | Brand color for this mode |
+| `--honeydeck-primary-foreground` | Text on primary backgrounds |
+| `--honeydeck-background` | Main slide background |
+| `--honeydeck-foreground` | Main text color |
+| `--honeydeck-surface` | Cards, code blocks, callouts |
+| `--honeydeck-surface-foreground` | Text on surfaces |
+| `--honeydeck-border` | Border/divider color |
+| `--honeydeck-accent` | Accent, computed as complementary by default |
+| `--honeydeck-accent-foreground` | Text on accent backgrounds |
+| `--honeydeck-link-color` | Link color, defaulting to inherit |
+| `--honeydeck-border-radius` | Default border radius |
+| `--honeydeck-font-heading` | Heading font family |
+| `--honeydeck-font-body` | Body font family |
+| `--honeydeck-font-mono` | Monospace font family |
+| `--honeydeck-font-base` | Base font size, defaulting to `16px` |
+| `--honeydeck-font-scale` | Heading scale factor, defaulting to `1.25` |
+| `--honeydeck-code-line-dim-opacity` | Dim opacity for non-highlighted code lines |
+
+## Use built-in layouts
+
+Select a layout in slide frontmatter:
+
+```mdx
+---
+layout: Section
+---
+
+# Big idea
+```
+
+If no `layout:` is specified, `Default` is used. Layout names are PascalCase.
+
+| Layout | Description |
+|--------|-------------|
+| `Blank` | Empty slide with only children |
+| `Default` | Title top-left, body flows below |
+| `Section` | Big centered heading for section breaks |
+| `Cover` | Opening/closing slide with title, body, author, and date |
+| `TwoCol` | Two equal columns |
+| `Image` | Prominent image with optional title and caption/content |
+| `ImageLeft` | Prominent left image with title and body on the right |
+| `ImageRight` | Prominent right image with title and body on the left |
+
+Extra slide frontmatter fields are passed to the selected layout:
+
+```mdx
+---
+layout: Cover
+author: You_Name_Here
+---
+
+# Honeydeck
+
+A modern slide framework.
+```
+
+### Two-column slides
+
+`TwoCol` uses slot components from the active layout set:
+
+```mdx
+---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+<Left>
+## Benefits
+- Fast iteration
+- Live reload
+</Left>
+
+<Right>
+## Trade-offs
+- Requires Node.js
+</Right>
+```
+
+For Bee layouts, import slots from the Bee path:
+
+```mdx
+import { Left, Right } from '@honeydeck/honeydeck/layouts/bee/TwoCol'
+```
+
+### Image slides
+
+`Image`, `ImageLeft`, and `ImageRight` accept `image`, `darkImage`, and `alt` frontmatter:
+
+```mdx
+---
+layout: ImageRight
+image: /photos/launch.jpg
+darkImage: /photos/launch-dark.jpg
+alt: Launch moment
+---
+
+# Launch moment
+
+Supporting context sits beside the image.
+```
+
+## Create custom layouts
+
+Custom layouts are React components. Use a layout map when you want `layout:` frontmatter to select them.
+
+```tsx
+// layouts/Hero.tsx
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+export default function HeroLayout({ title, children }: LayoutProps) {
+  return (
+    <div className="grid h-full place-items-center bg-gradient-to-br from-purple-900 to-indigo-900 p-12 text-center text-white">
+      <div>
+        {title ? <h1>{title}</h1> : null}
+        {children}
+      </div>
+    </div>
+  )
+}
+```
+
+Create a layout map:
+
+```ts
+// layouts/index.ts
+import type { LayoutMap } from '@honeydeck/honeydeck/types'
+import defaultLayouts from '@honeydeck/honeydeck/layouts'
+import HeroLayout from './Hero'
+
+export default {
+  ...defaultLayouts,
+  Hero: HeroLayout,
+} satisfies LayoutMap
+```
+
+Reference it from deck frontmatter:
+
+```yaml
+---
+layouts: "./layouts"
+---
+```
+
+Use it on any slide:
+
+```mdx
+---
+layout: Hero
+---
+
+# Special slide
+
+With a custom gradient background.
+```
+
+You can also import a React component directly and wrap slide content when you do not need a layout map:
+
+```mdx
+---
+
+import { GradientPanel } from './components/GradientPanel'
+
+<GradientPanel>
+# Special slide
+</GradientPanel>
+
+---
+```
+
+## Layout props
+
+`LayoutProps` is generic so layouts can type their accepted frontmatter:
+
+```ts
+type LayoutProps<F extends Record<string, unknown> = Record<string, unknown>> = {
+  title: ReactNode | null
+  children: ReactNode
+  rawChildren: ReactNode
+  frontmatter: F
+}
+```
+
+Example typed layout:
+
+```tsx
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+type CoverFrontmatter = {
+  author?: string
+  date?: string
+}
+
+export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
+  const { author, date } = frontmatter
+  return (/* ... */)
+}
+```
+
+## Layout demos
+
+Layouts can export a `demo` constant for `/#/layouts`:
+
+```tsx
+import type { LayoutDemo, LayoutProps } from '@honeydeck/honeydeck/types'
+
+type HeroFrontmatter = {
+  /** Short label shown above the title. */
+  eyebrow?: string
+}
+
+export default function HeroLayout({ title, children, frontmatter }: LayoutProps<HeroFrontmatter>) {
+  return (/* ... */)
+}
+
+export const demo: LayoutDemo<HeroFrontmatter> = {
+  mdx: `---
+layout: Hero
+eyebrow: Launch
+---
+
+# Hero moment
+
+This snippet and preview come from the same demo.`,
+}
+```
+
+`mdx` is the single source for both the live preview and the copyable usage snippet in the layouts reference page. If no demo is exported, the layout still appears with a “No demo MDX provided” hint.
+
+## Slot components
+
+Layouts that need content slots can export slot components alongside the layout:
+
+```tsx
+// layouts/TwoCol.tsx
+import type { ReactNode } from 'react'
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+export function Left({ children }: { children: ReactNode }) {
+  return <div data-honeydeck-slot="left" className="col-start-1 overflow-hidden">{children}</div>
+}
+
+export function Right({ children }: { children: ReactNode }) {
+  return <div data-honeydeck-slot="right" className="col-start-2 overflow-hidden">{children}</div>
+}
+
+export default function TwoColLayout({ title, children }: LayoutProps) {
+  return (
+    <div className="grid h-full grid-cols-2 gap-12">
+      {children}
+    </div>
+  )
+}
+```
+
+Users import slots from the layout module:
+
+```mdx
+import { Left, Right } from './layouts/TwoCol'
+```
+
+## Image helpers
+
+Built-in placeholder images are available as URL exports for custom image layouts:
+
+```ts
+import {
+  imagePlaceholder,
+  imagePlaceholderDark,
+  verticalImagePlaceholder,
+  verticalImagePlaceholderDark,
+} from '@honeydeck/honeydeck/layouts/placeholders'
+```
+
+Use `ColorModeImage` when a custom layout accepts separate light and dark image URLs:
+
+```tsx
+import { ColorModeImage } from '@honeydeck/honeydeck'
+
+<ColorModeImage src={image} darkSrc={darkImage} alt={alt} />
+```
+
+## Runtime reference
+
+During development, open the built-in reference pages:
+
+- `/#/theme` shows all `--honeydeck-*` CSS tokens with computed values and descriptions.
+- `/#/layouts` shows layouts from the active layout map, live visual previews, copyable snippets, and extracted frontmatter prop docs.
+- `/#/components` shows public built-in components exported from `@honeydeck/honeydeck/components`.

package/docs/{next-steps.md → deeper-dive.md}

@@ -1,4 +1,4 @@
-# Next steps
+# Diving deeper
 
 Use this guide after the quick start when you want to understand the main Honeydeck workflows without jumping straight into every reference page.
 
@@ -285,24 +285,26 @@ All tokens are mapped to Tailwind utilities:
 
 Available color utilities: `primary`, `primary-foreground`, `accent`, `accent-foreground`, `background`, `foreground`, `surface`, `surface-foreground`, and `border`.
 
-See [Kits](kits.md) for theme and layout customization.
+See [Customization](customization.md) for theme and layout customization.
 
-## Kits
+## Customization
 
-A kit is an npm package bundling a theme, layouts, and components.
+Customize Honeydeck with explicit CSS imports, React component imports, and layout maps.
 
 ```mdx
 ---
-layouts: "@company/honeydeck-kit-brand/layouts"
+layouts: "./layouts"
 ---
 
-import '@company/honeydeck-kit-brand/theme.css'
-import { Callout } from '@company/honeydeck-kit-brand/components'
+import './styles.css'
+import { Callout } from './components/Callout'
 
-# Slide with brand kit
+# Slide with custom pieces
+
+<Callout>Important!</Callout>
 ```
 
-Zero config still works: built-in defaults apply without imports. See [Kits](kits.md) and [Kit authoring](kit-authoring.md).
+Zero config still works: built-in defaults apply without imports. See [Customization](customization.md).
 
 ## Runtime reference
 

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-Honeydeck helps you create polished, interactive presentations from plain-text MDX. Write slides in Markdown, add React components when you need them, and present with built-in layouts, speaker notes, presenter mode, and PDF export.
+Honeydeck helps you create polished, interactive presentations using MDX. Write slides in Markdown, use different Layout, add React components when you need them, present using presenter mode, and export to PDF for easy sharing.
 
 ## Quick start
 
@@ -21,11 +21,11 @@ npm run build
 npm run pdf
 ```
 
-Running `honeydeck` with no subcommand shows CLI help.
+`npx @honeydeck/honeydeck` to see cli help.
 
 ## Your first deck
 
-Decks are MDX files. The first frontmatter block configures the deck and opening slide. Later `---` separators start new slides.
+Decks are MDX files. The first frontmatter block [configures the deck](configuration.md) and opening slide. Later `---` separators start new slides.
 
 ```mdx
 ---
@@ -62,7 +62,7 @@ Add React when it helps.
 </Right>
 ```
 
-Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
+Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`. See them in the [showacase/#/layouts](https://showcase.honeydeck.dev/#/layouts).
 
 ## What Honeydeck gives you
 
@@ -76,6 +76,13 @@ Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Defau
 - PDF export through headless Chromium
 - Optional Honeydeck agent skills for writing and migration help
 
+## Navigating your deck
+
+- Next or previous step using `→` `d` / `←` `a`
+- Next or previous slide with `↓` `s` / `↑` `w`
+- Overview of all slides `o`
+- Presenter mode `p`
+
 ## Common commands
 
 ```bash
@@ -91,13 +98,12 @@ honeydeck skill               # install optional Honeydeck agent skills
 
 ## Where to go next
 
-- [Next steps](next-steps.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills in one follow-up guide
+- [Deeper dive](deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills in one follow-up guide
 - [Slides](slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](configuration.md) - deck-level and slide-level frontmatter
 - [Steps and reveals](steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
 - [Components](components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
-- [Kits](kits.md) - themes, layout sets, Tailwind tokens, and third-party kits
-- [Kit authoring](kit-authoring.md) - layout maps, layout props, demos, and design tokens for kit authors
+- [Customization](customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](mobile.md) - mobile controls, touch gestures, and pinch zoom
 - [Presenter mode](presenter-mode.md) - notes, presenter window, sync, and mobile behavior
@@ -113,4 +119,6 @@ During development, open the runtime reference pages to see:
 - layout previews with copyable usage snippets
 - built-in component docs
 
+See those in our [showcase](https://showcase.honeydeck.dev/#/layouts)
+
 Honeydeck is built with MDX, React, Vite, and Tailwind v4.

package/docs/slidev-migration.md

@@ -34,7 +34,7 @@ The skill guides an agent through the common Slidev-to-Honeydeck mapping:
 | `pages/*.md` with `src:` includes | imported `.mdx` slide groups |
 | `public/**` | `public/**` |
 | `components/*.vue` | React `components/*.tsx` |
-| `layouts/*.vue` or Slidev themes | Honeydeck layouts, layout maps, or kits |
+| `layouts/*.vue` or Slidev themes | Honeydeck layouts, layout maps, React components, and CSS |
 | `<v-click>` / `<v-clicks>` | `<Reveal>` / `<RevealGroup>` |
 | trailing note comments | `<Notes>` |
 | `slidev`, `slidev build`, `slidev export` | `honeydeck dev`, `honeydeck build`, `honeydeck pdf` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.1.2",
+	"version": "0.2.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {
@@ -89,7 +89,6 @@
 		"#vite-plugin/*": "./src/vite-plugin/*"
 	},
 	"scripts": {
-		"build": "npm run typecheck",
 		"dev": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
 		"dev:init": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
 		"format": "biome check --write",

package/skills/SPEC.md

@@ -6,14 +6,14 @@
 
 Honeydeck ships installable agent skills:
 
-- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, kits, canonical package docs, and runtime reference pages.
+- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, canonical package docs, and runtime reference pages.
 - `skills/presentation-writing/SKILL.md` (`presentation-writing`) gives opinionated guidance for writing great slides and delivering good presentations: audience/goal/duration discovery, storyline, one idea per slide, strong headlines, sparse visuals, speaker notes, timing, narrative flow, progressive disclosure, and review heuristics.
 - `skills/slidev-migration/SKILL.md` (`slidev-migration`) helps AI agents migrate presentations from Slidev/sli.dev to Honeydeck: initialize a Honeydeck project when needed, convert `slides.md` to `deck.mdx`, map Slidev frontmatter/layouts/assets/notes/reveals/scripts to Honeydeck equivalents, and flag Vue/theme features that need manual React follow-up.
 
 Expected behavior:
 
 - All skills are discoverable by the `skills` CLI when users run `npx skills add <honeydeck-repo-url> --copy` or explicit `npx skills add <honeydeck-repo-url> --copy --skill honeydeck` / `--skill presentation-writing` / `--skill slidev-migration`.
-- The `honeydeck` skill instructs agents to use Honeydeck documentation (`Readme.md` for package overview, `docs/getting-started.md` for first-run guidance, package/root `SPEC.md`, linked colocated `SPEC.md` files, `docs/next-steps.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/kits.md`, `docs/configuration.md`, and related docs) as the source of truth when available.
+- The `honeydeck` skill instructs agents to use Honeydeck documentation (`Readme.md` for package overview, `docs/getting-started.md` for first-run guidance, package/root `SPEC.md`, linked colocated `SPEC.md` files, `docs/deeper-dive.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/customization.md`, `docs/configuration.md`, and related docs) as the source of truth when available.
 - The `honeydeck` skill documents a local docs discovery order: current project's `node_modules/@honeydeck/honeydeck`, monorepo checkout `packages/honeydeck`, package-root checkout docs, then the public docs URL.
 - The `presentation-writing` skill is framework-agnostic enough to help with presentation quality, while still working well alongside the Honeydeck skill.
 - The `slidev-migration` skill instructs agents to inspect existing Slidev projects, preserve source files until the user approves cleanup, initialize or merge Honeydeck starter files, migrate common Slidev syntax to Honeydeck MDX/React, and document unsupported or approximated features.

package/skills/honeydeck/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: honeydeck
-description: Help users create, edit, debug, and export Honeydeck MDX presentations. Use for Honeydeck syntax, deck.mdx structure, layouts, frontmatter, steps/reveals, presenter notes, code blocks, custom React components, kits/themes, CLI commands, dev preview, build, or PDF export.
+description: Help users create, edit, debug, and export Honeydeck MDX presentations. Use for Honeydeck syntax, deck.mdx structure, layouts, frontmatter, steps/reveals, presenter notes, code blocks, custom React components, themes, CLI commands, dev preview, build, or PDF export.
 ---
 
 # Honeydeck
@@ -22,11 +22,11 @@ Important docs:
 
 - `Readme.md` for the compact package overview and documentation index
 - `docs/getting-started.md` for quick start and first-run orientation
-- `docs/next-steps.md` for CLI details, feature overview, architecture, exports, and agent skills
+- `docs/deeper-dive.md` for CLI details, feature overview, architecture, exports, and agent skills
 - root/package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
 - `docs/slides.md` for deck structure, slide separators, and multi-file decks
 - `docs/steps-and-reveals.md` for step-by-step reveals and code steps
-- `docs/kits.md` and `docs/kit-authoring.md` for themes, layouts, and reusable kits
+- `docs/customization.md` for themes, layouts, custom React components, layout maps, demos, and design tokens
 - `docs/configuration.md` for frontmatter options
 - `docs/navigation.md`, `docs/mobile.md`, `docs/presenter-mode.md`, and `docs/pdf-export.md` for presenting/exporting