@honeydeck/honeydeck 0.1.0

package/docs/kits.md

@@ -0,0 +1,387 @@
+# 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)

package/docs/local-development.md

@@ -0,0 +1,95 @@
+# Local development
+
+This guide explains how to test Honeydeck locally before it is published to npm.
+
+## Prerequisites
+
+Honeydeck is currently developed and tested with Node 26+.
+
+```bash
+node --version
+```
+
+## Run Honeydeck from the repository
+
+From the Honeydeck repository:
+
+```bash
+npm install
+npm run dev
+```
+
+Root `npm run dev` starts the private showcase deck package and the marketing/docs site together.
+
+To run only the showcase deck:
+
+```bash
+npm -w @honeydeck/showcase run dev
+```
+
+To demo the starter deck generated by `honeydeck init`, run:
+
+```bash
+npm -w @honeydeck/honeydeck run dev
+```
+
+That points at the real starter template files through the source CLI:
+
+```bash
+node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx
+```
+
+## Link the local CLI
+
+From the Honeydeck package directory:
+
+```bash
+cd packages/honeydeck
+npm link
+```
+
+Then from any folder:
+
+```bash
+honeydeck --help
+honeydeck init --name demo-deck --skip-install
+```
+
+`npm link` exposes the local `honeydeck` command, but it does not publish Honeydeck to the npm registry.
+
+## Install local Honeydeck in a generated project
+
+Until Honeydeck is published, `npm install` inside a generated project may fail with:
+
+```txt
+404 Not Found - GET https://registry.npmjs.org/@honeydeck%2fhoneydeck - Not found
+```
+
+This happens because the generated project depends on `@honeydeck/honeydeck`, but npm cannot find it in the public registry yet.
+
+For local testing, link the local Honeydeck package into the generated project:
+
+```bash
+cd /path/to/generated-project
+npm link @honeydeck/honeydeck
+npm install
+npm run dev
+```
+
+If the global link does not exist yet, create it first from the Honeydeck package directory:
+
+```bash
+cd /path/to/honeydeck/packages/honeydeck
+npm link
+```
+
+You can also link the package folder directly without a global link step:
+
+```bash
+cd /path/to/generated-project
+npm link /path/to/honeydeck/packages/honeydeck
+npm install
+npm run dev
+```
+
+`npm link` keeps the generated project wired to your local checkout. Changes in the Honeydeck package are picked up without publishing to npm.

package/docs/mermaid.md

@@ -0,0 +1,198 @@
+# Mermaid
+
+Mermaid is not part of Honeydeck core. Use it as a normal project dependency and render diagrams through a local React component that you import from your deck.
+
+## Install
+
+```bash
+npm install mermaid
+```
+
+## Add a component
+
+Create `components/Mermaid.tsx`:
+
+```tsx
+import mermaid from "mermaid";
+import {
+	isValidElement,
+	type ReactNode,
+	useEffect,
+	useId,
+	useRef,
+	useState,
+} from "react";
+
+type MermaidProps = {
+	chart?: string;
+	children?: ReactNode;
+};
+
+function childrenToChart(children: ReactNode): string {
+	if (typeof children === "string" || typeof children === "number") {
+		return String(children);
+	}
+
+	if (Array.isArray(children)) {
+		return children.map(childrenToChart).join("");
+	}
+
+	if (isValidElement<{ children?: ReactNode }>(children)) {
+		return childrenToChart(children.props.children);
+	}
+
+	return "";
+}
+
+function themeColor(name: string, fallback: string): string {
+	const value = getComputedStyle(document.documentElement)
+		.getPropertyValue(name)
+		.trim();
+	return value || fallback;
+}
+
+function readHoneydeckColorMode(): "light" | "dark" {
+	if (typeof document === "undefined") return "light";
+	return document.documentElement.getAttribute("data-honeydeck-color-mode") ===
+		"dark"
+		? "dark"
+		: "light";
+}
+
+function useHoneydeckColorMode(): "light" | "dark" {
+	const [colorMode, setColorMode] = useState(readHoneydeckColorMode);
+
+	useEffect(() => {
+		const observer = new MutationObserver(() => {
+			setColorMode(readHoneydeckColorMode());
+		});
+
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: ["data-honeydeck-color-mode"],
+		});
+
+		return () => observer.disconnect();
+	}, []);
+
+	return colorMode;
+}
+
+export function Mermaid({ chart, children }: MermaidProps) {
+	const id = useId().replace(/[^a-zA-Z0-9_-]/g, "");
+	const ref = useRef<HTMLDivElement>(null);
+	const [error, setError] = useState<string | null>(null);
+	const colorMode = useHoneydeckColorMode();
+	const source = (chart ?? childrenToChart(children)).trim();
+
+	useEffect(() => {
+		let cancelled = false;
+
+		async function render() {
+			setError(null);
+
+			try {
+				const background = themeColor("--honeydeck-background", "#ffffff");
+				const foreground = themeColor("--honeydeck-foreground", "#111111");
+				const surface = themeColor("--honeydeck-surface", "#f3f4f6");
+				const surfaceForeground = themeColor(
+					"--honeydeck-surface-foreground",
+					foreground,
+				);
+				const primary = themeColor("--honeydeck-primary", "#6d4aff");
+				const accent = themeColor("--honeydeck-accent", primary);
+				const fontFamily = themeColor(
+					"--honeydeck-font-body",
+					"ui-sans-serif, system-ui, sans-serif",
+				);
+
+				mermaid.initialize({
+					startOnLoad: false,
+					theme: "base",
+					securityLevel: "strict",
+					themeVariables: {
+						background,
+						mainBkg: accent,
+						primaryColor: accent,
+						primaryBorderColor: primary,
+						primaryTextColor: surfaceForeground,
+						secondaryColor: surface,
+						secondaryBorderColor: accent,
+						secondaryTextColor: foreground,
+						tertiaryColor: accent,
+						tertiaryBorderColor: primary,
+						tertiaryTextColor: surfaceForeground,
+						lineColor: primary,
+						arrowheadColor: primary,
+						textColor: foreground,
+						fontFamily,
+						fontSize: "16px",
+						actorBkg: accent,
+						actorBorder: primary,
+						actorTextColor: surfaceForeground,
+						activationBkgColor: background,
+						activationBorderColor: accent,
+						signalColor: primary,
+						signalTextColor: foreground,
+						noteBkgColor: accent,
+						noteBorderColor: accent,
+						noteTextColor: surfaceForeground,
+					},
+				});
+
+				const result = await mermaid.render(`mermaid-${id}`, source);
+				if (cancelled || !ref.current) return;
+
+				ref.current.innerHTML = result.svg;
+				result.bindFunctions?.(ref.current);
+			} catch (err) {
+				if (cancelled) return;
+				setError(err instanceof Error ? err.message : String(err));
+			}
+		}
+
+		void render();
+
+		return () => {
+			cancelled = true;
+		};
+	}, [source, id, colorMode]);
+
+	return (
+		<figure className="user-mermaid m-0 overflow-x-auto rounded-honeydeck border border-border bg-surface p-[1em] text-surface-foreground">
+			{error ? (
+				<pre className="m-0 whitespace-pre-wrap rounded-honeydeck bg-background p-3 text-foreground">
+					<code>{error}</code>
+				</pre>
+			) : (
+				<div ref={ref} />
+			)}
+		</figure>
+	);
+}
+```
+
+## Add styles
+
+Add this to your `styles.css`, after your Honeydeck theme imports:
+
+```css
+.user-mermaid svg :is(p, div, span, .label, .nodeLabel, .edgeLabel) {
+	/* Honeydeck slide typography is large; keep Mermaid labels diagram-sized. */
+	font-size: 16px;
+}
+```
+
+## Use it in MDX
+
+```mdx
+import { Mermaid } from './components/Mermaid'
+
+<Mermaid>
+flowchart LR
+  A[Idea] --> B[Deck]
+  B --> C[Presentation]
+</Mermaid>
+```
+
+For a runnable example, see the repository's `demos/mermaid` folder.