Component Library Reconciliation Procedure

Updated: 2026-07-15 22:39 ET · Audited: 2026-07-13 16:35 ET

TL;DR: Five-phase procedure for deciding whether component-spec changes should roll into the real shared component library, and for surfacing new shared/reusable components: gate check → inventory → classify → update living docs → commit/PR. This is a different question from the Figma sync procedure: that one asks "do the spec docs match Figma?" — this one asks "does the real code in ALPAMobile.Presentation/Components/Library/ match the specs, and does anything new belong in the shared library?" Run this after a Figma sync's doc roll-up lands, or whenever the implementation gate status might have changed.

Table of Contents

1. Overview
2. When to run this
3. Phase 1 — Gate check
4. Phase 2 — Inventory: real library vs. specs
5. Phase 3 — Classify gaps
6. Phase 4 — Update the living reconciliation docs
7. Phase 5 — Commit and PR
8. File inventory
9. Gotchas

1. Overview

A Figma sync keeps the spec docs (docs/component-specifications/) faithful to Figma. It does not check whether the real shared component library — the code other features actually import — reflects what's specced, or whether new patterns that showed up across multiple specs deserve to be promoted into a shared atom/primitive rather than re-implemented per screen. That's this procedure's job.

As of 2026-07-13 this reconciliation exists only as dated, one-off snapshot artifacts (scaffold-component-reconciliation.html, component-library-plan.html) that explicitly call themselves "backlog artifacts, not a work order." This doc formalizes the repeatable procedure so those stop going stale between runs — update them in place each run rather than creating a new dated snapshot every time (that's how the AB#2087 gate-language staleness happened: the artifacts said "gated" for 12 days after the gate actually cleared, because nothing re-checked them).

2. When to Run This

• A Figma sync's Phase 5 doc roll-up just landed (new/changed component specs) — see figma-sync-procedure.html Phase 7, which points here.
• An implementation gate you were tracking (e.g. a Presentation Extraction WI) might have changed state — check Boards, don't assume from doc text (see Phase 1).
• The same hand-rolled pattern shows up in 2+ places during unrelated feature work — a signal a shared component candidate exists before this procedure even runs; capture it for the next pass.

3. Phase 1 — Gate Check

Verify live, don't trust doc text. Reconciliation artifacts reference a specific Azure Boards work item as the implementation gate (currently WI-2087, "Presentation Extraction," under Epic AB#2081). Doc text lags reality — it only updates when someone runs this procedure.

az boards work-item show --id <gate-WI> --query "{state:fields.\"System.State\"}" -o json

If the gate is now resolved but the doc still says "gated," that mismatch alone is a finding — update the gate language (see Phase 4) even if you do nothing else this pass. Do not assume a resolved gate WI means the specific migration/track it was blocking is complete — verify against real code (Phase 2) before changing a track's status from "not started" to "done."

4. Phase 2 — Inventory: Real Library vs. Specs

Compare what the specs describe against what actually exists in code:

• Shared library location — ALPAMobile.Presentation/Components/Library/ (the RCL home per D20, executed 2026-07-15 WI-2254/D61; the legacy MAUI-head ALPAMobile/Components/Library/ location is empty since the migration). A component appearing anywhere else is a migration gap, not a missing-component gap.
• Per spec page (docs/component-specifications/<name>/<name>-component.html), confirm: does a matching .razor renderer + ViewModel exist? If yes, is it in the target location? If no, is it built at all?
• Per scaffold/screen implementation (e.g. the Blazor scaffold pages), look for hand-rolled alpa-* CSS patterns that duplicate an existing spec — that's a consume-don't-rebuild gap, not a new-component gap.

5. Phase 3 — Classify Gaps

For each gap found in Phase 2, classify using the existing opt-in criterion (D40): the shared library is for recurring, data-driven controls; one-off static/informational content is exempt and may stay plain markup. The shared layer is atoms + tokens, not a base class — domain controls compose shared atoms rather than inheriting a shared base.

6. Phase 4 — Update the Living Reconciliation Docs

Edit in place. Do not create a new dated snapshot doc each run — that's what let the last one go stale. Update:

7. Phase 5 — Commit and PR

Same verification and branch conventions as the Figma sync procedure: tag-balance check on changed HTML, stage specific files (never git add -A), commit message format "docs: component library reconciliation (<what changed>)". Check how far behind the target branch your base commit is before pushing (see the Figma sync procedure's Gotchas — the same branch-staleness risk applies here).

8. File Inventory

9. Gotchas

• A resolved gate WI doesn't mean the specific track it was blocking is complete. Verify against real code, not just the WI's state field — see Phase 1. Example: WI-2087 resolved 2026-07-01 extracted the ViewModel/Presentation layer; it did not move the Razor renderers, even though component-library-plan.html's Track C was gated on it specifically for the renderer move.
• Don't conflate "wrong location" with "not built." A component can be fully built and correct, just sitting in the wrong project — as the whole library was in ALPAMobile/Components/Library/ until the 2026-07-15 WI-2254/D61 migration into ALPAMobile.Presentation. That's a migration item, not a build item.
• Implementation is still gated where the doc says it is — this procedure decides what belongs in the library and tracks whether it's built, it does not itself authorize starting implementation. Check Boards for scoping/prioritization before treating a "gate cleared" finding as a green light to start building.