create-coline-app 2.3.0 → 2.5.0

package/src/preview-capture.ts

@@ -0,0 +1,101 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { chromium } from "playwright";
+
+/** Mechanical browser checks supplement, never replace, looking at the images. */
+export async function capturePreview(origin: string, directory: string): Promise<number> {
+  await mkdir(directory, { recursive: true });
+  const browser = await chromium.launch().catch((cause: unknown) => {
+    throw new Error(
+      `Chromium could not start. Run npx playwright install chromium. ${String(cause)}`,
+    );
+  });
+  const results: Array<{ name: string; failures: string[] }> = [];
+  try {
+    for (const theme of ["light", "dark"]) {
+      for (const viewport of [
+        { name: "desktop", width: 1280, height: 800 },
+        { name: "mobile", width: 390, height: 844 },
+      ]) {
+        for (const state of ["ready", "empty", "error", "loading", "denied"]) {
+          const name = `${theme}-${viewport.name}-${state}`;
+          const failures: string[] = [];
+          const page = await browser.newPage({ viewport });
+          page.on("pageerror", (error) => failures.push(error.message));
+          page.on("console", (message) => {
+            if (message.type() === "error") failures.push(message.text());
+          });
+          try {
+            await page.goto(`${origin}/?theme=${theme}&state=${state}`);
+            await page.waitForFunction(
+              () =>
+                document.querySelector('iframe[data-ready="true"]') ||
+                document.body.dataset.previewError === "true",
+              undefined,
+              { timeout: 30_000 },
+            );
+            if (await page.locator("body").getAttribute("data-preview-error")) {
+              throw new Error(await page.locator("#notice").innerText());
+            }
+            // Let capabilities settle and fonts/layout paint; loading is deliberately unresolved.
+            await page.waitForTimeout(350);
+            const frame = page.frames().find((candidate) => candidate.url().includes("/app?"));
+            if (!frame) throw new Error("App iframe did not load.");
+            failures.push(
+              ...(await frame.evaluate(() => {
+                const issues: string[] = [];
+                if (document.documentElement.scrollWidth > document.documentElement.clientWidth + 1)
+                  issues.push("Page overflows horizontally");
+                const controls = document.querySelectorAll<HTMLInputElement>(
+                  "input:not([type=hidden]),textarea,select",
+                );
+                for (const control of controls) {
+                  if (
+                    !control.labels?.length &&
+                    !control.getAttribute("aria-label") &&
+                    !control.getAttribute("aria-labelledby")
+                  )
+                    issues.push(`Unlabelled ${control.tagName.toLowerCase()}`);
+                }
+                return issues;
+              })),
+            );
+            const contentHeight = await frame.evaluate(() => document.documentElement.scrollHeight);
+            // Include content below the fold inside the iframe, especially stacked details.
+            await page.locator("iframe").evaluate((element, height) => {
+              element.style.flex = "none";
+              element.style.height = `${Math.min(height, 12000)}px`;
+              document.body.style.height = "auto";
+            }, contentHeight);
+            await page.screenshot({ path: join(directory, `${name}.png`), fullPage: true });
+          } catch (error) {
+            failures.push(String(error));
+          } finally {
+            await page.close();
+          }
+          results.push({ name, failures });
+        }
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  await writeFile(
+    join(directory, "report.json"),
+    JSON.stringify(
+      {
+        origin,
+        checkedAt: new Date().toISOString(),
+        note: "Simulated data. Checks cover browser errors, page overflow, and form labels. Inspect screenshots and test interactions; this is not a visual quality or full accessibility certification.",
+        results,
+      },
+      null,
+      2,
+    ),
+  );
+  const failed = results.filter((result) => result.failures.length);
+  console.log(
+    `${results.length} preview captures; ${failed.length} with issues. ${join(directory, "report.json")}`,
+  );
+  return failed.length ? 1 : 0;
+}

package/src/preview.ts

@@ -0,0 +1,189 @@
+import { createServer } from "node:http";
+import { stat, mkdir, writeFile } from "node:fs/promises";
+import { watch } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+import { buildClientSource } from "./client-build";
+import { argValue } from "./args";
+
+const sourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "assets");
+const scriptSafe = (value: string) => value.replace(/<\/script/gi, "<\\/script");
+const hostHtml = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Coline app preview</title><style>*{box-sizing:border-box}body{display:flex;flex-direction:column;height:100dvh;margin:0;font:12px system-ui;background:#f6f6f6;color:#222}header{flex-shrink:0;display:flex;align-items:center;gap:14px;flex-wrap:wrap;padding:10px 14px;border-bottom:1px solid #ddd}label{display:flex;gap:5px;align-items:center}select{font:inherit;padding:3px}iframe{display:block;border:0;width:100%;flex:1;min-height:0;background:white}output{color:#666}strong{font-weight:600}</style></head><body><header><strong>Local preview · simulated data</strong><label>Theme<select data-param="theme"><option value="light">Light</option><option value="dark">Dark</option></select></label><label>State<select data-param="state"><option value="ready">Ready</option><option value="empty">Empty</option><option value="error">Error</option><option value="loading">Loading</option><option value="denied">Permission denied</option></select></label><output id="notice">Edits reset on reload. No credentials or uploads.</output></header><iframe title="App preview" sandbox="allow-scripts allow-forms"></iframe><script type="module">import("/host.js").catch(error => { document.querySelector("#notice").textContent = "Preview could not start. Run npm run check and inspect the browser error: " + error.message; document.body.dataset.previewError = "true"; console.error(error); });</script></body></html>`;
+
+export async function startPreview(dir: string, options: { port?: number; pattern?: string } = {}) {
+  const appDir = resolve(dir);
+  const pattern = options.pattern ?? "app";
+  if (!["app", "triage", "board", "settings"].includes(pattern))
+    throw new Error("Pattern must be app, triage, board, or settings.");
+  let revision = 0;
+  let cached: Promise<{ host: string; client: string }> | null = null;
+  const watcher = watch(appDir, { recursive: true }, (_event, name) => {
+    if (
+      !name ||
+      name
+        .split(/[\\/]/)
+        .some((part) => ["node_modules", ".git", ".coline", ".cache", "dist"].includes(part))
+    )
+      return;
+    revision++;
+    cached = null;
+  });
+  async function bundles() {
+    if (cached) return cached;
+    cached = (async () => {
+      let entry = "main.tsx";
+      if (pattern !== "app") {
+        await mkdir(join(appDir, ".coline"), { recursive: true });
+        entry = `.coline/preview-${pattern}.tsx`;
+        await writeFile(
+          join(appDir, entry),
+          `import * as React from "react"; import {createRoot} from "react-dom/client"; import {ColineAppProvider} from "@colineapp/ui"; import "@colineapp/ui/styles.css"; import "../app.css"; import {Example} from "../examples/${pattern}"; createRoot(document.getElementById("root")!).render(<ColineAppProvider><Example state={new URLSearchParams(location.search).get("state") ?? "ready"}/></ColineAppProvider>);`,
+        );
+      }
+      const seedPath = join(appDir, "preview.seed.ts");
+      const hasSeed = await stat(seedPath).then(
+        () => true,
+        () => false,
+      );
+      const host = await build({
+        entryPoints: [join(sourceRoot, "preview-host.ts")],
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "browser",
+        target: "es2022",
+        jsx: "automatic",
+        logLevel: "silent",
+        define: { "process.env.NODE_ENV": '"production"' },
+        plugins: [
+          {
+            name: "preview-app",
+            setup(builder) {
+              builder.onResolve({ filter: /^coline-preview-app$/ }, () => ({
+                path: join(appDir, "app.config.ts"),
+              }));
+              builder.onResolve({ filter: /^coline-preview-seed$/ }, () =>
+                hasSeed ? { path: seedPath } : { path: "seed", namespace: "preview" },
+              );
+              builder.onLoad({ filter: /.*/, namespace: "preview" }, () => ({
+                contents: "export async function seed() {}",
+                loader: "js",
+              }));
+              builder.onResolve({ filter: /^@colineapp\// }, (args) =>
+                args.pluginData?.resolved
+                  ? undefined
+                  : builder
+                      .resolve(args.path, {
+                        kind: "import-statement",
+                        resolveDir: appDir,
+                        pluginData: { resolved: true },
+                      })
+                      .then((result) => ({ path: result.path, errors: result.errors })),
+              );
+            },
+          },
+        ],
+      });
+      const client = await buildClientSource(appDir, entry);
+      return { host: host.outputFiles[0]!.text, client: client.files[client.entry]! };
+    })().catch((error) => {
+      cached = null;
+      throw error;
+    });
+    return cached;
+  }
+  const server = createServer(async (request, response) => {
+    const host = request.headers.host ?? "";
+    if (!/^127\.0\.0\.1:\d+$/.test(host) && !/^localhost:\d+$/.test(host)) {
+      response.writeHead(403);
+      response.end("Local preview only");
+      return;
+    }
+    const url = new URL(request.url ?? "/", `http://${host}`);
+    response.setHeader("Cache-Control", "no-store");
+    try {
+      if (url.pathname === "/revision") {
+        response.end(String(revision));
+        return;
+      }
+      if (url.pathname === "/") {
+        response.setHeader("Content-Type", "text/html");
+        response.end(hostHtml);
+        return;
+      }
+      if (url.pathname === "/host.js") {
+        response.setHeader("Content-Type", "text/javascript");
+        response.end((await bundles()).host);
+        return;
+      }
+      if (url.pathname === "/app") {
+        response.setHeader("Content-Type", "text/html");
+        response.setHeader(
+          "Content-Security-Policy",
+          "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none'; form-action 'none'; base-uri 'none'",
+        );
+        response.end(
+          `<!doctype html><html><head><meta name="viewport" content="width=device-width,initial-scale=1"></head><body><div id="root"></div><script>${scriptSafe((await bundles()).client)}</script></body></html>`,
+        );
+        return;
+      }
+      response.writeHead(404);
+      response.end("Not found");
+    } catch (error) {
+      response.writeHead(500, { "Content-Type": "text/plain" });
+      response.end(error instanceof Error ? error.message : String(error));
+    }
+  });
+  try {
+    await new Promise<void>((resolveReady, reject) => {
+      server.once("error", reject);
+      server.listen(options.port ?? 0, "127.0.0.1", resolveReady);
+    });
+  } catch (error) {
+    watcher.close();
+    throw error;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Preview failed to bind.");
+  return {
+    origin: `http://127.0.0.1:${address.port}`,
+    server,
+    close: async () => {
+      watcher.close();
+      server.closeAllConnections();
+      await new Promise<void>((resolveClose) => server.close(() => resolveClose()));
+    },
+  };
+}
+
+export async function runPreview(argv: string[]) {
+  const port = argValue(argv, "--port");
+  if (port && (!/^\d+$/.test(port) || Number(port) > 65535))
+    throw new Error("Port must be 0–65535.");
+  const preview = await startPreview(resolve(argValue(argv, "--dir") ?? "."), {
+    port: port ? Number(port) : 0,
+    pattern: argValue(argv, "--pattern") ?? "app",
+  });
+  console.log(
+    `Local preview: ${preview.origin}\nSimulated data. No credentials, uploads, or production writes. Reloading resets fixtures.`,
+  );
+  const screenshots = argValue(argv, "--screenshots");
+  if (screenshots) {
+    try {
+      const { capturePreview } = await import("./preview-capture");
+      return await capturePreview(preview.origin, resolve(screenshots));
+    } finally {
+      await preview.close();
+    }
+  }
+  return new Promise<number>((resolveExit) => {
+    const stop = () => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      void preview.close().then(() => resolveExit(0));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}

package/src/push.ts

@@ -1,6 +1,7 @@
+import { buildClientSource } from "./client-build";
 import { build } from "esbuild";
-import { readFile, readdir, stat } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tmpdir } from "node:os";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
@@ -29,9 +30,6 @@ export interface PushResult {
   versionId: string;
 }
 
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".css"]);
-const IGNORED_DIRECTORIES = new Set(["node_modules", "dist", ".git", ".cache", ".coline"]);
-
 export function resolvePushConfig(argv: readonly string[]): PushConfig {
   const apiKey = argValue(argv, "--api-key") ?? process.env.COLINE_API_KEY ?? null;
   if (!apiKey) {
@@ -53,7 +51,7 @@ export function resolvePushConfig(argv: readonly string[]): PushConfig {
   };
 }
 
-async function buildLogicBundle(appDir: string): Promise<string> {
+export async function buildLogicBundle(appDir: string): Promise<string> {
   const result = await build({
     entryPoints: [join(appDir, "app.config.ts")],
     bundle: true,
@@ -78,7 +76,7 @@ async function buildLogicBundle(appDir: string): Promise<string> {
  * (plan §6.2 two-artifact model). The app's SDK version travels inside
  * the bundle, so the CLI never needs to agree with it.
  */
-async function extractManifest(logicBundleJs: string): Promise<ManifestSummary> {
+export async function extractManifest(logicBundleJs: string): Promise<ManifestSummary> {
   const dir = await mkdtemp(join(tmpdir(), "coline-app-"));
   const bundlePath = join(dir, "app.config.mjs");
   try {
@@ -88,9 +86,7 @@ async function extractManifest(logicBundleJs: string): Promise<ManifestSummary>
     };
     const manifest = imported.default?.manifest;
     if (!manifest || typeof manifest !== "object") {
-      throw new Error(
-        "app.config.ts must default-export defineApp(...); no manifest was found.",
-      );
+      throw new Error("app.config.ts must default-export defineApp(...); no manifest was found.");
     }
     return JSON.parse(JSON.stringify(manifest)) as ManifestSummary;
   } finally {
@@ -108,39 +104,6 @@ function manifestHasReactSurfaces(manifest: ManifestSummary): boolean {
   return tiers.includes("react");
 }
 
-async function collectClientSource(
-  appDir: string,
-): Promise<{ entry: string; files: Record<string, string> } | null> {
-  const entry = "main.tsx";
-  const entryExists = await stat(join(appDir, entry)).then(
-    (item) => item.isFile(),
-    () => false,
-  );
-  if (!entryExists) {
-    return null;
-  }
-
-  const files: Record<string, string> = {};
-  async function walk(dir: string): Promise<void> {
-    for (const item of await readdir(dir, { withFileTypes: true })) {
-      if (item.isDirectory()) {
-        if (!IGNORED_DIRECTORIES.has(item.name)) {
-          await walk(join(dir, item.name));
-        }
-        continue;
-      }
-      const extension = item.name.slice(item.name.lastIndexOf("."));
-      if (!SOURCE_EXTENSIONS.has(extension) || item.name.endsWith(".test.ts")) {
-        continue;
-      }
-      const filePath = join(dir, item.name);
-      files[relative(appDir, filePath)] = await readFile(filePath, "utf8");
-    }
-  }
-  await walk(appDir);
-  return { entry, files };
-}
-
 async function resolveVersion(appDir: string, explicit: string | null): Promise<string> {
   if (explicit) {
     return explicit;
@@ -160,13 +123,11 @@ export async function pushAppVersion(config: PushConfig): Promise<PushResult> {
   const manifest = await extractManifest(logicBundleJs);
   const version = await resolveVersion(config.dir, config.version);
   const clientSource = manifestHasReactSurfaces(manifest)
-    ? await collectClientSource(config.dir)
+    ? await buildClientSource(config.dir)
     : null;
 
   if (manifestHasReactSurfaces(manifest) && !clientSource) {
-    throw new Error(
-      "The manifest declares react surfaces but no main.tsx client entry was found.",
-    );
+    throw new Error("The manifest declares react surfaces but no main.tsx client entry was found.");
   }
 
   const response = await fetch(

package/src/scaffold.ts

@@ -62,6 +62,7 @@ export async function runCreate(argv: string[]): Promise<number> {
   await rename(shippedGitignore, join(targetDir, ".gitignore")).catch(() => undefined);
 
   for (const relative of await walkFiles(targetDir)) {
+    if (/\.(png|jpg|jpeg|webp|gif|woff2?)$/i.test(relative)) continue;
     const filePath = join(targetDir, relative);
     const content = await readFile(filePath, "utf8");
     if (content.includes("__APP_KEY__") || content.includes("__APP_NAME__")) {
@@ -79,6 +80,11 @@ Next steps:
   cd ${target}
   npm install
   npm test
+  npm run check
+  npm run preview
+
+Preview uses disposable local data, with no credentials required.
+Read AGENTS.md for design examples and the bundled experimental UI skills.
 
 Then create a workspace API key with the apps.write scope in
 Workspace Settings → API, and push your first version:

package/templates/backendless/.agents/skills/coline-app-development/SKILL.md

@@ -1,70 +1,36 @@
 ---
 name: coline-app-development
-description: Build and debug a Coline App using the public SDK, hosted capabilities, tree UI, and sandboxed React UI.
+description: Build and debug a Coline App using its public SDK, capability permissions, hosted logic, sandboxed React, and local preview. Use for changes to app data, tools, surfaces, or integration.
 ---
 
 # Coline App development
 
-Use this skill for any task that changes a generated Coline App.
-
-## Start from the shipped contract
-
-Read the repository `AGENTS.md`, `app.config.ts`, `main.tsx`, `app.test.ts`,
-and `package.json`. The generated project is intentionally self-contained.
-Do not inspect `/Users/radin/coline-app`, private worktrees, first-party apps,
-or product internals to learn an app-authoring API. Use the installed package
-types, README files, and this skill.
-
-The project has two halves:
-
-- `app.config.ts` is the hosted logic bundle: manifest, permissions, tools,
-  file types, tree handlers, and capability calls.
-- `main.tsx` is the React client entry. The starter includes `@colineapp/ui`,
-  React, ReactDOM, and the CSS export; do not add a second bridge or fetch
-  data from a Coline API route.
-
-## Choose the right surface
-
-- Use `ui.*` tree nodes for previews, inline surfaces, mobile fallbacks, and
-  simple Kairo cards.
-- Use a React surface when the app needs local interaction, filtering, forms,
-  or an editor. Declare `{ tier: "react", entry: "main.tsx" }` and keep the
-  root wrapped in `<ColineAppProvider>`.
-- Use `useColine()` for capability calls and `useColineQuery()` for a bounded
-  loading/error/refetch loop. Never use `fetch`, localStorage, cookies, or
-  credentials in the sandbox.
-
-## Public SDK rules
-
-- Import logic from `@colineapp/sdk/v2` and tests from `@colineapp/sdk/testing`.
-- Prefix every tool name with the app key.
-- Validate inputs with `zod/v4` and declare honest effects (`read`, `write`,
-  `destructive`, or `external`).
-- Ask for the minimum permissions. Capability calls still require both the
-  declared permission and the tool effect ceiling.
-- Collections are typed record envelopes. `where` is exact-match on top-level
-  fields; query bounded pages and filter more complex predicates in memory.
-- Use `ui.*` for hosted handlers. Chat tool cards must stay within the
-  validated chat subset and remain small.
-
-## UI rules
-
-- Import components from `@colineapp/ui` and `@colineapp/ui/styles.css`.
-- Use the host theme tokens (`bg-background`, `text-foreground`,
-  `text-muted-foreground`, and related tokens); dark mode is supplied by the
-  host.
-- Render explicit loading, empty, and error states.
-- Keep components accessible and use the provided controls before writing
-  custom primitives.
-- Do not add a state library or network client for the first implementation.
-
-## Verify before pushing
-
-```sh
-npm run typecheck
-npm test
-```
-
-Then push with `npx coline-app dev --internal` or `npx coline-app push --internal`
-when the user has supplied `COLINE_BASE_URL` and `COLINE_API_KEY`. The local
-test workspace is the first proof; the hosted app is the second.
+Read `AGENTS.md`, `app.config.ts`, and the installed package declarations.
+Do not inspect private Coline repositories or invent capability signatures.
+
+1. Keep logic in `app.config.ts` and the React entry inside `ColineAppProvider`.
+   Import `@colineapp/ui/styles.css` followed by `./app.css`.
+2. Choose persistence deliberately: files for user documents; app collections
+   for structured records. Use `useLiveCollection` for collaborative record views,
+   `useColineQuery` for bounded other reads, and React state for transient controls.
+3. Declare the minimum permission and honest tool effect. Validate tool input
+   with `zod/v4`; tools use the app-key prefix. Share actions through
+   `coline.tools.invoke` rather than reimplementing a tool in the UI.
+4. Save files with `expectedVersion`. Catch rejected mutations and preserve
+   unsaved input. Permission-denied and conflict errors need different recovery;
+   never turn a conflict into a silent overwrite.
+5. Keep network access behind `coline.net.fetch` and the manifest allowlist.
+   No direct fetch, credentials, localStorage, or private API routes in the iframe.
+6. Test logic with `createTestWorkspace(app)`. Use explicit members and
+   `clientAs(userId)` for actor cases. Check installed types for query operators,
+   pagination, ACLs, and capability argument shapes.
+7. Run `npm test`, `npm run check`, and local preview. For UI work, also follow
+   the adjacent design and review skills. Only use upload commands when in scope.
+
+Preview is an in-memory workspace, not a hosted permission/performance test.
+Its native prompt-based pickers are intentionally simple. External service
+calls need explicit test handlers in logic tests; they are not real integrations.
+
+When replacing example React state with persistent records, read
+[the live-record recipe](references/live-records.md). It covers envelope data,
+nullable mutation results, draft preservation, pending states, and fixture seeding.

package/templates/backendless/.agents/skills/coline-app-development/references/live-records.md

@@ -0,0 +1,53 @@
+# Connect a screen to saved records
+
+The manifest needs `storage.app`. Add `realtime.subscribe` for live hints.
+In `ColineAppProvider`, use the public hook:
+
+```tsx
+type Story = { title: string; stage: string; description: string };
+const stories = useLiveCollection<Story>("stories", { limit: 100 });
+// Each envelope has id, data, version, and access. Render record.data.title.
+const visible = stories.records.filter(record => record.data.stage === stage);
+
+async function create() {
+  setError(null);
+  setSaving(true);
+  try {
+    const record = await stories.insert(
+      { title: title.trim(), stage: "Exploring", description },
+      { workspace: "write", readers: [], writers: [] },
+    );
+    if (!record) throw new Error("The story was not saved. Your draft is still here.");
+    setTitle(""); // Clear drafts only after success.
+  } catch (cause) {
+    setError(cause instanceof Error ? cause.message : String(cause));
+  } finally { setSaving(false); }
+}
+async function move(id: string, stage: string) {
+  try {
+    if (!await stories.update(id, { stage })) throw new Error("The story is no longer available.");
+  } catch (cause) {
+    setError(cause instanceof Error ? cause.message : String(cause));
+  }
+}
+```
+
+`title`, `description`, `saving`, and `error` above are ordinary React form state.
+Keep the draft on failure; don't blindly retry a conflict. `stories.pending` is
+a count; `stories.status === "loading"` is initial loading. Show
+`stories.error.message` and offer `stories.refresh()` for read recovery.
+A bounded view's search only covers loaded records. Disclose `nextCursor` or
+implement pagination rather than claiming the entire collection was searched.
+
+Seed in `preview.seed.ts` with the direct capability client. Its options shape
+differs from the hook's second argument:
+
+```ts
+await workspace.client().storage.collection<Story>("stories").insert(
+  { title: "A calmer workday", stage: "Exploring", description: "A useful story." },
+  { access: { workspace: "write", readers: [], writers: [] } },
+);
+```
+
+Preview fixtures reset on reload. Real hosted collections persist; a local
+preview passing does not prove hosted persistence or multi-user permissions.

package/templates/backendless/.agents/skills/coline-ui-design/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: coline-ui-design
+description: Design or improve a Coline App interface using working screen examples, host theme tokens, responsive patterns, and realistic states. Use when building pages, forms, boards, queues, editors, or improving unattractive UI.
+---
+
+# Coline UI design — experimental
+
+Make the user's main task obvious before adding decoration. Preserve an existing
+product design when present. This is a starting path, not a mandatory visual style.
+
+## Choose one useful starting point
+
+Write three short decisions: who uses this, what they do most, and what belongs
+on the first screen. Then inspect the nearest working example:
+
+| Main job | Start from | Preview command |
+| --- | --- | --- |
+| Review many items and act on one | `examples/triage.tsx` | `npm run preview -- --pattern triage` |
+| Move work through stages | `examples/board.tsx` | `npm run preview -- --pattern board` |
+| Configure preferences | `examples/settings.tsx` | `npm run preview -- --pattern settings` |
+| Read/write documents | `main.tsx` | `npm run preview` |
+
+Paths are relative to the app root. Reference screenshots live in this skill's
+`assets/` directory. View them if your model supports images. The source examples
+are the complete reference for text-only agents.
+
+For a small context budget: copy ONE example, keep its layout and state handling,
+change the domain objects and copy, then connect SDK data. For a distinctive
+product: compose the exported patterns or plain CSS deliberately. Do not force
+an editorial website, calendar, map, or canvas into a queue just because it exists.
+
+## Compose the screen
+
+- `AppPage`: title, short description, one main action; wide or reading width.
+- `PageToolbar`: search/filter controls near the content they change.
+- `RecordTable` + `SplitView` + `DetailPanel`: scan, select, inspect, act.
+- `Board` + `BoardColumn` + `BoardCard`: visible stages; explicit move controls
+  work with keyboard and touch. These components do not implement drag and drop.
+- `SettingsSection`: separate explanation from labelled fields.
+- `EmptyState`, `AppLoadingState`, `AppErrorState`: useful non-happy paths.
+- `StatusBadge`: restrained semantic status with text, never color alone.
+
+See installed `@colineapp/ui` declarations for props. Keep tables semantic; the
+first cell becomes a button when `onOpen` is supplied, so don't nest controls there.
+Move focus to opened details and return it when closing. When a move remounts a
+record in another column, restore focus to that record after rendering (and after
+pending controls are enabled). Keep horizontal scrolling
+inside boards/tables, not on the whole page.
+
+Use host tokens and exported controls. `app.css` compiles Tailwind automatically;
+write complete class names or a fixed map, not dynamically assembled utilities.
+Choose a compact consistent spacing scale, readable line lengths, and muted
+secondary text. Use color for meaning. Use one clear control for each action: a stage selector
+does not also need previous/next arrows on every card. Keep controls compact
+without shrinking touch targets or letting field labels stretch adjacent buttons.
+Don't add stat cards, giant greetings,
+gradients, decorative charts, or sidebars unless the user's job calls for them.
+
+## Make it real
+
+Replace example state with capabilities before calling the app complete. Seed
+believable names, long titles, and varied statuses in `preview.seed.ts`. Every
+visible action must work; preserve input on errors and show saving/disabled
+states. No pretend search, dead menus, invented metrics, or static success toasts.
+
+Run the adjacent `coline-ui-review` skill before finishing. If your model cannot
+inspect images, say so; mechanical checks alone do not establish visual quality.