Full @superset/ui coverage on /design + usage-drift audit page

.agents/skills/design-system/reference.md

@@ -0,0 +1,88 @@
+# Design system reference
+
+Source of truth for `@superset/ui` conventions and known gaps. This is a living backlog, not a
+finished spec — update it as decisions land (starting with the `/design/audit` review) and as new
+gaps get found.
+
+## Token table
+
+Defined in `apps/desktop/src/renderer/globals.css` (`:root` = dark/"ember" fallback,
+`:root.light` = light fallback), mapped into Tailwind's `--color-*`/`--radius-*` namespace via
+`@theme inline`. Match hardcoded colors against these before assuming a new token is needed.
+
+| Tailwind class | CSS variable |
+| --- | --- |
+| `bg-background` / `text-background` | `--background` |
+| `bg-foreground` / `text-foreground` | `--foreground` |
+| `bg-card` / `text-card-foreground` | `--card`, `--card-foreground` |
+| `bg-popover` / `text-popover-foreground` | `--popover`, `--popover-foreground` |
+| `bg-primary` / `text-primary-foreground` | `--primary`, `--primary-foreground` |
+| `bg-secondary` / `text-secondary-foreground` | `--secondary`, `--secondary-foreground` |
+| `bg-muted` / `text-muted-foreground` | `--muted`, `--muted-foreground` |
+| `bg-accent` / `text-accent-foreground` | `--accent`, `--accent-foreground` |
+| `bg-tertiary` / `bg-tertiary-active` | `--tertiary`, `--tertiary-active` |
+| `bg-destructive` / `text-destructive-foreground` | `--destructive`, `--destructive-foreground` |
+| `bg-warning` / `text-warning-foreground` | `--warning`, `--warning-foreground` |
+| `border-border` | `--border` |
+| `border-input` | `--input` |
+| `ring-ring` | `--ring` |
+| `bg-chart-1` … `bg-chart-5` | `--chart-1` … `--chart-5` |
+| `bg-sidebar*` / `text-sidebar*` / `border-sidebar-border` | `--sidebar*` |
+| `bg-highlight` / `text-highlight-foreground` | `--highlight`, `--highlight-foreground` |
+| — (used via CSS, not a utility) | `--highlight-match`, `--highlight-active` |
+| `bg-fill-hover` / `bg-fill-selected` | `--fill-hover`, `--fill-selected` |
+| `rounded-sm` / `rounded-md` / `rounded-lg` / `rounded-xl` | derived from `--radius` |
+
+No spacing-scale tokens beyond Tailwind's defaults — spacing isn't part of this audit.
+
+## `packages/ui/src/components/ui/*` conventions
+
+Observed across the 55 shadcn-derived primitives; deviations are called out below rather than
+silently followed:
+
+- `cn()` (from `packages/ui/src/lib/utils.ts`) merges every `className`. Only thin Radix
+  pass-throughs with nothing to merge (`aspect-ratio.tsx`, `collapsible.tsx`, `sonner.tsx`) skip it.
+- `data-slot="<component>"` on every primitive except `sonner.tsx`, `spinner.tsx`.
+- `cva()` + `VariantProps<typeof xVariants>` for anything with a real variant enum (button, badge,
+  alert, item, field, empty, input-group, button-group, navigation-menu, sidebar, toggle).
+  `toggle-group.tsx` correctly reuses `toggleVariants` via context instead of redefining it.
+- `asChild` / `Slot` forwarding is reserved for components meant to render as a link/anchor
+  (`button.tsx`, `badge.tsx`) — not applied elsewhere, correctly.
+
+## Known deviations (documented, not yet fixed)
+
+- **`input.tsx`** hand-rolls its `variant?: "default" | "ghost"` prop as a plain object instead of
+  `cva()`, and isn't typed with `VariantProps<>` like `button.tsx`/`badge.tsx` are. Bring it in line
+  with the rest of the variant-bearing primitives.
+- **Showcase gaps**: `chart.tsx`, `form.tsx`, and the full `sidebar.tsx` nav-shell aren't demoed
+  anywhere on `apps/web/src/app/design` (primitives page). `sidebar-card.tsx` *is* shown, via
+  `DataSection.tsx` — only the nav shell itself is missing.
+
+## Promotion-candidate backlog
+
+Tracked today on `/design/superset` → "Shared app components" → Desktop renderer, with import-site
+counts. Coupling assessed by reading each implementation:
+
+| Component | Path | Coupling | Verdict |
+| --- | --- | --- | --- |
+| `PickerTrigger` | `apps/desktop/src/renderer/components/PickerTrigger` | Pure UI — wraps `@superset/ui/button` with `cn()`, no app-specific imports | Ready to promote as-is |
+| `AgentSelect` | `.../renderer/components/AgentSelect` | Wraps `@superset/ui/select` cleanly, but hardcodes `useNavigate` (`@tanstack/react-router`) and desktop's preset-icon asset store | Needs navigation/icon-lookup lifted to props before promotion |
+| `MarkdownRenderer` | `.../renderer/components/MarkdownRenderer` | Uses `cn()`, but pulls `useMarkdownStyle` from a renderer Zustand store plus a `SelectionContextMenu` subcomponent | Style-config logic is portable; the global-store hook needs to become a prop |
+| `ColorSelector` | `.../renderer/components/ColorSelector` | Uses `cn()` and tokens correctly, but imports `PROJECT_COLORS`/`PROJECT_COLOR_DEFAULT` from an app-domain constants file | Needs the palette passed as a prop to become UI-only |
+
+Other candidates on the same list (`HotkeyMenuShortcut`, `ColorSelector`, `HotkeyTooltip`,
+`EmojiTextInput`, `ThemeSwatch`, `UpdatesPill`, `OpenInButton`, `AgentModelSelect`,
+`MarkdownEditor`) haven't been individually assessed yet — do that before promoting them.
+
+## Usage-drift backlog (found, not yet fixed)
+
+- **Hardcoded color literals**: 40 files in `apps/desktop/src` use a hex/rgb literal instead of a
+  token, outside theme/story/test files.
+- **Inline styles**: 86 files use `style={{...}}`; many are legitimately dynamic (runtime-computed
+  values, CSS properties with no Tailwind equivalent) — each needs a static/dynamic judgment call,
+  not a blind rewrite.
+- **Standard-component usage variance**: see `/design/audit` — Button usage alone spans ~11 distinct
+  visual treatments across canonical-variant-with-override and fully bespoke non-`Button` elements.
+  Badge and Input show smaller-scale versions of the same pattern. This is the highest-leverage
+  fix, and it's blocked on a human decision (which treatments are canonical) before any migration
+  or lint rule can be written — see `/design/audit` and reply with verdicts per bucket.

apps/web/package.json

@@ -26,6 +26,7 @@
 		"@trpc/server": "11.16.0",
 		"@trpc/tanstack-react-query": "11.16.0",
 		"@uiw/react-md-editor": "4.1.0",
+		"@xyflow/react": "12.10.2",
 		"better-auth": "1.6.22",
 		"framer-motion": "12.38.0",
 		"geist": "1.7.0",
@@ -38,7 +39,9 @@
 		"posthog-node": "5.28.8",
 		"react": "19.2.3",
 		"react-dom": "19.2.3",
+		"react-hook-form": "7.72.0",
 		"react-icons": "5.6.0",
+		"recharts": "2.15.4",
 		"require-in-the-middle": "8.0.1",
 		"server-only": "0.0.1",
 		"superjson": "2.2.6",

apps/web/src/app/design/audit/components/BadgeAuditSection/BadgeAuditSection.tsx

@@ -0,0 +1,35 @@
+import { Badge } from "@superset/ui/badge";
+
+import { ComponentCard } from "../../../components/ComponentCard";
+import { ShowcaseSection } from "../../../components/ShowcaseSection";
+
+export function BadgeAuditSection() {
+	return (
+		<ShowcaseSection
+			id="badge-audit"
+			index="02"
+			title="Badge — same disease, smaller scale"
+			description="31 files, 49 occurrences. Mostly clean; one repeated override."
+		>
+			<ComponentCard
+				title="1 · Canonical, correct"
+				importPath="PermissionsSettings.tsx"
+				copyable={false}
+				description="variant only, no className."
+			>
+				<Badge variant="secondary">Admin</Badge>
+			</ComponentCard>
+
+			<ComponentCard
+				title="2 · Unofficial &quot;compact&quot; size"
+				importPath="OrganizationSettings.tsx, PresetRow.tsx (copy-pasted ~5x)"
+				copyable={false}
+				description="className=&quot;text-[10px] h-4 px-1.5&quot; — badgeVariants has no size axis, so every caller re-derives one."
+			>
+				<Badge variant="secondary" className="h-4 px-1.5 text-[10px]">
+					You
+				</Badge>
+			</ComponentCard>
+		</ShowcaseSection>
+	);
+}

apps/web/src/app/design/audit/components/BadgeAuditSection/index.ts

@@ -0,0 +1 @@
+export { BadgeAuditSection } from "./BadgeAuditSection";

apps/web/src/app/design/audit/components/ButtonAuditSection/ButtonAuditSection.tsx

@@ -0,0 +1,208 @@
+"use client";
+
+import { Button } from "@superset/ui/button";
+import {
+	ArrowDown,
+	ChevronDown,
+	ChevronRight,
+	Copy,
+	ExternalLink,
+	MoreVertical,
+	Plus,
+	RefreshCw,
+	Terminal,
+	TriangleAlert,
+	X,
+} from "lucide-react";
+
+import { ComponentCard } from "../../../components/ComponentCard";
+import { ShowcaseSection } from "../../../components/ShowcaseSection";
+
+export function ButtonAuditSection() {
+	return (
+		<ShowcaseSection
+			id="button-audit"
+			index="01"
+			title="Button — treatments in the wild"
+			description="213 files, 449 real <Button> call sites, plus 363 raw <button> occurrences. Sampled below."
+		>
+			<ComponentCard
+				title="1 · Canonical, correct"
+				importPath="WorkspacesListView.tsx"
+				copyable={false}
+				description="variant + size only, no className. This is the target."
+			>
+				<Button variant="ghost" size="icon" aria-label="More options">
+					<MoreVertical />
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="2 · Canonical + layout-only className"
+				importPath="CommitInput.tsx"
+				copyable={false}
+				description="flex-1/gap are fine. Real file also adds h-7 text-xs, redundant with size=&quot;sm&quot; — trim on migration."
+			>
+				<Button variant="secondary" size="sm" className="flex-1 gap-1.5">
+					Commit
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="3 · Reimplements existing size=&quot;xs&quot;"
+				importPath="DeleteWorkspaceDialog.tsx (+6 more, copy-pasted verbatim)"
+				copyable={false}
+				description="size=&quot;sm&quot; className=&quot;h-7 px-3 text-xs&quot; — size=&quot;xs&quot; already does this correctly."
+			>
+				<Button variant="ghost" size="sm" className="h-7 px-3 text-xs">
+					Cancel
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="4 · Undersized icon override"
+				importPath="ChangesHeader.tsx, useOrderedSections.tsx"
+				copyable={false}
+				description="size=&quot;icon&quot; className=&quot;size-6 p-0&quot; — smaller than any defined icon size (icon-xs is size-7)."
+			>
+				<Button variant="ghost" size="icon" className="size-6 p-0">
+					<RefreshCw className="size-3.5" />
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="5a · Unofficial &quot;warning&quot; color"
+				importPath="PaymentFailedBanner.tsx"
+				copyable={false}
+				description="No warning variant exists in buttonVariants — this is hand-mixed from tokens."
+			>
+				<Button
+					variant="outline"
+					size="sm"
+					className="ml-auto h-7 shrink-0 border-warning/40 bg-warning/10 px-2.5 text-xs text-warning hover:bg-warning/20"
+				>
+					<TriangleAlert className="size-3.5" />
+					Update payment
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="5b · Unofficial &quot;destructive-ghost&quot; color"
+				importPath="FileDiffHeader.tsx"
+				copyable={false}
+				description="Same problem, different recolor — a second hand-mixed variant that doesn't exist."
+			>
+				<Button
+					variant="ghost"
+					size="icon"
+					className="size-6 text-destructive hover:text-destructive hover:bg-destructive/10"
+				>
+					<X className="size-3.5" />
+				</Button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="6 · Hand-built segmented group"
+				importPath="AddTabButton.tsx"
+				copyable={false}
+				description="Fakes ButtonGroup with manual rounded-*-none + shared borders instead of composing it."
+				span
+			>
+				<div className="flex">
+					<Button
+						variant="ghost"
+						className="h-7 gap-1 rounded-r-none border border-border/60 bg-muted/30 pl-2 pr-1.5 text-xs text-muted-foreground hover:bg-accent/60 hover:text-foreground"
+					>
+						<Terminal className="size-3.5" />
+						Terminal
+					</Button>
+					<Button
+						variant="ghost"
+						className="h-7 gap-1 rounded-none border border-l-0 border-border/60 bg-muted/30 px-1.5 text-xs text-muted-foreground hover:bg-accent/60 hover:text-foreground"
+					>
+						Browser
+					</Button>
+					<Button
+						variant="ghost"
+						size="icon"
+						className="size-7 rounded-l-none border border-l-0 border-border/60 bg-muted/30 px-1 text-muted-foreground hover:bg-accent/60 hover:text-foreground"
+					>
+						<ChevronDown className="size-3" />
+					</Button>
+				</div>
+			</ComponentCard>
+
+			<ComponentCard
+				title="7 · Bespoke flat-fill icon button"
+				importPath="NewWorkspaceButton.tsx"
+				copyable={false}
+				description="Raw <button>, never touches @superset/ui/button. Flat bg-fill-hover family."
+			>
+				<button
+					type="button"
+					className="group flex size-8 items-center justify-center rounded-md bg-fill-hover transition-colors hover:bg-fill-selected"
+				>
+					<Plus className="size-4" />
+				</button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="8 · Bespoke bordered-circle FAB"
+				importPath="ScrollToBottomButton.tsx"
+				copyable={false}
+				description="Raw <button>. Different family again: full radius, visible border, bg-background."
+			>
+				<button
+					type="button"
+					className="flex size-8 items-center justify-center rounded-full border border-border bg-background text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+				>
+					<ArrowDown className="size-4" />
+				</button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="9 · Bespoke glass/backdrop-blur toolbar button"
+				importPath="CodeBlockView.tsx (independently re-implemented in error.tsx)"
+				copyable={false}
+				description="Raw <button>. A third distinct family, duplicated by two different authors instead of shared."
+			>
+				<button
+					type="button"
+					className="flex h-6 w-6 items-center justify-center rounded border border-border bg-background/80 backdrop-blur transition-colors hover:bg-accent"
+				>
+					<Copy className="size-3" />
+				</button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="10 · Bespoke borderless hover-icon button"
+				importPath="ProjectHeader.tsx"
+				copyable={false}
+				description="Raw <button>. No default bg/border at all — a fourth family."
+			>
+				<button
+					type="button"
+					className="shrink-0 rounded p-1 transition-colors hover:bg-fill-hover"
+				>
+					<ChevronRight className="size-4 text-muted-foreground" />
+				</button>
+			</ComponentCard>
+
+			<ComponentCard
+				title="11 · Bare, no-chrome clickable icon"
+				importPath="MergedPortBadge.tsx, error.tsx, WorkspaceListItem.tsx (div role=&quot;button&quot;)"
+				copyable={false}
+				description="No radius/padding/bg at all — opacity-0 until group-hover. Hover this card to see it."
+			>
+				<div className="group flex size-8 items-center justify-center">
+					<button
+						type="button"
+						className="text-muted-foreground opacity-0 transition-opacity hover:text-primary focus-visible:opacity-100 focus-visible:outline-none group-hover:opacity-100"
+					>
+						<ExternalLink className="size-3.5" />
+					</button>
+				</div>
+			</ComponentCard>
+		</ShowcaseSection>
+	);
+}

apps/web/src/app/design/audit/components/ButtonAuditSection/index.ts

@@ -0,0 +1 @@
+export { ButtonAuditSection } from "./ButtonAuditSection";

apps/web/src/app/design/audit/components/InputAuditSection/InputAuditSection.tsx

@@ -0,0 +1,36 @@
+import { Input } from "@superset/ui/input";
+
+import { ComponentCard } from "../../../components/ComponentCard";
+import { ShowcaseSection } from "../../../components/ShowcaseSection";
+
+export function InputAuditSection() {
+	return (
+		<ShowcaseSection
+			id="input-audit"
+			index="03"
+			title="Input — one recurring override"
+			description="54 files, 84 occurrences. Mostly clean; one repeated full-chrome strip."
+		>
+			<ComponentCard
+				title="1 · Canonical, correct"
+				importPath="RenameBranchDialog.tsx"
+				copyable={false}
+				description="Default variant, no className."
+			>
+				<Input placeholder="Branch name" className="max-w-56" />
+			</ComponentCard>
+
+			<ComponentCard
+				title="2 · Borderless inline override"
+				importPath="PromptGroup.tsx (repeated with slight variation twice)"
+				copyable={false}
+				description="Strips the component's chrome entirely via className. Input already has variant=&quot;ghost&quot; — close, but doesn't match (padding/height differ) — worth comparing directly."
+			>
+				<Input
+					placeholder="Workspace name (optional)"
+					className="h-auto min-w-0 flex-1 border-none bg-transparent px-0 text-base font-medium shadow-none placeholder:text-muted-foreground/40 focus-visible:ring-0"
+				/>
+			</ComponentCard>
+		</ShowcaseSection>
+	);
+}

apps/web/src/app/design/audit/components/InputAuditSection/index.ts

@@ -0,0 +1 @@
+export { InputAuditSection } from "./InputAuditSection";