Review the public API, not the implementation internals

What it is

Once a component is called, consumers bind to the layer it promises: props, slots, observable state, accessibility roles, semantic aliases they are allowed to read. Class names in a stylesheet, private hooks, an incidental padding value — callers should not depend on those, and authors should remain free to change them. API-first review aims comments at that public contract, not at pixels in a screenshot or selectors in an implementation. Review the internals and contributors learn to pretty the happy path. Review the interface and they learn which table is frozen and which layer can still move next week.

The implementation may swap inside the contract. Change the contract, and every call site changes with it.

Why it happens

Coupling follows the names that are depended on. If review spends itself on “could this CSS be shorter” and “is this radius 8”, it freezes internals that should stay replaceable tomorrow. The expensive mistakes are elsewhere: a type prop that means both visual and HTML, a slot swallowed in one variant, keyboard and screen-reader behavior never written down, no list of aliases that survive a theme switch. None of that shows up in a still. Make the review object an interface table — meaning, default, and illegal combinations for each input; outputs and events; name/role/state in each state — and comments land on the face callers will actually touch. Selector hygiene can wait for the author or a later refactor; it should neither block admission nor stand in as a proxy for quality.

Where it stops holding

Accessibility and safety sometimes are the implementation: whether focus is trapped in a dialog, whether the control is a native button rather than a clickable div. Those look internal and are part of the contract, because assistive tech and browsers only honor that layer. If a performance budget says “do not read layout on the render path”, implementation choices enter review too. Visual regression can catch accidental drift as a supplement; it cannot replace the interface table — a component that matches pixels but whose props cannot be predicted will still be called wrong. One-off internal tools and unpublished drafts may be judged on effect; the moment the piece is declared “importable from other repos”, review switches to the contract.

Applying it

• Require an interface table in the contribution package: props, slots, events, accessibility promises, readable semantic aliases. No table, no review.
• Split comments into two columns: “contract” and “implementation suggestion”. Merge/no-merge is decided only by open items in the contract column; suggestions do not block.
• Do not treat “pixel-identical to the mock” as a pass, unless the gap falls on a visual token the contract named.
• Check: sample comments from the last five admission reviews. If more than half discuss class names, specific pixels, or internal file layout, the review is on the wrong layer. Then have an engineer who did not implement the piece call it from the interface table alone: if they can pick the right props on the first try without opening source, the table is carrying the contract. If they have to open source to use it, the API review has not happened.

Related

• Same group: R1.06.1 Who may add a component must be named · R1.06.2 An ungoverned system decays into a component pile · R1.06.3 High contribution cost drives teams around the system · R1.06.4 Promote only after several real call sites exist · R1.06.6 Maintenance is accepted with the component, not after the merge
• Adjacent: R1.12 Usage guidelines and anti-examples · R1.02 Component libraries and variants
• Search terms: API-first review · public contract · component interface