01 — Problem
The Challenge
AHEAD needed a way to set client expectations about manufacturer order-data support before a purchase rather than after something turned out to be missing. The question was straightforward — does this manufacturer provide estimated ship dates, ship confirmation, advanced tracking, asset serials? — but there was no place to record or surface those answers.
- No structured record of manufacturer order-data capabilities existed anywhere in the system
- Clients were learning about gaps after purchase, not before
- Internal teams had no shared reference for what a given manufacturer could or could not provide
- The curator-to-client workflow needed to be built from scratch, including permissions, data entry, and display
02 — Research
Defining the Capability Categories
The initial brief called for six capabilities. Working with the business owner during review, that number came down to four. ESD Accuracy was a judgment about a date the matrix already reports on, not a capability a manufacturer has or lacks. Entitlement Data sat outside the order-data expectations the matrix exists to set. The two that remained alongside the core four answered the same question a client actually asks — "can I rely on this or not" — but splitting why something was unreliable put a distinction in front of clients they could not act on. The merge to Partially Supported simplified both the data and the legend wording.
From Six Capabilities to Four
Est. Ship Date, Ship Confirmation, Advanced Tracking, and Asset Serials survived. ESD Accuracy was dropped because it evaluated a date the matrix already surfaces — it was a meta-rating, not a capability. Entitlement Data fell outside the core order-data expectations. The business owner made both calls; they clarified scope rather than reduced ambition.
From Four Support Levels to Three
Manually Supported and Partial answered the same client question and were consolidated into Partially Supported. The legend wording changed with this: from naming the mechanism ("manually provided") to naming what to expect ("provided for some orders, or on request rather than automatically"). A client can act on the second; they can only understand the first.
Understanding the Client Surface Constraint
The product stakeholder's constraint was that client-facing surfaces expose manufacturers and never vendor names. This came up during phase one when the mockup grouped manufacturers under distributor headers and showed spend per row. The constraint was structural, not aesthetic: the matrix is keyed to manufacturer rows and cannot point at a vendor. Satisfying it did not require ongoing discipline — it was satisfied by the data model's shape. It also turned phase one's one-rating-per-manufacturer unique index from a recorded limitation into exactly the right design.
What the Phase Two Mockup Got Wrong
The prototype grouped manufacturers under distributor/vendor headers and included spend and PO count columns. The stakeholder's constraint meant those vendor-axis rows were wrong rather than inconvenient. Dropping the vendor grouping removed the purchase-path dimension, which had its own effect: phase one's unique-per-manufacturer index stopped being a limitation and became correct. Phase three's redesign later reintroduced grouping — by coverage tier instead of by vendor — which satisfied the constraint without being discussed, because it was satisfied structurally.
03 — Approach
The process differed significantly across phases. Phase one was a build-then-review cycle where the most important decisions happened after the MR opened. Phase two was a build-and-iterate cycle shaped by a stale CSS build trap and three attempts at a symbol. The redesign was a canvas-first cycle where every decision resolved before any code was written.
- 01
Phase One: Build, Then Reshape Under Review
Six quiet days of building, then four consecutive days in which review comments changed the data model twice. The types table pattern — predefined value sets as a seeded database table with named constants, not string enums — came from the first review round and became the structural foundation of the whole feature. The second round moved the visibility flag off the organizations table and cut 221 lines of permission migration. Almost everything structural happened after the MR was opened.
- 02
The Types Table Decision
The reviewer's first comment was that predefined value sets belong in a types table, not a string enum, with a seeder and named constants. The types table went in the same day. It is the pattern the whole feature rests on: slugs, labels, legend text, icons, and colors as data rather than code. A fifth level could be seeded tomorrow by someone who has never seen the presentation layer. The page degrades gracefully for an unknown slug rather than rendering an empty circle.
- 03
The Visibility Flag Move
Moving the visibility flag from the organizations table onto the matrix row collapsed two visibility conditions into one, removed a join, retired an Ecto.Multi, and closed a security hole by shape rather than by vigilance. With the field absent from Organization, no form can cast it. One thing was lost: a manufacturer can no longer be marked "intended for the matrix" before being rated, because until then there is no row to hold the flag. That tradeoff was accepted.
- 04
Phase Two: The Symbol Problem
Partial support needed a half-filled circle. Font Awesome had the glyph. It took three attempts to discover that an icon font cannot draw what the design needed simultaneously — a filled half, which carries the meaning, and a thin edge, so the circle does not shout. fa-solid gives a filled half with a heavy edge. fa-regular gives a thin edge with no fill. CSS makes both properties independent values, so the pill draws itself with no glyph at all. Recognising that three rounds earlier would have saved all three.
- 05
Redesign: Canvas Before Code
The redesign settled every structural decision in 79 minutes on a shared canvas. The business owner reviewed four artboard rounds: today's table recreated for comparison, the proposal, a filtered state, and detail callouts. Each round removed something — filter chips, row lines, dark artboard, mobile layout, stat cards. What remained went directly to code with no visual iteration, because every argument had already happened on the canvas.
04 — Outcome
The capability matrix shipped across three phases between September and October 2026, moving from an internal admin tool to a live client-facing feature used by every Hatch customer.
Key decisions
Flag on organizations
A boolean on the organizations table. Publishing a manufacturer requires a join to read the flag, an Ecto.Multi to write across two tables, and a narrow changeset to prevent the general manufacturer edit form from casting it — which had already created a privilege-escalation hole.
Flag on the matrix row
The visibility flag lives on manufacturer_capability_matrices. One column filter, one upsert, no join. The security hole closes by shape: with no field on Organization, no form can cast it. One thing is lost — a manufacturer cannot be marked "intended for the matrix" before it is rated, because there is no row to hold the flag.
Why
The reviewer's argument was about table hygiene, but the simplification was larger than that argument suggested. Moving the flag eliminated the Multi, the join, the narrow changeset, and the class of bug that changeset was guarding against. The tradeoff — no "pending" state before rating — was accepted.