DesignKit

DesignKit is a SvelteKit application plus a small src/lib/dk utility library for mathematical UI tooling. It ships a deterministic proof page plus fourteen focused tools that turn structured inputs into repeatable outputs across layout solving, composition scoring, palette generation, perceptual distinctness, target acquisition, typography spacing, prepared paragraph layout, modular scales, glass CSS, optical corrections, APCA contrast checks, spring easing, minimum-jerk motion, balanced line breaking, and CSS auditing.

Advanced engine, runtime-backed ML features, API endpoints, and DesignDocument schema are documented in docs/advanced-engine.md.

Runbook

• pnpm dev starts the local app.
• pnpm dkcms:dev starts the standalone dkcms worker.
• pnpm dkcms:dev:all applies the local D1 schema, starts the worker, and starts the app together for end-to-end dev.
• pnpm dk --help shows the full DesignKit CLI surface.
• pnpm dk <command> runs the source-owned dk CLI through the package script wrapper.
• pnpm build:cli emits the publishable npm package files to dist/.
• pnpm pack:dry previews the npm tarball contents after the CLI build.
• pnpm lint runs ESLint with zero-warning tolerance.
• pnpm check:strict runs svelte-check and fails on warnings.
• pnpm test runs the Vitest suite.
• pnpm test:e2e builds the app and runs the Playwright suite.
• DK_VISUAL_SNAPSHOTS=1 pnpm exec playwright test e2e/component-gallery.e2e.ts runs the opt-in, platform-specific gallery screenshot checks.
• pnpm test:coverage runs the suite with coverage thresholds.
• pnpm build produces the production bundle.
• pnpm verify runs the full local verification sequence.

Architecture

• src/routes contains one route per tool plus a perfect proof page that composes several dk modules together.
• workers/dkcms is a sibling Cloudflare Worker that stores CMS state in D1, runs a Workflow-backed dk build loop, and emits generated pages.
• src/lib/dk contains the pure logic and string-generation helpers behind each tool.
• src/lib/dk/cli.ts is the source-owned CLI layer for the dk command surface.
• bin/dk.js is the local development wrapper used by pnpm dk.
• src/bin/dk.ts is the publishable CLI entrypoint compiled into dist/bin/dk.js.
• src/lib/styles/tokens.css and src/app.css define shared visual tokens and app-wide styles.

Documentation

• docs/advanced-engine.md: runtime-backed saliency/layout/compose, API endpoints, DesignDocument schema, app-shell behavior, and production defaults.
• pnpm dk <command> --help: command-level flags and formats.
• src/routes/README.md: route-to-module mapping.
• src/lib/dk/README.md: module responsibilities and library rules.

npm Package

The repo now packages the CLI as @dkcli/cli.

• Install globally: npm install -g @dkcli/cli
• Run via package binary: dk --help or dkcli --help
• Run one-off without installing: npx @dkcli/cli --help

Constraints

• Do not edit .svelte-kit/ or dk-current; both are generated artifacts.
• Internal route code should import directly from specific src/lib/dk/*.ts modules.
• Avoid $effect for local state synchronization; prefer derived state or explicit event handlers.

Deployment

Cloudflare deployment config lives in wrangler.jsonc. The current deploy script is pnpm deploy.

• Production runtime base URL is https://dkcli.com.
• dkcms is configured separately in workers/dkcms/wrangler.jsonc.
• The CLI keeps saliency/layout/compose local unless --runtime-url or DK_RUNTIME_URL is set. ml and auto without a runtime URL fall back to local heuristic analysis.
• AI is required for server-side ML importance scoring. DK_CACHE is optional. If you deploy with KV enabled, replace the placeholder namespace IDs in wrangler.jsonc.