design-folio 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# Design Folio
+
+A design presentation system for vibe-coded prototypes. Bridges the gap between how designers build prototypes with Claude and how they share and present design work.
+
+## What it does
+
+Folio wraps your prototype in a viewer with:
+
+- **Prototype tab** — your prototype at full size for testing interactions. No state picker, no design notes. Navigate using the links and UI in your prototype.
+- **Screens tab** — all your screens laid out for design review. Grid view (4-up with pan/zoom) and gallery view (single screen with design notes). This is where you examine design decisions.
+- **Changelog** — Claude-summarized history of what changed and when.
+- **Documents** — links to Figma files, PRDs, research decks, and other external context.
+
+## Setup
+
+Folio is designed to be set up by the `/folio` Claude Code skill, which handles installation, configuration, and ongoing maintenance automatically. You shouldn't need to configure anything manually.
+
+If you want to set it up manually:
+
+```bash
+npm install design-folio --save-dev
+```
+
+Add to your Vite config:
+
+```js
+import { folioPlugin } from 'design-folio/vite';
+
+export default defineConfig({
+  plugins: [folioPlugin()],
+});
+```
+
+Create a `folio.json` at your project root:
+
+```json
+{
+  "name": "Project Name",
+  "designer": "Your Name",
+  "description": "A short paragraph about the project.",
+  "viewport": "desktop",
+  "component": "./src/App.jsx",
+  "states": [
+    {
+      "key": "home",
+      "name": "1. Home",
+      "group": "Main",
+      "state": {},
+      "notes": "Design rationale for this screen."
+    }
+  ]
+}
+```
+
+## Configuration
+
+All fields in `folio.json` are optional. Folio works with zero config by defaulting to `./src/App.jsx` with a desktop viewport.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | `""` | Project name shown in the header |
+| `designer` | string | `""` | Designer name shown in the header |
+| `description` | string | `""` | Project description shown in the prototype tab sidebar |
+| `viewport` | string or object | `"desktop"` | `"desktop"`, `"wide-desktop"`, `"tablet"`, `"mobile"`, `"responsive"`, or `{ width, height }` |
+| `component` | string | `"./src/App.jsx"` | Path to the prototype component |
+| `syncTheme` | boolean | `false` | Pass Folio's light/dark theme to the prototype |
+| `prototypeUrl` | string | `"/"` | URL for "Open prototype" link |
+| `states` | array | `[]` | Screen states with keys, names, groups, state objects, and notes |
+| `changelog` | array | `[]` | Changelog entries grouped by date |
+| `links` | array | `[]` | External document links |
+
+### Viewport presets
+
+| Preset | Dimensions |
+|--------|-----------|
+| `desktop` | 1080 × 720 |
+| `wide-desktop` | 1440 × 900 |
+| `tablet` | 768 × 1024 |
+| `mobile` | 375 × 812 |
+| `responsive` | 100% width, auto height |
+
+### State objects
+
+Each state in the `states` array drives a screen. Your prototype component receives the `state` object as an `appState` prop and should render accordingly.
+
+```json
+{
+  "key": "home-empty",
+  "name": "2. Empty State",
+  "group": "Home",
+  "state": { "items": [], "loading": false },
+  "notes": "Shown before any data is loaded."
+}
+```
+
+## How it works
+
+Folio installs as a Vite plugin that serves your prototype component inside its viewer. Your prototype code is never modified — Folio wraps around it.
+
+The `/folio` skill handles:
+- Detecting your prototype type and structure
+- Generating `folio.json` with states, notes, and changelog
+- Pulling the project description from your README
+- Installing the Tailwind CSS dependency (required by the viewer)
+- Keeping the config updated as you continue vibe coding
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "design-folio",
+  "version": "0.1.0",
+  "description": "A design presentation system for vibe-coded prototypes",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./vite": "./src/plugin/vite-plugin.js",
+    "./styles": "./src/styles/folio.css"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "cd demo && npm run dev",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwindcss": "^4.2.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  },
+  "keywords": [
+    "design",
+    "prototype",
+    "viewer",
+    "vite-plugin"
+  ],
+  "license": "UNLICENSED"
+}

package/src/config/defaults.js

@@ -0,0 +1,19 @@
+export const VIEWPORT_PRESETS = {
+  desktop: { width: 1080, height: 720 },
+  'wide-desktop': { width: 1440, height: 900 },
+  tablet: { width: 768, height: 1024 },
+  mobile: { width: 375, height: 812 },
+  responsive: { width: '100%', height: 'auto' },
+};
+
+export const DEFAULT_CONFIG = {
+  name: '',
+  designer: '',
+  description: '',
+  viewport: 'desktop',
+  component: './src/App.jsx',
+  syncTheme: false,
+  states: [],
+  changelog: [],
+  links: [],
+};

package/src/config/load-config.js

@@ -0,0 +1,20 @@
+import { DEFAULT_CONFIG } from './defaults.js';
+
+/**
+ * Merges a user config object over the defaults.
+ * Returns a new object — does not mutate DEFAULT_CONFIG.
+ * Returns defaults when userConfig is null or undefined.
+ */
+export function mergeConfig(userConfig) {
+  if (userConfig == null) {
+    return { ...DEFAULT_CONFIG, states: [], changelog: [], links: [] };
+  }
+
+  return {
+    ...DEFAULT_CONFIG,
+    ...userConfig,
+    states: Array.isArray(userConfig.states) ? [...userConfig.states] : [...DEFAULT_CONFIG.states],
+    changelog: Array.isArray(userConfig.changelog) ? [...userConfig.changelog] : [...DEFAULT_CONFIG.changelog],
+    links: Array.isArray(userConfig.links) ? [...userConfig.links] : [...DEFAULT_CONFIG.links],
+  };
+}

package/src/hooks/useHashRoute.js

@@ -0,0 +1,93 @@
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * Parses the current window.location.hash into { tab, stateKey }.
+ *
+ * Supported patterns:
+ *   #/state/{key}     → { tab: 'prototype', stateKey: key }
+ *   #/screens/{key}   → { tab: 'screens',   stateKey: key }
+ *   #/screens         → { tab: 'screens',   stateKey: null }
+ *   #/changelog       → { tab: 'changelog', stateKey: null }
+ *   #/documents       → { tab: 'documents', stateKey: null }
+ *   (empty / none)    → { tab: 'prototype', stateKey: null }
+ */
+function parseHash(hash) {
+  if (!hash || hash === '#' || hash === '#/') {
+    return { tab: 'prototype', stateKey: null };
+  }
+
+  // Strip the leading '#'
+  const path = hash.startsWith('#') ? hash.slice(1) : hash;
+  // Strip optional leading '/'
+  const trimmed = path.startsWith('/') ? path.slice(1) : path;
+
+  const stateMatch = trimmed.match(/^state\/(.+)$/);
+  if (stateMatch) {
+    return { tab: 'prototype', stateKey: stateMatch[1] };
+  }
+
+  const screensMatch = trimmed.match(/^screens\/(.+)$/);
+  if (screensMatch) {
+    return { tab: 'screens', stateKey: screensMatch[1] };
+  }
+
+  const knownTabs = ['screens', 'changelog', 'documents'];
+  if (knownTabs.includes(trimmed)) {
+    return { tab: trimmed, stateKey: null };
+  }
+
+  return { tab: 'prototype', stateKey: null };
+}
+
+/**
+ * Hook that synchronises React state with the URL hash.
+ *
+ * Returns:
+ *   tab               - current tab name ('prototype' | 'screens' | 'changelog' | 'documents')
+ *   stateKey          - state key (string or null)
+ *   navigateTo        - (key: string) => void   — navigate to #/state/{key}
+ *   navigateToTab     - (tab: string) => void   — navigate to #/{tab} (empty for 'prototype')
+ *   navigateToScreen  - (key: string) => void   — navigate to #/screens/{key}
+ */
+export function useHashRoute() {
+  const [route, setRoute] = useState(() => parseHash(window.location.hash));
+
+  useEffect(() => {
+    function handleHashChange() {
+      setRoute(parseHash(window.location.hash));
+    }
+
+    window.addEventListener('hashchange', handleHashChange);
+    return () => {
+      window.removeEventListener('hashchange', handleHashChange);
+    };
+  }, []);
+
+  const navigateTo = useCallback((key) => {
+    window.location.hash = `#/state/${key}`;
+    setRoute({ tab: 'prototype', stateKey: key });
+  }, []);
+
+  const navigateToTab = useCallback((tab) => {
+    if (tab === 'prototype') {
+      window.location.hash = '';
+      setRoute({ tab: 'prototype', stateKey: null });
+    } else {
+      window.location.hash = `#/${tab}`;
+      setRoute({ tab, stateKey: null });
+    }
+  }, []);
+
+  const navigateToScreen = useCallback((key) => {
+    window.location.hash = `#/screens/${key}`;
+    setRoute({ tab: 'screens', stateKey: key });
+  }, []);
+
+  return {
+    tab: route.tab,
+    stateKey: route.stateKey,
+    navigateTo,
+    navigateToTab,
+    navigateToScreen,
+  };
+}

package/src/hooks/usePanZoom.js

@@ -0,0 +1,156 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+const MIN_ZOOM = 0.1;
+const MAX_ZOOM = 2;
+const INITIAL_ZOOM = 0.35;
+
+/**
+ * usePanZoom – provides pan and zoom state for a canvas container.
+ *
+ * @param {React.RefObject} containerRef – ref to the scroll/clip container element
+ * @returns {{ zoom, offset, fitToView, handlers }}
+ */
+export function usePanZoom(containerRef) {
+  const [zoom, setZoom] = useState(INITIAL_ZOOM);
+  const [offset, setOffset] = useState({ x: 0, y: 0 });
+
+  // Pan drag state (stored in a ref to avoid stale closures in mousemove)
+  const isPanning = useRef(false);
+  const panStart = useRef({ x: 0, y: 0 });
+  const offsetAtStart = useRef({ x: 0, y: 0 });
+
+  // ---------------------------------------------------------------------------
+  // Wheel: zoom toward cursor (Cmd/Ctrl + wheel only)
+  // ---------------------------------------------------------------------------
+  const onWheel = useCallback(
+    (e) => {
+      e.preventDefault();
+
+      const container = containerRef.current;
+      if (!container) return;
+
+      // Ctrl/Cmd + wheel = zoom toward cursor
+      if (e.ctrlKey || e.metaKey) {
+        const rect = container.getBoundingClientRect();
+        const cursorX = e.clientX - rect.left;
+        const cursorY = e.clientY - rect.top;
+
+        setZoom((prevZoom) => {
+          const delta = -e.deltaY * 0.001;
+          const nextZoom = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, prevZoom + delta * prevZoom));
+
+          setOffset((prevOffset) => ({
+            x: cursorX - (cursorX - prevOffset.x) * (nextZoom / prevZoom),
+            y: cursorY - (cursorY - prevOffset.y) * (nextZoom / prevZoom),
+          }));
+
+          return nextZoom;
+        });
+      } else {
+        // Regular scroll/trackpad = pan
+        setOffset((prev) => ({
+          x: prev.x - e.deltaX,
+          y: prev.y - e.deltaY,
+        }));
+      }
+    },
+    [containerRef],
+  );
+
+  // ---------------------------------------------------------------------------
+  // Pan – mouse drag
+  // ---------------------------------------------------------------------------
+  const onMouseDown = useCallback((e) => {
+    // Skip if the click target is an interactive element
+    if (e.target.closest('a, button')) return;
+
+    isPanning.current = true;
+    panStart.current = { x: e.clientX, y: e.clientY };
+    offsetAtStart.current = { x: 0, y: 0 }; // will be set from current offset below
+
+    // Capture current offset in the ref so mousemove can reference it
+    setOffset((prev) => {
+      offsetAtStart.current = prev;
+      return prev;
+    });
+
+    document.body.style.userSelect = 'none';
+  }, []);
+
+  const onMouseMove = useCallback((e) => {
+    if (!isPanning.current) return;
+
+    const dx = e.clientX - panStart.current.x;
+    const dy = e.clientY - panStart.current.y;
+
+    setOffset({
+      x: offsetAtStart.current.x + dx,
+      y: offsetAtStart.current.y + dy,
+    });
+  }, []);
+
+  const endPan = useCallback(() => {
+    if (!isPanning.current) return;
+    isPanning.current = false;
+    document.body.style.userSelect = '';
+  }, []);
+
+  // ---------------------------------------------------------------------------
+  // fitToView – measures content vs container and calculates a zoom to fit
+  // ---------------------------------------------------------------------------
+  const contentRef = useRef(null);
+
+  const fitToView = useCallback(
+    (ref) => {
+      // Allow passing an explicit content ref, or use the stored one
+      const contentEl = (ref || contentRef).current;
+      const containerEl = containerRef.current;
+      if (!contentEl || !containerEl) return;
+
+      const containerRect = containerEl.getBoundingClientRect();
+      // Measure content at zoom=1 (natural size)
+      const naturalWidth = contentEl.scrollWidth;
+      const naturalHeight = contentEl.scrollHeight;
+
+      const margin = 0.9;
+      const zoomX = (containerRect.width / naturalWidth) * margin;
+      const zoomY = (containerRect.height / naturalHeight) * margin;
+      const nextZoom = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, Math.min(zoomX, zoomY)));
+
+      // Center the content
+      const scaledWidth = naturalWidth * nextZoom;
+      const scaledHeight = naturalHeight * nextZoom;
+      const offsetX = (containerRect.width - scaledWidth) / 2;
+      const offsetY = (containerRect.height - scaledHeight) / 2;
+
+      setZoom(nextZoom);
+      setOffset({ x: offsetX, y: offsetY });
+    },
+    [containerRef],
+  );
+
+  // Attach wheel listener with { passive: false } so preventDefault() works
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.addEventListener('wheel', onWheel, { passive: false });
+    return () => el.removeEventListener('wheel', onWheel);
+  }, [onWheel, containerRef]);
+
+  return {
+    zoom,
+    offset,
+    setZoom,
+    setOffset,
+    fitToView,
+    contentRef,
+    handlers: {
+      onMouseDown,
+      onMouseMove,
+      onMouseUp: endPan,
+      onMouseLeave: endPan,
+    },
+  };
+}
+
+export default usePanZoom;

package/src/hooks/useTheme.js

@@ -0,0 +1,21 @@
+import { useState, useEffect } from 'react';
+
+export function useTheme() {
+  const [theme, setTheme] = useState('light');
+
+  useEffect(() => {
+    if (theme === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, [theme]);
+
+  const toggleTheme = () => {
+    setTheme((prev) => (prev === 'light' ? 'dark' : 'light'));
+  };
+
+  const isDark = theme === 'dark';
+
+  return { theme, isDark, toggleTheme };
+}