In a shared component library, a card component renders its own title, but pages nest that card at different depths so the correct heading rank varies. How would you design the component's markup contract, and what are the tradeoffs of each option?

## Why this is a design problem, not a markup problem Heading rank is a property of *position in the document*. A component is defined independently of position. That mismatch is structural: no amount of cleverness inside the component recovers information it was never given, and nothing in the platform computes rank from nesting — heading level is read straight off the tag name. So the only question is how the page's knowledge reaches the component, and every option is a tradeoff between ergonomics, auditability and failure mode. ## Option 1: rank as an explicit input The component accepts something like a `headingLevel` value and renders the matching tag. ```html <!-- what the page ends up emitting for a card placed under an h2 --> <article class="card"> <h3 class="card__title">Refund window</h3> <p>Thirty days from delivery.</p> </article> ``` **Strengths.** The level is visible where the decision is made. Reviewers can see it in the diff. It is greppable, so an audit can find every call site. It survives moving the component, because moving it forces you to touch the call. **Weaknesses.** It is repetitive, and it can be wrong at every call site independently. Under composition — a card inside a panel inside a page section — humans miscount. And a default value is a trap: whichever default you pick will be silently wrong somewhere. This is still my starting point, because its failures are *visible* and its fixes are local. ## Option 2: rank derived from composition A container establishes a level, and anything rendered inside it renders one rank deeper, so nesting produces the outline automatically. This is essentially the intent of the HTML5 outline algorithm — the difference being that here you implement it yourself in application code rather than expecting the platform to do it, and it can therefore genuinely work. **Strengths.** Correct-by-construction for the common case. Pages can be rearranged without touching every title. It removes the class of bug where someone copies a call site into a deeper context. **Weaknesses.** The rank is invisible at the call site, so nothing in a diff shows you it changed. It breaks in exactly the cases that are hardest to notice: a component rendered outside the nesting it assumes, content moved between containers, or anything rendered into a different part of the tree than where it is written. Deep composition can also run past level 6, which native tags cannot express. And it creates a rule every contributor must learn before their markup is correct. **When it wins.** Large, deeply-composed products with many contributors, where per-call-site correctness has already failed empirically. Adopt it with a test that renders representative pages and asserts the heading sequence. ## Option 3: one hardcoded rank everywhere Every card title is, say, an `h3`. Nobody chose this; teams arrive at it. It is not a compromise, it is a decision to have no outline. Every page's heading list is a flat run of same-level entries, and rank-based navigation stops distinguishing anything. It also hides the problem from tooling: skipped-level checks pass, because nothing is skipped — the structure is simply absent. Treat a component whose title tag is fixed in its implementation as a defect to fix, not a convention to keep. ## Option 4: role="heading" with aria-level ```html <div role="heading" aria-level="7">Nested subsection title</div> ``` This is real ARIA and it is honestly the right tool in two narrow cases: markup produced by a constrained renderer that cannot emit arbitrary tags, and genuine nesting deeper than six levels. The costs are real too — you give up the native element, you own the numeric value, and the default level for `role="heading"` is 2, so an omitted `aria-level` silently mislabels the heading. As a general strategy it violates the native-first instinct for no benefit. Worth noting that nesting deeper than six levels is usually a content-structure smell before it is a markup problem. The honest first response is to question the depth. ## What holds it together regardless of choice Whichever contract you pick, it decays without enforcement: - **Automated checks in CI.** Rules like axe-core's `heading-order` catch skipped levels on rendered pages. They cannot catch a flat outline or an unhelpful `h1`, so they are a floor, not a guarantee. - **A heading-sequence review step.** Reading only the headings of a page, in order, and asking whether it works as a table of contents is a two-minute check that catches what tooling cannot. - **A documented rule for the `h1`.** Exactly one per page, naming the page. That is a page-template concern, not a component one, and it is worth owning centrally so no component can claim it. - **A component API that makes the wrong thing hard.** If the title tag is not configurable at all, the flat outline is guaranteed by construction and no review will save you. ## The framing to give in an interview "The rank belongs to the page, not the component, so the contract has to carry it. I default to an explicit level input because its failures are visible, consider a composition-derived level once scale makes per-call-site correctness unreliable, reject a hardcoded rank because it silently deletes the outline, and keep `role="heading"` for the cases where I cannot emit a native tag. Then I back the choice with rendered-page checks, because none of these survive contact with a large team unenforced."