ucode-agent 1.26.1 → 1.27.0

package/skills/ui-ux/DIGEST.md

@@ -0,0 +1,135 @@
+# Interfaces, done properly — the short form
+
+The house style of a language model is a centred column, a purple-to-blue
+gradient, three identical cards, Inter at every size, and a lot of empty space.
+Everyone has seen it a thousand times, and it reads as generated on sight.
+This exists to stop you producing it.
+
+Order: direction, structure, tokens, components, states, motion, accessibility,
+look at it, report. Most bad interfaces are good CSS applied to an undecided
+design.
+
+## 1. Direction — one line each, before any code
+
+- **Job** — what the screen does, in a sentence a user would say.
+- **Mode** — **Operate** (tasks, tools, dashboards: speed and scannability),
+  **Persuade** (landing, pricing: earn attention in one screen), **Read** (docs:
+  measure and rhythm), **Experience** (portfolio: content leads). A dashboard
+  stays Operate however loud the brand is.
+- **Tone** — one word you commit to: clinical, warm, editorial, technical,
+  playful, industrial, calm, dense. "Modern and clean" is not a tone.
+- **The one memorable thing** — a colour, a type move, a texture, one
+  interaction. Exactly one. It is the difference between a design and a theme.
+
+## 2. Structure — hierarchy before decoration
+
+- Decide what the eye lands on first, second, third, and build it with size,
+  weight, colour and position before reaching for a box, a border or a card.
+  Three levels — primary, secondary, muted — is usually all a screen needs.
+- **The primary thing gets disproportionate size.** If a score or a total is
+  the point of the screen, make it three or four times bigger, not 10%.
+- Align to a grid and share edges. Ragged left edges are the single most common
+  reason a page feels amateur. Hold a max width (~1120px apps, 68ch prose).
+- Space **inside** a group must be smaller than space **between** groups.
+- One job per element. Put the primary action at the end of the flow it
+  completes; keep destructive actions away from safe ones.
+
+## 3. Tokens — set once, never use a raw value again
+
+Define in `:root` and use nothing else afterwards: a type scale (xs → hero,
+`clamp()` for the big sizes), one space scale (.25/.5/.75/1/1.5/2/3/4/6/8rem),
+colour, radius, and duration/easing.
+
+- **Neutrals carry a hue.** Flat `#808080` grey is what makes a UI look dead.
+  OKLCH keeps lightness steps perceptually even.
+- Roles, not names: `--bg`, `--surface`, `--surface-2`, `--line`, `--ink`,
+  `--ink-2`, `--ink-3`, `--accent`, `--accent-ink`, `--accent-soft`, plus
+  good/warn/bad. One accent family plus semantics — count the hues.
+- **Depth:** borders and background steps first; shadows only for things that
+  genuinely float (menus, popovers, modals, toasts).
+- **Dark mode:** swap variables, never invert. Surfaces get *lighter* as they
+  rise, text 92–95% lightness rather than pure white, and every accent
+  re-checked for contrast — most need to get lighter.
+- **Tailwind/shadcn:** re-theme the slate default in `globals.css`
+  (`--background`, `--foreground`, `--primary`, `--muted`, `--accent`,
+  `--destructive`, `--border`, `--ring`, `--radius`). Use the components for
+  behaviour, style them to the direction, and do not wrap every region in a
+  `Card`. No arbitrary values (`text-[17px]`) — that is a raw value in another
+  syntax. Icons: lucide, one stroke width, sized to the text beside them.
+
+## 4. Components — every state built in
+
+Every interactive element needs default, hover, focus-visible, active and
+disabled, plus selected, loading and error where they apply. A control with
+only a default state is unfinished, not minimal.
+
+- **Buttons:** verb labels ("Analyze label", not "Submit"), one primary per
+  view, 44px minimum height, loading keeps the width fixed so nothing jumps.
+- **Inputs:** a visible `<label>` always — a placeholder is not a label. Help
+  text below, errors below with an icon, `aria-invalid` and `aria-describedby`
+  wired. Validate on blur, re-validate on input once an error shows, never
+  shout on the first keystroke.
+- **Numbers and metrics:** large, with the scale ("7.4 / 10") and a label
+  saying what it measures. A colour band is never the only signal — pair it
+  with a word.
+- **Lists of findings:** most severe first, each one thing/value/why in a line
+  or two. None? Say so once; do not render an empty section header.
+- **Tables:** numbers right, text left, tabular numerals, sticky header, row
+  hover, a real empty state.
+
+## 5. States are most of the work
+
+An interface that only handles the happy path is a mockup. Every screen and
+every async action needs:
+
+- **Empty / first run** — what this is and the one action that starts it.
+  Never a blank rectangle.
+- **Loading** — skeletons shaped like the real content, or a spinner on the
+  control that was pressed; say what is happening past a second. Never blank
+  the page.
+- **Success** — the result and the next action.
+- **Error** — what failed in plain words, what to do, and the input preserved.
+  "You can fix this" and "we failed" need different words.
+- **Partial** — show what worked.
+- **Edge content** — longest realistic name, zero, missing field, a thousand
+  rows. Design for them rather than discovering them.
+
+Announce async results with `aria-live="polite"`.
+
+## 6. Motion
+
+One authored moment, not effects everywhere. Everything else 120–200ms,
+ease-out, on `transform`, `opacity`, `filter` and colour only — never `width`,
+`height`, `top` or `left`. Readable with motion off; honour
+`prefers-reduced-motion` every time.
+
+## 7. Accessibility and performance — non-negotiable
+
+- Contrast 4.5:1 body text and placeholders, 3:1 large text, icons and borders.
+- Every control keyboard-reachable in visual order, visible focus ring, Escape
+  closes overlays, focus returns to the trigger.
+- `<button>` for actions, `<a href>` for navigation, landmarks, one `<h1>`,
+  headings in order. `aria-label` on icon-only buttons, real `alt` text.
+- 44×44px touch targets, viewport meta, 16px minimum input text on mobile.
+- No layout shift: reserve space for images and async content,
+  `font-display: swap`. In Next.js, `next/image`, server components by default,
+  `"use client"` only where it is interactive.
+
+## 8. Do not
+
+Purple-to-blue gradients, gradient text, glassmorphism as decoration, glowing
+blobs. Three identical feature cards; cards inside cards. The big-number-plus-
+three-stats template. Tracked uppercase eyebrows over every section; 01/02/03
+numbering. Emoji as icons. Monospace as a costume. Centred long paragraphs.
+The default shadcn slate theme. Lorem ipsum, "Feature 1", "John Doe",
+placeholder images — write the real copy, it is part of the design. A modal
+for anything that does not need to interrupt.
+
+## 9. Look at it, then report
+
+Run it, then call `look_at_app` with the URL: it opens the app at 375px and
+1440px and reports console errors, failed requests, overflow, broken images and
+unlabeled controls. Fix what it finds in one pass, then check 375px (no
+horizontal scroll, nothing clipped), 1440px (a max width, no unreadable line
+lengths), the longest realistic content, every state, keyboard only, contrast,
+and the hue count.

package/src/core/context.js

@@ -1,151 +1,164 @@
-/**
- * context.js — what the model knows about the project before it asks.
- *
- * Two things go into the system prompt at the start of every turn:
- *
- *   the project map   every file, and the names each code file exports, so the
- *                     model can go straight to the right file instead of
- *                     spending round trips on list_dir and grep to find it
- *
- *   project memory    UCODE.md — the stack, the commands, the conventions, the
- *                     preferences — written once, remembered every session
- */
-
-import { promises as fs } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { walk } from '../tools/shared.js';
-
-export const MEMORY_FILE = 'UCODE.md';
-export const GLOBAL_MEMORY = path.join(os.homedir(), '.ucode', MEMORY_FILE);
-
-const MAP_FILES = 400;
-const MAP_CHARS = 8_000;
-const MEMORY_CHARS = 6_000;
-const SYMBOL_BYTES = 120_000;
-const SYMBOLS_PER_FILE = 8;
-
-const CODE = /\.(?:[cm]?[jt]sx?|py|go|rs|vue|svelte)$/i;
-
-// Files the map never needs to name.
-const NOISE = /(^|\/)(?:package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb|.*\.map|.*\.min\.[jc]ss?|\.DS_Store|next-env\.d\.ts)$/i;
-
-/** Parsed symbols, kept per file until the file's mtime changes. */
-const symbolCache = new Map();
-
-function symbolsIn(file, text) {
-  const found = [];
-  const add = (name) => { if (name && !found.includes(name)) found.push(name); };
-
-  if (/\.py$/i.test(file)) {
-    for (const m of text.matchAll(/^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm)) add(m[1]);
-  } else if (/\.go$/i.test(file)) {
-    for (const m of text.matchAll(/^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)/gm)) add(m[1]);
-    for (const m of text.matchAll(/^type\s+([A-Z]\w*)/gm)) add(m[1]);
-  } else if (/\.rs$/i.test(file)) {
-    for (const m of text.matchAll(/^pub\s+(?:async\s+)?(?:fn|struct|enum|trait)\s+(\w+)/gm)) add(m[1]);
-  } else {
-    for (const m of text.matchAll(/export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g)) add(m[1]);
-    if (/export\s+default\s+(?:async\s+)?function\s*\(/.test(text)) add('default');
-    for (const m of text.matchAll(/export\s*\{([^}]+)\}/g)) {
-      for (const part of m[1].split(',')) add(part.trim().split(/\s+as\s+/).pop());
-    }
-  }
-
-  return found.slice(0, SYMBOLS_PER_FILE);
-}
-
-async function symbolsFor(root, rel) {
-  const abs = path.join(root, rel);
-  try {
-    const stat = await fs.stat(abs);
-    if (stat.size > SYMBOL_BYTES) return [];
-    const cached = symbolCache.get(abs);
-    if (cached && cached.mtime === stat.mtimeMs) return cached.symbols;
-    const symbols = symbolsIn(rel, await fs.readFile(abs, 'utf8'));
-    symbolCache.set(abs, { mtime: stat.mtimeMs, symbols });
-    return symbols;
-  } catch {
-    return [];
-  }
-}
-
-/**
- * A compact outline of the project: directories, their files, and what each
- * code file exports. Bounded, so a large repository costs a fixed amount of
- * context rather than all of it.
- */
-export async function projectMap(root) {
-  const all = (await walk(root, { limit: MAP_FILES * 3 })).filter((f) => !NOISE.test(f));
-  if (all.length === 0) return '(the folder is empty — this is a new project)';
-
-  const files = all.slice(0, MAP_FILES).sort();
-  const symbols = await Promise.all(
-    files.map((f) => (CODE.test(f) ? symbolsFor(root, f) : Promise.resolve([])))
-  );
-
-  const byDir = new Map();
-  files.forEach((f, i) => {
-    const dir = path.posix.dirname(f);
-    const name = path.posix.basename(f);
-    const line = symbols[i].length ? `${name} · ${symbols[i].join(', ')}` : name;
-    if (!byDir.has(dir)) byDir.set(dir, []);
-    byDir.get(dir).push(line);
-  });
-
-  const out = [];
-  let size = 0;
-  let shown = 0;
-  for (const [dir, entries] of byDir) {
-    const block = [dir === '.' ? './' : `${dir}/`, ...entries.map((e) => `  ${e}`)].join('\n');
-    if (size + block.length > MAP_CHARS) {
-      out.push(`… ${files.length - shown} more files not shown`);
-      break;
-    }
-    out.push(block);
-    size += block.length;
-    shown += entries.length;
-  }
-  if (all.length > MAP_FILES) out.push(`… the project has ${all.length}+ files; the rest are not listed`);
-
-  return out.join('\n');
-}
-
-async function readCapped(file) {
-  try {
-    const text = (await fs.readFile(file, 'utf8')).trim();
-    if (!text) return '';
-    return text.length > MEMORY_CHARS ? `${text.slice(0, MEMORY_CHARS)}\n… (cut)` : text;
-  } catch {
-    return '';
-  }
-}
-
-/**
- * Standing instructions: ~/.ucode/UCODE.md for how you like to work anywhere,
- * then <project>/UCODE.md for this project. The project file comes second so
- * it wins where the two disagree.
- */
-export async function loadMemory(root) {
-  const personal = await readCapped(GLOBAL_MEMORY);
-  const project = await readCapped(path.join(root, MEMORY_FILE));
-  const parts = [];
-  if (personal) parts.push(`From ~/.ucode/${MEMORY_FILE} (applies everywhere):\n${personal}`);
-  if (project) parts.push(`From ./${MEMORY_FILE} (this project):\n${project}`);
-  return parts.join('\n\n');
-}
-
-/** Append one note to this project's UCODE.md, creating it if needed. */
-export async function remember(root, note) {
-  const file = path.join(root, MEMORY_FILE);
-  let existing = '';
-  try {
-    existing = await fs.readFile(file, 'utf8');
-  } catch {
-    existing = `# Project memory\n\nucode reads this at the start of every session in this folder.\n\n`;
-  }
-  const line = `- ${String(note).trim().replace(/\s+/g, ' ')}\n`;
-  const sep = existing.endsWith('\n') ? '' : '\n';
-  await fs.writeFile(file, existing + sep + line, 'utf8');
-  return file;
-}
+/**
+ * context.js — what the model knows about the project before it asks.
+ *
+ * Two things go into the system prompt at the start of every turn:
+ *
+ *   the project map   every file, and the names each code file exports, so the
+ *                     model can go straight to the right file instead of
+ *                     spending round trips on list_dir and grep to find it
+ *
+ *   project memory    UCODE.md — the stack, the commands, the conventions, the
+ *                     preferences — written once, remembered every session
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { walk } from '../tools/shared.js';
+
+export const MEMORY_FILE = 'UCODE.md';
+export const GLOBAL_MEMORY = path.join(os.homedir(), '.ucode', MEMORY_FILE);
+
+const MAP_FILES = 400;
+const MAP_CHARS = 8_000;
+const MEMORY_CHARS = 6_000;
+const SYMBOL_BYTES = 120_000;
+const SYMBOLS_PER_FILE = 8;
+
+const CODE = /\.(?:[cm]?[jt]sx?|py|go|rs|vue|svelte)$/i;
+
+// Files the map never needs to name.
+const NOISE = /(^|\/)(?:package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb|.*\.map|.*\.min\.[jc]ss?|\.DS_Store|next-env\.d\.ts)$/i;
+
+/** Parsed symbols, kept per file until the file's mtime changes. */
+const symbolCache = new Map();
+
+function symbolsIn(file, text) {
+  const found = [];
+  const add = (name) => { if (name && !found.includes(name)) found.push(name); };
+
+  if (/\.py$/i.test(file)) {
+    for (const m of text.matchAll(/^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm)) add(m[1]);
+  } else if (/\.go$/i.test(file)) {
+    for (const m of text.matchAll(/^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)/gm)) add(m[1]);
+    for (const m of text.matchAll(/^type\s+([A-Z]\w*)/gm)) add(m[1]);
+  } else if (/\.rs$/i.test(file)) {
+    for (const m of text.matchAll(/^pub\s+(?:async\s+)?(?:fn|struct|enum|trait)\s+(\w+)/gm)) add(m[1]);
+  } else {
+    for (const m of text.matchAll(/export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g)) add(m[1]);
+    if (/export\s+default\s+(?:async\s+)?function\s*\(/.test(text)) add('default');
+    for (const m of text.matchAll(/export\s*\{([^}]+)\}/g)) {
+      for (const part of m[1].split(',')) add(part.trim().split(/\s+as\s+/).pop());
+    }
+  }
+
+  return found.slice(0, SYMBOLS_PER_FILE);
+}
+
+async function symbolsFor(root, rel) {
+  const abs = path.join(root, rel);
+  try {
+    const stat = await fs.stat(abs);
+    if (stat.size > SYMBOL_BYTES) return [];
+    const cached = symbolCache.get(abs);
+    if (cached && cached.mtime === stat.mtimeMs) return cached.symbols;
+    const symbols = symbolsIn(rel, await fs.readFile(abs, 'utf8'));
+    symbolCache.set(abs, { mtime: stat.mtimeMs, symbols });
+    return symbols;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A compact outline of the project: directories, their files, and what each
+ * code file exports. Bounded, so a large repository costs a fixed amount of
+ * context rather than all of it.
+ */
+export async function projectMap(root) {
+  const all = (await walk(root, { limit: MAP_FILES * 3 })).filter((f) => !NOISE.test(f));
+  if (all.length === 0) return '(the folder is empty — this is a new project)';
+
+  const files = all.slice(0, MAP_FILES).sort();
+  const symbols = await Promise.all(
+    files.map((f) => (CODE.test(f) ? symbolsFor(root, f) : Promise.resolve([])))
+  );
+
+  const byDir = new Map();
+  files.forEach((f, i) => {
+    const dir = path.posix.dirname(f);
+    const name = path.posix.basename(f);
+    const line = symbols[i].length ? `${name} · ${symbols[i].join(', ')}` : name;
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(line);
+  });
+
+  const out = [];
+  let size = 0;
+  let shown = 0;
+  for (const [dir, entries] of byDir) {
+    const block = [dir === '.' ? './' : `${dir}/`, ...entries.map((e) => `  ${e}`)].join('\n');
+    if (size + block.length > MAP_CHARS) {
+      out.push(`… ${files.length - shown} more files not shown`);
+      break;
+    }
+    out.push(block);
+    size += block.length;
+    shown += entries.length;
+  }
+  if (all.length > MAP_FILES) out.push(`… the project has ${all.length}+ files; the rest are not listed`);
+
+  return out.join('\n');
+}
+
+/**
+ * Is there any code here yet?
+ *
+ * Answered from the map that has just been built rather than by walking the
+ * tree a second time. A folder with no code file in it has nothing to look up,
+ * rename or type-check, so the tools that do those things are dead weight in
+ * every request of the turn — and the whole tool list is re-read by the
+ * provider on every step.
+ */
+export function hasCode(map) {
+  return /\.(?:[cm]?[jt]sx?|py|go|rs|vue|svelte)(?![\w-])/i.test(String(map ?? ''));
+}
+
+async function readCapped(file) {
+  try {
+    const text = (await fs.readFile(file, 'utf8')).trim();
+    if (!text) return '';
+    return text.length > MEMORY_CHARS ? `${text.slice(0, MEMORY_CHARS)}\n… (cut)` : text;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Standing instructions: ~/.ucode/UCODE.md for how you like to work anywhere,
+ * then <project>/UCODE.md for this project. The project file comes second so
+ * it wins where the two disagree.
+ */
+export async function loadMemory(root) {
+  const personal = await readCapped(GLOBAL_MEMORY);
+  const project = await readCapped(path.join(root, MEMORY_FILE));
+  const parts = [];
+  if (personal) parts.push(`From ~/.ucode/${MEMORY_FILE} (applies everywhere):\n${personal}`);
+  if (project) parts.push(`From ./${MEMORY_FILE} (this project):\n${project}`);
+  return parts.join('\n\n');
+}
+
+/** Append one note to this project's UCODE.md, creating it if needed. */
+export async function remember(root, note) {
+  const file = path.join(root, MEMORY_FILE);
+  let existing = '';
+  try {
+    existing = await fs.readFile(file, 'utf8');
+  } catch {
+    existing = `# Project memory\n\nucode reads this at the start of every session in this folder.\n\n`;
+  }
+  const line = `- ${String(note).trim().replace(/\s+/g, ' ')}\n`;
+  const sep = existing.endsWith('\n') ? '' : '\n';
+  await fs.writeFile(file, existing + sep + line, 'utf8');
+  return file;
+}