Run 4: Design System Publish — Project Plan

Author: Technical Writer / Team Lead Date: 2026-04-07 Status: Planning Phase: 3.4 — Design System Publish Branch: jmpicnic/image-upload-frontend

Summary

Build, verify, and publish @arda-cards/design-system to GitHub Packages with the lifecycle types and updated image components produced in Runs 2, 3a, and 3b. This run gates Run 6 (SPA integration), which consumes the published package.

Entry Criteria

Criterion	Verification
Run 3b exit gate passed (all 5 image components updated, including `crossOrigin` canvas support)	Review Run 3b completion record in `plan/run-3b-cors-integration/`
`make check` passes in the `ux-prototype` worktree	`git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype status` — clean tree on `jmpicnic/image-upload-frontend`
`make test` passes	Run `make test` in worktree; all unit tests green
`make build` passes	Run `make build` in worktree; Storybook build succeeds

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
T-1	Full library build (`make build-lib`)	front-end-engineer	Entry criteria	Pending	`dist/` contains `canary.js`, `canary.cjs`, `canary.d.ts`, `types-canary.js`, `types-canary.cjs`, `types-canary.d.ts`; all other existing exports unchanged
T-2	CHANGELOG update	front-end-engineer	T-1	Pending	`CHANGELOG.md` includes Added entries for lifecycle types (`ValidationResult`, `FieldError`, `EditLifecycleCallbacks<T>`, `EditableComponentProps<T>`, `EditPhase`, `Validator<T>`), `useDraft<T>` hook, `UploadError` state, `contextErrors` prop, expanded `ItemGridLookups`, typed provider hook support; Changed entry for `ImageUploadDialog` progress indicator (simulated % → indeterminate)
T-3	Version bump (minor)	front-end-engineer	T-2	Pending	`package.json` version incremented by one minor version per Keep a Changelog rules (Added → minor bump); version matches CHANGELOG entry
T-4	Final checks (`make check`, `make test`, `make build`, `make build-lib`)	front-end-engineer	T-3	Pending	All four `make` targets pass with no errors or warnings
T-5	Commit, push, create PR, run `pr-steward`, merge	front-end-engineer	T-4	Pending	PR created to `main` with attribution block; CI checks pass; reviewer comments resolved; PR merged
T-6	Verify publication to GitHub Packages	front-end-engineer	T-5	Pending	`npm view @arda-cards/design-system versions` shows the new version; `npm pack` confirms `canary` and `types-canary` assets are present in the tarball
T-7	Documentation commit	front-end-engineer	T-6	Pending	`make pr-checks` passes in the documentation worktree; changes committed referencing Phase 3.4

Exit Criteria

Criterion	Verification
`@arda-cards/design-system` published to GitHub Packages at new minor version	`npm view @arda-cards/design-system versions --registry=https://npm.pkg.github.com`
Published package includes lifecycle types and updated components	`npm pack @arda-cards/design-system@<version> --registry=https://npm.pkg.github.com && tar -tf arda-cards-design-system-<version>.tgz \| grep -E "canary\|types-canary"`
All CI checks passed and PR merged to `main`	PR status shows merged; CI green
Documentation worktree committed with `make pr-checks` passing	`git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation log --oneline -3`

Handoff

Artifacts Consumed

Artifact	Source	Produced By
Lifecycle types and `useDraft<T>` hook in `ux-prototype` canary	`ux-prototype` worktree, branch `jmpicnic/image-upload-frontend`	Run 2
5 updated image components (without `crossOrigin`)	`ux-prototype` worktree	Run 3a
`crossOrigin` canvas support added to all 5 components	`ux-prototype` worktree	Run 3b

Artifacts Produced

Artifact	Location	Consumed By
`@arda-cards/design-system` npm package at new minor version	GitHub Packages (`npm.pkg.github.com`)	Run 6 (SPA integration — T-1 bumps the dependency)
Documentation commit referencing Phase 3.4	`documentation` worktree	Run 7 (documentation PR)

Agent Prompt Template

Use the following prompt to spawn the front-end-engineer agent for this run. Paste the full text as the Task tool input.

You are a front-end-engineer working in the ux-prototype worktree for the
image-upload-frontend project.

**Worktree**: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype
**Branch**: jmpicnic/image-upload-frontend
**Documentation worktree**: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation

Load the following skills before starting:
- path-conventions
- document-writing
- release-lifecycle

Read the specification before beginning:
/Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation/src/content/docs/roadmap/completed/item-image-upload/3-frontend-implementation/34-design-system-publish/specification.md

Your task is to execute Run 4 of the image-upload-frontend project (Phase 3.4 —
Design System Publish). Complete the following tasks in order:

T-1: Run `make build-lib` in the ux-prototype worktree. Verify that `dist/`
     contains `canary.js`, `canary.cjs`, `canary.d.ts`, `types-canary.js`,
     `types-canary.cjs`, and `types-canary.d.ts`.

T-2: Update CHANGELOG.md with Added and Changed entries per the release-lifecycle
     skill conventions. See specification.md §T-2 for the required entries.

T-3: Bump the version in `package.json` by one minor version (Added → minor).
     Confirm the version matches the CHANGELOG entry.

T-4: Run all four checks in sequence:
     - make check     (lint + typecheck)
     - make test      (unit tests)
     - make build     (Storybook build)
     - make build-lib (library build with declarations)
     All must pass before proceeding.

T-5: Commit all changes (CHANGELOG, version bump, dist artifacts if tracked).
     Push to branch jmpicnic/image-upload-frontend. Create a PR to main with
     attribution block. Run /pr-steward <pr-url>. Wait for approval and merge.

T-6: After merge, verify the package is published:
     npm view @arda-cards/design-system versions --registry=https://npm.pkg.github.com
     Verify lifecycle exports are in the published tarball.

T-7: In the documentation worktree, run `make pr-checks`. Commit documentation
     changes referencing Phase 3.4.

All tool calls must use absolute paths. Never use `cd` — use absolute paths
or `git -C <path>` for git commands.

Report completion with: (a) the new published version number, (b) the PR URL,
and (c) confirmation that `make pr-checks` passed in the documentation worktree.