@aexol/spectral 0.7.0 → 0.7.1

package/dist/agent/index.js

@@ -25,8 +25,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { StringEnum } from "@mariozechner/pi-ai";
-import { getMarkdownTheme, withFileMutationQueue, } from "@mariozechner/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
+import { withFileMutationQueue, } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents } from "./agents.js";
 // ---------------------------------------------------------------------------
@@ -34,7 +34,6 @@ import { discoverAgents } from "./agents.js";
 // ---------------------------------------------------------------------------
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
-const COLLAPSED_ITEM_COUNT = 10;
 // ---------------------------------------------------------------------------
 // Helpers — formatting
 // ---------------------------------------------------------------------------
@@ -68,69 +67,6 @@ function formatUsageStats(usage, model) {
         parts.push(model);
     return parts.join(" ");
 }
-function formatToolCall(toolName, args, themeFg) {
-    const shortenPath = (p) => {
-        const home = os.homedir();
-        return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
-    };
-    switch (toolName) {
-        case "bash": {
-            const command = args.command || "...";
-            const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
-            return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
-        }
-        case "read": {
-            const rawPath = (args.file_path || args.path || "...");
-            const filePath = shortenPath(rawPath);
-            const offset = args.offset;
-            const limit = args.limit;
-            let text = themeFg("accent", filePath);
-            if (offset !== undefined || limit !== undefined) {
-                const startLine = offset ?? 1;
-                const endLine = limit !== undefined ? startLine + limit - 1 : "";
-                text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
-            }
-            return themeFg("muted", "read ") + text;
-        }
-        case "write": {
-            const rawPath = (args.file_path || args.path || "...");
-            const filePath = shortenPath(rawPath);
-            const content = (args.content || "");
-            const lines = content.split("\n").length;
-            let text = themeFg("muted", "write ") + themeFg("accent", filePath);
-            if (lines > 1)
-                text += themeFg("dim", ` (${lines} lines)`);
-            return text;
-        }
-        case "edit": {
-            const rawPath = (args.file_path || args.path || "...");
-            return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
-        }
-        case "ls": {
-            const rawPath = (args.path || ".");
-            return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
-        }
-        case "find": {
-            const pattern = (args.pattern || "*");
-            const rawPath = (args.path || ".");
-            return (themeFg("muted", "find ") +
-                themeFg("accent", pattern) +
-                themeFg("dim", ` in ${shortenPath(rawPath)}`));
-        }
-        case "grep": {
-            const pattern = (args.pattern || "");
-            const rawPath = (args.path || ".");
-            return (themeFg("muted", "grep ") +
-                themeFg("accent", `/${pattern}/`) +
-                themeFg("dim", ` in ${shortenPath(rawPath)}`));
-        }
-        default: {
-            const argsStr = JSON.stringify(args);
-            const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
-            return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
-        }
-    }
-}
 // ---------------------------------------------------------------------------
 // Helpers — message extraction
 // ---------------------------------------------------------------------------
@@ -146,20 +82,6 @@ function getFinalOutput(messages) {
     }
     return "";
 }
-function getDisplayItems(messages) {
-    const items = [];
-    for (const msg of messages) {
-        if (msg.role === "assistant") {
-            for (const part of msg.content) {
-                if (part.type === "text")
-                    items.push({ type: "text", text: part.text });
-                else if (part.type === "toolCall")
-                    items.push({ type: "toolCall", name: part.name, args: part.arguments });
-            }
-        }
-    }
-    return items;
-}
 // ---------------------------------------------------------------------------
 // Helpers — concurrency, temp files, binary detection
 // ---------------------------------------------------------------------------
@@ -471,7 +393,9 @@ export default function subagentExtension(pi) {
                     details: makeDetails("single")([]),
                 };
             }
-            // Security: if project-local agents are enabled, confirm with user
+            // Security: if project-local agents are enabled, confirm with user.
+            // In headless mode (no TUI), project-local agents are silently allowed —
+            // the caller is already trusted (it's the coding agent itself).
             if ((agentScope === "project" || agentScope === "both") &&
                 confirmProjectAgents &&
                 ctx.hasUI) {
@@ -661,148 +585,72 @@ export default function subagentExtension(pi) {
                 details: makeDetails("single")([]),
             };
         },
-        // ── Rendering ─────────────────────────────────────────────────
-        renderCall(args, theme, _context) {
+        // ── Rendering (headless-compatible: plain text strings, no TUI imports) ──
+        renderCall(args, _theme, _context) {
             const scope = args.agentScope ?? "user";
             if (args.chain && args.chain.length > 0) {
-                let text = theme.fg("toolTitle", theme.bold("subagent ")) +
-                    theme.fg("accent", `chain (${args.chain.length} steps)`) +
-                    theme.fg("muted", ` [${scope}]`);
+                let text = `subagent chain (${args.chain.length} steps) [${scope}]`;
                 for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
                     const step = args.chain[i];
                     const cleanTask = step.task.replace(/\{previous\}/g, "").trim();
                     const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask;
-                    text +=
-                        "\n  " +
-                            theme.fg("muted", `${i + 1}.`) +
-                            " " +
-                            theme.fg("accent", step.agent) +
-                            theme.fg("dim", ` ${preview}`);
+                    text += `\n  ${i + 1}. ${step.agent} ${preview}`;
                 }
                 if (args.chain.length > 3)
-                    text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
-                return new Text(text, 0, 0);
+                    text += `\n  ... +${args.chain.length - 3} more`;
+                return new Text(text);
             }
             if (args.tasks && args.tasks.length > 0) {
-                let text = theme.fg("toolTitle", theme.bold("subagent ")) +
-                    theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
-                    theme.fg("muted", ` [${scope}]`);
+                let text = `subagent parallel (${args.tasks.length} tasks) [${scope}]`;
                 for (const t of args.tasks.slice(0, 3)) {
                     const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task;
-                    text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview}`)}`;
+                    text += `\n  ${t.agent} ${preview}`;
                 }
                 if (args.tasks.length > 3)
-                    text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`;
-                return new Text(text, 0, 0);
+                    text += `\n  ... +${args.tasks.length - 3} more`;
+                return new Text(text);
             }
             const agentName = args.agent || "...";
             const preview = args.task
-                ? args.task.length > 60
-                    ? `${args.task.slice(0, 60)}...`
-                    : args.task
+                ? args.task.length > 60 ? `${args.task.slice(0, 60)}...` : args.task
                 : "...";
-            let text = theme.fg("toolTitle", theme.bold("subagent ")) +
-                theme.fg("accent", agentName) +
-                theme.fg("muted", ` [${scope}]`);
-            text += `\n  ${theme.fg("dim", preview)}`;
-            return new Text(text, 0, 0);
+            return new Text(`subagent ${agentName} [${scope}]\n  ${preview}`);
         },
-        renderResult(result, { expanded }, theme, _context) {
+        renderResult(result, _opts, _theme, _context) {
             const details = result.details;
             if (!details || details.results.length === 0) {
                 const text = result.content[0];
-                return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+                return new Text(text?.type === "text" ? text.text : "(no output)");
             }
-            const mdTheme = getMarkdownTheme();
-            const renderDisplayItems = (items, limit) => {
-                const toShow = limit ? items.slice(-limit) : items;
-                const skipped = limit && items.length > limit ? items.length - limit : 0;
-                let text = "";
-                if (skipped > 0)
-                    text += theme.fg("muted", `... ${skipped} earlier items\n`);
-                for (const item of toShow) {
-                    if (item.type === "text") {
-                        const preview = expanded
-                            ? item.text
-                            : item.text.split("\n").slice(0, 3).join("\n");
-                        text += `${theme.fg("toolOutput", preview)}\n`;
-                    }
-                    else {
-                        text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
-                    }
-                }
-                return text.trimEnd();
-            };
+            const lines = [];
             if (details.mode === "single" && details.results.length === 1) {
                 const r = details.results[0];
-                const isError = r.exitCode !== 0 ||
-                    r.stopReason === "error" ||
-                    r.stopReason === "aborted";
-                const icon = isError
-                    ? theme.fg("error", "✗")
-                    : theme.fg("success", "✓");
-                const displayItems = getDisplayItems(r.messages);
+                const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+                const icon = isError ? "✗" : "✓";
                 const finalOutput = getFinalOutput(r.messages);
-                if (expanded) {
-                    const container = new Container();
-                    let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
-                    if (isError && r.stopReason)
-                        header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
-                    container.addChild(new Text(header, 0, 0));
-                    if (isError && r.errorMessage)
-                        container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
-                    container.addChild(new Spacer(1));
-                    container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
-                    container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
-                    container.addChild(new Spacer(1));
-                    container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
-                    if (displayItems.length === 0 && !finalOutput) {
-                        container.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
-                    }
-                    else {
-                        for (const item of displayItems) {
-                            if (item.type === "toolCall")
-                                container.addChild(new Text(theme.fg("muted", "→ ") +
-                                    formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0));
-                        }
-                        if (finalOutput) {
-                            container.addChild(new Spacer(1));
-                            container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-                        }
-                    }
-                    const usageStr = formatUsageStats(r.usage, r.model);
-                    if (usageStr) {
-                        container.addChild(new Spacer(1));
-                        container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
-                    }
-                    return container;
-                }
-                let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
-                if (isError && r.stopReason)
-                    text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+                lines.push(`${icon} ${r.agent} (${r.agentSource})${isError && r.stopReason ? ` [${r.stopReason}]` : ""}`);
                 if (isError && r.errorMessage)
-                    text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
-                else if (displayItems.length === 0)
-                    text += `\n${theme.fg("muted", "(no output)")}`;
+                    lines.push(`Error: ${r.errorMessage}`);
+                lines.push("");
+                lines.push("─── Task ───");
+                lines.push(r.task);
+                lines.push("");
+                lines.push("─── Output ───");
+                if (!finalOutput) {
+                    lines.push("(no output)");
+                }
                 else {
-                    text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
-                    if (displayItems.length > COLLAPSED_ITEM_COUNT)
-                        text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+                    lines.push(finalOutput.trim());
                 }
                 const usageStr = formatUsageStats(r.usage, r.model);
-                if (usageStr)
-                    text += `\n${theme.fg("dim", usageStr)}`;
-                return new Text(text, 0, 0);
+                if (usageStr) {
+                    lines.push("");
+                    lines.push(usageStr);
+                }
+                return new Text(lines.join("\n"));
             }
             const aggregateUsage = (results) => {
-                const total = {
-                    input: 0,
-                    output: 0,
-                    cacheRead: 0,
-                    cacheWrite: 0,
-                    cost: 0,
-                    turns: 0,
-                };
+                const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
                 for (const r of results) {
                     total.input += r.usage.input;
                     total.output += r.usage.output;
@@ -815,137 +663,64 @@ export default function subagentExtension(pi) {
             };
             if (details.mode === "chain") {
                 const successCount = details.results.filter((r) => r.exitCode === 0).length;
-                const icon = successCount === details.results.length
-                    ? theme.fg("success", "✓")
-                    : theme.fg("error", "✗");
-                if (expanded) {
-                    const container = new Container();
-                    container.addChild(new Text(icon +
-                        " " +
-                        theme.fg("toolTitle", theme.bold("chain ")) +
-                        theme.fg("accent", `${successCount}/${details.results.length} steps`), 0, 0));
-                    for (const r of details.results) {
-                        const rIcon = r.exitCode === 0
-                            ? theme.fg("success", "✓")
-                            : theme.fg("error", "✗");
-                        const displayItems = getDisplayItems(r.messages);
-                        const finalOutput = getFinalOutput(r.messages);
-                        container.addChild(new Spacer(1));
-                        container.addChild(new Text(`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0));
-                        container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
-                        for (const item of displayItems) {
-                            if (item.type === "toolCall") {
-                                container.addChild(new Text(theme.fg("muted", "→ ") +
-                                    formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0));
-                            }
-                        }
-                        if (finalOutput) {
-                            container.addChild(new Spacer(1));
-                            container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-                        }
-                        const stepUsage = formatUsageStats(r.usage, r.model);
-                        if (stepUsage)
-                            container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0));
-                    }
-                    const usageStr = formatUsageStats(aggregateUsage(details.results));
-                    if (usageStr) {
-                        container.addChild(new Spacer(1));
-                        container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
-                    }
-                    return container;
-                }
-                let text = icon +
-                    " " +
-                    theme.fg("toolTitle", theme.bold("chain ")) +
-                    theme.fg("accent", `${successCount}/${details.results.length} steps`);
+                const icon = successCount === details.results.length ? "✓" : "✗";
+                lines.push(`${icon} chain ${successCount}/${details.results.length} steps`);
                 for (const r of details.results) {
-                    const rIcon = r.exitCode === 0
-                        ? theme.fg("success", "✓")
-                        : theme.fg("error", "✗");
-                    const displayItems = getDisplayItems(r.messages);
-                    text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
-                    if (displayItems.length === 0)
-                        text += `\n${theme.fg("muted", "(no output)")}`;
+                    const rIcon = r.exitCode === 0 ? "✓" : "✗";
+                    const finalOutput = getFinalOutput(r.messages);
+                    lines.push("");
+                    lines.push(`─── Step ${r.step}: ${r.agent} ${rIcon}`);
+                    lines.push(`Task: ${r.task}`);
+                    if (finalOutput)
+                        lines.push(finalOutput.trim());
                     else
-                        text += `\n${renderDisplayItems(displayItems, 5)}`;
+                        lines.push("(no output)");
+                    const stepUsage = formatUsageStats(r.usage, r.model);
+                    if (stepUsage)
+                        lines.push(stepUsage);
                 }
                 const usageStr = formatUsageStats(aggregateUsage(details.results));
-                if (usageStr)
-                    text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
-                text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-                return new Text(text, 0, 0);
+                if (usageStr) {
+                    lines.push("");
+                    lines.push(`Total: ${usageStr}`);
+                }
+                return new Text(lines.join("\n"));
             }
             if (details.mode === "parallel") {
                 const running = details.results.filter((r) => r.exitCode === -1).length;
                 const successCount = details.results.filter((r) => r.exitCode === 0).length;
                 const failCount = details.results.filter((r) => r.exitCode > 0).length;
                 const isRunning = running > 0;
-                const icon = isRunning
-                    ? theme.fg("warning", "⏳")
-                    : failCount > 0
-                        ? theme.fg("warning", "◐")
-                        : theme.fg("success", "✓");
+                const icon = isRunning ? "⏳" : failCount > 0 ? "◐" : "✓";
                 const status = isRunning
                     ? `${successCount + failCount}/${details.results.length} done, ${running} running`
                     : `${successCount}/${details.results.length} tasks`;
-                if (expanded && !isRunning) {
-                    const container = new Container();
-                    container.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`, 0, 0));
-                    for (const r of details.results) {
-                        const rIcon = r.exitCode === 0
-                            ? theme.fg("success", "✓")
-                            : theme.fg("error", "✗");
-                        const displayItems = getDisplayItems(r.messages);
-                        const finalOutput = getFinalOutput(r.messages);
-                        container.addChild(new Spacer(1));
-                        container.addChild(new Text(`${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0));
-                        container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
-                        for (const item of displayItems) {
-                            if (item.type === "toolCall") {
-                                container.addChild(new Text(theme.fg("muted", "→ ") +
-                                    formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0));
-                            }
-                        }
-                        if (finalOutput) {
-                            container.addChild(new Spacer(1));
-                            container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-                        }
-                        const taskUsage = formatUsageStats(r.usage, r.model);
-                        if (taskUsage)
-                            container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0));
-                    }
-                    const usageStr = formatUsageStats(aggregateUsage(details.results));
-                    if (usageStr) {
-                        container.addChild(new Spacer(1));
-                        container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
-                    }
-                    return container;
-                }
-                let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
+                lines.push(`${icon} parallel ${status}`);
                 for (const r of details.results) {
-                    const rIcon = r.exitCode === -1
-                        ? theme.fg("warning", "⏳")
-                        : r.exitCode === 0
-                            ? theme.fg("success", "✓")
-                            : theme.fg("error", "✗");
-                    const displayItems = getDisplayItems(r.messages);
-                    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
-                    if (displayItems.length === 0)
-                        text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`;
+                    const rIcon = r.exitCode === -1 ? "⏳" : r.exitCode === 0 ? "✓" : "✗";
+                    const finalOutput = getFinalOutput(r.messages);
+                    lines.push("");
+                    lines.push(`─── ${r.agent} ${rIcon}`);
+                    lines.push(`Task: ${r.task}`);
+                    if (finalOutput)
+                        lines.push(finalOutput.trim());
                     else
-                        text += `\n${renderDisplayItems(displayItems, 5)}`;
+                        lines.push(r.exitCode === -1 ? "(running...)" : "(no output)");
+                    const taskUsage = formatUsageStats(r.usage, r.model);
+                    if (taskUsage)
+                        lines.push(taskUsage);
                 }
                 if (!isRunning) {
                     const usageStr = formatUsageStats(aggregateUsage(details.results));
-                    if (usageStr)
-                        text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
+                    if (usageStr) {
+                        lines.push("");
+                        lines.push(`Total: ${usageStr}`);
+                    }
                 }
-                if (!expanded)
-                    text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-                return new Text(text, 0, 0);
+                return new Text(lines.join("\n"));
             }
             const text = result.content[0];
-            return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+            return new Text(text?.type === "text" ? text.text : "(no output)");
         },
     });
 }

package/dist/cli.js

@@ -112,6 +112,10 @@ function resolveOpenRouterAttributionPath() {
 function resolveAgentExtensionPath() {
     return resolveExtensionEntry("agent", "index");
 }
+/** Absolute path to the bundled designer extension. */
+function resolveDesignerExtensionPath() {
+    return resolveExtensionEntry("designer", "index");
+}
 // ---- Branded helpers ---------------------------------------------------------
 function printVersion() {
     process.stdout.write(`spectral ${VERSION} — ${TAGLINE}\n`);
@@ -290,12 +294,19 @@ async function main() {
         process.stderr.write(`spectral: bundled agent extension not found at ${agentExtPath}. This is a packaging bug.\n`);
         process.exit(1);
     }
+    // Bundled designer extension for design tasks (prototypes, slide decks, mobile apps, etc.)
+    const designerExtPath = resolveDesignerExtensionPath();
+    if (!existsSync(designerExtPath)) {
+        process.stderr.write(`spectral: bundled designer extension not found at ${designerExtPath}. This is a packaging bug.\n`);
+        process.exit(1);
+    }
     const extFlags = [
         "--extension", aexolExtPath,
         "--extension", mcpExtPath,
         "--extension", obsMemPath,
         "--extension", openrouterAttrPath,
         "--extension", agentExtPath,
+        "--extension", designerExtPath,
     ];
     const finalArgs = [...extFlags, ...args];
     delegateToPi(finalArgs);

package/dist/designer/data/systems/agentic/DESIGN.md

@@ -0,0 +1,71 @@
+# Design System Inspired by Agentic
+
+> Category: Themed & Unique
+> Conversational AI-first interface with minimal controls, clear outcomes, and delegated task flows for agentic workflows.
+
+## 1. Visual Theme & Atmosphere
+
+Conversational AI-first interface with minimal controls, clear outcomes, and delegated task flows for agentic workflows.
+
+- **Visual style:** modern, bold
+- **Color stance:** surface/subtle layers
+- **Design intent:** Keep outputs recognizable to this style family while preserving usability and readability.
+
+## 2. Color
+
+- **Primary:** `#FF5701` — Token from style foundations.
+- **Secondary:** `#F6F6F1` — Token from style foundations.
+- **Success:** `#16A34A` — Token from style foundations.
+- **Warning:** `#D97706` — Token from style foundations.
+- **Danger:** `#DC2626` — Token from style foundations.
+- **Surface:** `#FFFFFF` — Token from style foundations.
+- **Text:** `#111827` — Token from style foundations.
+- **Neutral:** `#FFFFFF` — Derived from the surface token for official format compatibility.
+
+- Favor Primary (#FF5701) for CTA emphasis.
+- Use Surface (#FFFFFF) for large backgrounds and cards.
+- Keep body copy on Text (#111827) for legibility.
+
+## 3. Typography
+
+- **Scale:** 14/16/18/24/32/40
+- **Families:** primary=Playfair Display, display=Playfair Display, mono=JetBrains Mono
+- **Weights:** 100, 200, 300, 400, 500, 600, 700, 800, 900
+- Headings should carry the style personality; body text should optimize scanability and contrast.
+
+## 4. Spacing & Grid
+
+- **Spacing scale:** 8pt baseline grid
+- Keep vertical rhythm consistent across sections and components.
+- Align columns and modules to a predictable grid; avoid ad-hoc offsets.
+
+## 5. Layout & Composition
+
+- Prefer clear content blocks with consistent internal padding.
+- Keep hierarchy obvious: headline → support text → primary action.
+- Use whitespace to separate concerns before adding borders or shadows.
+
+## 6. Components
+
+- Buttons: primary action uses `#FF5701`; secondary actions stay neutral.
+- Inputs: strong focus-visible states, clear labels, and predictable error messaging.
+- Cards/sections: use consistent radii, spacing, and elevation strategy across the page.
+
+## 7. Motion & Interaction
+
+- Use subtle transitions that emphasize Primary (#FF5701) as the interaction signal.
+- Default to short, purposeful transitions (150–250ms) with stable easing.
+- Ensure hover, focus-visible, active, disabled, and loading states are explicit.
+
+## 8. Voice & Brand
+
+- Tone should reflect the visual style: concise, confident, and product-specific.
+- Keep microcopy action-oriented and avoid generic filler language.
+- Preserve the style identity in headlines while keeping UI labels literal and clear.
+
+## 9. Anti-patterns
+
+- Do not introduce off-palette colors when an existing token can solve the problem.
+- Do not flatten hierarchy by using the same type size/weight for all text.
+- Do not add decorative effects that reduce readability or accessibility.
+- Do not mix unrelated visual metaphors in the same interface.