docs(layer-card): RFC for first-class composition of Secondary

[mattrothenberg]

Summary

Proposal page for aligning teams on a recommended composition pattern for LayerCard.Secondary. Not a code change to LayerCard itself — this is a design artifact.

An audit of LayerCard.Secondary across our largest consumer found ~360 usages across ~140 files. ~40 of those reimplement flex items-center justify-between with two grouping <div>s by hand, plus a long tail of inline icons, tooltips, badges, switches, tabs, and pagination crammed into the same slot. Heights drift visibly across the product.

Proposal (in three parts)

1. Pin the height. Replace p-4 with h-14 px-4 on Secondary (56px). Vertical sizing comes from h-14, not padding, so content variation can't change the strip height.
2. Add LayerCard.Title and LayerCard.Actions sub-components. Composition only — no slot props. JSX order = visual order. Actions uses ml-auto (no justify-between parent toggle).
3. Support render on Secondary for the "whole header is a link" case. Already idiomatic in kumo (LayerCard root, Tooltip, etc.). Hover/focus/cursor affordances activate via [&[href]]: attribute selectors baked into the base classes — automatic when consumers do render={<a/>}, no-op otherwise.

What this PR adds

• packages/kumo-docs-astro/src/pages/components/layer-card-secondary.mdx — the proposal doc
• packages/kumo-docs-astro/src/components/demos/LayerCardSecondaryProposalDemo.tsx — 12 demos covering each archetype from the audit (label-only, title with icon/tooltip/badge, toggle card, toolbar with Tabs, toolbar with Select size="sm" as the recommended alternative, linked header, footer, skeleton, height-consistency strip, anti-pattern)
• A changeset for @cloudflare/kumo-docs-astro

The prototype Title / Actions / render-aware Secondary are defined locally in the demo file as a stand-in. They are not exported and the real LayerCard is unchanged.

Required follow-up component tweaks

The 56px height invariant requires a few small changes elsewhere before it can ship for all use cases. Each is scoped and tracked separately:

• Tabs — needs a small variant (~32px control height) to fit the Secondary strip. Today consumers override with [&_[role=tablist]]:h-9.
• Select — confirm size="sm" is the documented choice for Actions. Already fits today; this proposal uses it as the recommended alternative until small Tabs lands.
• Pagination — variable height, currently used in ~6 footer-style Secondaries. Calibration needed.

Why composition (not props)

Considered but rejected: <LayerCard.Secondary title="…" icon={…} badge={…} actions={…} />. Every prop introduces a "what wins, prop or children?" broken state, and prop-shaped slots impose an order the consumer can't override. Composition answers all of that by construction.

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@472

commit: 8e1a350

[github-actions]

Docs Preview

View docs preview

Commit: 9e58dde

[github-actions]

Visual Regression Report — 19 changed, 19 unchanged

19 screenshot(s) with visual changes:

Button / Variant: Secondary

161 px (0.16%) changed

Before	After	Diff

Button / Loading State

869 px (0.86%) changed

Before	After	Diff

Dialog / Dialog With Actions

200 px (0.2%) changed

Before	After	Diff

Dialog / Dialog Basic

192 px (0.19%) changed

Before	After	Diff

Dialog / Dialog Alert

2,499 px (2.46%) changed

Before	After	Diff

Dialog / Dialog Confirmation

352 px (0.35%) changed

Before	After	Diff

Dialog / Dialog With Select

130 px (0.13%) changed

Before	After	Diff

Select / Select Basic

530 px (0.52%) changed

Before	After	Diff

Select / Select Sizes

947 px (0.51%) changed

Before	After	Diff

Select / Select Without Label

161 px (0.16%) changed

Before	After	Diff

Select / Select With Field

635 px (0.54%) changed

Before	After	Diff

Select / Select Placeholder

595 px (0.59%) changed

Before	After	Diff

Select / Select With Tooltip

294 px (0.29%) changed

Before	After	Diff

Select / Select Custom Rendering

611 px (0.6%) changed

Before	After	Diff

Select / Select Loading

0 px (0%) changed

Before	After	Diff

Select / Select Grouped

194 px (0.19%) changed

Before	After	Diff

Select / Select Grouped With Disabled

673 px (0.66%) changed

Before	After	Diff

Select / Select Long List

1,346 px (1.14%) changed

Before	After	Diff

Select (Open)

2,657 px (0.01%) changed

Before	After	Diff

19 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Ghost
• Button / Variant: Destructive
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Icon Only
• Button / Disabled State
• Button / Title
• Button / Link as Button
• Dialog / Dialog With Combobox
• Dialog / Dialog With Dropdown
• Dialog (Open)
• Select / Select Multiple
• Select / Select Complex
• Select / Select Disabled Options
• Select / Select Disabled Items

---

Generated by Kumo Visual Regression