Files
PaperClipAI/ui/src/components/TrustPresetSection.tsx
T
c07e650cd7 feat(ui): single-source design tokens, visual regression suite, and theme retune (#9134)
## 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>
2026-07-07 16:22:16 -05:00

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>
);
}