@kondeio/kdf 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to KDF are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## [0.1.3] - 2026-06-29
+
+### Added
+- Added `createDesign(pageTokens, shared)` for imported JSON token objects. This
+  is the preferred API for Astro SSR, Hono, Next.js, Cloudflare Workers, and
+  other bundled runtimes because JSON files become build dependencies instead of
+  runtime filesystem paths.
+- Added the pure `@kondeio/kdf/edge` export for runtimes that reject Node
+  built-ins entirely.
+- Added `DesignSharedTokens` type for shared token maps such as
+  `{ button: buttonTokens }`.
+
+### Changed
+- Documentation now distinguishes the Node file API (`getDesign(page)`) from the
+  imported JSON API (`createDesign(tokens, shared)`), including Cloudflare
+  Workers guidance.
+
 ## [0.1.2] - 2026-06-22
 
 ### Changed

package/README.md

@@ -35,21 +35,28 @@ not a CSS engine.
 
 ## Runtime Support
 
-KDF core runs in Node/server-side JavaScript environments because it reads JSON
-from disk with Node `fs`.
+KDF has two runtime modes:
 
-- Works with server-rendered Next.js, Astro, Hono, or similar Node runtimes.
+- `createDesign(tokens, shared)` uses JSON objects imported by the host app.
+  This is the preferred mode for Astro, Next.js, Hono, Cloudflare Workers, and
+  other edge/serverless runtimes because bundlers can see and include the JSON.
+- `getDesign(page)` reads `kdf/<page>.json` from disk with Node `fs`. This is
+  convenient for Node/server apps and local tooling, but it is not the right
+  API for edge runtimes that do not have your local filesystem.
+
+- Works with server-rendered Next.js, Astro, Hono, Cloudflare Workers, or similar runtimes.
 - The included `@kondeio/kdf/plugin` export is the official Next.js integration.
 - Next.js plugin target: App Router, Next.js 14+ (`next >=14`).
-- `getDesign()`, `d()`, and `d.css()` are server-only. Browser/client
-  components cannot call them directly; resolve classes server-side and pass
-  class names down when needed.
+- `getDesign()` is server-only. Browser/client components should use resolved
+  class strings from a server boundary or use imported JSON with `createDesign()`
+  when the bundler/runtime supports it.
 
 | Framework | Status | How KDF is used |
 | --- | --- | --- |
-| Next.js | Tested | Core API in server-rendered code, plus the official `@kondeio/kdf/plugin` integration. |
-| Astro | Tested | Core API in server-rendered code. |
-| Hono | Tested | Core API in server handlers. |
+| Next.js | Tested | `createDesign()` with imported JSON, or `getDesign()` in Node/server-rendered code plus the optional plugin. |
+| Astro | Tested | `createDesign()` with imported JSON for SSR/edge builds. |
+| Hono | Tested | `createDesign()` with imported JSON in handlers, or `getDesign()` in Node handlers. |
+| Cloudflare Workers | Supported | `createDesign()` with imported JSON. Do not pass local absolute file paths. |
 
 ## Install
 
@@ -172,6 +179,41 @@ Example token:
 
 ## Usage
 
+### Imported JSON API
+
+Use `createDesign()` when the app is bundled for Astro, Next.js, Hono, or
+Cloudflare Workers:
+
+```tsx
+import { createDesign } from "@kondeio/kdf";
+import homepageTokens from "../kdf/homepage.json";
+import buttonTokens from "../kdf/shared/button.json";
+import typographyTokens from "../kdf/shared/typography.json";
+
+const d = createDesign(homepageTokens, {
+  button: buttonTokens,
+  typography: typographyTokens,
+});
+
+<h1 data-kdf="hero.title" className={d("hero.title")}>
+  {t("hero.headline")}
+</h1>
+```
+
+This makes the JSON a normal build dependency. The bundler includes it in the
+output instead of KDF trying to read a machine-local path at runtime.
+
+If a runtime or bundler rejects Node built-ins entirely, import the pure entry:
+
+```ts
+import { createDesign } from "@kondeio/kdf/edge";
+```
+
+### File API
+
+Use `getDesign()` in Node/server environments where reading from `kdf/*.json` at
+runtime is intentional:
+
 ```tsx
 import { getDesign } from "@kondeio/kdf";
 
@@ -235,11 +277,11 @@ const cn = createClassComposer({
 
 ## Server-only
 
-`getDesign()`, `d()`, and `d.css()` read JSON from disk via Node `fs`, so they
-run on the **server only**: Next.js Server Components, Astro server rendering,
-Hono handlers, or equivalent Node/server-rendered code. They do **not** work
-inside browser-only code or a Next.js Client Component (`"use client"`), which
-has no filesystem.
+`getDesign()` reads JSON from disk via Node `fs`, so it runs on the **server
+only**: Next.js Server Components, Astro Node server rendering, Hono Node
+handlers, or equivalent Node/server-rendered code. It does **not** work inside
+browser-only code or a Next.js Client Component (`"use client"`), which has no
+filesystem.
 
 For client components, resolve on the server and pass the resulting className
 string down as a prop:
@@ -250,6 +292,9 @@ const d = getDesign("homepage");
 return <ClientThing className={d("hero.cta")} />;
 ```
 
+For edge/serverless deploys, prefer `createDesign(importedJson, shared)` so the
+tokens are bundled as code/data instead of looked up from a runtime path.
+
 ## References
 
 Reference shared tokens from shared/:
@@ -283,8 +328,8 @@ Playwright checks.
 
 ## Cache Behavior
 
-KDF caches design JSON files by default. In development it revalidates with
-file `mtime`/`size` checks so repeated `d()` calls do not create disk-read
+`getDesign()` caches design JSON files by default. In development it revalidates
+with file `mtime`/`size` checks so repeated `d()` calls do not create disk-read
 storms during HMR.
 
 ```tsx

package/dist/class-compose.d.ts

@@ -0,0 +1,35 @@
+import { type ClassValue } from "clsx";
+export type ClassMergeFunction = (className: string) => string;
+export interface ClassComposerOptions {
+    /**
+     * Optional app-defined semantic merge step.
+     *
+     * KDF's default merge only removes exact duplicate classes. If an app wants
+     * semantic rules such as "keep the last class in this project-specific group",
+     * inject that logic here.
+     */
+    merge?: ClassMergeFunction;
+}
+/**
+ * Remove exact duplicate class names while preserving first-seen order.
+ *
+ * This is intentionally semantic-free: it does not try to understand any CSS
+ * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
+ */
+export declare function dedupeClasses(className: string): string;
+/**
+ * Create a UI-library agnostic class composer.
+ *
+ * Default behavior:
+ * - flatten strings, arrays, and objects through clsx
+ * - drop falsy values
+ * - normalize whitespace
+ * - remove exact duplicate class names
+ *
+ * Apps that need semantic class conflict handling can inject their own merge
+ * function. KDF does not ship CSS-framework-specific class rules.
+ */
+export declare function createClassComposer(options?: ClassComposerOptions): (...inputs: ClassValue[]) => string;
+export declare const composeClasses: (...inputs: ClassValue[]) => string;
+export declare const cx: (...inputs: ClassValue[]) => string;
+export declare const cn: (...inputs: ClassValue[]) => string;

package/dist/class-compose.js

@@ -0,0 +1,40 @@
+import { clsx } from "clsx";
+/**
+ * Remove exact duplicate class names while preserving first-seen order.
+ *
+ * This is intentionally semantic-free: it does not try to understand any CSS
+ * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
+ */
+export function dedupeClasses(className) {
+    const seen = new Set();
+    const output = [];
+    for (const part of className.trim().split(/\s+/)) {
+        if (!part || seen.has(part))
+            continue;
+        seen.add(part);
+        output.push(part);
+    }
+    return output.join(" ");
+}
+/**
+ * Create a UI-library agnostic class composer.
+ *
+ * Default behavior:
+ * - flatten strings, arrays, and objects through clsx
+ * - drop falsy values
+ * - normalize whitespace
+ * - remove exact duplicate class names
+ *
+ * Apps that need semantic class conflict handling can inject their own merge
+ * function. KDF does not ship CSS-framework-specific class rules.
+ */
+export function createClassComposer(options = {}) {
+    const merge = options.merge ?? dedupeClasses;
+    return (...inputs) => {
+        const joined = clsx(...inputs);
+        return merge(joined);
+    };
+}
+export const composeClasses = createClassComposer();
+export const cx = composeClasses;
+export const cn = composeClasses;

package/dist/create-design.d.ts

@@ -0,0 +1,18 @@
+import type { DesignAccessor, DesignSharedTokens, DesignTokenFile } from "./types.js";
+interface ResolveRuntimeOptions {
+    shared?: DesignSharedTokens;
+    resolveRef?: (component: string, key: string) => unknown;
+}
+/** Resolve className for a token path. */
+export declare function resolveClassName(path: string, pageTokens: DesignTokenFile | null, options?: ResolveRuntimeOptions): string;
+/** Resolve CSS custom properties for a token path */
+export declare function resolveCSS(path: string, pageTokens: DesignTokenFile | null): Record<string, string>;
+/**
+ * Create a design accessor from imported JSON token objects.
+ *
+ * This is the preferred API for edge runtimes and build-time bundlers because
+ * the host app imports JSON explicitly instead of asking KDF to read a path at
+ * runtime.
+ */
+export declare function createDesign(pageTokens: DesignTokenFile | null, shared?: DesignSharedTokens): DesignAccessor;
+export {};

package/dist/create-design.js

@@ -0,0 +1,108 @@
+/** Get value from nested object by dot-path */
+function getByPath(obj, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}
+/**
+ * Resolve a single @reference: "@button.cta"
+ * @button.cta -> shared.button.cta, external resolver, or page-level fallback.
+ */
+function resolveSingleRef(ref, pageTokens, depth, options) {
+    if (depth > 5)
+        return "";
+    const refPart = ref.slice(1); // remove @
+    const dotIdx = refPart.indexOf(".");
+    const component = dotIdx > 0 ? refPart.slice(0, dotIdx) : refPart;
+    const key = dotIdx > 0 ? refPart.slice(dotIdx + 1) : "";
+    // Reject path-traversal when a file-backed resolver is used.
+    if (!/^[A-Za-z0-9_-]+$/.test(component)) {
+        if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+            console.warn(`[kdf] ignoring unsafe @ref component: "${component}"`);
+        }
+        return "";
+    }
+    let resolved = undefined;
+    const sharedToken = options?.shared?.[component];
+    if (key && sharedToken) {
+        resolved = getByPath(sharedToken, key);
+    }
+    if (resolved === undefined && key && options?.resolveRef) {
+        resolved = options.resolveRef(component, key);
+    }
+    if (resolved === undefined && pageTokens) {
+        resolved = getByPath(pageTokens, refPart);
+    }
+    if (typeof resolved === "string") {
+        return resolveTokenString(resolved, pageTokens, depth + 1, options);
+    }
+    if (resolved && typeof resolved === "object" && "className" in resolved) {
+        const className = resolved.className;
+        return resolveTokenString(className, pageTokens, depth + 1, options);
+    }
+    return "";
+}
+/**
+ * Resolve a token string that may contain multiple @refs and plain classes.
+ * Examples:
+ *   "@button.cta"                           -> resolves single ref
+ *   "@button.cta shadow-xl"                 -> resolves ref + extra classes
+ *   "@button.base @button.ghost @button.sm" -> resolves all refs
+ */
+function resolveTokenString(value, pageTokens, depth = 0, options) {
+    if (depth > 5)
+        return value;
+    const parts = value.split(/\s+/).filter(Boolean);
+    const resolved = parts.map((part) => {
+        if (part.startsWith("@")) {
+            return resolveSingleRef(part, pageTokens, depth, options);
+        }
+        return part;
+    });
+    return resolved.filter(Boolean).join(" ");
+}
+/** Resolve className for a token path. */
+export function resolveClassName(path, pageTokens, options) {
+    const val = pageTokens
+        ? getByPath(pageTokens, path)
+        : undefined;
+    if (val === undefined)
+        return "";
+    if (typeof val === "string") {
+        return resolveTokenString(val, pageTokens, 0, options);
+    }
+    if (typeof val === "object" && val && "className" in val) {
+        const className = val.className;
+        return resolveTokenString(className, pageTokens, 0, options);
+    }
+    return "";
+}
+/** Resolve CSS custom properties for a token path */
+export function resolveCSS(path, pageTokens) {
+    const val = pageTokens
+        ? getByPath(pageTokens, path)
+        : undefined;
+    if (val && typeof val === "object" && "css" in val) {
+        return val.css;
+    }
+    return {};
+}
+/**
+ * Create a design accessor from imported JSON token objects.
+ *
+ * This is the preferred API for edge runtimes and build-time bundlers because
+ * the host app imports JSON explicitly instead of asking KDF to read a path at
+ * runtime.
+ */
+export function createDesign(pageTokens, shared = {}) {
+    const accessor = ((path) => {
+        return resolveClassName(path, pageTokens, { shared });
+    });
+    accessor.css = (path) => {
+        return resolveCSS(path, pageTokens);
+    };
+    return accessor;
+}

package/dist/edge.d.ts

@@ -0,0 +1,3 @@
+export { cn, composeClasses, createClassComposer, cx, dedupeClasses, type ClassComposerOptions, type ClassMergeFunction, } from "./class-compose.js";
+export { createDesign } from "./create-design.js";
+export type { DesignAccessor, DesignSharedTokens, DesignTokenFile, DesignTokenValue, } from "./types.js";

package/dist/edge.js

@@ -0,0 +1,2 @@
+export { cn, composeClasses, createClassComposer, cx, dedupeClasses, } from "./class-compose.js";
+export { createDesign } from "./create-design.js";

package/dist/index.d.ts

@@ -1,18 +1,8 @@
-import { type ClassValue } from "clsx";
 import type { DesignAccessor, GetDesignOptions } from "./types.js";
-export type { DesignAccessor, DesignTokenFile, DesignTokenValue, GetDesignOptions, KdfCacheMode, } from "./types.js";
+export { cn, composeClasses, createClassComposer, cx, dedupeClasses, type ClassComposerOptions, type ClassMergeFunction, } from "./class-compose.js";
+export { createDesign } from "./create-design.js";
+export type { DesignAccessor, DesignSharedTokens, DesignTokenFile, DesignTokenValue, GetDesignOptions, KdfCacheMode, } from "./types.js";
 export { clearKdfCache } from "./resolver.js";
-export type ClassMergeFunction = (className: string) => string;
-export interface ClassComposerOptions {
-    /**
-     * Optional app-defined semantic merge step.
-     *
-     * KDF's default merge only removes exact duplicate classes. If an app wants
-     * semantic rules such as "keep the last class in this project-specific group",
-     * inject that logic here.
-     */
-    merge?: ClassMergeFunction;
-}
 /**
  * Get design accessor for a page.
  *
@@ -23,26 +13,3 @@ export interface ClassComposerOptions {
  * Resolution order: kdf/<page>.json -> kdf/shared/
  */
 export declare function getDesign(page: string, options?: GetDesignOptions): DesignAccessor;
-/**
- * Remove exact duplicate class names while preserving first-seen order.
- *
- * This is intentionally semantic-free: it does not try to understand any CSS
- * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
- */
-export declare function dedupeClasses(className: string): string;
-/**
- * Create a UI-library agnostic class composer.
- *
- * Default behavior:
- * - flatten strings, arrays, and objects through clsx
- * - drop falsy values
- * - normalize whitespace
- * - remove exact duplicate class names
- *
- * Apps that need semantic class conflict handling can inject their own merge
- * function. KDF does not ship CSS-framework-specific class rules.
- */
-export declare function createClassComposer(options?: ClassComposerOptions): (...inputs: ClassValue[]) => string;
-export declare const composeClasses: (...inputs: ClassValue[]) => string;
-export declare const cx: (...inputs: ClassValue[]) => string;
-export declare const cn: (...inputs: ClassValue[]) => string;

package/dist/index.js

@@ -1,5 +1,6 @@
-import { clsx } from "clsx";
 import { loadFile, resolveClassName, resolveCSS } from "./resolver.js";
+export { cn, composeClasses, createClassComposer, cx, dedupeClasses, } from "./class-compose.js";
+export { createDesign } from "./create-design.js";
 export { clearKdfCache } from "./resolver.js";
 /**
  * Get design accessor for a page.
@@ -21,42 +22,3 @@ export function getDesign(page, options) {
     };
     return accessor;
 }
-/**
- * Remove exact duplicate class names while preserving first-seen order.
- *
- * This is intentionally semantic-free: it does not try to understand any CSS
- * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
- */
-export function dedupeClasses(className) {
-    const seen = new Set();
-    const output = [];
-    for (const part of className.trim().split(/\s+/)) {
-        if (!part || seen.has(part))
-            continue;
-        seen.add(part);
-        output.push(part);
-    }
-    return output.join(" ");
-}
-/**
- * Create a UI-library agnostic class composer.
- *
- * Default behavior:
- * - flatten strings, arrays, and objects through clsx
- * - drop falsy values
- * - normalize whitespace
- * - remove exact duplicate class names
- *
- * Apps that need semantic class conflict handling can inject their own merge
- * function. KDF does not ship CSS-framework-specific class rules.
- */
-export function createClassComposer(options = {}) {
-    const merge = options.merge ?? dedupeClasses;
-    return (...inputs) => {
-        const joined = clsx(...inputs);
-        return merge(joined);
-    };
-}
-export const composeClasses = createClassComposer();
-export const cx = composeClasses;
-export const cn = composeClasses;

package/dist/resolver.d.ts

@@ -1,4 +1,5 @@
 import type { DesignTokenFile, GetDesignOptions } from "./types.js";
+import { resolveCSS } from "./create-design.js";
 /** Returns KDF root path — reads env at call time, not module load time */
 declare function getKdfRoot(): string;
 export declare function clearKdfCache(): void;
@@ -6,6 +7,5 @@ declare function loadFile(name: string, options?: GetDesignOptions): DesignToken
 /** Resolve className for a token path.
  *  Looks in page JSON first. @references resolve from shared/ files. */
 export declare function resolveClassName(path: string, pageTokens: DesignTokenFile | null, options?: GetDesignOptions): string;
-/** Resolve CSS custom properties for a token path */
-export declare function resolveCSS(path: string, pageTokens: DesignTokenFile | null): Record<string, string>;
 export { loadFile, getKdfRoot };
+export { resolveCSS };

package/dist/resolver.js

@@ -1,5 +1,6 @@
 import { readFileSync, statSync } from "fs";
 import { isAbsolute, join } from "path";
+import { resolveClassName as resolveClassNameFromTokens, resolveCSS, } from "./create-design.js";
 /** Returns KDF root path — reads env at call time, not module load time */
 function getKdfRoot() {
     const dir = process.env.KDF_DIR || "kdf";
@@ -78,7 +79,6 @@ function loadFile(name, options) {
 function loadFileAbsolute(filePath, options) {
     return loadJsonFile(filePath, options);
 }
-/** Get value from nested object by dot-path */
 function getByPath(obj, path) {
     return path.split(".").reduce((acc, key) => {
         if (acc && typeof acc === "object" && key in acc) {
@@ -87,98 +87,27 @@ function getByPath(obj, path) {
         return undefined;
     }, obj);
 }
-/**
- * Resolve a single @reference: "@button.cta"
- * @button.cta -> load shared/button.json -> key "cta"
- */
-function resolveSingleRef(ref, pageTokens, depth, options) {
-    if (depth > 5)
-        return "";
-    const refPart = ref.slice(1); // remove @
-    const dotIdx = refPart.indexOf(".");
-    const component = dotIdx > 0 ? refPart.slice(0, dotIdx) : refPart;
-    const key = dotIdx > 0 ? refPart.slice(dotIdx + 1) : "";
-    // Reject path-traversal in the component name: it becomes part of a file path
-    // (shared/<component>.json). A ref like "@../../secret.x" must never escape the
-    // shared/ folder. Allow only safe filename chars.
-    if (!/^[A-Za-z0-9_-]+$/.test(component)) {
-        if (process.env.NODE_ENV !== "production") {
-            console.warn(`[kdf] ignoring unsafe @ref component: "${component}"`);
-        }
-        return "";
-    }
-    // Load shared/<component>.json — cascade: template shared → root shared
-    let resolved = undefined;
+function resolveFileRef(component, key, options) {
     // 1. Template-specific shared (e.g., designs/lander/shared/button.json)
     const templateShared = loadFile(`shared/${component}`, options);
-    if (key && templateShared) {
-        resolved = getByPath(templateShared, key);
+    if (templateShared) {
+        const resolved = getByPath(templateShared, key);
+        if (resolved !== undefined)
+            return resolved;
     }
     // 2. Root shared fallback (e.g., designs/shared/button.json)
-    if (resolved === undefined && key) {
-        const rootShared = loadFileAbsolute(join(getKdfRoot(), "..", "shared", `${component}.json`), options);
-        if (rootShared) {
-            resolved = getByPath(rootShared, key);
-        }
-    }
-    // 3. Fallback: check page-level tokens
-    if (resolved === undefined && pageTokens) {
-        resolved = getByPath(pageTokens, refPart);
+    const rootShared = loadFileAbsolute(join(getKdfRoot(), "..", "shared", `${component}.json`), options);
+    if (rootShared) {
+        return getByPath(rootShared, key);
     }
-    if (typeof resolved === "string") {
-        // Resolved value might itself contain @refs
-        return resolveTokenString(resolved, pageTokens, depth + 1, options);
-    }
-    if (resolved && typeof resolved === "object" && "className" in resolved) {
-        const cn = resolved.className;
-        return resolveTokenString(cn, pageTokens, depth + 1, options);
-    }
-    return "";
-}
-/**
- * Resolve a token string that may contain multiple @refs and plain classes.
- * Examples:
- *   "@button.cta"                         -> resolves single ref
- *   "@button.cta shadow-xl"               -> resolves ref + appends classes
- *   "@button.base @button.ghost @button.sm" -> resolves all three refs
- */
-function resolveTokenString(value, pageTokens, depth = 0, options) {
-    if (depth > 5)
-        return value;
-    const parts = value.split(/\s+/).filter(Boolean);
-    const resolved = parts.map((part) => {
-        if (part.startsWith("@")) {
-            return resolveSingleRef(part, pageTokens, depth, options);
-        }
-        return part;
-    });
-    return resolved.filter(Boolean).join(" ");
+    return undefined;
 }
 /** Resolve className for a token path.
  *  Looks in page JSON first. @references resolve from shared/ files. */
 export function resolveClassName(path, pageTokens, options) {
-    const val = pageTokens
-        ? getByPath(pageTokens, path)
-        : undefined;
-    if (val === undefined)
-        return "";
-    if (typeof val === "string") {
-        return resolveTokenString(val, pageTokens, 0, options);
-    }
-    if (typeof val === "object" && val && "className" in val) {
-        const cn = val.className;
-        return resolveTokenString(cn, pageTokens, 0, options);
-    }
-    return "";
-}
-/** Resolve CSS custom properties for a token path */
-export function resolveCSS(path, pageTokens) {
-    const val = pageTokens
-        ? getByPath(pageTokens, path)
-        : undefined;
-    if (val && typeof val === "object" && "css" in val) {
-        return val.css;
-    }
-    return {};
+    return resolveClassNameFromTokens(path, pageTokens, {
+        resolveRef: (component, key) => resolveFileRef(component, key, options),
+    });
 }
 export { loadFile, getKdfRoot };
+export { resolveCSS };

package/dist/types.d.ts

@@ -18,6 +18,8 @@ export interface DesignTokenFile {
 export interface DesignTokenGroup {
     [key: string]: DesignTokenValue | DesignTokenGroup;
 }
+/** Shared design token objects keyed by @ref component name, e.g. { button } */
+export type DesignSharedTokens = Record<string, DesignTokenFile | null | undefined>;
 /** Resolved design accessor for a page */
 export interface DesignAccessor {
     /** Get className for a dot-path: d("hero.title") */

package/docs/doc.md

@@ -466,7 +466,37 @@ export default {
 
 ## Runtime API
 
-KDF core runs in Node/server-side JavaScript because it reads JSON from disk.
+KDF has two runtime APIs.
+
+### Imported JSON / Edge-Safe API
+
+Use `createDesign()` when the host app is built by Vite, Astro, Next.js, Hono,
+or Cloudflare Workers:
+
+```ts
+import { createDesign, cn } from "@kondeio/kdf";
+import homepageTokens from "../kdf/homepage.json";
+import buttonTokens from "../kdf/shared/button.json";
+import typographyTokens from "../kdf/shared/typography.json";
+
+const d = createDesign(homepageTokens, {
+  button: buttonTokens,
+  typography: typographyTokens,
+});
+```
+
+This API does not read design JSON from a path. The app imports JSON explicitly,
+so the bundler can include the token files in the deployment artifact.
+
+For runtimes that reject Node built-ins completely, use the pure subpath:
+
+```ts
+import { createDesign, cn } from "@kondeio/kdf/edge";
+```
+
+### Node File API
+
+Use `getDesign()` when runtime filesystem reads are intentional:
 
 ```ts
 import { getDesign, cn, clearKdfCache } from "@kondeio/kdf";
@@ -481,11 +511,12 @@ d("hero.title");      // resolved className string
 d.css("hero.title");  // CSS custom properties object
 ```
 
-Server-only rule:
+Server-only rule for `getDesign()`:
 
-- use `getDesign()` in server-rendered code
+- use `getDesign()` in Node/server-rendered code
 - do not call it directly inside browser-only Client Components
 - resolve classes server-side and pass strings down when needed
+- use `createDesign(importedJson, shared)` for edge/serverless builds
 
 Cache options:
 

package/docs/skill.md

@@ -3,8 +3,8 @@
 Use this skill whenever you build, review, or modify UI that uses Konde Design Framework.
 
 Package: `@kondeio/kdf`
-Runtime target: Node/server-side JavaScript. Tested with Next.js, Astro, and Hono.
-Primary API: `getDesign`, `cn`, `cx`, `composeClasses`, `dedupeClasses`, `createClassComposer`, `clearKdfCache`
+Runtime target: Node/server-side JavaScript plus edge/serverless builds with imported JSON. Tested with Next.js, Astro, Hono, and Cloudflare Workers.
+Primary API: `createDesign`, `getDesign`, `cn`, `cx`, `composeClasses`, `dedupeClasses`, `createClassComposer`, `clearKdfCache`
 Required convention: every `d()` usage must have matching `data-kdf`
 
 ## Goal
@@ -50,7 +50,26 @@ kdf/shared/*.json
 
 2. Locate the relevant UI component or page.
 
-3. Confirm package import:
+3. Confirm package import.
+
+For bundled SSR/edge runtimes such as Astro SSR or Cloudflare Workers, prefer
+imported JSON:
+
+```ts
+import { createDesign, cn } from "@kondeio/kdf";
+import pageTokens from "../kdf/homepage.json";
+import buttonTokens from "../kdf/shared/button.json";
+
+const d = createDesign(pageTokens, { button: buttonTokens });
+```
+
+If the runtime rejects Node built-ins entirely, use:
+
+```ts
+import { createDesign, cn } from "@kondeio/kdf/edge";
+```
+
+For Node/server-only apps that intentionally read files at runtime:
 
 ```ts
 import { getDesign, cn } from "@kondeio/kdf";
@@ -62,6 +81,12 @@ import { getDesign, cn } from "@kondeio/kdf";
 const d = getDesign("homepage");
 ```
 
+or:
+
+```ts
+const d = createDesign(pageTokens, { button: buttonTokens });
+```
+
 5. Confirm the styling framework scans KDF JSON if it generates CSS by scanning source files:
 
 ```css
@@ -72,6 +97,15 @@ or equivalent framework/source scanning config.
 
 ## Non-negotiable Rules
 
+### 0. Pick the Right Runtime API
+
+Use `createDesign(importedJson, shared)` for Astro SSR, Cloudflare Workers, and
+other bundled edge/serverless deployments. Do not pass local absolute paths such
+as `/Volumes/.../designs/homepage.json` into deployed code.
+
+Use `getDesign(page)` only when runtime filesystem reads from `kdf/*.json` are
+intentional and the target runtime is Node/server.
+
 ### 1. Do Not Guess Design
 
 If a class belongs to the design system, put it in JSON and read it with `d()`.
@@ -325,8 +359,8 @@ clearKdfCache();
 
 Use this checklist before finishing KDF-related UI work.
 
-- [ ] Page imports `getDesign` from `@kondeio/kdf`.
-- [ ] Page creates one accessor per design page, for example `getDesign("homepage")`.
+- [ ] Page imports the correct runtime API: `createDesign` for imported JSON/edge, `getDesign` for Node file mode.
+- [ ] Page creates one accessor per design page, for example `createDesign(pageTokens, sharedTokens)` or `getDesign("homepage")`.
 - [ ] Every `d()` usage has matching `data-kdf`.
 - [ ] Shared repeated styles live in `kdf/shared`.
 - [ ] One-off page styles live in `kdf/<page>.json`.
@@ -347,7 +381,7 @@ Use this when reviewing code written by another agent.
 - [ ] `data-kdf` values match the token paths exactly.
 - [ ] No design drift through arbitrary inline styling classes.
 - [ ] KDF JSON remains valid JSON.
-- [ ] Shared refs point to existing shared token files.
+- [ ] Shared refs point to existing shared token files or imported shared token objects.
 - [ ] `@` refs are not used for business logic.
 - [ ] No non-English or informal comments are introduced into user-facing app source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kondeio/kdf",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent-first design consistency for Node-powered web apps. KDF gives AI agents a JSON source of truth for consistent UI.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,10 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./edge": {
+      "import": "./dist/edge.js",
+      "types": "./dist/edge.d.ts"
+    },
     "./plugin": {
       "import": "./dist/plugin.js",
       "types": "./dist/plugin.d.ts"