mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 12:04:41 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Its UI is the operator's daily surface: task lists, boards, budgets, agent status — all built on shadcn components and Tailwind > - Visual values (colors, spacing, type sizes, radii) were hardcoded at ~1,600 call sites: the same "small gray label" was 9/10/11px depending on the file, charts disagreed with chips about status colors, two toggle-switch implementations coexisted in two greens, and there was no visual regression coverage > - This made the UI drift-prone and made any restyle a hundreds-of-files project, which discourages design iteration > - This pull request extracts visual values into a single token layer in `ui/src/index.css`, adds a Storybook visual regression suite backed by external immutable baseline archives, and then applies a deliberate retune reviewed change-by-change on screenshot diffs > - The benefit is that Paperclip's look becomes a config surface: retheming is a token edit reviewed as a snapshot diff, drift is blocked by a token gate, and future UI PRs can prove exactly what changed visually without committing hundreds of PNGs ## Linked Issues or Issue Description No existing public issue covers this work (searched "design tokens", "visual regression", "design system" across issues and PRs). Related in spirit: Refs #8982 (theming a hardcoded panel — a one-off instance of the same problem class this PR addresses systematically). **Problem (feature-request form):** UI visual values are hardcoded per call site with no source of truth and no regression coverage; consistency depends on reviewer memory, and restyling requires mass file edits. **Proposed solution (this PR):** a single token layer + enforcement gate + externally stored visual snapshot suite, then an intentional restyle on top of that foundation. ## What Changed - **Token extraction (zero visual change, machine-verified during development):** committed codemods (`scripts/codemod-*.mjs`) moved ~1,600 hardcoded color/type/spacing/radius/shadow/misc values into named tokens in a non-inline `:root` block of `ui/src/index.css`. - **Visual regression suite:** `pnpm test:storybook-visual` covers 255 stories × light/dark = 510 Playwright screenshots at `maxDiffPixels: 0`, plus new primitive-coverage stories and deterministic-render fixes. - **External visual baselines:** committed PNG snapshots were removed. `tests/storybook-visual/baseline-manifest.json` pins an immutable archive URL/hash/size/count, and `scripts/storybook-visual-baseline.mjs` handles `download`, `verify`, `pack`, and trusted maintainer `upload` flows. - **Opt-in visual CI artifacts:** added a `Storybook Visual` workflow that runs on manual dispatch or PRs labeled `storybook-visual`, downloads/verifies the baseline, runs Playwright, and uploads Playwright report/test-result artifacts for review. Normal PR runs do not mutate baseline objects. - **Token gate:** `pnpm check:token-gates` — zero hex literals, zero arbitrary bracket values, zero raw font-sizes in `ui/src/components/**` and `ui/src/pages/**`, with a documented inline allowlist for legitimate opt-outs. - **Theme retune (intentional, snapshot-reviewed):** new base theme values; radius ladder derived from a single `--radius` knob; micro-type cluster collapsed to a named ladder (`--text-nano/micro/compact` + Tailwind `text-xs`/`text-sm`); letter-spacing collapsed to named steps. - **One status-color vocabulary:** charts, quota/budget bar fills, RUNNING/live chips, and liveness indicators all use the canonical `--status-*` hues. Light-mode legibility fixes for red alert surfaces that used dark-tuned text classes. - **One switch:** `ToggleSwitch` restyled to the registry capsule form, second hand-rolled implementation removed, and all call sites unified. - **Docs:** `DESIGN.md` is the design contract; `doc/design/` holds audit reports, decision logs, and updated guidance for external baseline review/update workflows. - Dead code removed (`agentStatusBadge` duplicate map), byte-identical contrast constants consolidated, semantic renames (`--project-seed`/`--project-none`, `--liveness-blue`). ## Verification - `pnpm check:token-gates` — 3/3 gates CLEAN during the design-system run - `pnpm typecheck` && `pnpm --filter @paperclipai/ui build` — green during the design-system run - `node --test scripts/__tests__/storybook-visual-baseline.test.mjs` — pass after external-baseline rework - `pnpm exec tsc --noEmit --pretty false --module NodeNext --moduleResolution NodeNext --target ES2022 --types node,@playwright/test tests/storybook-visual/playwright.config.ts tests/storybook-visual/storybook-visual.spec.ts` — pass after external-baseline rework - `git diff --check origin/pr/9134..HEAD` — pass after external-baseline rework - `find tests/storybook-visual -type f -name '*.png' -print | wc -l` — `0` - `node scripts/storybook-visual-baseline.mjs verify` — intentionally fails closed until the first trusted maintainer publishes the baseline archive and updates `baseline-manifest.json` ## Risks - **Large but shallow:** the PR still touches many UI files due to mechanical token extraction and retune work, but committed PNG snapshot churn has been removed from the branch. - **Baseline publication required before the visual suite can pass in clean clones:** the manifest currently has placeholder archive metadata. A trusted maintainer must publish the first immutable archive, then update `baseline-manifest.json`. - **Rendering platform variance:** the external baseline should be captured in the documented Linux/Chromium environment. Future CI runs verify against the pinned archive and fail closed on checksum/count mismatch. - **Visual CI is opt-in while stabilizing:** add the `storybook-visual` label or dispatch the workflow manually to produce downloadable Playwright report/test-result artifacts. - **Scheduled follow-ups, deliberately out of scope:** Tailwind palette classes map to semantic tokens in a dedicated pass; card/pill component consolidation; ESLint ratchet. Tracked in `doc/design/DECISION-SHEET.md`. ## Model Used Claude Fable 5 (Anthropic, `claude-fable-5`, Mythos-class tier) with extended thinking, running in Claude Code with tool use; mechanical phases delegated to Claude Sonnet subagents. Follow-up external-baseline rework assisted by OpenAI Codex (`gpt-5` coding agent with repository, terminal, and GitHub tool use). All bulk rewrites executed via deterministic, idempotent scripts committed in `scripts/`; intentional visual changes were human-reviewed on screenshot contact sheets. ## 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) - [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 - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run targeted local verification and documented the intentional baseline-publication failure above - [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 any risks above - [ ] All Paperclip CI gates are green *(pending new CI run after this rework)* - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups *(pending review)* - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) and OpenAI Codex --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Dotta <bippadotta@protonmail.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
259 lines
11 KiB
TypeScript
259 lines
11 KiB
TypeScript
import { useEffect, useMemo, useState } from "react";
|
|
import type { AgentPermissions, TrustPreset } from "@paperclipai/shared";
|
|
import { Lock, ShieldAlert } from "lucide-react";
|
|
import { Button } from "@/components/ui/button";
|
|
import { Field, CollapsibleSection } from "./agent-config-primitives";
|
|
import {
|
|
buildPermissionsForTrustPreset,
|
|
clearSingleLowTrustBoundaryTarget,
|
|
getLowTrustBoundary,
|
|
getSingleLowTrustBoundaryTarget,
|
|
getTrustPreset,
|
|
isCeLowTrustBoundaryEditable,
|
|
lowTrustBoundaryHasScope,
|
|
setSingleLowTrustBoundaryTarget,
|
|
summarizeLowTrustBoundaryTarget,
|
|
TRUST_PRESET_DESCRIPTIONS,
|
|
TRUST_PRESET_LABELS,
|
|
type LowTrustBoundaryTarget,
|
|
} from "../lib/trust-policy-ui";
|
|
import { cn } from "../lib/utils";
|
|
|
|
const inputClass =
|
|
"w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
|
|
|
|
function formatCount(value: readonly unknown[] | undefined, singular: string, plural: string) {
|
|
const count = value?.length ?? 0;
|
|
if (count === 0) return "-";
|
|
return `${count} ${count === 1 ? singular : plural}`;
|
|
}
|
|
|
|
function PolicyRow({ label, value }: { label: string; value: string }) {
|
|
return (
|
|
<div className="flex items-start justify-between gap-3 py-1.5 text-sm">
|
|
<span className="shrink-0 text-xs text-muted-foreground">{label}</span>
|
|
<span className={cn("min-w-0 text-right", value === "-" && "text-muted-foreground")}>{value}</span>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export interface LowTrustBoundaryCandidate {
|
|
id: string;
|
|
label: string;
|
|
}
|
|
|
|
type LowTrustBoundaryTargetType = LowTrustBoundaryTarget["type"];
|
|
|
|
const BOUNDARY_TARGET_LABELS: Record<LowTrustBoundaryTargetType, string> = {
|
|
project: "Project",
|
|
root_issue: "Root issue",
|
|
issue: "Issue",
|
|
};
|
|
|
|
export function TrustPresetSection({
|
|
permissions,
|
|
onChange,
|
|
disabled,
|
|
companyId,
|
|
projectCandidates = [],
|
|
issueCandidates = [],
|
|
candidatesLoading,
|
|
}: {
|
|
permissions: Partial<AgentPermissions> | null | undefined;
|
|
onChange: (permissions: Partial<AgentPermissions>) => void;
|
|
disabled?: boolean;
|
|
companyId?: string | null;
|
|
projectCandidates?: LowTrustBoundaryCandidate[];
|
|
issueCandidates?: LowTrustBoundaryCandidate[];
|
|
candidatesLoading?: boolean;
|
|
}) {
|
|
const [policyOpen, setPolicyOpen] = useState(false);
|
|
const preset = getTrustPreset(permissions);
|
|
const boundary = getLowTrustBoundary(permissions);
|
|
const boundaryTarget = getSingleLowTrustBoundaryTarget(boundary);
|
|
const [targetType, setTargetType] = useState<LowTrustBoundaryTargetType>(boundaryTarget?.type ?? "project");
|
|
const lowTrust = preset === "low_trust_review";
|
|
const hasScope = lowTrustBoundaryHasScope(boundary);
|
|
const boundaryEditable = isCeLowTrustBoundaryEditable(boundary);
|
|
const policy = permissions?.authorizationPolicy ?? null;
|
|
const managedPermissions = useMemo(
|
|
() => buildPermissionsForTrustPreset(permissions, preset),
|
|
[permissions, preset],
|
|
);
|
|
|
|
useEffect(() => {
|
|
if (boundaryTarget) setTargetType(boundaryTarget.type);
|
|
}, [boundaryTarget?.type]);
|
|
|
|
function handlePresetChange(value: string) {
|
|
const nextPreset: TrustPreset = value === "low_trust_review" ? "low_trust_review" : "standard";
|
|
onChange(buildPermissionsForTrustPreset(permissions, nextPreset));
|
|
}
|
|
|
|
function handleBoundaryTargetChange(targetId: string) {
|
|
if (!companyId || !targetId) return;
|
|
onChange(setSingleLowTrustBoundaryTarget(permissions, companyId, { type: targetType, id: targetId }));
|
|
}
|
|
|
|
function handleClearBoundary() {
|
|
onChange(clearSingleLowTrustBoundaryTarget(permissions));
|
|
}
|
|
|
|
const targetCandidates = targetType === "project" ? projectCandidates : issueCandidates;
|
|
const boundaryValue = boundaryTarget?.type === targetType ? boundaryTarget.id : "";
|
|
|
|
return (
|
|
<div>
|
|
<h3 className="mb-3 text-sm font-medium">Trust</h3>
|
|
<div className="rounded-lg border border-border p-4 space-y-3">
|
|
<Field label="Trust preset" hint="Choose how broadly this agent can read and act on Paperclip work objects.">
|
|
<select
|
|
className={inputClass}
|
|
value={preset}
|
|
onChange={(event) => handlePresetChange(event.target.value)}
|
|
disabled={disabled}
|
|
>
|
|
<option value="standard">{TRUST_PRESET_LABELS.standard}</option>
|
|
<option value="low_trust_review">{TRUST_PRESET_LABELS.low_trust_review}</option>
|
|
</select>
|
|
</Field>
|
|
<p className="text-xs text-muted-foreground">{TRUST_PRESET_DESCRIPTIONS[preset]}</p>
|
|
|
|
{lowTrust ? (
|
|
<div
|
|
role={hasScope ? "status" : "alert"}
|
|
aria-live="polite"
|
|
className={cn(
|
|
"rounded-md border px-3 py-2.5 text-sm flex gap-2",
|
|
hasScope
|
|
? "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-100"
|
|
: "border-destructive/30 bg-destructive/10 text-destructive",
|
|
)}
|
|
>
|
|
{hasScope ? (
|
|
<ShieldAlert className="mt-0.5 h-4 w-4 shrink-0" />
|
|
) : (
|
|
<Lock className="mt-0.5 h-4 w-4 shrink-0" />
|
|
)}
|
|
<div className="min-w-0 flex-1 space-y-2">
|
|
<div>
|
|
<p className="font-medium">
|
|
{hasScope ? "Containment active" : "Containment not configured"}
|
|
</p>
|
|
<p className="mt-1 text-xs leading-5">
|
|
{hasScope
|
|
? "This agent can only read and mutate work inside its assigned review boundary. Raw output is quarantined from higher-trust agents until a trusted reviewer promotes it."
|
|
: "This agent is set to low-trust review, but no project, root issue, or issue scope is set in the core policy. Add a scope before this agent can run without denial."}
|
|
</p>
|
|
</div>
|
|
{boundaryEditable ? (
|
|
<div className="rounded-md border border-border/70 bg-background/70 p-3 text-foreground space-y-3">
|
|
<div className="grid gap-3 sm:grid-cols-(--gtc-12)">
|
|
<Field label="Boundary type">
|
|
<select
|
|
className={inputClass}
|
|
value={targetType}
|
|
onChange={(event) => setTargetType(event.target.value as LowTrustBoundaryTargetType)}
|
|
disabled={disabled}
|
|
>
|
|
<option value="project">Project</option>
|
|
<option value="root_issue">Root issue</option>
|
|
<option value="issue">Issue</option>
|
|
</select>
|
|
</Field>
|
|
<Field label={BOUNDARY_TARGET_LABELS[targetType]}>
|
|
<select
|
|
className={inputClass}
|
|
value={boundaryValue}
|
|
onChange={(event) => handleBoundaryTargetChange(event.target.value)}
|
|
disabled={disabled || !companyId || candidatesLoading || targetCandidates.length === 0}
|
|
>
|
|
<option value="">
|
|
{candidatesLoading
|
|
? "Loading…"
|
|
: targetCandidates.length === 0
|
|
? `No ${targetType === "project" ? "projects" : "issues"} available`
|
|
: "Select boundary"}
|
|
</option>
|
|
{targetCandidates.map((candidate) => (
|
|
<option key={candidate.id} value={candidate.id}>
|
|
{candidate.label}
|
|
</option>
|
|
))}
|
|
</select>
|
|
</Field>
|
|
</div>
|
|
<div className="flex flex-wrap items-center justify-between gap-2">
|
|
<p className="text-xs text-muted-foreground">
|
|
CE saves one containment boundary at a time. Saved policies include this company id.
|
|
</p>
|
|
{boundaryTarget ? (
|
|
<Button
|
|
type="button"
|
|
size="sm"
|
|
variant="outline"
|
|
className="h-7 px-2.5 text-xs"
|
|
onClick={handleClearBoundary}
|
|
disabled={disabled}
|
|
>
|
|
Clear boundary
|
|
</Button>
|
|
) : null}
|
|
</div>
|
|
</div>
|
|
) : (
|
|
<div className="rounded-md border border-border/70 bg-background/70 p-3 text-foreground">
|
|
<p className="text-sm font-medium">Managed by EE/API</p>
|
|
<p className="mt-1 text-xs leading-5 text-muted-foreground">
|
|
This policy has {summarizeLowTrustBoundaryTarget(boundary).toLowerCase()} and cannot be edited by the CE single-boundary editor.
|
|
</p>
|
|
</div>
|
|
)}
|
|
<p className="text-xs text-muted-foreground">
|
|
Want to set more than one containment boundary?{" "}
|
|
<a
|
|
className="underline underline-offset-2 hover:text-foreground"
|
|
href="https://paperclip.ing/ee"
|
|
target="_blank"
|
|
rel="noreferrer"
|
|
>
|
|
Get Paperclip EE.
|
|
</a>
|
|
</p>
|
|
<CollapsibleSection
|
|
title="View policy"
|
|
open={policyOpen}
|
|
onToggle={() => setPolicyOpen((open) => !open)}
|
|
>
|
|
<div className="divide-y divide-border/60 text-foreground">
|
|
<PolicyRow label="Preset" value="Low-trust review v1" />
|
|
<PolicyRow label="Raw output" value="Quarantined from higher-trust agents" />
|
|
<PolicyRow label="Projects" value={formatCount(boundary?.projectIds, "project", "projects")} />
|
|
<PolicyRow label="Root issue" value={boundary?.rootIssueId ? boundary.rootIssueId.slice(0, 8) : "-"} />
|
|
<PolicyRow label="Explicit issues" value={formatCount(boundary?.issueIds, "issue", "issues")} />
|
|
<PolicyRow label="Allowed agents" value={formatCount(boundary?.allowedAgentIds, "agent", "agents")} />
|
|
<PolicyRow label="Allowed tools" value={boundary?.allowedToolClasses?.join(" · ") || "-"} />
|
|
<PolicyRow label="Allowed secrets" value={formatCount(boundary?.allowedSecretBindingIds, "binding", "bindings")} />
|
|
<PolicyRow label="Promotion target" value={boundary?.outputPromotionTarget?.issueId?.slice(0, 8) ?? "-"} />
|
|
<PolicyRow
|
|
label="EE fields"
|
|
value={Object.keys(policy ?? {}).some((key) => !["trustPreset", "reviewPreset", "trustBoundary"].includes(key))
|
|
? "Custom advanced policy fields preserved"
|
|
: "-"}
|
|
/>
|
|
</div>
|
|
</CollapsibleSection>
|
|
</div>
|
|
</div>
|
|
) : null}
|
|
|
|
{managedPermissions.authorizationPolicy?.reviewPreset ? null : (
|
|
<p className="text-xs text-muted-foreground">
|
|
Advanced permissions remain editable through the EE permissions extension when installed.
|
|
</p>
|
|
)}
|
|
</div>
|
|
</div>
|
|
);
|
|
}
|