@hienlh/ppm 0.22.10 → 0.23.0

package/src/shared/design-canvas-check.ts

@@ -0,0 +1,148 @@
+/**
+ * The canvas self-check's report: what the bridge measured in the live design document,
+ * plus what the parent adds (runtime issues the bridge already reported, the device frame).
+ *
+ * Everything in a report was produced inside the design frame, where the page's own scripts
+ * run, so it is untrusted: {@link parseLayoutCheckReport} and {@link parseCanvasCheckReport}
+ * cap every field and are run by the parent (frame message) and again by the server (POST
+ * body). The text built from a report for an agent fences it as page content.
+ */
+
+import { DESIGN_GEN_RE } from "./design-types";
+
+export const CHECK_KINDS = [
+  "implicit-grid", "runtime", "page-overflow", "offscreen", "clipped", "collapsed", "overlap",
+] as const;
+export type CanvasCheckKind = (typeof CHECK_KINDS)[number];
+
+export const MAX_CHECK_FINDINGS = 30;
+export const MAX_FINDING_CHARS = 300;
+export const MAX_ELEMENT_CHARS = 200;
+/** The decoded image may be at most this big; the data URL is base64, a third larger. */
+export const MAX_SCREENSHOT_BYTES = 400 * 1024;
+export const MAX_SCREENSHOT_WIDTH = 1280;
+/** Shape of a check request id: minted by whoever asks, echoed by whoever answers. */
+export const CHECK_REQUEST_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+
+export interface CanvasCheckFinding {
+  kind: CanvasCheckKind;
+  message: string;
+  /** The element it is about: tag, id/classes, `data-ppm-id`, a little text. */
+  element?: string;
+}
+
+export interface CanvasCheckScreenshot {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+
+/** What the bridge measures. */
+export interface LayoutCheckReport {
+  viewport: { width: number; height: number };
+  page: { width: number; height: number };
+  findings: CanvasCheckFinding[];
+  /** Findings per kind before the cap, so a truncated list still says how much was cut. */
+  counts: Partial<Record<CanvasCheckKind, number>>;
+  screenshot?: CanvasCheckScreenshot;
+  /** Why there is no screenshot, or what it may get wrong. */
+  screenshotNote?: string;
+}
+
+/** What the parent sends on: the bridge's report plus the document and frame it came from. */
+export interface CanvasCheckReport extends LayoutCheckReport {
+  file: string;
+  gen: string | null;
+  /** The device frame the canvas was showing (desktop, tablet, phone, slide). */
+  frame: string;
+}
+
+type Raw = Record<string, unknown>;
+const isObj = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+const dim = (v: unknown, max = 100_000): number | null =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= max ? Math.round(v) : null;
+const text = (v: unknown, max: number): string | null => (typeof v === "string" ? v.slice(0, max) : null);
+const kindOf = (v: unknown): CanvasCheckKind | undefined => CHECK_KINDS.find((k) => k === v);
+const DATA_URL_RE = /^data:image\/(?:jpeg|png);base64,[A-Za-z0-9+/]+={0,2}$/;
+const MAX_DATA_URL_CHARS = Math.ceil(MAX_SCREENSHOT_BYTES / 3) * 4 + 32;
+
+function parseSize(v: unknown): { width: number; height: number } | null {
+  if (!isObj(v)) return null;
+  const width = dim(v.width), height = dim(v.height);
+  return width === null || height === null ? null : { width, height };
+}
+
+function parseScreenshot(v: unknown): CanvasCheckScreenshot | undefined {
+  if (!isObj(v) || typeof v.dataUrl !== "string") return undefined;
+  if (v.dataUrl.length > MAX_DATA_URL_CHARS || !DATA_URL_RE.test(v.dataUrl)) return undefined;
+  const width = dim(v.width, 4096), height = dim(v.height, 8192);
+  if (!width || !height) return undefined;
+  return { dataUrl: v.dataUrl, width, height };
+}
+
+/** A validated bridge report, or null. Findings beyond the cap and unknown kinds are dropped. */
+export function parseLayoutCheckReport(raw: unknown): LayoutCheckReport | null {
+  if (!isObj(raw) || !Array.isArray(raw.findings)) return null;
+  const viewport = parseSize(raw.viewport), page = parseSize(raw.page);
+  if (!viewport || !page) return null;
+  const findings: CanvasCheckFinding[] = [];
+  for (const f of raw.findings.slice(0, MAX_CHECK_FINDINGS)) {
+    if (!isObj(f)) continue;
+    const kind = kindOf(f.kind), message = text(f.message, MAX_FINDING_CHARS);
+    if (!kind || !message) continue;
+    const element = text(f.element, MAX_ELEMENT_CHARS);
+    findings.push(element ? { kind, message, element } : { kind, message });
+  }
+  const counts: Partial<Record<CanvasCheckKind, number>> = {};
+  if (isObj(raw.counts)) {
+    for (const kind of CHECK_KINDS) {
+      const n = dim(raw.counts[kind], 1_000_000);
+      if (n) counts[kind] = n;
+    }
+  }
+  const report: LayoutCheckReport = { viewport, page, findings, counts };
+  const screenshot = parseScreenshot(raw.screenshot);
+  if (screenshot) report.screenshot = screenshot;
+  const note = text(raw.screenshotNote, MAX_FINDING_CHARS);
+  if (note) report.screenshotNote = note;
+  return report;
+}
+
+export function parseCanvasCheckReport(raw: unknown): CanvasCheckReport | null {
+  const base = parseLayoutCheckReport(raw);
+  if (!base || !isObj(raw)) return null;
+  const file = text(raw.file, 512) ?? "";
+  const gen = typeof raw.gen === "string" && DESIGN_GEN_RE.test(raw.gen) ? raw.gen : null;
+  const frame = text(raw.frame, 40) ?? "";
+  return { ...base, file, gen, frame };
+}
+
+export interface RuntimeIssueInput {
+  kind: string;
+  message: string;
+  source?: string;
+  line?: number;
+}
+
+/**
+ * Fold the runtime issues the parent collected for this load into a bridge report, in the
+ * order {@link CHECK_KINDS} lists, keeping the overall cap.
+ */
+export function withRuntimeIssues(report: LayoutCheckReport, issues: readonly RuntimeIssueInput[]): LayoutCheckReport {
+  const runtime: CanvasCheckFinding[] = issues.map((issue) => {
+    const where = issue.source ? ` (${issue.source}${issue.line ? `:${issue.line}` : ""})` : "";
+    return { kind: "runtime", message: `${issue.kind}: ${issue.message}${where}`.slice(0, MAX_FINDING_CHARS) };
+  });
+  const all = [...report.findings, ...runtime];
+  const rank = (f: CanvasCheckFinding) => CHECK_KINDS.indexOf(f.kind);
+  const sorted = all.map((f, i) => ({ f, i })).sort((a, b) => rank(a.f) - rank(b.f) || a.i - b.i).map((x) => x.f);
+  const counts = { ...report.counts };
+  if (runtime.length) counts.runtime = (counts.runtime ?? 0) + runtime.length;
+  return { ...report, findings: sorted.slice(0, MAX_CHECK_FINDINGS), counts };
+}
+
+/** Findings the report counted, including those cut by the cap. */
+export function totalFindings(report: Pick<LayoutCheckReport, "counts" | "findings">): number {
+  const counted = Object.values(report.counts).reduce((sum, n) => sum + (n ?? 0), 0);
+  return Math.max(counted, report.findings.length);
+}

package/src/shared/design-cdn-hosts.ts

@@ -0,0 +1,17 @@
+/**
+ * Hosts a design canvas may load scripts, styles, fonts and images from. The canvas CSP
+ * allows exactly these (over https) and the design instructions list the same array, so the
+ * agent is told up front instead of discovering a blocked host as a blank preview.
+ *
+ * `cdn.jsdelivr.net` and `unpkg.com` proxy all of npm (jsdelivr also GitHub), so anything
+ * published there can run in the sandbox. That is accepted: the frame has an opaque origin,
+ * no PPM token, and `connect-src` limited to its own design, so it can render but not phone
+ * home through `fetch`.
+ */
+export const DESIGN_CDN_HOSTS = [
+  "cdn.tailwindcss.com",
+  "cdn.jsdelivr.net",
+  "unpkg.com",
+  "fonts.googleapis.com",
+  "fonts.gstatic.com",
+] as const;

package/src/shared/design-comment-types.ts

@@ -0,0 +1,111 @@
+import { DESIGN_GEN_RE } from "./design-types";
+
+/**
+ * Pinned element comments: what is stored in `designs/<slug>/.design/comments.json` and
+ * what travels between the canvas, the server and the prompt builder.
+ *
+ * An anchor names an element two ways. `ppmId` (its start-tag offset) is exact, but only
+ * for the `gen` it was read under: after the AI edits text above the element every later
+ * offset moves, and an old id can name a *different* element. The text quote (the
+ * element's own text plus a little of what precedes and follows it) survives that, and
+ * `cssPath` breaks ties. See `bridge-anchor-resolve.ts`.
+ *
+ * Everything in an anchor may have come from the page, whose own scripts can say anything,
+ * so {@link parseCommentAnchor} caps and shape-checks every field wherever one enters.
+ */
+
+export interface CommentQuote {
+  exact: string;
+  prefix: string;
+  suffix: string;
+}
+
+export interface CommentAnchor {
+  /** The HTML file, relative to the design folder. */
+  file: string;
+  ppmId: number | null;
+  gen: string | null;
+  tag: string;
+  cssPath: string;
+  quote: CommentQuote;
+}
+
+export interface DesignComment {
+  id: string;
+  file: string;
+  anchor: CommentAnchor;
+  body: string;
+  /**
+   * The element's markup, sliced by the server out of the source file when the comment was
+   * made (or last re-anchored). Null when the page's `gen` no longer matched the file, or
+   * the element was created by a script. Never the markup the page reported.
+   */
+  snippet: string | null;
+  createdAt: string;
+  updatedAt: string;
+  resolvedAt?: string;
+  sentAt?: string;
+}
+
+export const COMMENT_LIMITS = {
+  maxComments: 500,
+  body: 4000,
+  snippet: 2000,
+  exact: 160,
+  prefix: 32,
+  suffix: 32,
+  cssPath: 512,
+  file: 1024,
+} as const;
+
+/** Lowest resolver score that still counts as the same element (see resolveAnchor). */
+export const REANCHOR_MIN_SCORE = 0.55;
+
+export const COMMENT_ID_RE = /^[0-9a-f]{12}$/;
+export const ELEMENT_TAG_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/**
+ * What `describeElement` can produce: `#id`, `tag:nth-of-type(n)` and ` > `. Anything else
+ * is not a path the canvas made, and it is embedded in prompts, so it is dropped.
+ */
+export const CSS_PATH_RE = /^[A-Za-z0-9_#:() >-]*$/;
+
+type Raw = Record<string, unknown>;
+
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+const capped = (v: unknown, max: number): string => (typeof v === "string" ? v.slice(0, max) : "");
+
+/** A page-supplied quote, capped; HTML comments are removed because they read as instructions. */
+export function parseCommentQuote(v: unknown): CommentQuote {
+  const q = isRaw(v) ? v : {};
+  return {
+    exact: stripHtmlComments(capped(q.exact, COMMENT_LIMITS.exact * 2)).slice(0, COMMENT_LIMITS.exact),
+    prefix: stripHtmlComments(capped(q.prefix, COMMENT_LIMITS.prefix * 2)).slice(-COMMENT_LIMITS.prefix),
+    suffix: stripHtmlComments(capped(q.suffix, COMMENT_LIMITS.suffix * 2)).slice(0, COMMENT_LIMITS.suffix),
+  };
+}
+
+export function parsePpmId(v: unknown): number | null | undefined {
+  if (v === null) return null;
+  return typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 0x7fffffff ? v : undefined;
+}
+
+/** A validated anchor, or null. `file` must be a non-empty string; the server checks the path. */
+export function parseCommentAnchor(v: unknown): CommentAnchor | null {
+  if (!isRaw(v)) return null;
+  const ppmId = parsePpmId(v.ppmId);
+  const gen = v.gen === null ? null : typeof v.gen === "string" && DESIGN_GEN_RE.test(v.gen) ? v.gen : undefined;
+  const file = typeof v.file === "string" ? v.file : "";
+  const tag = typeof v.tag === "string" ? v.tag.toLowerCase() : "";
+  if (ppmId === undefined || gen === undefined || !file || file.length > COMMENT_LIMITS.file || !ELEMENT_TAG_RE.test(tag)) return null;
+  const rawPath = capped(v.cssPath, COMMENT_LIMITS.cssPath);
+  return { file, ppmId, gen, tag, cssPath: CSS_PATH_RE.test(rawPath) ? rawPath : "", quote: parseCommentQuote(v.quote) };
+}
+
+/** Removes `<!-- … -->`, including an unterminated one running to the end. */
+export function stripHtmlComments(text: string): string {
+  return text.replace(/<!--[\s\S]*?(?:-->|$)/g, "");
+}
+
+export function isOpenComment(c: Pick<DesignComment, "resolvedAt">): boolean {
+  return !c.resolvedAt;
+}

package/src/shared/design-slide-doc-parse.ts

@@ -0,0 +1,140 @@
+import {
+  MAX_RUN_TEXT, MAX_SLIDE_EDGE_PX, MAX_SLIDE_IMAGE_BYTES, MAX_SLIDE_ITEMS, MAX_SLIDE_WARNINGS, MAX_SLIDES, MAX_TEXT_RUNS,
+  type Slide, type SlideBox, type SlideColor, type SlideDoc, type SlideItem, type SlideShapeItem, type SlideTextAlign,
+  type SlideTextItem, type SlideTextRun, type SlideTextValign,
+} from "./design-slide-doc";
+
+/**
+ * The one validator a measured deck passes before anything of it reaches the PPTX writer.
+ * One malformed item anywhere rejects the whole document: the frame is untrusted, and a
+ * partial deck would silently drop content the user expects to see.
+ */
+
+const MAX_COORD = 100_000;
+
+const HEX_RE = /^[0-9A-F]{6}$/;
+const FONT_RE = /^[\p{L}\p{N} ._-]{1,64}$/u;
+const IMAGE_DATA_RE = /^data:image\/(?:png|jpeg);base64,[A-Za-z0-9+/]+={0,2}$/;
+const ALIGNS: readonly SlideTextAlign[] = ["left", "center", "right", "justify"];
+const VALIGNS: readonly SlideTextValign[] = ["top", "middle", "bottom"];
+
+type Raw = Record<string, unknown>;
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+const finite = (v: unknown, max = MAX_COORD): number | null =>
+  (typeof v === "number" && Number.isFinite(v) && Math.abs(v) <= max ? v : null);
+
+export function parseSlideColor(v: unknown): SlideColor | null {
+  if (!isRaw(v) || typeof v.hex !== "string" || !HEX_RE.test(v.hex)) return null;
+  const alpha = finite(v.alpha, 1);
+  return alpha === null || alpha < 0 ? null : { hex: v.hex, alpha };
+}
+
+function parseBox(v: Raw): SlideBox | null {
+  const x = finite(v.x), y = finite(v.y), w = finite(v.w), h = finite(v.h);
+  if (x === null || y === null || w === null || h === null || w <= 0 || h <= 0) return null;
+  const box: SlideBox = { x, y, w, h };
+  if (v.rotation !== undefined) {
+    const r = finite(v.rotation, 360);
+    if (r === null) return null;
+    if (r !== 0) box.rotation = r;
+  }
+  return box;
+}
+
+function parseRun(v: unknown): SlideTextRun | null {
+  if (!isRaw(v) || typeof v.text !== "string") return null;
+  const run: SlideTextRun = { text: v.text.slice(0, MAX_RUN_TEXT) };
+  for (const flag of ["bold", "italic", "underline", "breakLine"] as const) {
+    if (v[flag] === true) run[flag] = true;
+  }
+  if (v.color !== undefined) {
+    const color = parseSlideColor(v.color);
+    if (!color) return null;
+    run.color = color;
+  }
+  if (v.sizePx !== undefined) {
+    const size = finite(v.sizePx, 4000);
+    if (size === null || size <= 0) return null;
+    run.sizePx = size;
+  }
+  // A font name the pattern does not allow is dropped rather than refusing the run:
+  // PowerPoint then uses its default face, which is what a missing font does anyway.
+  if (typeof v.font === "string" && FONT_RE.test(v.font)) run.font = v.font;
+  return run;
+}
+
+function parseItem(v: unknown, budget: { imageBytes: number }): SlideItem | null {
+  if (!isRaw(v)) return null;
+  const box = parseBox(v);
+  if (!box) return null;
+  if (v.kind === "text") {
+    if (!Array.isArray(v.runs) || v.runs.length === 0 || v.runs.length > MAX_TEXT_RUNS) return null;
+    const runs = v.runs.map(parseRun);
+    if (runs.some((r) => r === null)) return null;
+    const align = ALIGNS.find((a) => a === v.align);
+    const valign = VALIGNS.find((a) => a === v.valign);
+    if (!align || !valign) return null;
+    const item: SlideTextItem = { kind: "text", ...box, runs: runs as SlideTextRun[], align, valign };
+    const lh = v.lineHeightPx === undefined ? undefined : finite(v.lineHeightPx, 4000);
+    if (lh === null || (lh !== undefined && lh <= 0)) return null;
+    if (lh !== undefined) item.lineHeightPx = lh;
+    if (v.bullet === "bullet" || v.bullet === "number") item.bullet = v.bullet;
+    return item;
+  }
+  if (v.kind === "shape") {
+    const item: SlideShapeItem = { kind: "shape", ...box };
+    if (v.fill !== undefined) {
+      const fill = parseSlideColor(v.fill);
+      if (!fill) return null;
+      item.fill = fill;
+    }
+    if (v.border !== undefined) {
+      if (!isRaw(v.border)) return null;
+      const width = finite(v.border.widthPx, 1000);
+      const color = parseSlideColor(v.border.color);
+      if (width === null || width <= 0 || !color) return null;
+      item.border = { widthPx: width, color };
+    }
+    if (v.radiusPx !== undefined) {
+      const r = finite(v.radiusPx);
+      if (r === null || r < 0) return null;
+      if (r > 0) item.radiusPx = r;
+    }
+    return item.fill || item.border ? item : null;
+  }
+  if (v.kind === "image") {
+    if (typeof v.data !== "string" || v.data.length > MAX_SLIDE_IMAGE_BYTES - budget.imageBytes) return null;
+    if (!IMAGE_DATA_RE.test(v.data)) return null;
+    budget.imageBytes += v.data.length;
+    return { kind: "image", ...box, data: v.data };
+  }
+  return null;
+}
+
+/** A validated deck, or null. One malformed item anywhere rejects the whole document. */
+export function parseSlideDoc(v: unknown): SlideDoc | null {
+  if (!isRaw(v)) return null;
+  const width = finite(v.width, MAX_SLIDE_EDGE_PX), height = finite(v.height, MAX_SLIDE_EDGE_PX);
+  if (width === null || height === null || width < 1 || height < 1) return null;
+  if (!Array.isArray(v.slides) || v.slides.length === 0 || v.slides.length > MAX_SLIDES) return null;
+  if (!Array.isArray(v.warnings) || v.warnings.length > MAX_SLIDE_WARNINGS) return null;
+  if (!v.warnings.every((w) => typeof w === "string")) return null;
+  const budget = { imageBytes: 0 };
+  const slides: Slide[] = [];
+  for (const raw of v.slides) {
+    if (!isRaw(raw) || !Array.isArray(raw.items) || raw.items.length > MAX_SLIDE_ITEMS) return null;
+    const slide: Slide = { items: [] };
+    if (raw.background !== undefined) {
+      const bg = parseSlideColor(raw.background);
+      if (!bg) return null;
+      slide.background = bg;
+    }
+    for (const item of raw.items) {
+      const parsed = parseItem(item, budget);
+      if (!parsed) return null;
+      slide.items.push(parsed);
+    }
+    slides.push(slide);
+  }
+  return { width, height, slides, warnings: (v.warnings as string[]).map((w) => w.slice(0, 300)) };
+}

package/src/shared/design-slide-doc.ts

@@ -0,0 +1,91 @@
+/**
+ * A slide deck as the design bridge measured it in the browser, on its way to the PPTX writer.
+ *
+ * The bridge reads positions and computed styles off the live canvas (the user's browser is
+ * the renderer), so everything here is in CSS pixels relative to the slide's top-left corner.
+ * It is untrusted like every frame message: a page script can post the same shape, so
+ * `parseSlideDoc` (design-slide-doc-parse.ts) caps every count, string and number, accepts
+ * colours only as six hex digits and images only as PNG/JPEG data URLs, and bounds the total
+ * image payload, using the limits below.
+ */
+
+export interface SlideColor {
+  /** `RRGGBB`, uppercase. */
+  hex: string;
+  /** 0 (transparent) to 1 (opaque). */
+  alpha: number;
+}
+
+export interface SlideTextRun {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  color?: SlideColor;
+  /** Font size in CSS px. */
+  sizePx?: number;
+  /** The first family of the computed `font-family`, unquoted. */
+  font?: string;
+  /** A line break follows this run. */
+  breakLine?: boolean;
+}
+
+export interface SlideBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Clockwise degrees. */
+  rotation?: number;
+}
+
+export type SlideTextAlign = "left" | "center" | "right" | "justify";
+export type SlideTextValign = "top" | "middle" | "bottom";
+
+export interface SlideTextItem extends SlideBox {
+  kind: "text";
+  runs: SlideTextRun[];
+  align: SlideTextAlign;
+  valign: SlideTextValign;
+  lineHeightPx?: number;
+  bullet?: "bullet" | "number";
+}
+
+export interface SlideShapeItem extends SlideBox {
+  kind: "shape";
+  fill?: SlideColor;
+  border?: { widthPx: number; color: SlideColor };
+  radiusPx?: number;
+}
+
+export interface SlideImageItem extends SlideBox {
+  kind: "image";
+  /** `data:image/png;base64,…` or `data:image/jpeg;base64,…`. */
+  data: string;
+}
+
+export type SlideItem = SlideTextItem | SlideShapeItem | SlideImageItem;
+
+export interface Slide {
+  background?: SlideColor;
+  items: SlideItem[];
+}
+
+export interface SlideDoc {
+  /** Slide size in CSS px (1280x720 for a standard deck). */
+  width: number;
+  height: number;
+  slides: Slide[];
+  /** What could not be reproduced exactly, one line each, already naming the slide. */
+  warnings: string[];
+}
+
+export const MAX_SLIDES = 200;
+export const MAX_SLIDE_ITEMS = 600;
+export const MAX_TEXT_RUNS = 400;
+export const MAX_RUN_TEXT = 5000;
+export const MAX_SLIDE_WARNINGS = 200;
+/** Total size of every image data URL in one deck. */
+export const MAX_SLIDE_IMAGE_BYTES = 50 * 1024 * 1024;
+/** Largest slide edge, in px: PowerPoint's own limit is 56 inches. */
+export const MAX_SLIDE_EDGE_PX = 5376;

package/src/shared/design-system-init-prompt.ts

@@ -0,0 +1,35 @@
+/**
+ * The message that sets up a project's design system, placed in the design chat's composer
+ * for the user to review and send (never sent automatically).
+ *
+ * It asks for one read of the codebase and exactly two files, `designs/DESIGN.md` and
+ * `designs/tokens.css`, which every design session is told to follow and link. Writing
+ * anything else is ruled out explicitly, because this runs in a design session whose
+ * permission default auto-approves file edits inside the project.
+ */
+export function buildDesignSystemInitPrompt(): string {
+  return `Set up this project's design system so every design here matches the product.
+
+1. Read the codebase once to learn its visual language: global stylesheets, theme and token
+   files (CSS custom properties, Tailwind config, theme objects), the font setup, and a few
+   of the most used UI components (buttons, inputs, cards, navigation). Skip dependencies,
+   build output and generated files.
+
+2. Write \`designs/DESIGN.md\`, a concise guide for designing screens for this product:
+   - brand character and tone in a few sentences;
+   - the colour palette with roles (background, surface, text, muted text, accent, border,
+     success, warning, danger), each with its value, for light and dark mode if both exist;
+   - typography: font families, the type scale, weights and line heights;
+   - spacing scale, corner radii, shadows and borders;
+   - the look of the core components, with the class names or markup patterns the code uses;
+   - layout conventions (widths, grids, breakpoints) and any do's and don'ts you noticed.
+
+3. Write \`designs/tokens.css\` with a single \`:root { ... }\` block declaring those values as
+   CSS custom properties with clear names (\`--color-accent\`, \`--radius-md\`, \`--space-4\`,
+   \`--font-body\`...), plus a \`@media (prefers-color-scheme: dark)\` block if the product
+   has a dark theme. Plain CSS only: no imports, no build step, no framework syntax.
+
+Take the values from the code rather than inventing them, and say where you are unsure.
+Create or change only those two files: do not modify any other file in the project, and do
+not create a design folder.`;
+}