@honeydeck/honeydeck 0.1.2 → 0.3.0

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>
-```

package/docs/kits.md

@@ -1,387 +0,0 @@
-# Customization - Kits
-
-Honeydeck works out of the box with sensible defaults. Customize progressively — override a color, swap a layout, or adopt a full kit from npm.
-
-## Zero Config
-
-A plain deck needs no imports or configuration:
-
-```mdx
-# Hello world
-
-This just works with built-in styling.
-```
-
-Honeydeck automatically loads base CSS with default design tokens and the built-in layout set.
-
-## Customizing Colors & Typography
-
-Import a CSS file to override design tokens. The cascade does the rest:
-
-```mdx
-import './my-theme.css'
-
-# Now with my brand colors
-```
-
-```css
-/* my-theme.css */
-:root {
-  --honeydeck-primary: oklch(55% 0.25 280);
-  --honeydeck-font-heading: 'Playfair Display', serif;
-  --honeydeck-border-radius: 1rem;
-}
-```
-
-You only override what you want — everything else keeps its default. Both light and dark modes can be targeted:
-
-```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);
-}
-```
-
-### Available Tokens
-
-| Token | Purpose |
-|-------|---------|
-| `--honeydeck-primary` | Brand color (per mode) |
-| `--honeydeck-background` | Slide background |
-| `--honeydeck-foreground` | Main text color |
-| `--honeydeck-surface` | Cards, code blocks, callouts |
-| `--honeydeck-border` | Border/divider color |
-| `--honeydeck-accent` | Accent, computed as complementary by default |
-| `--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-border-radius` | Default border radius |
-| `--honeydeck-code-line-dim-opacity` | Dim for non-highlighted code lines |
-
-→ Full token reference in [Kit Authoring](kit-authoring.md#design-tokens)
-
-### Bundled Themes
-
-Honeydeck defaults to a clean black, white, and grey theme:
-
-```css
-@import "tailwindcss";
-@import "@honeydeck/honeydeck/theme.css";
-```
-
-`@honeydeck/honeydeck/themes/clean.css` is available as an optional clean theme layer when you want to name that layer directly.
-
-Honeydeck also includes a Bee theme that can be layered on top of the base theme:
-
-```css
-@import "tailwindcss";
-@import "@honeydeck/honeydeck/theme.css";
-@import "@honeydeck/honeydeck/themes/bee.css";
-```
-
-### Bundled Layout Sets
-
-The default layout set is clean and minimal:
-
-```yaml
----
-layouts: "@honeydeck/honeydeck/layouts"
----
-```
-
-The same clean set is also available through the named clean kit import path `@honeydeck/honeydeck/layouts/clean`.
-
-Use the Bee layout set with the Bee theme when you want the original playful Bee look:
-
-```yaml
----
-layouts: "@honeydeck/honeydeck/layouts/bee"
----
-```
-
-For two-column slides, import slots from the matching layout set:
-
-```mdx
-// Clean default
-import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
-```
-
-```mdx
-// Bee layout set
-import { Left, Right } from '@honeydeck/honeydeck/layouts/bee/TwoCol'
-```
-
-### Using Tailwind
-
-Tokens are mapped to Tailwind utilities, so you can use them inline:
-
-```mdx
-<div className="bg-surface text-surface-foreground border border-border rounded-honeydeck">
-  Styled with theme tokens
-</div>
-```
-
-## Using Layouts
-
-in your decks frontmatter, configure which layouts to use:
-
-```yaml
----
-layouts: "awsome-kit/layouts"
----
-```
-
-Select a layout in slide frontmatter:
-
-```yaml
----
-layout: Section
----
-
-# Big Idea
-```
-
-If no `layout:` is specified, `Default` is used. Layout names are PascalCase.
-
-### Built-in Layouts
-
-| 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 (title, body, author) |
-| `TwoCol` | Two equal columns |
-| `Image` | Prominent image with optional title and children |
-| `ImageLeft` | Prominent left image with title and body on the right |
-| `ImageRight` | Prominent right image with title and body on the left |
-
-### Passing Props to Layouts
-
-Layouts receive extra frontmatter fields as props; Cover body copy belongs in the slide content:
-
-```mdx
----
-layout: Cover
-author: You_Name_Here
----
-
-# Honeydeck
-
-A modern slide framework.
-```
-
-### Two-Column Layout
-
-`TwoCol` uses slot components you import:
-
-```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>
-```
-
-### Image Layout
-
-Displays a specified image large and prominent:
-
-```yaml
----
-layout: Image
-image: /diagrams/architecture.png
-darkImage: /diagrams/architecture-dark.png
----
-
-# System Architecture
-
-Our distributed system.
-```
-
-### Side Image Layouts
-
-`ImageLeft` and `ImageRight` place the image beside the content while using the same `image`, `darkImage`, and `alt` frontmatter as `Image`:
-
-```yaml
----
-layout: ImageRight
-image: /photos/launch.jpg
-darkImage: /photos/launch-dark.jpg
-alt: Launch moment
----
-
-# Launch Moment
-
-Supporting context sits beside the image.
-```
-
-## Creating Custom Layouts
-
-Custom layouts are React components you import and wrap content with:
-
-```tsx
-// components/GradientLayout.tsx
-import type { ReactNode } from 'react'
-
-export function GradientLayout({ children }: { children: ReactNode }) {
-  return (
-    <div className="grid place-items-center h-full bg-gradient-to-br from-purple-900 to-indigo-900 text-white p-12">
-      {children}
-    </div>
-  )
-}
-```
-
-Use it in MDX:
-
-```mdx
----
-
-import { GradientLayout } from './components/GradientLayout'
-
-<GradientLayout>
-# Special Slide
-
-With a custom gradient background.
-</GradientLayout>
-
----
-```
-
-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} />
-```
-
-### Creating a Reusable Layout Set
-
-For a set of layouts you want to reuse across slides or decks, create a layout map:
-
-```ts
-// layouts/index.ts
-import defaultLayouts from '@honeydeck/honeydeck/layouts'
-import HeroLayout from './Hero'
-
-export default {
-  ...defaultLayouts,
-  Hero: HeroLayout,
-}
-```
-
-Layouts can export a colocated demo for `/#/layouts`:
-
-```tsx
-// layouts/Hero.tsx
-import type { LayoutDemo, LayoutProps } from '@honeydeck/honeydeck/types'
-
-export default function HeroLayout({ title, children }: LayoutProps) {
-  return (/* ... */)
-}
-
-export const demo: LayoutDemo = {
-  mdx: `---
-layout: Hero
----
-
-# Hero Moment
-
-This snippet and preview come from the same demo.`,
-}
-```
-
-Reference it in deck frontmatter:
-
-```yaml
----
-layouts: "./layouts"
----
-```
-
-Now you can use `layout: Hero` in any slide. The docs reference lists every layout in the active map, even if no slide currently uses it.
-
-## Using Third-Party Kits
-
-A **kit** is an npm package that bundles theme CSS, layouts, and/or components. You reference each part individually:
-
-```yaml
----
-layouts: "@company/honeydeck-kit-brand/layouts"
----
-```
-
-```mdx
-import '@company/honeydeck-kit-brand/theme.css'
-import { Callout } from '@company/honeydeck-kit-brand/components'
-
-# Hello
-
-<Callout>Important!</Callout>
-```
-
-### Mix and Match
-
-Since each concern is an explicit reference, mix freely:
-
-```yaml
----
-layouts: "@company/honeydeck-kit-brand/layouts"
----
-```
-
-```mdx
-import '@other/honeydeck-kit-minimal/theme.css'
-import { Callout } from '@company/honeydeck-kit-brand/components'
-```
-
-Use layouts from one kit, colors from another, components from a third.
-
-### Extending a Kit's Theme
-
-Layer your overrides on top of a kit's CSS:
-
-```css
-/* my-overrides.css */
-@import '@company/honeydeck-kit-brand/theme.css';
-
-:root {
-  --honeydeck-primary: oklch(50% 0.2 300);
-  --honeydeck-font-heading: 'My Font', sans-serif;
-}
-```
-
-```mdx
-import './my-overrides.css'
-```
-
-→ Building your own kit? See [Kit Authoring](kit-authoring.md)