diff --git a/docs/superpowers/plans/2026-06-08-design-kit-consistency.md b/docs/superpowers/plans/2026-06-08-design-kit-consistency.md new file mode 100644 index 0000000..6b0890c --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-design-kit-consistency.md @@ -0,0 +1,211 @@ +# Design-Kit Consistency — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add three shared helpers (`useLang`, `segmentClass`, `rowStateClass`), adopt them across the duplicated sites, and apply behavior-preserving kit one-offs (delete dead Card, sidebar focusRing, login PageTitle, field-list Badge, size-4, icon dismiss buttons). + +**Architecture:** Task 1 creates the helpers + deletes Card (additive/safe). Task 2 adopts the 3 helpers across 6 + 3 + 4 sites. Task 3 applies the one-off cleanups + full gate. Behavior-preserving throughout; `check:colors`/`check:size`/existing component tests are the guards. + +**Tech Stack:** React 19 + TS + pnpm, Tailwind v4 (token classes + `cn`), react-i18next, Base UI, Vitest 4 + RTL. + +**Conventions:** pnpm; **no `any`/`eslint-disable`/`@ts-ignore`**; no codename; double-quote+semicolon; token classes only (`check:colors`). `tsconfig` has `noUnusedLocals`, so remove any destructure that becomes unused. + +**Spec:** `docs/superpowers/specs/2026-06-08-design-kit-consistency-design.md` + +**Key facts (verified current):** +- `lib/focus-ring.ts` exports `focusRing = "outline-none focus-visible:ring-3 focus-visible:ring-ring/50"`. `cn` is `@/lib/utils`. +- `Button` (`@/components/ui/button`) has sizes incl. `icon-sm`. `Badge` (`@/components/ui/badge`) has a `secondary` variant. `PageTitle` (`@/components/ui/page-title`) is an `

` styled `text-2xl font-semibold tracking-tight`. +- `components/ui/card.tsx` has ZERO importers and no `card.stories`. +- `useLang` sites (each currently `const lang = i18n.language.startsWith("sv") ? "sv" : "en";`): `objects/object-detail.tsx:59`, `objects/field-input.tsx:32`, `vocab/vocabulary-terms.tsx:13`, `vocab/vocabulary-list.tsx:17`, `fields/field-list.tsx:27`, `authorities/authorities-page.tsx:19`. +- `segmentClass` sites: `objects/objects-table.tsx:174` (`` className={`${focusRing} rounded-md px-2 py-1 ${active ? "bg-primary text-primary-foreground" : "border"}`} ``), `search/search-panel.tsx:76` (`className={cn("rounded-md px-2 py-0.5", focusRing, active ? "bg-primary text-primary-foreground" : "border")}`), `authorities/authorities-page.tsx:41` (`cn("rounded-md px-3 py-1 text-sm", focusRing, isActive ? "bg-primary text-primary-foreground" : "border")`). +- `rowStateClass` sites: `objects/objects-table.tsx:252` (`selected ? "bg-primary/10" : "hover:bg-muted"`), `vocab/vocabulary-list.tsx:113` (`isActive ? "bg-primary/10" : "hover:bg-muted"`), `search/search-result-row.tsx:15` (`isActive ? "bg-primary/10" : "hover:bg-muted"`), `fields/field-list.tsx:86` (`def.key === selectedKey ? "bg-primary/10" : ""` — note the missing idle hover). + +--- + +# Task 1: Create helpers + delete dead Card + +**Files:** Create `web/src/lib/use-lang.ts`, `web/src/lib/class-recipes.ts`, `web/src/lib/class-recipes.test.ts`; Delete `web/src/components/ui/card.tsx`. + +- [ ] **Step 1: `web/src/lib/use-lang.ts`:** +```ts +import { useTranslation } from "react-i18next"; + +/** The instance's active UI language, narrowed to the two supported locales. */ +export function useLang(): "sv" | "en" { + const { i18n } = useTranslation(); + return i18n.language.startsWith("sv") ? "sv" : "en"; +} +``` + +- [ ] **Step 2: `web/src/lib/class-recipes.ts`:** +```ts +import { cn } from "@/lib/utils"; + +import { focusRing } from "./focus-ring"; + +/** Segmented-control / filter-pill item. Unifies the active/inactive token recipe + + * focus ring; callers pass their contextual padding/size via `className`. */ +export function segmentClass(active: boolean, className?: string): string { + return cn("rounded-md", focusRing, active ? "bg-primary text-primary-foreground" : "border", className); +} + +/** Selected vs idle row background for master-detail / list rows. */ +export function rowStateClass(active: boolean): string { + return active ? "bg-primary/10" : "hover:bg-muted"; +} +``` + +- [ ] **Step 3: `web/src/lib/class-recipes.test.ts`** (write + run): +```ts +import { expect, test } from "vitest"; + +import { rowStateClass, segmentClass } from "./class-recipes"; + +test("segmentClass active uses the primary tokens + focus ring", () => { + const cls = segmentClass(true, "px-2 py-1"); + expect(cls).toContain("bg-primary"); + expect(cls).toContain("text-primary-foreground"); + expect(cls).toContain("focus-visible:ring-ring/50"); + expect(cls).toContain("px-2"); +}); + +test("segmentClass inactive uses border, not the primary fill", () => { + const cls = segmentClass(false); + expect(cls).toContain("border"); + expect(cls).not.toContain("bg-primary"); +}); + +test("rowStateClass toggles selected vs idle-hover", () => { + expect(rowStateClass(true)).toBe("bg-primary/10"); + expect(rowStateClass(false)).toBe("hover:bg-muted"); +}); +``` +Run: `cd web && pnpm vitest run src/lib/class-recipes.test.ts` → 3 passing. + +- [ ] **Step 4: Delete the dead Card component:** +```bash +cd /Users/olsson/Laboratory/biggus-dickus +git rm web/src/components/ui/card.tsx +``` +(Confirm no references first: `git grep -n "components/ui/card\"" web/src` returns nothing.) + +- [ ] **Step 5: Verify + lint:** +```bash +cd web && pnpm vitest run src/lib/class-recipes.test.ts && pnpm typecheck && pnpm lint +``` +Expected: green (Card had no importers, so its deletion can't break typecheck/lint). + +- [ ] **Step 6: Commit** +```bash +cd /Users/olsson/Laboratory/biggus-dickus +git add web/src/lib/use-lang.ts web/src/lib/class-recipes.ts web/src/lib/class-recipes.test.ts +git rm -q web/src/components/ui/card.tsx 2>/dev/null; git add -A web/src/components/ui +git commit -m "feat(web): useLang + segmentClass/rowStateClass helpers; delete dead Card (#66)" +``` + +--- + +# Task 2: Adopt the helpers across the duplicated sites + +**Files:** Modify `objects/object-detail.tsx`, `objects/field-input.tsx`, `vocab/vocabulary-terms.tsx`, `vocab/vocabulary-list.tsx`, `fields/field-list.tsx`, `authorities/authorities-page.tsx`, `objects/objects-table.tsx`, `search/search-panel.tsx`, `search/search-result-row.tsx`. + +- [ ] **Step 1: Adopt `useLang()` in the 6 components.** In each of `objects/object-detail.tsx`, `objects/field-input.tsx`, `vocab/vocabulary-terms.tsx`, `vocab/vocabulary-list.tsx`, `fields/field-list.tsx`, `authorities/authorities-page.tsx`: add `import { useLang } from "../lib/use-lang";` and replace `const lang = i18n.language.startsWith("sv") ? "sv" : "en";` with `const lang = useLang();`. Then, if `i18n` is no longer referenced anywhere else in that component, change `const { t, i18n } = useTranslation();` to `const { t } = useTranslation();` (the `noUnusedLocals` typecheck will fail otherwise — so this removal is required wherever `i18n` becomes unused). Note `authorities/authorities-page.tsx` also imports `focusRing` and uses `cn` — leave those. + +- [ ] **Step 2: Adopt `segmentClass` at the 3 segmented sites.** + - `objects/objects-table.tsx`: add `import { segmentClass } from "../lib/class-recipes";`; change the pill `className` (currently `` `${focusRing} rounded-md px-2 py-1 ${active ? "bg-primary text-primary-foreground" : "border"}` ``) to `className={segmentClass(active, "px-2 py-1")}`. If `focusRing` is now unused in this file, remove its import. (The object-number `` also uses `focusRing` — if so, KEEP the import.) + - `search/search-panel.tsx`: add the import; change `className={cn("rounded-md px-2 py-0.5", focusRing, active ? "bg-primary text-primary-foreground" : "border")}` to `className={segmentClass(active, "px-2 py-0.5")}`. Remove now-unused `focusRing`/`cn` imports if they're unused elsewhere in the file. + - `authorities/authorities-page.tsx`: add the import; change the NavLink className callback body `cn("rounded-md px-3 py-1 text-sm", focusRing, isActive ? "bg-primary text-primary-foreground" : "border")` to `segmentClass(isActive, "px-3 py-1 text-sm")`. Remove now-unused `focusRing`/`cn` imports if unused elsewhere. + +- [ ] **Step 3: Adopt `rowStateClass` at the 4 selected-row sites.** Add `import { rowStateClass } from "…/lib/class-recipes";` (or extend the existing class-recipes import) to each: + - `objects/objects-table.tsx`: in the row `className`, change `${selected ? "bg-primary/10" : "hover:bg-muted"}` to `${rowStateClass(selected)}`. + - `vocab/vocabulary-list.tsx`: change `${isActive ? "bg-primary/10" : "hover:bg-muted"}` to `${rowStateClass(isActive)}`. + - `search/search-result-row.tsx`: change `${isActive ? "bg-primary/10" : "hover:bg-muted"}` to `${rowStateClass(isActive)}`. + - `fields/field-list.tsx`: change `${def.key === selectedKey ? "bg-primary/10" : ""}` to `${rowStateClass(def.key === selectedKey)}` (this ADDS the `hover:bg-muted` idle hover the others have — an intended consistency fix). + +- [ ] **Step 4: Verify (vitest ONCE for the affected suites), typecheck, lint:** +```bash +cd web && pnpm vitest run src/objects src/vocab src/fields src/authorities src/search && pnpm typecheck && pnpm lint +``` +Expected: green. These are class-string-equivalent changes (segmentClass/rowStateClass produce the same token sets; `cn` ordering is irrelevant to Tailwind), so the existing component tests pass unchanged. `field-list`'s row now also carries `hover:bg-muted` (additive). If a test asserted the exact old className string, update it to match the new equivalent (unlikely — tests query by role/text). + +- [ ] **Step 5: Commit** +```bash +cd /Users/olsson/Laboratory/biggus-dickus +git add web/src/objects/object-detail.tsx web/src/objects/field-input.tsx web/src/vocab/vocabulary-terms.tsx web/src/vocab/vocabulary-list.tsx web/src/fields/field-list.tsx web/src/authorities/authorities-page.tsx web/src/objects/objects-table.tsx web/src/search/search-panel.tsx web/src/search/search-result-row.tsx +git commit -m "refactor(web): adopt useLang + segmentClass/rowStateClass across sites (#66)" +``` + +--- + +# Task 3: One-off kit cleanups + full gate + +**Files:** Modify `shell/sidebar.tsx`, `auth/login-page.tsx`, `fields/field-list.tsx`, `shell/theme-switch.tsx`, `shell/user-menu.tsx`, `shell/header-search.tsx`, `objects/objects-page.tsx`, `objects/object-detail-drawer.tsx`. + +- [ ] **Step 1: `shell/sidebar.tsx`** — use the `focusRing` constant. Add `import { focusRing } from "../lib/focus-ring";` (if not already imported). At the two `cn(...)` sites (lines ~46 and ~88) replace the literal `"focus-visible:ring-3 focus-visible:ring-ring/50"` entry with `focusRing`. (Both are inside `cn(...)` lists, so just swap the string for the constant.) + +- [ ] **Step 2: `auth/login-page.tsx`** — use `PageTitle`. Add `import { PageTitle } from "@/components/ui/page-title";` and change `

{app_name}

` to `{app_name}`. + +- [ ] **Step 3: `fields/field-list.tsx`** — type-tag → `Badge`. Add `import { Badge } from "@/components/ui/badge";` and change the type-tag `{…}` (line ~97) to `{…}` (keep the inner expression/children unchanged). + +- [ ] **Step 4: Icon sizing → `size-4`** in the 3 app-source sites: `shell/theme-switch.tsx:39` (`` → `className="size-4"`), `shell/user-menu.tsx:27` (`` → `size-4`), `shell/header-search.tsx:23` (the search icon's `… h-4 w-4 …` → replace `h-4 w-4` with `size-4`, keeping the other classes). Do NOT touch `components/ui/select.tsx`. + +- [ ] **Step 5: Icon dismiss buttons → kit Button.** + - `objects/objects-page.tsx:54`: add `import { Button } from "@/components/ui/button";` (if absent) and change the `` to: +```tsx + +``` + - `objects/object-detail-drawer.tsx:31-36`: add `import { Button } from "@/components/ui/button";` and render the `DrawerClose` AS the kit Button via the render prop: +```tsx + } + > + +``` + (This mirrors the `AlertDialogTrigger render={` (import `Button`). + - `objects/object-detail-drawer.tsx:33` (Base UI ``) → keep `DrawerClose` for its + close-on-click semantics, render it AS the kit Button via the render prop: + `}>` (mirrors the `AlertDialogTrigger render={ +
diff --git a/web/src/objects/objects-table.tsx b/web/src/objects/objects-table.tsx index cc67458..046c33f 100644 --- a/web/src/objects/objects-table.tsx +++ b/web/src/objects/objects-table.tsx @@ -7,6 +7,7 @@ import type { components } from "../api/schema"; import { useObjectsPage } from "../api/queries"; import { useDebouncedValue } from "../lib/use-debounced-value"; import { focusRing } from "../lib/focus-ring"; +import { segmentClass, rowStateClass } from "../lib/class-recipes"; import { useConfig } from "../config/config-context"; import { VisibilityBadge } from "./visibility-badge"; import { Button, buttonVariants } from "@/components/ui/button"; @@ -171,7 +172,7 @@ export function ObjectsTable() { type="button" aria-pressed={active} onClick={() => setVisibility(value)} - className={`${focusRing} rounded-md px-2 py-1 ${active ? "bg-primary text-primary-foreground" : "border"}`} + className={segmentClass(active, "px-2 py-1")} > {value === "all" ? t("search.all") : t(`visibility.${value}`)} @@ -248,9 +249,7 @@ export function ObjectsTable() { navigate(`/objects/${object.id}?${params}`)} - className={`cursor-pointer border-b text-sm ${ - selected ? "bg-primary/10" : "hover:bg-muted" - }`} + className={`cursor-pointer border-b text-sm ${rowStateClass(selected)}`} > setVisibility(value)} - className={cn("rounded-md px-2 py-0.5", focusRing, active ? "bg-primary text-primary-foreground" : "border")} + className={segmentClass(active, "px-2 py-0.5")} > {value === "all" ? t("search.all") : t(`visibility.${value}`)} diff --git a/web/src/search/search-result-row.tsx b/web/src/search/search-result-row.tsx index 5f54d56..99ae43f 100644 --- a/web/src/search/search-result-row.tsx +++ b/web/src/search/search-result-row.tsx @@ -2,6 +2,7 @@ import { NavLink } from "react-router-dom"; import type { components } from "../api/schema"; import { VisibilityBadge } from "../objects/visibility-badge"; +import { rowStateClass } from "../lib/class-recipes"; import { Highlight } from "./highlight"; type SearchHitView = components["schemas"]["SearchHitView"]; @@ -12,7 +13,7 @@ export function SearchResultRow({ hit }: { hit: SearchHitView }) { - `block border-b px-3 py-2 ${isActive ? "bg-primary/10" : "hover:bg-muted"}` + `block border-b px-3 py-2 ${rowStateClass(isActive)}` } >
{hit.object_name}
diff --git a/web/src/shell/header-search.tsx b/web/src/shell/header-search.tsx index c0b50ca..afdf27d 100644 --- a/web/src/shell/header-search.tsx +++ b/web/src/shell/header-search.tsx @@ -20,7 +20,7 @@ export function HeaderSearch() {
cn( "flex items-center gap-2 rounded-md px-2 py-1 outline-none", - "focus-visible:ring-3 focus-visible:ring-ring/50", + focusRing, collapsed && "justify-center", isActive && "bg-accent font-medium", ); @@ -85,7 +86,8 @@ export function Sidebar() { title={t(collapsed ? "nav.expandSidebar" : "nav.collapseSidebar")} className={cn( "flex items-center justify-center rounded-md p-1 outline-none", - "hover:bg-accent focus-visible:ring-3 focus-visible:ring-ring/50", + "hover:bg-accent", + focusRing, "disabled:pointer-events-none disabled:opacity-50", )} > diff --git a/web/src/shell/theme-switch.tsx b/web/src/shell/theme-switch.tsx index 266751b..50bded4 100644 --- a/web/src/shell/theme-switch.tsx +++ b/web/src/shell/theme-switch.tsx @@ -36,7 +36,7 @@ export function ThemeSwitch() { : "text-muted-foreground hover:text-foreground", )} > - + ); })} diff --git a/web/src/shell/user-menu.tsx b/web/src/shell/user-menu.tsx index 643feb1..6d7cf0f 100644 --- a/web/src/shell/user-menu.tsx +++ b/web/src/shell/user-menu.tsx @@ -24,7 +24,7 @@ export function UserMenu() { - + {me.email} } diff --git a/web/src/vocab/vocabulary-list.tsx b/web/src/vocab/vocabulary-list.tsx index 581d09b..9f0ecec 100644 --- a/web/src/vocab/vocabulary-list.tsx +++ b/web/src/vocab/vocabulary-list.tsx @@ -3,6 +3,8 @@ import { NavLink } from "react-router-dom"; import { useTranslation } from "react-i18next"; import { useVocabularies, useCreateVocabulary, useRenameVocabulary, useDeleteVocabulary } from "../api/queries"; +import { useLang } from "../lib/use-lang"; +import { rowStateClass } from "../lib/class-recipes"; import { byKey } from "../lib/sort"; import { DeleteConfirmDialog } from "../components/delete-confirm-dialog"; import { MutationError } from "../components/mutation-error"; @@ -12,9 +14,9 @@ import { Label } from "@/components/ui/label"; import { ListSkeleton } from "@/components/ui/skeletons"; export function VocabularyList() { - const { t, i18n } = useTranslation(); + const { t } = useTranslation(); - const lang = i18n.language.startsWith("sv") ? "sv" : "en"; + const lang = useLang(); const { data, isLoading, isError } = useVocabularies(); @@ -110,7 +112,7 @@ export function VocabularyList() { - `block flex-1 px-3 py-2 text-sm ${isActive ? "bg-primary/10" : "hover:bg-muted"}` + `block flex-1 px-3 py-2 text-sm ${rowStateClass(isActive)}` } > {v.key} diff --git a/web/src/vocab/vocabulary-terms.tsx b/web/src/vocab/vocabulary-terms.tsx index 402379e..d8705e8 100644 --- a/web/src/vocab/vocabulary-terms.tsx +++ b/web/src/vocab/vocabulary-terms.tsx @@ -2,15 +2,16 @@ import { useParams } from "react-router-dom"; import { useTranslation } from "react-i18next"; import { useTerms, useAddTerm, useVocabularies } from "../api/queries"; +import { useLang } from "../lib/use-lang"; import { useBreadcrumb } from "../shell/use-breadcrumb"; import { FilteredRecordList } from "../components/filtered-record-list"; import { LabelledRecordCreateForm } from "../components/labelled-record-create-form"; import { TermRow } from "./term-row"; export function VocabularyTerms() { - const { t, i18n } = useTranslation(); + const { t } = useTranslation(); const { id } = useParams(); - const lang = i18n.language.startsWith("sv") ? "sv" : "en"; + const lang = useLang(); const { data: terms, isLoading, isError } = useTerms(id); const addTerm = useAddTerm();