Draft: Build agent-ready design proposal system (#16875)

## Thinking Path

> - Paperclip helps people manage AI agents and their work.
> - People need consistent UI patterns to review and control that work.
> - The current board uses related layouts and controls with different
spacing, type, and behavior.
> - That drift makes it hard for a designer or an agent to build a new
page from a reliable reference.
> - Storybook can show the shared patterns and the states they need to
support.
> - This pull request adds design proposals, a local sandbox, and
reusable UI controls so people can compare the patterns in context.
> - The benefit is a clearer design system that agents can use to build
consistent UI.

## Linked Issues or Issue Description

**Subsystem affected**

`ui/` — React board UI and Storybook.

**Problem or motivation**

Board pages repeat visual and interaction decisions. Storybook did not
provide a complete reference for task views, conversation states,
typography, toolbars, tabs, and light/dark colors. People could not
compare a proposed pattern with the running board in one place.

**Proposed solution**

Add a staged Design Proposals catalog with foundations, components,
layouts, and page specimens. Add an opt-in sandbox. Reuse production
components where possible. Include synthetic conversation states and
shared controls so reviewers can compare and refine them.

**Alternatives considered**

Separate static mockups would not show keyboard behavior, responsive
layout, or real component states. Rebuilding each page only in Storybook
would allow the reference to drift from the board.

**Roadmap alignment**

This improves existing board UI and Skills Manager surfaces. It does not
add a new control-plane capability.

## What Changed

- Added dark and light color references, typography and conversation
specimens, and component stories for buttons, tabs, toolbars, sidebar,
popovers, activity, and task lists.
- Added a local design sandbox with synthetic task conversation playback
and representative states.
- Shared collection toolbars and navigation patterns across task, agent,
project, routine, skill, connector, and artifact pages.
- Added the streamlined Skills tabs and a My Skills collection that uses
the shared skill cards.
- Restored saved-thread access during synthetic playback, kept connector
searchbox semantics, and updated reproduction checks after moving trial
stories.
- Documented the proposed patterns and added focused UI, catalog, and
browser checks.

## Verification

- `pnpm check:token-gates`, `node scripts/check-maps.mjs`, and `node
scripts/storybook-catalog.mjs --check` passed.
- Full workspace `pnpm -r typecheck` and `pnpm build` passed after
merging master. After the review fixes, focused UI typecheck, `pnpm
build-storybook`, 23 Skills Sources tests, and all 15 Storybook
typography browser tests passed.
- Focused task-thread and system-notice suites passed: 251 tests.
Connector Browse passed 84 tests; the connector, attachment, recovery,
and Storybook flyout browser journeys passed locally.
- A local full Vitest run hit one intermittent chat-channels integration
failure; that test passed in isolation. GitHub CI
[39347996059](https://github.com/paperclipai/paperclip/actions/runs/39347996059)
passed on the exact latest commit: 55 successful checks and two skipped
draft-only Storybook jobs.
- Greptile reviewed the exact latest commit at 5/5 with no new comments
or open review threads. GitHub reports the branch as cleanly mergeable.

## Risks

- This PR changes 206 files and exceeds the repository's 100-file review
target. Review by commit and consider a scoped split before merge.
- Design Proposals are staged references. Fixture interactions do not
prove API behavior, permissions, or provider execution.
- UI changes to shared controls may affect pages outside the proposal
sandbox. Focused browser checks and the full CI matrix passed.

## Model Used

- OpenAI Codex, GPT-6 family. The exact runtime model ID and context
window are not exposed in this session. The model used reasoning, code
execution, browser inspection, and local tests. Earlier branch commits
were also AI-assisted in this Codex conversation.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details available in this session)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above where applicable
- [x] I have either linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run focused tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Scott Tong <scott@scotts-mbp-m5-max.local>
Co-authored-by: Paperclip <noreply@paperclip.ing>

scripts/storybook-button-usage.mjs

@@ -0,0 +1,80 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const require = createRequire(path.join(root, "ui/package.json"));
+const storybookRequire = createRequire(require.resolve("storybook/internal/csf-tools"));
+const { parse } = storybookRequire("@babel/parser");
+const traverse = storybookRequire("@babel/traverse").default;
+
+function canonicalImport(source, file) {
+  if (source === "@/components/ui/button") return true;
+  return source.startsWith(".") && path.posix.normalize(path.posix.join(path.posix.dirname(file), source))
+    .replace(/\.[jt]sx?$/, "") === "ui/src/components/ui/button";
+}
+
+function propValue(attributes, name, fallback) {
+  const explicit = attributes.find(attribute => attribute.type === "JSXAttribute" && attribute.name.name === name);
+  if (!explicit) return attributes.some(attribute => attribute.type === "JSXSpreadAttribute") ? "dynamic / spread" : fallback;
+  // A subsequent spread may override even an explicit literal.
+  if (attributes.slice(attributes.indexOf(explicit) + 1).some(attribute => attribute.type === "JSXSpreadAttribute")) return "dynamic / spread";
+  const value = explicit.value?.type === "JSXExpressionContainer" ? explicit.value.expression : explicit.value;
+  return value?.type === "StringLiteral" ? value.value : "dynamic";
+}
+
+/** Count source call sites, never rendered instances or user activity. */
+export function buttonReferences(source, file, scope) {
+  const ast = parse(source, { sourceType: "module", plugins: ["typescript", "jsx"] });
+  const entries = [];
+  traverse(ast, {
+    JSXOpeningElement(element) {
+      const name = element.node.name;
+      const local = name.type === "JSXIdentifier" ? name.name : name.type === "JSXMemberExpression" && name.object.type === "JSXIdentifier" ? name.object.name : null;
+      if (!local) return;
+      const binding = element.scope.getBinding(local);
+      if (!binding || !canonicalImport(binding.path.parent.source?.value ?? "", file)) return;
+      const importedButton = binding.path.isImportSpecifier() && (binding.path.node.imported.name ?? binding.path.node.imported.value) === "Button" && name.type === "JSXIdentifier";
+      const namespaceButton = binding.path.isImportNamespaceSpecifier() && name.type === "JSXMemberExpression" && name.property.name === "Button";
+      if (!importedButton && !namespaceButton) return;
+      entries.push({ file, line: element.node.loc.start.line, scope,
+        variant: propValue(element.node.attributes, "variant", "default"),
+        size: propValue(element.node.attributes, "size", "default"),
+      });
+    },
+  });
+  return entries;
+}
+
+function walk(directory) {
+  return readdirSync(path.join(root, directory), { withFileTypes: true }).flatMap(entry => {
+    const file = `${directory}/${entry.name}`;
+    return entry.isDirectory() ? walk(file) : /\.tsx$/.test(file) && !/\.(test|spec|stories)\.tsx$/.test(file) ? [file] : [];
+  });
+}
+
+function inventory() {
+  const roots = [["ui/src", "app"]];
+  const entries = roots.flatMap(([directory, scope]) => walk(directory).flatMap(file => {
+    const source = readFileSync(path.join(root, file), "utf8");
+    // Parsing is unnecessary for modules that cannot import the subject.
+    return /\bButton\b/.test(source) ? buttonReferences(source, file, scope) : [];
+  }));
+  return { entries: entries.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line) };
+}
+
+/** Storybook-only module: publish counts and locations, without bundling app source text. */
+export function storybookButtonUsage() {
+  const id = "virtual:paperclip-button-usage";
+  return {
+    name: "paperclip-button-usage",
+    resolveId(value) { if (value === id) return `\0${id}`; },
+    load(value) { if (value === `\0${id}`) return `export default ${JSON.stringify(inventory())};`; },
+    handleHotUpdate(context) {
+      if (!/\/ui\/src\/.*\.tsx$/.test(context.file)) return;
+      const module = context.server.moduleGraph.getModuleById(`\0${id}`);
+      if (module) { context.server.moduleGraph.invalidateModule(module); return [...context.modules, module]; }
+    },
+  };
+}

scripts/storybook-button-usage.test.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buttonReferences } from "./storybook-button-usage.mjs";
+
+test("button usage follows canonical imports and aliases, excluding native and unrelated buttons", () => {
+  const entries = buttonReferences(`
+    import { Button as Action } from '@/components/ui/button';
+    import * as UI from './ui/button';
+    import { Button } from './OtherButton';
+    export const View = () => <><Action variant="outline" size="sm" /><UI.Button /><Button /><button /></>;
+  `, "ui/src/components/Example.tsx", "app");
+  assert.equal(entries.length, 2);
+  assert.deepEqual(entries.map(({ variant, size, scope }) => ({ variant, size, scope })), [
+    { variant: "outline", size: "sm", scope: "app" }, { variant: "default", size: "default", scope: "app" },
+  ]);
+});
+
+test("dynamic props and spread precedence are not reported as known defaults", () => {
+  const entries = buttonReferences(`
+    import { Button } from '@/components/ui/button';
+    export const View = () => <><Button {...props} /><Button variant={style} /><Button variant="cta" {...props} /><Button {...props} variant="ghost" /></>;
+  `, "ui/src/pages/Example.tsx", "app");
+  assert.deepEqual(entries.map(entry => entry.variant), ["dynamic / spread", "dynamic", "dynamic / spread", "ghost"]);
+  assert.deepEqual(entries.map(entry => entry.size), ["dynamic / spread", "default", "dynamic / spread", "dynamic / spread"]);
+});

scripts/storybook-catalog.mjs

@@ -14,6 +14,7 @@ const statuses = ["current", "proposed", "historical", "mixed", "unreviewed"];
 const implementations = ["production", "prototype", "mixed", "guide", "unreviewed"];
 const boundaries = ["fixtures", "fixture-server", "static", "unreviewed"];
 const annotationFields = new Set(["capabilities", "status", "implementation", "boundary", "notes", "home", "exception", "replacement"]);
+const specialHomes = { overview: "Overview", "design-proposals": "Design proposals", foundations: "Foundations" };
 
 function files(root, dir) {
   return readdirSync(path.join(root, dir), { withFileTypes: true }).flatMap(entry => {
@@ -74,7 +75,7 @@ export function catalogFromStories(stories, index) {
   const navigation = new Map(index.sections.flatMap(section => section.features.map(feature => [feature.id, `${sidebarLabel(section.title)}/${sidebarLabel(feature.title)}`])));
   return { version: 2, entries: stories.map(story => {
     const entry = { status: "unreviewed", implementation: "unreviewed", boundary: "unreviewed", notes: "", ...story.annotation, file: story.file, stableId: story.metaId, sidebarTitle: story.title };
-    const prefix = navigation.get(storyHome(entry)) ?? ({ overview: "Overview", foundations: "Foundations" })[storyHome(entry)];
+    const prefix = navigation.get(storyHome(entry)) ?? specialHomes[storyHome(entry)];
     return { ...entry, purpose: story.title?.startsWith(`${prefix}/`) ? story.title.slice(prefix.length + 1) : story.title };
   }) };
 }
@@ -91,14 +92,18 @@ export function validateCatalog(catalog, stories, index) {
     if (!boundaries.includes(entry.boundary)) errors.push(`${label}: invalid data boundary`);
     if (typeof entry.notes !== "string") errors.push(`${label}: notes must be text`);
     if (!Array.isArray(entry.capabilities) || entry.capabilities.some(ref => typeof ref !== "string")) { errors.push(`${label}: capabilities must be an array of IDs`); continue; }
-    if (entry.home !== undefined && entry.home !== "foundations") errors.push(`${label}: only shared foundations may override the capability home`);
+    if (entry.home !== undefined && !["foundations", "design-proposals"].includes(entry.home)) errors.push(`${label}: only shared foundations and design proposals may override the capability home`);
     if (entry.exception !== undefined && (typeof entry.exception !== "string" || !entry.exception.trim())) errors.push(`${label}: exception must be nonempty text`);
     if (entry.home === "foundations" && !entry.exception) errors.push(`${label}: foundation home needs an explicit reason`);
+    if (entry.home === "design-proposals") {
+      if (entry.status !== "proposed") errors.push(`${label}: design proposal home requires proposed status`);
+      if (!entry.exception) errors.push(`${label}: design proposal home needs an explicit staging reason`);
+    }
     for (const ref of entry.capabilities) if (!refs.has(ref)) errors.push(`${label}: unknown feature capability ${ref}`);
     if (!entry.capabilities.length && !entry.exception) errors.push(`${label}: unmapped story needs an explicit reason`);
     if (entry.capabilities.length !== new Set(entry.capabilities).size) errors.push(`${label}: duplicate capability references`);
     const area = storyHome(entry);
-    const prefix = navigation.get(area) ?? ({ overview: "Overview", foundations: "Foundations" })[area];
+    const prefix = navigation.get(area) ?? specialHomes[area];
     if (!label.startsWith(`${storyRoot}/${area}/`)) errors.push(`${label}: story must live in its primary feature folder ${area}`);
     if (!prefix || typeof entry.sidebarTitle !== "string" || !entry.sidebarTitle.startsWith(`${prefix}/`)) errors.push(`${label}: sidebar title must match its feature-map home`);
     if (typeof entry.stableId !== "string" || !entry.stableId.trim()) errors.push(`${label}: explicit meta ID is required`);
@@ -124,7 +129,10 @@ export function renderIndex(catalog, stories, index) {
     "[Contract and maintenance](../storybook-map/README.md) · [Verification routes](verification.md)", "",
     `${stories.length} story files; ${stories.reduce((n, story) => n + story.ids.length, 0)} indexed stories. Counts describe inventory, not passed tests or complete feature coverage.`, "",
     "Status describes product alignment; implementation describes the rendered subject; boundary describes simulated data. Limitations are authored alongside each story. Classification is not executed evidence. Related capabilities cross-list one canonical story file.", ""];
-  const homes = index.sections.flatMap(section => section.features.map(feature => ({ ...feature, section: section.title })));
+  const homes = [
+    { id: "design-proposals", title: "Proposed design system", section: "Design proposals", description: "Staged design work for review. These examples retain capability references but do not count as current product coverage." },
+    ...index.sections.flatMap(section => section.features.map(feature => ({ ...feature, section: section.title }))),
+  ];
   homes.push({ id: "foundations-and-guides", title: "Shared foundations and guides", section: "Foundations", description: "Shared components and contributor guidance outside the product feature index." });
   let currentSection;
   for (const feature of homes) {
@@ -134,7 +142,7 @@ export function renderIndex(catalog, stories, index) {
       lines.push(`## ${feature.section}`, "");
       currentSection = feature.section;
     }
-    lines.push(`### ${feature.title}`, "", feature.description, "", ...(area !== "foundations-and-guides" ? [`[Feature recipe](../feature-map/${area}.md)`, ""] : []));
+    lines.push(`### ${feature.title}`, "", feature.description, "", ...(!["foundations-and-guides", "design-proposals"].includes(area) ? [`[Feature recipe](../feature-map/${area}.md)`, ""] : []));
     if (!entries.length) lines.push("No primary story suite. Check capability lookup below for related examples; this does not imply a missing product feature.", "");
     else lines.push(
       "| Story suite | Capabilities | Product / implementation / data | Stories / play functions | Review note |",

scripts/storybook-catalog.test.mjs

@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { test } from "node:test";
-import { catalogFromStories, generateStorybook, renderVerification, scanStories, validateCatalog } from "./storybook-catalog.mjs";
+import { catalogFromStories, generateStorybook, renderIndex, renderVerification, scanStories, validateCatalog } from "./storybook-catalog.mjs";
 import { featureIndex } from "./feature-map.mjs";
 import { mapFixture } from "./map-test-fixture.mjs";
 
@@ -72,6 +72,48 @@ test("foundations preserve home and cross-capability references", t => {
   assert.match(inspect(f).errors.join("\n"), /foundation home needs an explicit reason/);
 });
 
+test("design proposals keep stable IDs and capability links in a separate catalog section without filling coverage gaps", t => {
+  const f = mapFixture(t);
+  const originalIds = scanStories(f.root)[0].ids;
+  rmSync(path.join(f.root, f.file));
+  f.story("task", {
+    home: "design-proposals",
+    status: "proposed",
+    capabilities: ["tasks/create", "tasks/discussion"],
+    implementation: "production",
+    boundary: "fixtures",
+    exception: "Opt-in task row refresh awaiting design review and application rollout.",
+  }, { area: "design-proposals", title: "Design proposals/Tasks/Task row" });
+  const { catalog, stories, index, errors } = inspect(f);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(stories[0].ids, originalIds);
+  assert.equal(catalog.entries[0].home, "design-proposals");
+  assert.equal(catalog.entries[0].purpose, "Tasks/Task row");
+  const report = renderIndex(catalog, stories, index);
+  const proposalSection = report.split("## Design proposals\n")[1].split("## Work\n")[0];
+  assert.match(proposalSection, /Design proposals\/Tasks\/Task row/);
+  assert.doesNotMatch(report, /feature-map\/design-proposals\.md/);
+  assert.match(report, /- `tasks\/create`: .*\(proposed\)/);
+  assert.match(report, /- `tasks\/discussion`: .*\(proposed\)/);
+  assert.match(renderVerification(catalog, index), /2 without a current, mixed or unreviewed example/);
+});
+
+test("design proposal homes require proposed status, a staging reason and their own navigation", t => {
+  const f = mapFixture(t);
+  const metadata = { home: "design-proposals", status: "proposed", capabilities: ["tasks/create"], exception: "Staged refresh for review." };
+  const options = { area: "design-proposals", title: "Design proposals/Tasks/Task row" };
+  for (const status of ["current", "mixed", "unreviewed", "historical"]) {
+    f.story("proposal", { ...metadata, status }, options);
+    assert.match(inspect(f).errors.join("\n"), /design proposal home requires proposed status/);
+  }
+  f.story("proposal", { ...metadata, exception: undefined }, options);
+  assert.match(inspect(f).errors.join("\n"), /design proposal home needs an explicit staging reason/);
+  f.story("proposal", metadata, { ...options, title: "Work/Tasks/Task row" });
+  assert.match(inspect(f).errors.join("\n"), /sidebar title/);
+  f.story("misplaced", metadata, { title: options.title });
+  assert.match(inspect(f).errors.join("\n"), /primary feature folder design-proposals/);
+});
+
 test("duplicate IDs, missing replacement references and collisions with generated guides fail", t => {
   const f = mapFixture(t);
   f.story("other", { capabilities: ["tasks/create"] }, { id: "stable-task" });

scripts/storybook-feature-index.mjs

@@ -8,7 +8,7 @@ export const generatedRoot = "ui/storybook/generated";
 export const generatedPreview = "ui/storybook/.storybook/preview.tsx";
 
 export function featureOrder(index) {
-  return ["Overview", ...index.sections.flatMap(section => [sidebarLabel(section.title),
+  return ["Overview", "Design proposals", ["Foundations", "Components", "Layouts", "Pages", "AI Generated Test Pages", "Patterns", "Guidelines"], ...index.sections.flatMap(section => [sidebarLabel(section.title),
     section.features.flatMap(feature => [sidebarLabel(feature.title), ["Overview", "*"]]),
   ]), "Foundations"];
 }

scripts/storybook-feature-index.test.mjs

@@ -16,7 +16,7 @@ test("recipes own discovery, names, section order and multiline capability descr
   assert.deepEqual(index.sections.map(section => section.title), ["Work", "Connections"]);
   assert.deepEqual(index.sections.flatMap(section => section.features.map(feature => feature.id)), ["tasks", "goals", "apps"]);
   assert.equal(index.sections[0].features[0].capabilities[0].description, "Create work; retain its description.");
-  assert.deepEqual(featureOrder(index), ["Overview", "Work", ["Tasks", ["Overview", "*"], "Goals", ["Overview", "*"]], "Connections", ["Apps", ["Overview", "*"]], "Foundations"]);
+  assert.deepEqual(featureOrder(index), ["Overview", "Design proposals", ["Foundations", "Components", "Layouts", "Pages", "AI Generated Test Pages", "Patterns", "Guidelines"], "Work", ["Tasks", ["Overview", "*"], "Goals", ["Overview", "*"]], "Connections", ["Apps", ["Overview", "*"]], "Foundations"]);
 });
 
 test("equal local orders preserve independently added features using their stable filename", t => {