Run 2: Visual Foundation (Theme Migration)

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	On jmpicnic/component-consolidation branch	git -C /Users/jmp/code/arda/ux-prototype branch --show-current	jmpicnic/component-consolidation
2	Working tree is clean	git -C /Users/jmp/code/arda/ux-prototype status --porcelain | wc -l | tr -d ' '	0
3	Run 1 foundation complete: primitives directory exists	test -d /Users/jmp/code/arda/ux-prototype/src/components/canary/primitives && echo EXISTS	EXISTS
4	Run 1 foundation complete: tokens.css updated	grep -c 'orange' /Users/jmp/code/arda/ux-prototype/src/styles/tokens.css | awk '{print ($1 > 0) ? "FOUND" : "MISSING"}'	FOUND
5	DataGrid molecule exists	test -f /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx && echo EXISTS	EXISTS
6	Tests pass (Run 1 baseline)	npm run test --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS
7	Worktree available for theme reference	test -d /Users/jmp/code/arda/callil-consolidation-worktree && echo EXISTS	EXISTS
8	Run 1 exit gate passed	bash run-1-foundation/validate-exit.sh	ALL CHECKS PASSED

Artifact Specifications

Artifact	Path	Format	Description
Updated DataGrid molecule	ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx	TSX	Retrofitted from 'legacy' theme string to themeQuartz with design-system token mapping
AG Grid theme CSS (if needed)	ux-prototype/src/styles/ag-theme-arda.css	CSS	Updated Arda AG Grid theme tokens if additional CSS custom properties are needed
ThemedGrid story	ux-prototype/src/components/canary/molecules/data-grid/data-grid.stories.tsx	TSX	New ThemedGrid story demonstrating the theme migration
Regenerated VRT baselines	ux-prototype/__screenshots__/	PNG	Updated baselines for all grid-related stories

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
2.1	Read item-grid theme configuration from worktree	front-end-engineer	—	Pending	Token mapping document extracted: row height, header height, font family/size/weight, cell padding, color tokens, column borders, wrapper border radius
2.2	Apply themeQuartz to DataGrid molecule with design-system tokens	front-end-engineer	2.1	Pending	DataGrid uses themeQuartz instead of 'legacy'; token mapping applied (48px rows, 36px headers, Geist Sans 14px/13px, 600 weight, 12px padding, Arda color tokens, column borders, border radius); npx tsc --noEmit passes
2.3	Add ThemedGrid visual story	front-end-engineer	2.2	Pending	Story exists in data-grid stories file; renders grid with themed appearance; demonstrates token mapping in action
2.4	VRT before/after comparison (critical gate)	front-end-engineer	2.3	Pending	All grid stories reviewed for visual diffs; expected variances confirmed (row heights, fonts, colors, borders change from defaults to Arda tokens); VRT baselines regenerated and committed
2.5	Playwright MCP visual verification	front-end-engineer	2.4	Pending	Screenshots of DataGrid and EntityDataGrid stories captured; row heights, header styling, font rendering, cell padding, color tokens verified; ThemedGrid compared against item-grid appearance in worktree Storybook

Task Details

Task 2.1: Read Item-Grid Theme Configuration

Working directory: /Users/jmp/code/arda/ux-prototype Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree Governs: analysis/grid-integration.md (decision #5)

Steps:

1. Read the worktree’s item-grid component to extract its AG Grid theme configuration:
   • callil-consolidation-worktree/src/components/canary/organisms/item-grid/ — look for theme setup
   • callil-consolidation-worktree/src/components/canary/molecules/item-grid/ — look for grid configuration
2. Document the token mapping:
   • Row height: 48px
   • Header height: 36px
   • Font: Geist Sans, 14px body, 13px headers, 600 weight
   • Cell padding: 12px
   • Color tokens: map to CSS custom properties from tokens.css
   • Column border styling
   • Wrapper border radius
3. Note any AG Grid themeQuartz parameters or createTheme calls.
4. Record the mapping for use in Task 2.2.

This is a read-only analysis task — no files are modified.

Task 2.2: Apply themeQuartz to DataGrid Molecule

Working directory: /Users/jmp/code/arda/ux-prototype

Steps:

1. Open src/components/canary/molecules/data-grid/data-grid.tsx.
2. Replace the 'legacy' theme string with themeQuartz import from ag-grid-community.
3. Apply the token mapping from Task 2.1:
   • Configure themeQuartz with the extracted parameters.
   • Map Arda design tokens (CSS custom properties from tokens.css) to AG Grid theme parameters.
   • Set row height (48px), header height (36px), font configuration, cell padding, color mappings, border styling.
4. Update the wrapper element styling if needed (border radius).
5. Verify: npx tsc --noEmit passes.

Intermediate gate: npx tsc --noEmit

Task 2.3: Add ThemedGrid Visual Story

Working directory: /Users/jmp/code/arda/ux-prototype

Steps:

1. Add a ThemedGrid story to src/components/canary/molecules/data-grid/data-grid.stories.tsx.
2. The story should render a grid with sample data that demonstrates:
   • Arda-themed row heights and header heights
   • Font styling (Geist Sans, correct sizes and weights)
   • Color token application (background, text, borders)
   • Cell padding
3. Use fixture data that exercises multiple column types if possible.
4. Verify: npm run build-storybook passes.

Task 2.4: VRT Before/After Comparison (Critical Gate)

Working directory: /Users/jmp/code/arda/ux-prototype

This is the critical verification gate for Run 2. The theme change will diff every grid story.

Steps:

1. Identify all affected stories: DataGrid molecule stories, EntityDataGrid factory stories, EntityDataGridShim stories, and any other stories rendering an AG Grid.
2. Review the VRT diffs. Expected variances:
   • Row heights change from browser defaults to 48px
   • Header heights change to 36px
   • Fonts change to Geist Sans with specified sizes/weights
   • Colors change from defaults to Arda tokens
   • Borders change to column border styling
3. If the visual changes match the expected Arda design tokens, regenerate all affected baselines:

   npx playwright test --project=vrt --update-snapshots

4. Commit the regenerated baselines.

Gate: VRT baselines regenerated and committed. All VRT tests pass with new baselines.

Task 2.5: Playwright MCP Visual Verification

Working directory: /Users/jmp/code/arda/ux-prototype

Steps:

1. Start Storybook dev server: npm run dev (if not already running).
2. Navigate to DataGrid stories and take screenshots:
   • DataGrid Default story
   • ThemedGrid story (new)
3. Navigate to EntityDataGrid stories and take screenshots.
4. Verify in each screenshot:
   • Row heights appear correct (~48px)
   • Header styling matches specification (36px height, 13px font, 600 weight)
   • Font rendering is Geist Sans at correct sizes
   • Cell padding appears correct (~12px)
   • Color tokens are applied (Arda orange accents, correct background/foreground)
5. Compare ThemedGrid story against item-grid’s existing appearance in the worktree Storybook for reference.

Internal Dependency Graph

2.1 (read theme config) --> 2.2 (apply themeQuartz) --> 2.3 (ThemedGrid story) --> 2.4 (VRT comparison) --> 2.5 (Playwright MCP)

Strictly sequential. Task 2.1 is read-only analysis that informs 2.2. Tasks 2.4 and 2.5 are both verification gates.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Tests pass	npm run test --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS
2	TypeScript compiles	npx tsc --noEmit --project /Users/jmp/code/arda/ux-prototype/tsconfig.json > /dev/null 2>&1 && echo PASS	PASS
3	Storybook builds	npm run build-storybook --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS
4	DataGrid uses themeQuartz (not legacy)	grep -c "themeQuartz" /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx	1 or more
5	No ‘legacy’ theme string in DataGrid	grep -c "'legacy'" /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx	0
6	ThemedGrid story exists	grep -c "ThemedGrid" /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.stories.tsx	1 or more
7	VRT baselines committed (no uncommitted screenshot changes)	git -C /Users/jmp/code/arda/ux-prototype status --porcelain __screenshots__/ | wc -l | tr -d ' '	0
8	VRT tests pass with new baselines	npx playwright test --project=vrt --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS
9	No regressions in non-grid tests	npm run test --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS

Agent Prompt Templates

Front End Engineer — fe-visual-foundation

You are executing Run 2 (Visual Foundation) of the Callil Consolidation project. Your working directory is /Users/jmp/code/arda/ux-prototype on branch jmpicnic/component-consolidation. The worktree at /Users/jmp/code/arda/callil-consolidation-worktree is your read-only reference for the item-grid theme configuration.

Context:

• This run retrofits the DataGrid molecule from the 'legacy' AG Grid theme to themeQuartz with Arda design-system tokens.
• This is the highest visual risk in the project — the theme change will diff every grid story.
• The critical gate is the VRT before/after comparison (Task 2.4). All grid VRT baselines will change and must be reviewed before regeneration.

Tasks (strictly sequential):

1. Task 2.1 — Read Theme Config: Analyze worktree item-grid to extract theme token mapping (row height 48px, header 36px, Geist Sans fonts, 12px padding, color tokens, borders, border radius). Read-only — no file changes.
2. Task 2.2 — Apply themeQuartz: Replace 'legacy' with themeQuartz in DataGrid molecule, apply token mapping. Gate: npx tsc --noEmit.
3. Task 2.3 — ThemedGrid Story: Add ThemedGrid story to demonstrate the themed grid.
4. Task 2.4 — VRT Comparison: Review all grid VRT diffs, confirm expected variances, regenerate baselines. This is the critical gate.
5. Task 2.5 — Playwright MCP: Visual verification of grid appearance via browser screenshots.

Critical rules:

• Use absolute paths for all tool calls.
• Read analysis/grid-integration.md for design decisions (especially decision #5 on AG Grid theme).
• The token mapping must use CSS custom properties from tokens.css (updated in Run 1).
• Commit after the theme change (Task 2.2) and again after VRT baseline regeneration (Task 2.4).

Reference paths:

• Analysis doc: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/grid-integration.md
• DataGrid molecule: /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx
• DataGrid stories: /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.stories.tsx
• Worktree item-grid: /Users/jmp/code/arda/callil-consolidation-worktree/src/components/canary/organisms/item-grid/
• Worktree item-grid molecules: /Users/jmp/code/arda/callil-consolidation-worktree/src/components/canary/molecules/item-grid/
• Design tokens: /Users/jmp/code/arda/ux-prototype/src/styles/tokens.css
• AG Grid theme CSS: /Users/jmp/code/arda/ux-prototype/src/styles/ag-theme-arda.css

Personas Required

Persona	Tasks Assigned	Working Directory	Spawn Order	Agent Name
front-end-engineer	2.1, 2.2, 2.3, 2.4, 2.5	/Users/jmp/code/arda/ux-prototype	1	fe-visual-foundation

All agents use mode: "bypassPermissions".

Worktree Strategy

Worktrees are NOT needed for Run 2. Single agent working sequentially on the same branch. The pre-existing worktree at /Users/jmp/code/arda/callil-consolidation-worktree/ is a read-only reference — it is not created, modified, or managed by this run.

Implementation Output

At run completion, write the following to implementation/run-2-visual-foundation/:

Artifact	File	Description
Run summary	summary.md	What was done, decisions made during implementation, deviations from plan
Byproducts log	byproducts.md	Discovered issues, TODOs, observations for later runs
Validation output	validation-output.txt	Stdout from validate-exit.sh execution
Session log	session-log.md	Agent session IDs, timestamps, notable events

Path: documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/implementation/run-2-visual-foundation/

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
Branch jmpicnic/component-consolidation with foundation work	Run 0, Run 1	ux-prototype repo
Updated tokens.css (Arda orange palette)	Run 1	ux-prototype/src/styles/tokens.css
Primitives directory	Run 1	ux-prototype/src/components/canary/primitives/
Canonical cn imports	Run 1	@/types/canary/utils across codebase

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
DataGrid molecule with themeQuartz	Run 3 (organism grid rendering), Run 5 (entity-data-grid base), Run 6 (item-grid refactor)	ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx
ThemedGrid story	Run 3 (visual reference), Run 8 (acceptance)	ux-prototype/src/components/canary/molecules/data-grid/data-grid.stories.tsx
Regenerated VRT baselines (grid)	Run 3 (organism port baseline), Run 6 (item-grid regression comparison)	ux-prototype/__screenshots__/