dekit-cli 0.4.2 → 0.4.3

package/dist/editor/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Dekit Editor</title>
-  <script type="module" crossorigin src="/assets/index-D16Bm-Rw.js"></script>
+  <script type="module" crossorigin src="/assets/index-hySfUCIY.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-HLKs1tz-.css">
 </head>
 <body>

package/docs/usage.md

@@ -132,6 +132,7 @@ Every page and component must be registered:
 
 ```yaml
 version: 1.0
+device: "iPhone 16"
 global-style: "global.css"
 
 components:
@@ -143,6 +144,13 @@ pages:
   home:
     template: "pages/home/home.html"
     style: "pages/home/home.css"
+    properties:
+      showBanner:
+        type: boolean
+        default: true
+      itemCount:
+        type: number
+        default: 3
   about:
     template: "pages/about/about.html"
     style: "pages/about/about.css"
@@ -150,6 +158,44 @@ pages:
 
 All paths are relative to the `.dekit/` directory.
 
+### device
+
+Sets the target device for the project. Affects screenshot default viewport and editor initial device.
+
+Accepts a preset name (e.g. `"iPhone 16"`, `"iPad Air"`, `"Desktop 1440"`) or custom dimensions:
+
+```yaml
+device:
+  width: 400
+  height: 800
+  dpr: 2
+```
+
+When omitted, screenshots default to 1280×800.
+
+### Page Properties
+
+Pages can declare properties — typed parameters with defaults. Properties are injected as `window.__DEKIT_PROPS__` in the page, so your HTML/JS can read them to control rendering.
+
+**Supported types:** `boolean`, `number`, `string`.
+
+**Using properties in page HTML:**
+```html
+<section class="banner">...</section>
+<script>
+  if (!window.__DEKIT_PROPS__.showBanner) {
+    document.querySelector('.banner').remove();
+  }
+</script>
+```
+
+**Override properties in screenshots** with `--props`:
+```bash
+dekit screenshot '$${home}' --props showBanner=false --props itemCount=5
+```
+
+Values are converted based on the declared type (not guessed). Unspecified props use their default.
+
 ## CLI Reference
 
 ### dekit init [path] [--template name]
@@ -162,6 +208,7 @@ Templates: `blank`, `landing`, `dashboard`, `mobile`.
 dekit init                           # .dekit/ in current directory
 dekit init my-project                # my-project/.dekit/
 dekit init --template landing        # With template
+dekit init --template mobile --device "iPhone 16"  # With device
 dekit init --template                # List available templates
 ```
 
@@ -202,6 +249,7 @@ dekit screenshot '$${home@.hero}'              # Element only
 dekit screenshot '$${home}' --device iphone-14 # Device size
 dekit screenshot '$${home}' --full-page        # Include scroll area
 dekit screenshot '$${home}' -o output.png      # Custom output path
+dekit screenshot '$${home}' --props showBanner=false --props itemCount=5  # Override properties
 dekit screenshot --all                         # All pages
 ```
 
@@ -231,19 +279,160 @@ When you see a `$${...}` pattern in user messages:
 
 You don't need to parse refs yourself — just pass them to the CLI.
 
+## Best Practices
+
+### 1. Start with DESIGN.md
+
+Before writing any HTML/CSS, read `.dekit/DESIGN.md`. This is the design system source of truth for the project.
+
+- **If DESIGN.md exists** — read it and follow the design specifications (colors, typography, components, spacing) when building pages.
+- **If DESIGN.md does not exist** — generate one based on the current design task requirements before writing any code. Infer the visual style, color palette, and layout rules from the user's request, then write `.dekit/DESIGN.md`.
+- **If the user's request conflicts with DESIGN.md** — update DESIGN.md first to reflect the new requirements, then implement the changes. DESIGN.md is always the single source of truth; code follows the spec, not the other way around.
+
+The recommended sections:
+
+```markdown
+# DESIGN.md
+
+## 1. Visual Theme & Atmosphere
+Clean, minimal SaaS aesthetic with generous white space. Light and airy,
+professional but approachable. Rounded geometry, subtle shadows, no hard borders.
+
+## 2. Color Palette & Roles
+- **Royal Blue** (`#2563eb`): Primary brand, CTA backgrounds, active states
+- **Amber** (`#f59e0b`): Accent, highlights, badges
+- **Slate 900** (`#0f172a`): Headings, primary text
+- **Slate 500** (`#64748b`): Body text, descriptions
+- **Slate 100** (`#f1f5f9`): Surface backgrounds, cards
+- **White** (`#ffffff`): Page background
+- **Red 500** (`#ef4444`): Error states, destructive actions
+- **Green 500** (`#22c55e`): Success states, confirmations
+
+## 3. Typography Rules
+- Font: system-ui, -apple-system, sans-serif
+- Headings: weight 700, tight line-height (1.1-1.2)
+- Body: weight 400, relaxed line-height (1.5-1.6), 16px base
+- Small/labels: weight 500, 12-14px, uppercase tracking for overlines
+
+## 4. Component Stylings
+- **Buttons**: 8px radius, 12px 24px padding. Primary: blue bg + white text.
+  Outline: transparent bg + blue border + blue text. Hover darkens 10%.
+- **Cards**: white bg, 12px radius, 1px solid #e2e8f0 border,
+  shadow 0 1px 3px rgba(0,0,0,0.1). No header stripe.
+- **Inputs**: 8px radius, 1px #d1d5db border, 10px 14px padding.
+  Focus: blue border + blue ring shadow.
+
+## 5. Layout & Spacing Principles
+- 4px base grid. Spacing scale: 4, 8, 16, 24, 32, 48, 64, 96.
+- Page max-width: 1200px, centered.
+- Section vertical padding: 64-96px.
+- Card grid: 16-24px gap.
+
+## 6. Pages
+- **home** — hero with CTA, features grid (3 cols), pricing cards, footer
+- **dashboard** — sidebar nav, stats bar, task list with filters
+```
+
+Write DESIGN.md first, then derive `global.css` tokens from it. Update the document as the design evolves.
+
+### 2. Derive global.css from DESIGN.md
+
+Translate the colors, typography, and spacing from DESIGN.md into CSS custom properties in `global.css`:
+
+```css
+:root {
+  /* From §2 Color Palette */
+  --color-primary: #2563eb;
+  --color-accent: #f59e0b;
+  --color-text: #0f172a;
+  --color-muted: #64748b;
+  --color-bg: #ffffff;
+  --color-surface: #f1f5f9;
+  --color-border: #e2e8f0;
+  --color-error: #ef4444;
+  --color-success: #22c55e;
+
+  /* From §4 Component Stylings */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+
+  /* From §5 Layout & Spacing */
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 16px;
+  --space-lg: 24px;
+  --space-xl: 48px;
+}
+```
+
+Pages should reference these variables (`var(--color-primary)`) instead of hardcoding values. This ensures consistency and makes global changes a single-file edit.
+
+### 3. Build section by section, screenshot after each
+
+Don't write an entire page before checking the result. Build incrementally:
+
+```
+1. Write the hero section HTML + CSS
+2. dekit screenshot '$${home@.hero}'     # Verify just the hero
+3. Write the features grid
+4. dekit screenshot '$${home}'           # Verify overall layout
+5. Continue section by section
+```
+
+Catching issues early avoids cascading problems. A broken layout in the hero affects everything below it.
+
+### 4. Use properties for state variants
+
+When a page has multiple states (empty, loading, error, different data counts), use properties instead of duplicating pages:
+
+```yaml
+pages:
+  dashboard:
+    template: pages/dashboard/dashboard.html
+    style: pages/dashboard/dashboard.css
+    properties:
+      taskCount:
+        type: number
+        default: 5
+      showEmptyState:
+        type: boolean
+        default: false
+```
+
+Then screenshot each variant:
+
+```bash
+dekit screenshot '$${dashboard}'                              # Normal state
+dekit screenshot '$${dashboard}' --props showEmptyState=true  # Empty state
+dekit screenshot '$${dashboard}' --props taskCount=0          # Zero items
+dekit screenshot '$${dashboard}' --props taskCount=100        # Many items
+```
+
+### 5. Extract repeated patterns into components
+
+When you see the same HTML structure appear twice or more, extract it into a Web Component:
+
+```bash
+dekit add component ui-card
+```
+
+Move the shared markup into the component's `<template>` with `<slot>` for variable content. This keeps pages DRY and makes global updates to the pattern a single-file change.
+
 ## Design Workflow
 
 ### Self-directed design loop
 
 ```
 1. dekit init --template landing          # Start project
-2. Edit .dekit/pages/home/home.html       # Write HTML
-3. Edit .dekit/pages/home/home.css        # Write CSS
-4. dekit screenshot '$${home}'            # Take screenshot
-5. Read the screenshot file               # Analyze the result
-6. Edit HTML/CSS to fix issues            # Iterate
-7. Repeat 4-6 until satisfied             # Keep improving
-8. dekit serve                            # Let human review
+2. Read .dekit/DESIGN.md or generate one  # Design system first
+3. Derive design tokens in global.css     # From DESIGN.md
+4. Build page section by section          # Incremental progress
+5. dekit screenshot '$${home}'            # Verify after each section
+6. Read the screenshot, iterate           # Fix issues early
+7. Extract components when patterns repeat
+8. Screenshot all property variants       # Cover edge cases
+9. dekit serve                            # Let human review
 ```
 
 ### Human feedback loop

package/editor/src/App.tsx

@@ -56,6 +56,14 @@ export function App() {
         if (data.pages.length > 0) {
           setCurrentPage(data.pages[0]);
         }
+        if (data.device) {
+          const preset = DEVICE_PRESETS.find(
+            (d) => d.name === data.device!.name
+          );
+          setDeviceMode(preset ? preset.name : "custom");
+          setDeviceWidth(data.device.width);
+          setDeviceHeight(data.device.height);
+        }
       });
   }, []);
 

package/editor/src/types.ts

@@ -14,10 +14,18 @@ export interface DOMTreeNode {
   children: DOMTreeNode[];
 }
 
+export interface DeviceConfig {
+  width: number;
+  height: number;
+  dpr: number;
+  name?: string;
+}
+
 export interface EditorConfig {
   pages: string[];
   pagePaths: Record<string, string>;
   components: string[];
+  device: DeviceConfig | null;
   designServerUrl: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dekit-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "type": "module",
   "description": "A code-first design toolkit for agents and humans — create, preview, and screenshot HTML/CSS designs",
   "keywords": [

package/src/cli/init.test.ts

@@ -48,6 +48,28 @@ describe("runInit", () => {
     await expect(runInit([tempDir])).rejects.toThrow(/already exists/i);
   });
 
+  test("mobile template includes device by default", async () => {
+    await runInit([tempDir, "--template", "mobile"]);
+
+    const content = readFileSync(join(tempDir, ".dekit/dekit.yaml"), "utf-8");
+    expect(content).toContain("iPhone 16");
+  });
+
+  test("--device flag writes device to dekit.yaml", async () => {
+    await runInit([tempDir, "--device", "iPad Air"]);
+
+    const content = readFileSync(join(tempDir, ".dekit/dekit.yaml"), "utf-8");
+    expect(content).toContain("iPad Air");
+  });
+
+  test("--device flag overrides template default device", async () => {
+    await runInit([tempDir, "--template", "mobile", "--device", "Pixel 8"]);
+
+    const content = readFileSync(join(tempDir, ".dekit/dekit.yaml"), "utf-8");
+    expect(content).toContain("Pixel 8");
+    expect(content).not.toContain("iPhone 16");
+  });
+
   test("lists templates when --template given without value", async () => {
     const consoleSpy = vi.spyOn(console, "log");
     await runInit(["--template"]);

package/src/cli/init.ts

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve, join } from "node:path";
+import yaml from "js-yaml";
 
 const TEMPLATES_DIR = join(import.meta.dirname, "../../templates/projects");
 
@@ -8,6 +9,7 @@ const AVAILABLE_TEMPLATES = ["blank", "landing", "dashboard", "mobile"];
 export async function runInit(args: string[]) {
   let targetDir = process.cwd();
   let template = "blank";
+  let deviceArg: string | undefined;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -19,6 +21,8 @@ export async function runInit(args: string[]) {
       }
       template = next;
       i++;
+    } else if (arg === "--device") {
+      deviceArg = args[++i];
     } else if (!arg.startsWith("-")) {
       targetDir = resolve(arg);
     }
@@ -44,5 +48,12 @@ export async function runInit(args: string[]) {
   mkdirSync(dekitDir, { recursive: true });
   cpSync(templateDir, dekitDir, { recursive: true });
 
+  if (deviceArg) {
+    const yamlPath = join(dekitDir, "dekit.yaml");
+    const doc = yaml.load(readFileSync(yamlPath, "utf-8")) as Record<string, unknown>;
+    doc.device = deviceArg;
+    writeFileSync(yamlPath, yaml.dump(doc, { quotingType: '"', forceQuotes: false }));
+  }
+
   console.log(`Created dekit project in ${dekitDir} (template: ${template})`);
 }

package/src/cli/screenshot.ts

@@ -19,6 +19,7 @@ function parseArgs(args: string[]): {
   width?: number;
   height?: number;
   fullPage: boolean;
+  props: Record<string, string>;
 } {
   let ref: string | undefined;
   let outputPath: string | undefined;
@@ -26,6 +27,7 @@ function parseArgs(args: string[]): {
   let width: number | undefined;
   let height: number | undefined;
   let fullPage = false;
+  const props: Record<string, string> = {};
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -39,6 +41,13 @@ function parseArgs(args: string[]): {
       height = parseInt(args[++i], 10);
     } else if (arg === "--full-page") {
       fullPage = true;
+    } else if (arg === "--props") {
+      const kv = args[++i];
+      const eqIdx = kv.indexOf("=");
+      if (eqIdx === -1) {
+        throw new Error(`Invalid --props format: "${kv}". Expected key=value`);
+      }
+      props[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
     } else if (!arg.startsWith("-")) {
       ref = arg;
     }
@@ -48,19 +57,19 @@ function parseArgs(args: string[]): {
     throw new Error("Missing ref argument. Expected format: $${page} or $${page@selector}");
   }
 
-  return { ref, outputPath, deviceName, width, height, fullPage };
+  return { ref, outputPath, deviceName, width, height, fullPage, props };
 }
 
 export async function runScreenshot(config: DesignConfig, args: string[]) {
-  const { ref, outputPath, deviceName, width, height, fullPage } = parseArgs(args);
+  const { ref, outputPath, deviceName, width, height, fullPage, props } = parseArgs(args);
 
   // Parse and validate the ref (throws on invalid format)
   const parsedRef = parseRef(ref);
 
-  // Resolve viewport from --device or --width/--height flags
-  let viewportWidth = 1280;
-  let viewportHeight = 800;
-  let devicePixelRatio = 1;
+  // Resolve viewport from --device or --width/--height flags, falling back to config.device
+  let viewportWidth = config.device?.width ?? 1280;
+  let viewportHeight = config.device?.height ?? 800;
+  let devicePixelRatio = config.device?.dpr ?? 1;
 
   if (deviceName) {
     const normalizedInput = deviceName.toLowerCase().replace(/\s+/g, "-");
@@ -131,7 +140,12 @@ export async function runScreenshot(config: DesignConfig, args: string[]) {
     });
 
     const pageKey = parsedRef.pageKey;
-    const url = `http://localhost:${port}/page/${pageKey}?noinspector`;
+    const urlObj = new URL(`http://localhost:${port}/page/${pageKey}`);
+    urlObj.searchParams.set("noinspector", "");
+    for (const [key, value] of Object.entries(props)) {
+      urlObj.searchParams.set(`props.${key}`, value);
+    }
+    const url = urlObj.toString();
     await page.goto(url, { waitUntil: "networkidle0" });
 
     if (parsedRef.type === "element") {

package/src/editor-server.ts

@@ -20,10 +20,18 @@ export async function startEditorServer(
       for (const [name, def] of Object.entries(config.pages)) {
         pagePaths[name] = join(config.baseDir, def.template);
       }
+      const pageProperties: Record<string, Record<string, { type: string; default: unknown }>> = {};
+      for (const [name, def] of Object.entries(config.pages)) {
+        if (def.properties) {
+          pageProperties[name] = def.properties;
+        }
+      }
       const payload = {
         pages: Object.keys(config.pages),
         pagePaths,
+        pageProperties,
         components: Object.keys(config.components),
+        device: config.device ?? null,
         designServerUrl: `http://localhost:${designPort}`,
       };
       res.setHeader("Content-Type", "application/json");

package/src/parser.test.ts

@@ -55,6 +55,170 @@ pages:
     ).rejects.toThrow(/not found|does not exist/i);
   });
 
+  test("parses device as preset name string", async () => {
+    const yaml = `
+version: 1.0
+device: "iPhone 16"
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toEqual({
+      width: 393,
+      height: 852,
+      dpr: 3,
+      name: "iPhone 16",
+    });
+  });
+
+  test("parses device as custom dimensions object", async () => {
+    const yaml = `
+version: 1.0
+device:
+  width: 400
+  height: 800
+  dpr: 2
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toEqual({
+      width: 400,
+      height: 800,
+      dpr: 2,
+    });
+  });
+
+  test("device defaults dpr to 1 when omitted", async () => {
+    const yaml = `
+version: 1.0
+device:
+  width: 400
+  height: 800
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device!.dpr).toBe(1);
+  });
+
+  test("device is undefined when not specified", async () => {
+    const yaml = `
+version: 1.0
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toBeUndefined();
+  });
+
+  test("rejects unknown device preset name", async () => {
+    const yaml = `
+version: 1.0
+device: "Nokia 3310"
+pages: {}
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Unknown device/i);
+  });
+
+  test("rejects device object without width/height", async () => {
+    const yaml = `
+version: 1.0
+device:
+  dpr: 2
+pages: {}
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/width.*height/i);
+  });
+
+  test("parses page properties", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      showBanner:
+        type: boolean
+        default: true
+      itemCount:
+        type: number
+        default: 3
+      title:
+        type: string
+        default: "Hello"
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.pages["home"].properties).toEqual({
+      showBanner: { type: "boolean", default: true },
+      itemCount: { type: "number", default: 3 },
+      title: { type: "string", default: "Hello" },
+    });
+  });
+
+  test("page without properties has undefined properties", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.pages["home"].properties).toBeUndefined();
+  });
+
+  test("rejects invalid property type", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      color:
+        type: color
+        default: red
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Invalid type.*color/i);
+  });
+
+  test("rejects property with mismatched default type", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      count:
+        type: number
+        default: "not a number"
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/must be a number/i);
+  });
+
+  test("rejects property missing default", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      flag:
+        type: boolean
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Missing default/i);
+  });
+
   test("rejects missing version field", async () => {
     const yaml = `
 global-style: "global.css"