Files
PaperClipAI/ui/storybook/support/design-proposals/SegmentedControllersPreview.tsx
T
7b9334cd10 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>
2026-10-19 17:45:26 -07:00

71 lines
7.7 KiB
TypeScript

import { useState, type ReactNode } from "react";
import { Columns3, List, Network, SquareKanban } from "lucide-react";
import { FilePreviewModeToggle, type FilePreviewMode } from "@/components/FilePreviewModeToggle";
import { Button } from "@/components/ui/button";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
export interface SegmentedControllersPreviewProps {
width: "full" | "narrow";
disableAgentActions: boolean;
onWidthChange?: (width: SegmentedControllersPreviewProps["width"]) => void;
}
function Specimen({ title, source, children }: { title: string; source: string; children: ReactNode }) {
return <section aria-label={title} className="min-w-0 space-y-4 border-t border-border pt-6">
<div className="space-y-1"><h2 className="text-lg font-normal text-foreground">{title}</h2><p className="text-xs">{source}</p></div>
<div className="overflow-x-auto p-2">{children}</div>
</section>;
}
function PanelSwitch({ label, items, grid = false, disabled = false }: { label: string; items: string[]; grid?: boolean; disabled?: boolean }) {
const [value, setValue] = useState(items[0]);
return <Tabs value={value} onValueChange={setValue} className="gap-4">
<TabsList aria-label={label} className={grid ? "grid w-full grid-cols-2" : undefined}>
{items.map((item, index) => <TabsTrigger key={item} value={item} disabled={disabled && index === 1}>{item}</TabsTrigger>)}
</TabsList>
{items.map(item => <TabsContent key={item} value={item}><p className="text-xs">Selected panel: {item}. Fixture content only.</p></TabsContent>)}
</Tabs>;
}
function LayoutSwitch({ kind }: { kind: "proposal" | "issues" | "agents" }) {
const [selected, setSelected] = useState(0);
const items = kind === "agents" ? [{ label: "List view", icon: List }, { label: "Org chart view", icon: Network }] : [{ label: "List view", icon: List }, { label: "Board view", icon: kind === "proposal" ? Columns3 : SquareKanban }];
return <div className={kind === "proposal" ? "design-view-toggle" : "flex w-fit items-center overflow-hidden rounded-md border border-border"} role="group" aria-label={`${kind} layout`}>
{items.map(({ label, icon: Icon }, index) => kind === "issues" ? <button key={label} aria-label={label} title={label} aria-pressed={selected === index} onClick={() => setSelected(index)} className={`flex h-8 w-8 items-center justify-center transition-colors ${selected === index ? "bg-accent text-foreground" : "text-muted-foreground hover:text-foreground"}`}><Icon className="h-3.5 w-3.5" /></button> : <Button key={label} type="button" size={kind === "agents" ? "icon-sm" : "icon"} variant={kind === "agents" && selected === index ? "secondary" : "ghost"} className={kind === "proposal" ? "design-toolbar-button design-toolbar-icon" : `rounded-none ${index === 1 ? "border-l border-border" : ""}`} aria-label={label} title={label} aria-pressed={selected === index} onClick={() => setSelected(index)}><Icon className={kind === "agents" ? "h-3.5 w-3.5" : undefined} aria-hidden /></Button>)}
</div>;
}
function InstructionSwitch() {
const [mode, setMode] = useState("read");
return <div className="flex w-fit items-center rounded-md border border-border p-0.5" role="group" aria-label="Instruction file view">
{["read", "edit", "raw"].map(value => <Button key={value} type="button" size="sm" variant={mode === value ? "secondary" : "ghost"} className="capitalize" aria-pressed={mode === value} onClick={() => setMode(value)}>{value}</Button>)}
</div>;
}
function FileSwitch() {
const [mode, setMode] = useState<FilePreviewMode>("rendered");
return <FilePreviewModeToggle mode={mode} onChange={setMode} label="File preview mode" />;
}
function ModelSwitch() {
const [lane, setLane] = useState("primary");
return <div className="flex w-full overflow-hidden rounded-md border border-border" role="radiogroup" aria-label="Model lane">
{["primary", "custom"].map(value => <button key={value} type="button" role="radio" aria-checked={lane === value} className={`flex-1 px-2 py-1 text-xs capitalize transition-colors hover:bg-accent/40 ${lane === value ? "bg-accent text-foreground" : ""}`} onClick={() => setLane(value)}>{value === "primary" ? "Primary" : "Override"}</button>)}
</div>;
}
export function SegmentedControllersPreview({ width, disableAgentActions, onWidthChange }: SegmentedControllersPreviewProps) {
return <main data-testid="segmented-controllers-preview" className="min-h-dvh space-y-8 bg-background p-6 font-sans text-muted-foreground sm:p-10">
<header className="space-y-3"><p className="text-xs">Design proposals · Components</p><h1 className="text-2xl font-semibold text-foreground">Segmented controllers</h1>
<p className="max-w-3xl text-sm">Compare current connected choices: panel tabs, layout switches, file modes and model lanes. Each example keeps its existing styling and semantics; interactions affect local fixture state only.</p>
<label className="flex w-fit items-center gap-3 text-xs">Container width<select aria-label="Segmented controller container width" className="rounded-md border border-border bg-background px-3 py-2 text-sm" value={width} onChange={event => onWidthChange?.(event.target.value as SegmentedControllersPreviewProps["width"])}><option value="full">Full</option><option value="narrow">Narrow</option></select></label>
</header>
<div className={`space-y-8 ${width === "narrow" ? "max-w-sm" : "max-w-none"}`}>
<Specimen title="Audit activity scope" source="AuditFeed · production TabsList/TabsTrigger composition. The Agent Actions disabled state is controlled in Storybook."><PanelSwitch label="Activity scope" items={["Activity", "Agent Actions"]} disabled={disableAgentActions} /></Specimen>
<Specimen title="Task layout · proposal" source="TaskListToolbar · Design Proposals and sandbox composition, using the shared design-view-toggle styling."><div className="design-page-toolbar" data-canonical-toolbar><LayoutSwitch kind="proposal" /></div></Specimen>
<Specimen title="Task layout · production" source="IssuesList and LegacyIssuesList · inline production list/board composition with native pressed buttons."><LayoutSwitch kind="issues" /></Specimen>
<Specimen title="Agent layout" source="Agents · production List / Org chart shared Button composition."><LayoutSwitch kind="agents" /></Specimen>
<Specimen title="Instruction file mode" source="AgentDetail · production Read / Edit / Raw Button composition."><InstructionSwitch /></Specimen>
<Specimen title="File preview mode" source="FilePreviewModeToggle · actual shared production component, Rendered / Raw."><FileSwitch /></Specimen>
<Specimen title="Secret ownership" source="Secrets · production two-column TabsList composition. No secrets are read or created."><PanelSwitch label="Secret ownership" items={["Organization", "Each user"]} grid /></Specimen>
<Specimen title="Secret value source" source="Secrets · same two-column composition with Managed value / External reference choices."><PanelSwitch label="Secret value source" items={["Managed value", "External reference"]} grid /></Specimen>
<Specimen title="Goal content" source="GoalDetail · default production TabsList composition, including count labels."><PanelSwitch label="Goal content" items={["Sub-Goals (3)", "Projects (2)"]} /></Specimen>
<Specimen title="Model lane" source="IssueProperties · production inline radio composition. Preserves existing click behavior; keyboard arrow navigation is a consolidation gap."><ModelSwitch /></Specimen>
</div>
<p className="max-w-3xl text-xs">Inline page controls are isolated compositions of their production primitives, not full production-page mounts. These examples establish a comparison surface, not backend or accessibility acceptance. No existing app controls have been restyled.</p>
</main>;
}