@kondeio/kdf 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to KDF are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com); versions follow semver.
+
+## [0.1.0] - 2026-06-18
+
+Initial public release candidate.
+
+### Changed
+- **Class composition is now UI-library agnostic.** `cn()` / `cx()` /
+  `composeClasses()` normalize and dedupe exact duplicate classes by default,
+  while `createClassComposer({ merge })` allows app-defined semantic merge
+  rules without adding framework-specific runtime dependencies to KDF.
+- Package scope renamed `@konde/kdf` → `@kondeio/kdf`.
+- `package.json` description clarified: KDF is a Node/server-side package with
+  an optional Next.js plugin and UI-library agnostic class composition.
+
+### Added
+- `dedupeClasses()`, `composeClasses()`, `cx()`, and
+  `createClassComposer({ merge })`.
+- Documented the **server-only** constraint (resolver uses Node `fs`) across
+  README, `docs/kdf-doc.md`, and `docs/kdf-skill.md`, with the
+  resolve-on-server / pass-className-as-prop pattern.
+- `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`.
+
+### Fixed
+- `@ref` component names are validated against `^[A-Za-z0-9_-]+$` — path-traversal
+  references (`..`, separators) are rejected instead of resolving to arbitrary
+  `.json` files.
+- Corrected the plugin "auto-inject CSS" claim: `withKDF()` only exposes paths
+  via env (`KDF_DIR`, `KDF_SERVER_CSS`, `KDF_CLIENT_CSS`); the host app wires the
+  stylesheet.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to KDF
+
+Thanks for your interest in improving the Konde Design Framework.
+
+## Local setup
+
+KDF builds with [Bun](https://bun.sh) (Node 18+ also works for running `dist`).
+
+```bash
+git clone https://github.com/KondeIO/kdf.git
+cd kdf
+bun install
+```
+
+## Build & verify
+
+```bash
+bun run build       # tsc -> dist/
+bun run typecheck   # tsc --noEmit
+bun run test        # unit tests
+```
+
+A change is ready for review when `typecheck` and `test` pass and `dist/` has
+been rebuilt (the published artifact lives in `dist/`).
+
+## Project layout
+
+```
+src/         TypeScript source (authoritative)
+dist/        Build output (tsc) — published to npm
+kdf/         Starter design tokens shipped to consumers
+example/     Reference usage
+docs/        Concept, agent skill, and license docs
+```
+
+## Pull requests
+
+- Branch off `main`; keep PRs focused on one change.
+- Keep the core **UI-library agnostic** — do not add framework-specific runtime
+  dependencies. Class conflict rules belong in app-level
+  `createClassComposer({ merge })` integrations.
+- The resolver is **server-only** (Node `fs`). Do not introduce browser/DOM
+  assumptions into `src/resolver.ts`.
+- Update `CHANGELOG.md` under `## Unreleased`.
+- Run `bun run build` before committing so `src` and `dist` stay in sync.
+
+## Conventions
+
+- ESM only; internal imports use explicit `.js` extensions (`./resolver.js`).
+- Match the existing code style (no new formatter configs in a PR).
+- Add or update docs in `docs/` when behavior changes.
+
+## Reporting bugs
+
+Open an issue at https://github.com/KondeIO/kdf/issues with a minimal repro.
+For security issues, see [SECURITY.md](./SECURITY.md) — do **not** open a public
+issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konde.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# @kondeio/kdf - Konde Design Framework
+
+Agent-first design consistency for Node-powered web apps.
+
+KDF gives AI agents a JSON source of truth for layout, spacing, typography, and
+component styling. Agents can build or update UI from that source in
+server-side JavaScript apps instead of rediscovering design rules across
+components, pages, and previous sessions.
+
+Think of it like i18n for design: one page maps to one JSON file, and each
+rendered element can point back to its exact design key with `data-kdf`. Users
+stay in the approval loop and adjust the source only when intent or product
+direction changes.
+
+## Why
+
+Styling drifts when class names live only inside `.tsx` files:
+
+- the same button slowly gets five different variants
+- spacing changes page by page
+- colors and typography become inconsistent
+- each new AI session has to rediscover the design rules
+- users spend time correcting visual drift through chat
+
+KDF moves repeatable styling into JSON:
+
+- agents apply tokens before changing UI
+- users can review and adjust the source when needed
+- `data-kdf` maps every DOM element back to its exact JSON path
+- the same design key can be scanned, tested, reviewed, and edited later
+
+KDF works with your existing styling stack: plain CSS, CSS modules, utility CSS,
+Bootstrap, shadcn, or a custom design system. It is not a component library and
+not a CSS engine.
+
+## Runtime Support
+
+KDF core runs in Node/server-side JavaScript environments because it reads JSON
+from disk with Node `fs`.
+
+- Works with server-rendered Next.js, Astro, Hono, or similar Node 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.
+
+| 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. |
+
+## Install
+
+Install the package:
+
+```bash
+npm install @kondeio/kdf
+pnpm add @kondeio/kdf
+bun add @kondeio/kdf
+```
+
+By default, install also scaffolds a starter `kdf/` folder when one does not
+already exist. Existing files are never overwritten.
+
+To install the dependency without running the initializer:
+
+```bash
+npm install @kondeio/kdf --ignore-scripts
+```
+
+Run initialization manually later:
+
+```bash
+npx kdf init
+```
+
+`npx kdf init` uses the local package binary when `@kondeio/kdf` is already
+installed in the project.
+
+Initialize a custom design directory:
+
+```bash
+KDF_DIR=./designs npx kdf init
+```
+
+## File Structure
+
+```
+kdf/
+  shared/              <- shared defaults (button, typography, layout, card)
+  homepage.json        <- starter page design
+  konde-server.css     <- critical project overrides
+  konde.css            <- non-critical project overrides
+```
+
+The package repository also keeps additional page JSON examples under
+`example/sample-pages/`. They are reference material only and are not copied by
+`postinstall` or `kdf init`.
+
+Typical app structure:
+
+```
+my-app/
+  app/
+    page.tsx
+    pricing/page.tsx
+  components/
+    hero.tsx
+    pricing-table.tsx
+  kdf/
+    shared/
+      button.json
+      card.json
+      color.json
+      layout.json
+      typography.json
+    homepage.json
+    konde-server.css
+    konde.css
+  next.config.ts
+```
+
+## Custom Design Directory
+
+The default design directory is `./kdf`.
+
+Use `./designs` or `./design` through `KDF_DIR` in any Node/server-side runtime:
+
+```bash
+KDF_DIR=./designs npm run dev
+```
+
+```tsx
+import { getDesign } from "@kondeio/kdf";
+
+const d = getDesign("homepage");
+```
+
+In Next.js, the optional plugin sets `KDF_DIR` for the app:
+
+```ts
+// next.config.ts
+import withKDF from "@kondeio/kdf/plugin";
+
+export default withKDF({ dir: "./designs" })(nextConfig);
+```
+
+With that config, KDF reads:
+
+```text
+designs/
+  shared/
+  homepage.json
+  konde-server.css
+  konde.css
+```
+
+Example token:
+
+```json
+{
+  "$layout": ["hero", "features", "footer"],
+  "hero": {
+    "wrapper": "mx-auto max-w-6xl px-6 py-20",
+    "title": "@typography.h1",
+    "cta": "@button.cta"
+  }
+}
+```
+
+## Usage
+
+```tsx
+import { getDesign } from "@kondeio/kdf";
+
+const d = getDesign("homepage");
+
+<h1 data-kdf="hero.title" className={d("hero.title")}>
+  {t("hero.headline")}
+</h1>
+```
+
+## Class Composition
+
+KDF includes small class composition helpers that work with any UI library:
+
+| Helper | Purpose |
+| --- | --- |
+| `cn()` | Joins conditional classes, drops falsy values, normalizes whitespace, and removes exact duplicates. |
+| `cx()` | Alias of `cn()`. |
+| `composeClasses()` | Same default composer with a more explicit name. |
+| `dedupeClasses()` | Removes exact duplicates from an existing class string. |
+| `createClassComposer({ merge })` | Creates a composer with an app-defined merge step. |
+
+The default behavior is intentionally universal. It normalizes whitespace and
+dedupes exact class names, but does not interpret semantic conflicts such as
+color, spacing, variant, or framework-specific utility groups.
+
+```tsx
+import { cn, getDesign } from "@kondeio/kdf";
+
+const d = getDesign("homepage");
+
+<button
+  data-kdf="hero.cta"
+  className={cn(d("hero.cta"), isActive && d("hero.cta-active"), className)}
+>
+  Start
+</button>
+```
+
+Remove exact duplicates:
+
+```ts
+import { dedupeClasses } from "@kondeio/kdf";
+
+dedupeClasses("btn btn btn-primary");
+// "btn btn-primary"
+```
+
+Add project-specific merge rules:
+
+```ts
+import { createClassComposer } from "@kondeio/kdf";
+
+const cn = createClassComposer({
+  merge(className) {
+    // Example: apply project-specific class rules here.
+    return className;
+  },
+});
+```
+
+## 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.
+
+For client components, resolve on the server and pass the resulting className
+string down as a prop:
+
+```tsx
+// Server Component
+const d = getDesign("homepage");
+return <ClientThing className={d("hero.cta")} />;
+```
+
+## References
+
+Reference shared tokens from shared/:
+
+```json
+{ "hero": { "cta": "@button.cta" } }
+```
+
+Extend with extra classes:
+
+```json
+{ "hero": { "cta": "@button.cta shadow-xl text-lg" } }
+```
+
+Multiple refs:
+
+```json
+{ "hero": { "login": "@button.base @button.ghost @button.sm" } }
+```
+
+## `data-kdf`
+
+Every element using `d()` should have matching `data-kdf`:
+
+```tsx
+<div data-kdf="hero.wrapper" className={d("hero.wrapper")}>
+```
+
+This makes the rendered UI traceable for agent scanning, visual editing, and
+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
+storms during HMR.
+
+```tsx
+const d = getDesign("homepage", { cache: "auto", maxAgeMs: 250 });
+```
+
+Use `clearKdfCache()` for explicit invalidation in custom tooling.
+
+## CSS Custom Properties
+
+For values not expressible as reusable classes:
+
+```json
+{
+  "hero": {
+    "title": {
+      "className": "text-3xl",
+      "css": { "--kdf-accent": "oklch(0.546 0.245 262)" }
+    }
+  }
+}
+```
+
+Generated CSS can live in `konde.css`. The plugin exposes its path via env
+(`KDF_CLIENT_CSS`); wire the `<link>`/import in your app (e.g. last in
+`globals.css`) — the plugin does not inject it for you.
+
+## Commands
+
+- `kdf init` - scaffold the starter `kdf/` folder and generated CSS files.
+- `bun example/preview.ts [tailwind|shadcn|bootstrap|pure-css]` - run the local
+  KDF example preview. Use `PORT=4410` to avoid port conflicts and
+  `KDF_PREVIEW_OPEN=0` for test/CI runs without opening a browser.
+
+## Next.js Config
+
+Default KDF directory (`./kdf`):
+
+```ts
+// next.config.ts
+import withKDF from "@kondeio/kdf/plugin";
+
+export default withKDF()(nextConfig);
+```
+
+Custom KDF directory (`./my-design`):
+
+```ts
+// next.config.ts
+import withKDF from "@kondeio/kdf/plugin";
+
+export default withKDF({ dir: "./my-design" })(nextConfig);
+```
+
+## Key Symbols
+
+| Symbol | Purpose | Example |
+| --- | --- | --- |
+| `$` | Component binding | `"$": "Button"` |
+| `@` | Shared style reference | `"@button.cta"` |
+| `$layout` | Page section order | `["hero", "footer"]` |
+
+## Documentation and Skills
+
+- [`docs/kdf-doc.md`](./docs/kdf-doc.md) - KDF concept, architecture, conventions, and operating model.
+- [`docs/kdf-skill.md`](./docs/kdf-skill.md) - agent-facing implementation and review checklist.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, build/test commands,
+and PR conventions. Keep the core UI-library agnostic and the resolver
+server-only.
+
+## Security
+
+`@kondeio/kdf` runs a `postinstall` script that scaffolds a starter `kdf/`
+folder into your project (never overwrites, no network calls). To skip it:
+`npm install @kondeio/kdf --ignore-scripts` or `KDF_SKIP_INIT=1`. Full details
+and vulnerability reporting in [SECURITY.md](./SECURITY.md).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE) for the full license text.

package/SECURITY.md

@@ -0,0 +1,53 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues **privately** — do not open a public GitHub issue.
+
+Email: **security@konde.io** (or open a private security advisory on the
+GitHub repository).
+
+Include a description, affected version, and a minimal reproduction if possible.
+We aim to acknowledge reports within a few business days.
+
+## Install-time behavior (`postinstall`)
+
+KDF runs a `postinstall` script that **scaffolds a starter `kdf/` folder** into
+the consuming project so the package works out of the box. You should know
+exactly what it does:
+
+- **What it writes:** a `kdf/` folder at the project root (`INIT_CWD`) containing
+  starter design JSON (`shared/*.json`, `homepage.json`) and generated CSS files
+  (`konde-server.css`, `konde.css`).
+- **What it never does:** it never overwrites an existing `kdf/` folder, never
+  touches files outside `kdf/`, makes no network calls, and reads/writes no
+  secrets or credentials.
+- **When it is skipped:** it does nothing if `kdf/` already exists.
+
+### Opting out
+
+```bash
+# Skip all install scripts (npm):
+npm install @kondeio/kdf --ignore-scripts
+
+# Or disable just KDF scaffolding:
+KDF_SKIP_INIT=1 npm install @kondeio/kdf
+```
+
+You can scaffold manually later with:
+
+```bash
+npx kdf init
+```
+
+## Reference resolution safety
+
+`@ref` component names (e.g. `@button.cta` → `shared/button.json`) are validated
+against `^[A-Za-z0-9_-]+$`. References containing path separators or `..` are
+rejected, so a ref cannot read files outside the `shared/` folder. Design JSON is
+authored by developers (trusted input); this is defense-in-depth.
+
+## Supported versions
+
+KDF is pre-1.0 (`0.x`). Security fixes target the latest published `0.x`
+release.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { mkdirSync, existsSync, copyFileSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeKondeCSS } from "./css-generator.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, "..", "kdf");
+const commands = {
+    init: cmdInit,
+};
+function cmdInit() {
+    const targetDir = join(process.cwd(), process.env.KDF_DIR || "kdf");
+    if (existsSync(targetDir)) {
+        console.log("kdf/ directory already exists. Skipping init.");
+        return;
+    }
+    // Create kdf/ and kdf/shared/
+    mkdirSync(join(targetDir, "shared"), { recursive: true });
+    // Copy shared token files
+    const sharedDir = join(TEMPLATES_DIR, "shared");
+    if (existsSync(sharedDir)) {
+        for (const file of readdirSync(sharedDir).filter((f) => f.endsWith(".json"))) {
+            copyFileSync(join(sharedDir, file), join(targetDir, "shared", file));
+        }
+    }
+    // Copy homepage.json as starter
+    const homepageSrc = join(TEMPLATES_DIR, "homepage.json");
+    if (existsSync(homepageSrc)) {
+        copyFileSync(homepageSrc, join(targetDir, "homepage.json"));
+    }
+    // Generate empty CSS files inside kdf/ folder
+    writeKondeCSS(targetDir);
+    console.log("Initialized:");
+    console.log("");
+    console.log("  kdf/");
+    console.log("    shared/");
+    console.log("      button.json");
+    console.log("      card.json");
+    console.log("      color.json");
+    console.log("      layout.json");
+    console.log("      typography.json");
+    console.log("    homepage.json");
+    console.log("    konde-server.css  (critical overrides — import in layout.tsx)");
+    console.log("    konde.css         (non-critical overrides — <link> last in <head>)");
+}
+// --- Main ---
+const command = process.argv[2];
+if (!command || !commands[command]) {
+    console.log("@kondeio/kdf - Design-as-JSON for agent-assisted UI");
+    console.log("");
+    console.log("Commands:");
+    console.log("  init       Scaffold kdf/ folder + konde.css");
+    console.log("");
+    console.log("Usage:");
+    console.log("  npx @kondeio/kdf init");
+    process.exit(command ? 1 : 0);
+}
+commands[command]();

package/dist/css-generator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate empty konde-server.css scaffold.
+ * Server-side loaded (import in layout.tsx) — inlined in HTML, no FOUC.
+ * For critical overrides that must be present on first paint.
+ */
+export declare function generateKondeServerCSS(): string;
+/**
+ * Generate empty konde.css scaffold.
+ * Client-side loaded (<link> last in <head>) — highest specificity.
+ * For non-critical overrides, experiments, CSS hacks.
+ */
+export declare function generateKondeCSS(): string;
+/**
+ * Write CSS files to disk — only if file doesn't exist.
+ * Safe to call multiple times; never overwrites user edits.
+ */
+export declare function writeKondeCSS(outputDir?: string): void;

package/dist/css-generator.js

@@ -0,0 +1,59 @@
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+/**
+ * Generate empty konde-server.css scaffold.
+ * Server-side loaded (import in layout.tsx) — inlined in HTML, no FOUC.
+ * For critical overrides that must be present on first paint.
+ */
+export function generateKondeServerCSS() {
+    return `/* konde-server.css — Critical design overrides (server-rendered) */
+/* Imported in layout.tsx — inlined in HTML, no FOUC */
+/* Edit freely — KDF will never overwrite this file */
+
+/* Use for:
+   - Critical layout fixes that cause visual shift
+   - CSS custom properties needed on first paint
+   - Override shared component visibility per page
+
+   Examples:
+   :root { --kdf-primary: #4F46E5; }
+   [data-kdf="hero.slider"] { display: none; }
+*/
+`;
+}
+/**
+ * Generate empty konde.css scaffold.
+ * Client-side loaded (<link> last in <head>) — highest specificity.
+ * For non-critical overrides, experiments, CSS hacks.
+ */
+export function generateKondeCSS() {
+    return `/* konde.css — Custom design overrides (client-side) */
+/* Loaded LAST in <head> via <link> — highest specificity */
+/* Edit freely — KDF will never overwrite this file */
+
+/* Use for:
+   - Fine-tune padding/margin/width
+   - Non-critical visual tweaks
+   - Quick experiments and CSS hacks
+
+   Examples:
+   [data-kdf="hero.title"] { letter-spacing: -0.02em; }
+   [data-kdf="hero.wrapper"] { gap: 3rem; }
+*/
+`;
+}
+/**
+ * Write CSS files to disk — only if file doesn't exist.
+ * Safe to call multiple times; never overwrites user edits.
+ */
+export function writeKondeCSS(outputDir) {
+    const dir = outputDir || process.cwd();
+    const serverCss = join(dir, "konde-server.css");
+    const clientCss = join(dir, "konde.css");
+    if (!existsSync(serverCss)) {
+        writeFileSync(serverCss, generateKondeServerCSS(), "utf-8");
+    }
+    if (!existsSync(clientCss)) {
+        writeFileSync(clientCss, generateKondeCSS(), "utf-8");
+    }
+}