@honeydeck/honeydeck 0.1.2 → 0.2.0

package/skills/slidev-migration/SKILL.md

@@ -16,7 +16,7 @@ Before changing files, read the available project/package docs:
 - `Readme.md`, `docs/getting-started.md`, root `SPEC.md`, linked colocated `SPEC.md` files, and `docs/slides.md` for Honeydeck deck structure
 - `docs/configuration.md` for Honeydeck frontmatter
 - `docs/steps-and-reveals.md` for Reveal/RevealGroup/code steps
-- `docs/kits.md` and `docs/kit-authoring.md` for layouts/themes/components
+- `docs/customization.md` for layouts, themes, components, layout maps, and design tokens
 - Existing Slidev files: `slides.md`, `pages/**/*.md`, `components/**/*.vue`, `layouts/**/*.vue`, `styles/**`, `public/**`, `package.json`, `vite.config.*`, and local theme/addon packages
 
 If Honeydeck docs are not nearby, package docs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
@@ -51,7 +51,7 @@ Create a working Honeydeck presentation that preserves the talk's structure, con
 | `public/**` | `public/**` copied unchanged; root-relative `/assets/...` paths usually keep working |
 | `components/*.vue` | `components/*.tsx` React components |
 | `layouts/*.vue` | React layouts plus a layout map selected with deck frontmatter `layouts: "./layouts"` |
-| Slidev theme package | Honeydeck kit/theme/layout map, or local React layouts + CSS |
+| Slidev theme package | Honeydeck theme CSS, layout map, or local React layouts + CSS |
 | `styles/style.css` or `styles/index.*` | `styles.css` imported from `deck.mdx` |
 | `slidev`, `slidev build`, `slidev export` scripts | `honeydeck dev`, `honeydeck build`, `honeydeck pdf` scripts |
 

package/src/cli/index.ts

@@ -116,7 +116,7 @@ ${formatTopLevelBanner()}
     honeydeck dev --open
     honeydeck pdf --steps all --mode dark -o slides.pdf
 
-  🎞  Happy presenting!
+  🐝  Happy presenting!
 `);
 }
 

package/src/layouts/SPEC.md

@@ -1,170 +1,99 @@
-# Honeydeck Layouts and Kits Specification
+# Honeydeck Layouts and Customization Specification
 
-> Observable behavior for kits, layout maps, built-in layouts, layout props, and layout demos.
+> Observable behavior for theme CSS, layout maps, built-in layouts, layout props, and layout demos.
 
-## Kits — Theme, Layouts, Components
+## Customization — Theme CSS, Layout Maps, Components
 
-A **kit** is an npm package (or local folder) that bundles three concerns. Honeydeck does not require a special registry mechanism; themes are CSS imports, layouts are default-exported layout maps, and components are normal React/MDX imports:
+Honeydeck customization is explicit composition. Themes are CSS imports, layouts come from a default-exported layout map, and components are normal React/MDX imports:
 
 | Concern | What it is | How it's used |
 |---------|-----------|---------------|
-| Theme | CSS file (tokens, colors, typography) | explicit CSS import from MDX or another CSS file |
-| Layouts | Layout component map | `layouts:` in frontmatter |
-| Components | Reusable React components | `import` in MDX |
+| Theme | CSS file with tokens, colors, and typography | explicit CSS import from MDX or another CSS file |
+| Layouts | layout component map | `layouts:` in frontmatter |
+| Components | reusable React components | explicit `import` in MDX |
 
-### Kit Package Structure
+These references may point to local project files or normal installed packages. Honeydeck does not provide special publishing or registry behavior.
 
-```txt
-@company/honeydeck-kit-brand/
-  package.json
-  theme.css              ← CSS tokens/variables
-  layouts/
-    index.ts             ← exports LayoutMap
-    Blank.tsx
-    Default.tsx
-    Cover.tsx
-    Section.tsx
-    TwoCol.tsx
-    Image.tsx
-    ImageLeft.tsx
-    ImageRight.tsx
-  components/
-    Callout.tsx
-    Badge.tsx
-```
+### Zero Config
 
-### Using a Kit
+A plain `deck.mdx` file with no frontmatter still works with built-in layouts:
 
 ```mdx
----
-title: My Talk
-layouts: "@company/honeydeck-kit-brand/layouts"
----
-
-import '@company/honeydeck-kit-brand/theme.css'
-import './my-overrides.css'
-
-import { Callout } from '@company/honeydeck-kit-brand/components'
-
-# First slide
+# Hello world
 
-<Callout>Important!</Callout>
+This renders with the built-in default layout.
 ```
 
-### Mix and Match
+Styling is provided only by explicit CSS imports. Honeydeck does not auto-inject Tailwind, `@honeydeck/honeydeck/theme.css`, or custom theme CSS. The starter project imports `./styles.css` from `deck.mdx`; `styles.css` imports Tailwind and `@honeydeck/honeydeck/theme.css`. Without that import, slides still render with built-in layouts, but mostly with browser/default styling. User imports override via cascade.
 
-Theme CSS from one kit, layouts from another, components from a third:
+### Theme Layering
 
-```mdx
----
-layouts: "@company/honeydeck-kit-brand/layouts"
----
-
-import '@other/honeydeck-kit-minimal/theme.css'
-import { Badge } from '@third/honeydeck-kit-fancy/components'
-```
-
-### Local Kits
-
-Create a kit in your project folder:
+Honeydeck ships optional theme layers that are imported after the base theme. Theme layers are token overrides and are not standalone replacements for the base theme:
 
-```txt
-awesome-talk/
-  theme.css
-  layouts/
-    index.ts
-    MyCustom.tsx
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+@import "@honeydeck/honeydeck/themes/clean.css";
 ```
 
-Reference locally (relative to the deck entry file):
+Honeydeck includes:
 
-```yaml
----
-layouts: "./layouts"
----
-```
+| Theme import | Purpose |
+|--------------|---------|
+| `@honeydeck/honeydeck/theme.css` | Preferred base theme import; clean black/white/grey defaults |
+| `@honeydeck/honeydeck/themes/base.css` | Package export alias for the base theme |
+| `@honeydeck/honeydeck/themes/clean.css` | Optional clean visual style layer |
+| `@honeydeck/honeydeck/themes/bee.css` | Bee theme layer for the original playful palette |
 
-```mdx
-import './theme.css'
-```
+Use `@honeydeck/honeydeck/layouts` for clean default layouts. Use `@honeydeck/honeydeck/layouts/bee` together with `@honeydeck/honeydeck/themes/bee.css` for the Bee visual style.
 
-### Kit CSS Inheritance
+### CSS Overrides
 
-Use standard CSS `@import` for extending another kit's theme:
+Use standard CSS cascade and `@import` to layer overrides:
 
 ```css
-/* theme.css — extends company kit */
-@import '@company/honeydeck-kit-brand/theme.css';
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
 
 :root {
   --honeydeck-primary: oklch(55% 0.25 145);
 }
 ```
 
-### Layout Inheritance
+### Layout Maps
 
-Use JS spread to compose layouts from multiple sources:
+Create a layout map in the project and reference it relative to the deck entry file:
+
+```yaml
+---
+layouts: "./layouts"
+---
+```
+
+Layout maps may compose entries with JavaScript spread:
 
 ```ts
 // layouts/index.ts
-import companyLayouts from '@company/honeydeck-kit-brand/layouts'
-import fancyLayouts from '@fancy/honeydeck-kit/layouts'
+import defaultLayouts from '@honeydeck/honeydeck/layouts'
 import { MyCustomCover } from './Cover'
 
 export default {
-  ...companyLayouts,
-  Section: fancyLayouts.Section,
+  ...defaultLayouts,
   Cover: MyCustomCover,
 } satisfies LayoutMap
 ```
 
-### Zero Config
-
-A plain `deck.mdx` file with no frontmatter still works with built-in layouts:
-
-```mdx
-# Hello world
-
-This renders with the built-in default layout.
-```
-
-Styling is provided only by explicit CSS imports. Honeydeck does not auto-inject Tailwind, `@honeydeck/honeydeck/theme.css`, or kit theme CSS. The starter project imports `./styles.css` from `deck.mdx`; `styles.css` imports Tailwind and `@honeydeck/honeydeck/theme.css`. Without that import, slides still render with built-in layouts, but mostly with browser/default styling. User imports override via cascade.
-
-### Bundled Theme Layers
-
-Honeydeck ships optional theme layers that are imported after the base theme. Theme layers are token overrides and are not standalone replacements for the base theme:
-
-```css
-@import "tailwindcss";
-@import "@honeydeck/honeydeck/theme.css";
-@import "@honeydeck/honeydeck/themes/clean.css";
-```
-
-Honeydeck includes:
-
-| Theme import | Purpose |
-|--------------|---------|
-| `@honeydeck/honeydeck/theme.css` | Preferred base theme import; clean black/white/grey defaults |
-| `@honeydeck/honeydeck/themes/base.css` | Package export alias for the base theme |
-| `@honeydeck/honeydeck/themes/clean.css` | Optional clean visual style layer |
-| `@honeydeck/honeydeck/themes/bee.css` | Bee theme layer for the original playful palette |
-
-Use `@honeydeck/honeydeck/layouts` for clean default layouts. Use `@honeydeck/honeydeck/layouts/bee` together with `@honeydeck/honeydeck/themes/bee.css` for the Bee visual style.
-
 ### Progressive Customization
 
 ```txt
 Level 0: plain `deck.mdx`    → built-in layouts, browser/default styling
-Level 1: import CSS             → Tailwind, base styling, and token overrides
-Level 2: set layouts:           → custom layout map
-Level 3: local kit folder       → full control
-Level 4: publish npm kit        → share across projects
+Level 1: import CSS          → Tailwind, base styling, and token overrides
+Level 2: import components   → reusable React pieces in MDX
+Level 3: set layouts:        → custom layout map
 ```
 
 ---
 
----
-
 ## Layouts
 
 ### Default Layouts

package/src/runtime/views/SPEC.md

@@ -100,7 +100,7 @@ Toggled via `o` or the overview button. Overview is also directly addressable as
 
 Built-in reference pages start at `/#/theme`. Included in both dev and production builds.
 
-User-facing product copy should call this area "reference pages". Reserve "kit" for the reusable theme/layout/component package concept described in [Kits — Theme, Layouts, Components](../../layouts/SPEC.md#kits--theme-layouts-components).
+User-facing product copy should call this area "reference pages". Theme, layout, and component customization is described in [Customization — Theme CSS, Layout Maps, Components](../../layouts/SPEC.md#customization--theme-css-layout-maps-components).
 
 ### Routes
 

package/docs/kit-authoring.md

@@ -1,207 +0,0 @@
-# Kit Authoring
-
-Guide for building reusable Honeydeck kits (themes, layouts, components).
-
-## Type Exports
-
-All types for kit authors come from the `'honeydeck'` package:
-
-```ts
-import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck'
-```
-
-| Type | Purpose |
-|------|---------|
-| `LayoutProps<F>` | Props passed to layout components (generic for frontmatter) |
-| `LayoutMap` | `Record<string, ComponentType<LayoutProps<any>>>` |
-| `LayoutDemo<F>` | Demo data for the docs reference page |
-
-## Layout Map
-
-The `layouts:` frontmatter resolves to a module that default-exports a `LayoutMap`:
-
-```ts
-import type { LayoutMap } from '@honeydeck/honeydeck'
-import { BlankLayout } from './Blank'
-import { DefaultLayout } from './Default'
-import { CoverLayout } from './Cover'
-import { SectionLayout } from './Section'
-import { TwoColLayout } from './TwoCol'
-import { ImageLayout } from './Image'
-import { ImageLeftLayout } from './ImageLeft'
-import { ImageRightLayout } from './ImageRight'
-
-export default {
-  Blank: BlankLayout,
-  Default: DefaultLayout,
-  Cover: CoverLayout,
-  Section: SectionLayout,
-  TwoCol: TwoColLayout,
-  Image: ImageLayout,
-  ImageLeft: ImageLeftLayout,
-  ImageRight: ImageRightLayout,
-} satisfies LayoutMap
-```
-
-## 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       // extracted first h1 content
-  children: ReactNode           // remaining content (h1 removed)
-  rawChildren: ReactNode        // full unmodified content (h1 included)
-  frontmatter: F
-}
-```
-
-Example typed layout:
-
-```tsx
-import type { LayoutProps } from '@honeydeck/honeydeck'
-
-type CoverFrontmatter = {
-  author?: string
-  date?: string
-}
-
-export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
-  const { author, date } = frontmatter
-  return (/* ... */)
-}
-```
-
-This enables a future language server to extract frontmatter types for autocomplete.
-
-## Image Helpers
-
-Custom layouts can import `ColorModeImage` from `honeydeck` to render optional light/dark image variants with Honeydeck's Tailwind color-mode utilities:
-
-```tsx
-import { ColorModeImage } from '@honeydeck/honeydeck'
-
-<ColorModeImage src={image} darkSrc={darkImage} alt={alt} />
-```
-
-## Layout Demos
-
-Layouts optionally export a `demo` constant for the docs reference page:
-
-```tsx
-import type { LayoutProps, LayoutDemo } from '@honeydeck/honeydeck'
-
-type CoverFrontmatter = {
-  /** Speaker or organization shown below the title. */
-  author?: string
-}
-
-export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
-	const { author } = frontmatter
-	return (/* ... */)
-}
-
-export const demo: LayoutDemo<CoverFrontmatter> = {
-  mdx: `---
-layout: Cover
-author: Hendrik
----
-
-# Welcome to My Talk
-
-Building the future of presentations.`,
-}
-```
-
-`mdx` is the single source for both the live visual preview and the copyable usage snippet. Honeydeck compiles it with the slide MDX pipeline, extracts frontmatter/title/steps, and renders it through the active layout map.
-
-If no static `demo.mdx` is exported, the layout still appears in `/#/layouts` with a “No demo MDX provided” hint.
-
-## Slot Components
-
-Layouts that need content slots (like `TwoCol`) export slot components alongside the layout:
-
-```tsx
-// layouts/TwoCol.tsx
-import type { LayoutProps } from '@honeydeck/honeydeck'
-import type { ReactNode } from 'react'
-
-export function Left({ children }: { children: ReactNode }) { /* ... */ }
-export function Right({ children }: { children: ReactNode }) { /* ... */ }
-
-export default function TwoColLayout({ title, children }: LayoutProps) {
-  return (/* ... */)
-}
-```
-
-Users import slots from the layout path:
-
-```mdx
-import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
-import { Left, Right } from '@company/honeydeck-kit-brand/layouts/TwoCol'
-```
-
-## Runtime Reference
-
-Honeydeck includes built-in runtime reference pages in dev and production builds:
-
-- **Theme tab (`/#/theme`):** All `--honeydeck-*` CSS tokens with computed values and descriptions.
-- **Layouts tab (`/#/layouts`):** All layouts currently available in the active deck layout map, live visual previews rendered from `demo.mdx`, copyable usage snippets from the same MDX source, and prop docs extracted from `LayoutProps<Frontmatter>` field comments.
-- **Components tab (`/#/components`):** Public built-in components exported from `@honeydeck/honeydeck/components`, generated documentation from exported component JSDoc comments interpreted as Markdown/MDX, side navigation, and params tables extracted from exported props types.
-
-Package Markdown guides are published through the Honeydeck docs site rather than rendered as in-deck pages.
-
-Token descriptions are extracted from CSS comments preceding `--honeydeck-*` declarations at build time.
-
-## Dependency Policy
-
-- `honeydeck` and kits declare `react` and `react-dom` as `peerDependencies`.
-- Kits may declare compatible `honeydeck` versions via `peerDependencies`.
-- Kits using Tailwind declare compatible Tailwind versions as peer dependencies.
-- Generated slide projects install concrete dependency versions.
-
-## 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);
-  /* ... */
-}
-```
-
-Full token list:
-
-| 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 (default: 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 (default: 16px) |
-| `--honeydeck-font-scale` | Heading scale factor (default: 1.25) |
-| `--honeydeck-code-line-dim-opacity` | Dim opacity for non-highlighted code lines |
-
-## Tailwind Mapping
-
-All tokens are mapped to Tailwind utilities:
-
-```mdx
-<div className="bg-surface text-surface-foreground border border-border rounded-honeydeck">
-  Card content
-</div>
-```