@kondeio/kdf 0.1.0

package/docs/kdf-skill.md

@@ -0,0 +1,374 @@
+# KDF Skill
+
+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`
+Required convention: every `d()` usage must have matching `data-kdf`
+
+## Goal
+
+Build UI from KDF JSON instead of improvising styles in JSX.
+
+KDF is the design source of truth. Code should render the design. Agents should not invent spacing, colors, typography, or section order when a KDF token exists or should exist.
+
+## Install Behavior
+
+Check whether the host app already has `@kondeio/kdf` installed before adding it.
+
+Default install:
+
+```bash
+npm install @kondeio/kdf
+```
+
+This scaffolds starter `kdf/` through `postinstall` if the folder does not exist.
+
+Opt out:
+
+```bash
+npm install @kondeio/kdf --ignore-scripts
+```
+
+Manual init:
+
+```bash
+npx kdf init
+```
+
+Do not document fake custom npm flags such as `--noinit`. Use `--ignore-scripts`.
+
+## Before You Edit
+
+1. Locate the relevant design file:
+
+```text
+kdf/<page>.json
+kdf/shared/*.json
+```
+
+2. Locate the relevant UI component or page.
+
+3. Confirm package import:
+
+```ts
+import { getDesign, cn } from "@kondeio/kdf";
+```
+
+4. Confirm page accessor:
+
+```ts
+const d = getDesign("homepage");
+```
+
+5. Confirm the styling framework scans KDF JSON if it generates CSS by scanning source files:
+
+```css
+@source "../kdf/**/*.json";
+```
+
+or equivalent framework/source scanning config.
+
+## Non-negotiable Rules
+
+### 1. Do Not Guess Design
+
+If a class belongs to the design system, put it in JSON and read it with `d()`.
+
+Wrong:
+
+```tsx
+<h1 className="text-5xl font-semibold tracking-tight">
+```
+
+Right:
+
+```tsx
+<h1 data-kdf="hero.title" className={d("hero.title")}>
+```
+
+### 2. Always Add `data-kdf`
+
+Every token usage must be traceable.
+
+Wrong:
+
+```tsx
+<h1 className={d("hero.title")}>
+```
+
+Right:
+
+```tsx
+<h1 data-kdf="hero.title" className={d("hero.title")}>
+```
+
+The `data-kdf` value must match the `d()` path.
+
+### 3. Keep Component Logic in Code
+
+KDF controls design, not business logic.
+
+Keep these in code:
+
+- data fetching
+- state
+- event handlers
+- conditional rendering
+- permissions
+- accessibility behavior
+- component implementation
+
+Keep these in KDF JSON:
+
+- classes
+- page section order
+- visibility via `$layout`
+- shared style references
+- CSS custom properties
+- component design metadata such as `$`, `variant`, and `size`
+
+### 4. Prefer Shared Tokens
+
+If a style repeats across pages, move it into `kdf/shared`.
+
+Example:
+
+```json
+{
+  "hero": {
+    "cta": "@button.cta"
+  }
+}
+```
+
+Avoid copying the same long button class into many page files.
+
+### 5. Use KDF Class Composition
+
+Use `cn()` when combining KDF tokens with conditional classes or caller-provided `className`.
+
+```tsx
+className={cn(d("button.base"), active && d("button.active"), className)}
+```
+
+Do not concatenate class strings manually when conditional classes can drift or duplicate.
+
+KDF provides universal class helpers:
+
+- `cn()` joins conditional classes, drops falsy values, normalizes whitespace,
+  and removes exact duplicate classes.
+- `cx()` is an alias of `cn()`.
+- `composeClasses()` is the same default composer with a more explicit name.
+- `dedupeClasses()` removes exact duplicate class names from an existing string.
+- `createClassComposer({ merge })` lets the app inject project-specific class
+  rules.
+
+Default KDF composition is semantic-free. It does not resolve color, spacing,
+variant, or framework-specific conflicts. If an app needs those rules, define
+them at app level:
+
+```ts
+import { createClassComposer } from "@kondeio/kdf";
+
+export const cn = createClassComposer({
+  merge(className) {
+    return applyProjectClassRules(className);
+  }
+});
+```
+
+### 6. Resolve Design Server-Side
+
+`getDesign()` / `d()` / `d.css()` read JSON via Node `fs` — server-only. Never
+call them in a Client Component (`"use client"`); the browser has no filesystem.
+Resolve in server-rendered code such as a Next.js Server Component, Astro
+server render, or Hono server handler, then pass the resulting className string
+down to browser/client components as a prop.
+
+```tsx
+// Server Component
+const d = getDesign("homepage");
+return <ClientThing className={d("hero.cta")} />;
+```
+
+## JSON Patterns
+
+### String Token
+
+```json
+{
+  "hero": {
+    "wrapper": "mx-auto max-w-6xl px-6 py-20"
+  }
+}
+```
+
+```tsx
+<section data-kdf="hero.wrapper" className={d("hero.wrapper")} />
+```
+
+### Object Token
+
+```json
+{
+  "hero": {
+    "title": {
+      "$": "h1",
+      "className": "@typography.h1"
+    }
+  }
+}
+```
+
+```tsx
+<h1 data-kdf="hero.title" className={d("hero.title")} />
+```
+
+### CSS Properties
+
+```json
+{
+  "hero": {
+    "title": {
+      "className": "text-3xl",
+      "css": {
+        "--kdf-accent": "oklch(0.546 0.245 262)"
+      }
+    }
+  }
+}
+```
+
+```tsx
+<h1
+  data-kdf="hero.title"
+  className={d("hero.title")}
+  style={d.css("hero.title")}
+/>
+```
+
+## References
+
+Use `@` for shared style references.
+
+```json
+{
+  "hero": {
+    "cta": "@button.cta"
+  }
+}
+```
+
+Extend a shared reference:
+
+```json
+{
+  "hero": {
+    "cta": "@button.cta shadow-xl"
+  }
+}
+```
+
+Use multiple references:
+
+```json
+{
+  "hero": {
+    "login": "@button.base @button.ghost @button.sm"
+  }
+}
+```
+
+## Page Layout
+
+Use `$layout` for section order and visibility.
+
+```json
+{
+  "$layout": ["hero", "features", "footer"],
+  "hero": {},
+  "features": {},
+  "footer": {}
+}
+```
+
+Rules:
+
+- render sections in `$layout` order
+- hide sections missing from `$layout`
+- keep section token data even when hidden if it may be reused later
+
+## Cache Behavior
+
+KDF caches JSON by default.
+
+Development mode revalidates with file `mtimeMs` and `size` checks to avoid disk-read storms during HMR.
+
+Use explicit cache options only when needed:
+
+```ts
+const d = getDesign("homepage", {
+  cache: "auto",
+  maxAgeMs: 250
+});
+```
+
+Use custom invalidation only for tooling:
+
+```ts
+clearKdfCache();
+```
+
+## Implementation Checklist
+
+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")`.
+- [ ] Every `d()` usage has matching `data-kdf`.
+- [ ] Shared repeated styles live in `kdf/shared`.
+- [ ] One-off page styles live in `kdf/<page>.json`.
+- [ ] Conditional class composition uses `cn()`, `cx()`, or `composeClasses()`.
+- [ ] Exact duplicate class cleanup uses `dedupeClasses()` when operating on an existing class string.
+- [ ] App-specific semantic merge rules use `createClassComposer({ merge })`, not hardcoded KDF internals.
+- [ ] CSS custom properties use `d.css(path)`.
+- [ ] The app's styling framework scans KDF JSON files when required.
+- [ ] No large design class strings are hardcoded in JSX when a token should exist.
+- [ ] `$layout` is respected if the page uses section ordering.
+
+## Review Checklist
+
+Use this when reviewing code written by another agent.
+
+- [ ] No legacy `@konde/kdf` imports remain; use `@kondeio/kdf`.
+- [ ] No element uses `d("...")` without `data-kdf`.
+- [ ] `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.
+- [ ] `@` refs are not used for business logic.
+- [ ] No non-English or informal comments are introduced into user-facing app source.
+
+## Validation Commands
+
+From the host app:
+
+```bash
+bun run build
+```
+
+Use the host app's existing lint, typecheck, test, and build commands when they
+exist.
+
+## Agent Behavior
+
+If a user asks for a KDF UI change:
+
+1. Inspect current JSON.
+2. Inspect the rendered component/page.
+3. Update JSON first when the change is design-only.
+4. Update TSX only when structure, behavior, or data flow changes.
+5. Verify `data-kdf` coverage.
+6. Run the smallest relevant validation.

package/example/bootstrap/globals.css

@@ -0,0 +1,12 @@
+/* Bootstrap 5 — via CDN */
+@import url("https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css");
+
+/* Bridge: KDF CSS variables → Bootstrap CSS variables */
+.btn-primary {
+  --bs-btn-bg: var(--kdf-primary, #0d6efd);
+  --bs-btn-border-color: var(--kdf-primary, #0d6efd);
+  --bs-btn-hover-bg: var(--kdf-primary, #0d6efd);
+  --bs-btn-hover-border-color: var(--kdf-primary, #0d6efd);
+}
+
+/* Load konde.css after framework CSS in the host app. withKDF() only exposes paths. */

package/example/bootstrap/hero-section.tsx

@@ -0,0 +1,38 @@
+import { getDesign } from "@kondeio/kdf";
+
+export function HeroSection() {
+  const d = getDesign("homepage");
+
+  return (
+    <section data-kdf="hero.wrapper" className={d("hero.wrapper")}>
+      <div data-kdf="hero.content" className={d("hero.content")}>
+        <h1 data-kdf="hero.title" className={d("hero.title")}>
+          Build websites with AI
+        </h1>
+        <p data-kdf="hero.description" className={d("hero.description")}>
+          The AI orchestration platform for web development teams.
+        </p>
+        <div data-kdf="hero.actions" className={d("hero.actions")}>
+          <a href="/about" data-kdf="hero.cta-secondary" className={d("hero.cta-secondary")}>
+            Learn more
+          </a>
+          <a href="/pricing" data-kdf="hero.cta-primary" className={d("hero.cta-primary")}>
+            Get started
+          </a>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+/*
+  kdf/shared/button.json (Bootstrap version):
+    "base": "btn",
+    "cta": "btn btn-primary btn-lg shadow",
+    "outline": "btn btn-outline-secondary"
+
+  kdf/homepage.json:
+    "hero.cta-primary": "@button.cta"
+
+  Same JSON structure, different class values.
+*/

package/example/bootstrap/kdf/homepage.json

@@ -0,0 +1,35 @@
+{
+  "hero": {
+    "wrapper": "row align-items-center g-5",
+    "content": "col-lg-6",
+    "title": {
+      "className": "@typography.h1",
+      "css": {
+        "color": "orange",
+        "font-size": "3.5rem",
+        "--kdf-title-accent": "blue"
+      }
+    },
+    "description": {
+      "className": "mt-3 @typography.body",
+      "css": { "color": "#6c757d" }
+    },
+    "actions": "mt-4 d-flex gap-3",
+    "cta-primary": "@button.base @button.cta @button.lg",
+    "cta-secondary": "@button.base @button.outline",
+    "slider": "col-lg-6"
+  },
+  "template-grid": {
+    "wrapper": "row row-cols-1 row-cols-sm-2 row-cols-lg-3 g-4 mt-5",
+    "card": "@card.base @card.hover",
+    "card-image": "card-img-top",
+    "card-body": "card-body",
+    "card-title": "card-title fw-medium fs-6",
+    "card-category": "@typography.small"
+  },
+  "pagination": {
+    "wrapper": "mt-4 d-flex justify-content-center gap-2",
+    "button": "@button.base @button.ghost @button.sm",
+    "active": "@button.base @button.primary @button.sm"
+  }
+}

package/example/bootstrap/kdf/shared/button.json

@@ -0,0 +1,10 @@
+{
+  "base": "btn",
+  "primary": "btn-primary",
+  "outline": "btn-outline-secondary",
+  "ghost": "btn-link text-decoration-none",
+  "cta": "btn-primary shadow",
+  "sm": "btn-sm",
+  "md": "",
+  "lg": "btn-lg"
+}

package/example/bootstrap/kdf/shared/card.json

@@ -0,0 +1,4 @@
+{
+  "base": "card",
+  "hover": "shadow-sm"
+}

package/example/bootstrap/kdf/shared/color.json

@@ -0,0 +1,17 @@
+{
+  "primary": {
+    "css": { "--kdf-primary": "red" }
+  },
+  "danger": {
+    "css": { "--kdf-danger": "#dc3545" }
+  },
+  "success": {
+    "css": { "--kdf-success": "#198754" }
+  },
+  "warning": {
+    "css": { "--kdf-warning": "#ffc107" }
+  },
+  "accent": {
+    "css": { "--kdf-accent": "#fd7e14" }
+  }
+}

package/example/bootstrap/kdf/shared/layout.json

@@ -0,0 +1,7 @@
+{
+  "header": "sticky-top bg-white border-bottom py-2 px-4",
+  "sidebar": "position-fixed top-0 start-0 vh-100 bg-white border-end d-none d-lg-block",
+  "content": "flex-grow-1 p-4",
+  "main": "d-flex flex-column",
+  "footer": "border-top py-4 px-4"
+}

package/example/bootstrap/kdf/shared/typography.json

@@ -0,0 +1,8 @@
+{
+  "h1": "display-4 fw-bold",
+  "h2": "display-6 fw-bold",
+  "h3": "h4 fw-semibold",
+  "body": "lead",
+  "muted": "small",
+  "small": "fs-6"
+}

package/example/bootstrap/konde-server.css

@@ -0,0 +1,3 @@
+/* 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 */

package/example/bootstrap/konde.css

@@ -0,0 +1,3 @@
+/* konde.css — Custom design overrides */
+/* Loaded LAST in <head> for highest specificity */
+/* Edit freely — KDF will never overwrite this file */