# Task 007 Controls 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:** Rebuild every standard button, field, choice and native select against the approved Figma control system, preserve behaviour, and deliver the result as one verified PR. **Architecture:** Define the control vocabulary once as Tailwind `@utility` rules in `apps/web/src/theme.css`, lock its measurable design contract in `apps/web/src/tokens.test.ts`, then migrate existing native controls without introducing shared React wrappers. Keep specialised toolbar, table-rail, tab and menu controls specialised where their interaction model already requires it. **Tech Stack:** React, TypeScript, Tailwind CSS v4, Bun test, dprint, oxlint, Playwright. --- ## Interface contract - `btn` is the shared behavioural/typographic base. - `btn-sm`, `btn-md` and `btn-icon` are the only sizes: 24px, 32px and a 28px square. - `btn-primary`, `btn-secondary`, `btn-ghost` and `btn-destructive` are the only standard tiers. - `field` owns the standard field edge, disabled state and invalid state. - `field-ghost` is the transparent-at-rest native-select treatment. - `choice-control` continues to style native checkbox and radio inputs. - Consumers retain their existing layout classes, event handlers, state and accessible names. The exact new palette values are: ```css --color-brand-active: oklch(0.37546 0.06382 210.435); /* #034a54 */ --color-destructive-hover: oklch(0.56972 0.16045 24.136); /* #c44746 */ --color-destructive-active: oklch(0.53376 0.1489 24.091); /* #b34140 */ ``` ## Task 1: Lock and implement the shared control vocabulary **Files:** - Modify: `apps/web/src/tokens.test.ts` - Modify: `apps/web/src/theme.css` - [ ] **Step 1: Add failing design-contract tests** Extend the existing `controls` test group so it checks observable values rather than utility implementation order: ```ts expect(sizes("btn-md")).toEqual({ height: 32 }); expect(sizes("btn-sm")).toEqual({ height: 24 }); expect(sizes("btn-icon")).toEqual({ height: 28, width: 28 }); expect(hex("--color-destructive-hover")).toBe("#c44746"); expect(hex("--color-destructive-active")).toBe("#b34140"); ``` Also assert: - every button tier has guarded hover/active rules and no rest border; - disabled buttons resolve to gray-200/gray-600; - focus and invalid outlines are 2px with a 2px offset; - fields and choices use the 20% edge, disabled uses the 7% edge; - checked checkboxes contain the check-path glyph; - ghost fields are transparent at rest and expose the 20% edge on hover. - [ ] **Step 2: Run the focused test and confirm RED** Run: `bun test apps/web/src/tokens.test.ts` Expected: FAIL because the new tokens and utilities do not exist. - [ ] **Step 3: Implement the utility contract** In `theme.css`: - add the three exact palette tokens above; - make the global focus outline `2px solid var(--color-brand)` with `2px` offset; - add `btn`, the three sizes and four tiers; - place the common disabled fill/ink in `btn`, with tier hover/active selectors guarded by `:not(:disabled)`; - add `field` and `field-ghost` state rules; - update `choice-control` disabled presentation to gray-200/gray-600 with the 7% edge; - keep the existing extra control-boundary stroke only inside `@media (prefers-contrast: more)` so normal controls show exactly the designed 20% edge. Representative shape: ```css @utility btn { display: inline-flex; align-items: center; justify-content: center; border: 0; border-radius: var(--radius-md); font-size: var(--text-sm); font-weight: 500; &:disabled { background-color: var(--color-gray-200); color: var(--color-gray-600); cursor: default; } } ``` - [ ] **Step 4: Run the focused test and confirm GREEN** Run: `bun test apps/web/src/tokens.test.ts` Expected: PASS. - [ ] **Step 5: Format and commit the checkpoint** Run: `bunx dprint fmt apps/web/src/theme.css apps/web/src/tokens.test.ts` Run: `git diff --check && git status --short` Commit: `git add apps/web/src/theme.css apps/web/src/tokens.test.ts && git commit -m "Define shared control utilities"` ## Task 2: Migrate standard buttons without changing behaviour **Files:** - Modify: `apps/web/src/app.tsx` - Modify: `apps/web/src/chat/chat.tsx` - Modify: `apps/web/src/chat/transcript.tsx` - Modify: `packages/editor/src/comments.tsx` - Modify: `packages/editor/src/decisions.tsx` - Modify: `packages/question/src/react/question-view.tsx` - Test: `apps/web/src/tokens.test.ts` - [ ] **Step 1: Add a failing migration guard for standard buttons** Add a narrowly scoped source-contract test listing the standard control files above. It should report file and line for button class lists that still combine bespoke rest fills/padding with a standard action button. Exclude specialised tabs, table rails, cell toolbar controls, quote-navigation links and change chips. The guard should require a standard button to contain: ```ts /(?:^|\s)btn(?:\s|$)/; ``` and exactly one size plus one tier utility. - [ ] **Step 2: Run the focused test and confirm RED** Run: `bun test apps/web/src/tokens.test.ts` Expected: FAIL with the unmigrated standard buttons named. - [ ] **Step 3: Replace bespoke standard-button styling** Apply the utility API while preserving handlers, disabled expressions, labels, element types and layout-only classes: - `btn btn-md btn-primary`: Join, Submit and primary confirmations; - `btn btn-sm btn-secondary`: Stop, Cancel, Keep it and neutral card actions; - `btn btn-sm btn-ghost`: Withdraw, Ask again and low-emphasis actions; - `btn btn-sm btn-destructive`: destructive confirmation actions; - `btn btn-icon btn-ghost`: pane toggle and true icon-only actions; - full-row disclosure buttons keep their width/alignment classes but use `btn` tier/state vocabulary where they are actions rather than tabs. Do not migrate the task-008 bubble toolbar, table rails, tabs, menus, change chips or relation-navigation controls just to satisfy a broad search. - [ ] **Step 4: Run focused and package tests** Run: `bun test apps/web/src/tokens.test.ts packages/question/src packages/editor/src` Expected: PASS with existing control behaviour tests unchanged. - [ ] **Step 5: Format and commit the checkpoint** Run: `bunx dprint fmt apps/web/src/app.tsx apps/web/src/chat/chat.tsx apps/web/src/chat/transcript.tsx packages/editor/src/comments.tsx packages/editor/src/decisions.tsx packages/question/src/react/question-view.tsx apps/web/src/tokens.test.ts` Run: `git diff --check && git status --short` Commit: `git add apps/web/src apps/web/src/chat packages/editor/src/comments.tsx packages/editor/src/decisions.tsx packages/question/src/react/question-view.tsx && git commit -m "Migrate standard button tiers"` ## Task 3: Migrate fields, choices and native selects **Files:** - Modify: `apps/web/src/app.tsx` - Modify: `apps/web/src/chat/chat.tsx` - Modify: `packages/editor/src/comments.tsx` - Modify: `packages/editor/src/widgets/callout.tsx` - Modify: `packages/editor/src/widgets/render-blocks.tsx` - Modify: `packages/question/src/react/question-view.tsx` - Test: `apps/web/src/tokens.test.ts` - [ ] **Step 1: Add failing consumer guards** Add focused migration assertions that identify: - standard text inputs and textareas missing `field`; - native checkbox/radio inputs missing `choice-control`; - the callout-kind and code-language selects missing `field-ghost`; - any remaining disabled-opacity utility in these control files. Keep the fixture list explicit so unrelated hidden/native inputs do not become false positives. - [ ] **Step 2: Run the focused test and confirm RED** Run: `bun test apps/web/src/tokens.test.ts` Expected: FAIL with the unmigrated fields and selects named. - [ ] **Step 3: Migrate controls in place** - Add `field` to sign-in, chat, comment and questionnaire text inputs/textareas while retaining their dimensions and resize/layout behaviour. - Add `choice-control` to questionnaire checkbox/radio inputs; keep each surrounding `