/repeated-component-alignment

name: repeated-component-alignment
description: Cards, rows, tiles and cells are fixed slot models that stay aligned when content length varies. Use when building or reviewing any repeated component.
metadata:
  priority: 8
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "**/*.vue"
    - "**/*.svelte"
    - "design-system/**"
    - "ui/**"
  promptSignals:
    phrases:
      - "card"
      - "list item"
      - "repeated component"
      - "equal height"
      - "same place"
      - "aligned"
      - "read more"
      - "truncate"
      - "ellipsis"
      - "line clamp"
      - "different lengths"
      - "tile"
retrieval:
  aliases:
    - repeated component consistency
    - slot model
    - equal height cards
    - aligned list items
    - card alignment
    - truncate text
    - line clamp
    - ellipsis
    - read more link position
  intents:
    - keep elements in the same place across repeated components
    - make cards or list items the same height
    - align CTAs and values across instances
    - handle long and short text in a repeated component
    - truncate overflowing text but keep it readable
  examples:
    - my cards look different because the descriptions have different lengths
    - keep the read more link in the same place on every card
    - the badge pushes the title down on some items
    - align the prices across all the tiles
    - truncate long titles but keep them readable

Repeated Component Alignment

When a component is rendered many times — a card grid, a list, a table, a nav menu, a row of KPI tiles, a feed — it stops being a single box and becomes a **pattern**. The value of a pattern is rhythm: the eye learns the layout once and scans the same slot across every instance (the title row, the price row, the action row). Variable content length breaks that rhythm unless the component is built to absorb it.

The principle is general. A **card** is the most common case, but the same rule governs list rows, table cells, nav items, tiles, comment entries, dashboard widgets, search results — anything repeated. Treat each as a **fixed slot model**, not a free-form container.

The goal: **content of any length, instances that look identical.** This is partly content production (write to a target length) and partly layout engineering (build slots that tolerate the variance). This skill covers the layout half and where the two meet.

---

The Slot Model

Name the slots once and treat them as a contract every instance honours. A product card, as a worked example:

┌──────────────────────┐
│ [media]              │  ← fixed aspect ratio
│                      │
├──────────────────────┤
│ ● Badge              │  ← optional slot, space reserved
│ Title                │  ← clamp to N lines
│ Subtitle / meta      │
│                      │
│ Description text…    │  ← flexible slot, grows
│                      │
├──────────────────────┤
│ €19.99      Read more│  ← anchor, pinned to bottom
└──────────────────────┘

The same three rules apply to a **list row** (avatar · name · meta · status pinned right), a **KPI tile** (label · big number · trend pinned bottom), or a **search result** (title · url · snippet clamped):

• **Every slot has a fixed position**, whether or not it has content in a given instance.
• **One slot absorbs the variance** (usually the description/snippet). All others are fixed or clamped.
• **Anchor elements are pinned** — the primary action or value (CTA, price, status, trend) sits at the same position in every instance regardless of how much content is above or beside it.

---

Controls That Swap by State

A cell that shows a different control per state — a button, then an input, then a value or link — is still one slot. Give each position a fixed width and stretch whatever control it holds to fill it. The same position carries the same role in every row and every state. Content-sized controls change width with their label, so the row reflows, neighbouring controls move under the cursor, and the column stops reading as one list.

A toolbar's primary action gets the same protection. Pin it to the row's edge, keep the row from wrapping, let the one variable-width item (a range label, a title) truncate, and keep controls that only sometimes apply mounted and disabled rather than unmounted. A control kept disabled this way uses `aria-disabled="true"` so it stays focusable, ignores activation in its own handler (the attribute blocks nothing), and says why it is unavailable in a tooltip or nearby text (see [[wcag-accessibility]]). Nothing that appears, disappears or changes width may sit between the primary action and its edge, or the button moves while the user aims at it.

Aligning the Anchor

The single most common defect: text of different lengths makes the anchor element (a "Read more" link, a price, a status chip) float to a different position in each instance. Fix it by letting the flexible slot grow and pushing the anchor to a fixed edge.

**Vertical layout (cards, tiles) — pin the footer to the bottom:**

.item {
  display: flex;
  flex-direction: column;
  height: 100%;            /* fill the grid/flex track */
}

.item__media {
  aspect-ratio: 4 / 3;     /* never let media height vary */
  object-fit: cover;
}

.item__description {
  flex: 1;                 /* the flexible slot absorbs the slack */
}

.item__footer {
  margin-top: auto;        /* pin the anchor (price + CTA) to the bottom */
}

For instances to be **equal height as siblings**, the container track must stretch them — CSS Grid and Flex do this by default (`align-items: stretch`). Then `height: 100%` makes each instance fill its track, and `margin-top: auto` aligns every footer.

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
  gap: var(--space-4);
  /* align-items: stretch is the default — do not override it */
}

**Horizontal layout (