Overview

Goal

Consolidate two independent streams of component work into a single coherent component library in ux-prototype:

• jmpicnic branch (jmpicnic/list-view-management-620) — entity-data-grid factory, cell atoms (8 types), data-grid molecule, dirty tracking, column persistence. Focus: general-purpose grid infrastructure.

• callil branch (jmpicnic/callil-consolidation, via worktree) — sidebar, app-header, item-details, item-grid organisms, shadcn/ui primitives layer, design token system. Focus: page-level composition and visual design.

The consolidation is not a mechanical merge. It requires semantic analysis of overlapping code, architectural decisions about component organization, and evolutionary changes to the grid infrastructure to support the capabilities both architects implemented independently.

Key Outcomes

1. Unified component hierarchy — all components under src/components/canary/ with consistent naming, imports, and patterns (primitives → atoms → molecules → organisms).
2. Entity-data-grid as the grid foundation — item-grid (and future entity grids) built on entity-data-grid, eliminating duplicated framework code.
3. Arda design tokens — orange-branded palette, responsive control heights, and themeQuartz AG Grid styling as the visual foundation.
4. Published package — @arda-cards/design-system barrel exports reflect the consolidated library.

Reader’s Guide

Analysis Documents

Start here to understand the decisions. Each document covers a specific topic with options evaluated, decisions recorded (with dates), and rationale.

Document	What it covers	Start here if you want to understand…
analysis/index.md	Master index of all decisions	All cross-cutting decisions in one place — branch strategy, canonical paths, component organization, barrel exports, styles, dependencies
analysis/grid-integration.md	Entity-data-grid evolution	How item-grid’s capabilities (auto-publish, search, actions, pagination, theme) are promoted into entity-data-grid
analysis/primitives.md	Component organization	Why stock shadcn goes in canary/primitives/ and custom components go in canary/atoms/; includes organism import mapping
analysis/styles.md	CSS token system	Why the worktree’s Arda orange palette replaces the main clone’s blue-slate; how tokens.css and globals.css are restructured
analysis/dependencies.md	npm package changes	Which worktree dependencies to keep/drop and why; library build analysis for runtime vs dev classification
analysis/test-coverage.md	Stories, tests, VRT	What test/story gaps the consolidation creates and how to fill them; play function step DSL convention; VRT expected variances
analysis/canary-refactor.md	Validation harness	Why canary-refactor/ is adapted after (not during) consolidation and what deferred sub-tasks exist

Decision Log

Document	What it covers
decision-log.md	Chronological record of all 45 decisions + external tickets, with rationale and source document links

Project Blueprint and Plans

The execution plan. Read this after the analysis to understand the sequencing.

Document	What it covers
project-blueprint.md	10 runs (0-9) sequenced risk-first with verification gates, intermediate checkpoints, Playwright MCP visual checks, and entry/exit criteria per run
plan/team-split-assessment.md	Complexity analysis justifying the 10-run decomposition
plan/choreography.md	Execution sequence, artifact dependencies, hand-off protocol, recovery procedures
plan/run-N-*/project-plan.md	Detailed task lists, entry/exit criteria, validation scripts per run

Reading Order

1. Quick overview: This file → decision-log.md (all decisions) → project-blueprint.md (dependency graph at the bottom)
2. Deep dive on a topic: Follow the links in the analysis index to the relevant document
3. Implementation planning: plan/choreography.md → individual run-N-*/project-plan.md files
4. Implementation execution: Run-by-run, referencing analysis documents for design rationale; write outputs to implementation/run-N-*/

Status

• Analysis phase: Complete — all design decisions recorded (45 decisions, see decision-log.md)
• Blueprint: Complete — 10 runs defined with verification gates
• Planning: Complete — detailed task plans for all 10 runs with validate-exit.sh scripts
• Implementation: Complete — all 10 runs executed, PR #59 merged to main (2026-03-20)
• Storybook polish: Complete — stories, MDX docs, ordering, Playground controls, cursor policy, sidebar molecule rendering
• CI: All checks green — build-and-test, VRT, CodeQL, Vercel
• External tickets:
  • #824 — server-side search via Query DSL (future)
  • #825 — remove Arda prefix from canary names (done in PR #59)
  • #828 — fix 4 play functions that fail in CI static build (skip-ci tagged)