Comparison Table Builder

---
name: comparison-table-builder
description: Use when generating a product or feature comparison table. Triggers on "comparison table", "vs competitor page", "feature matrix", "us vs them".
---

# Comparison Table Builder

Comparison tables are powerful but easy to abuse. The "us vs them" page where you have 47 green checks and they have 47 red Xs is transparent BS and erodes trust. Be honest — your product loses on some axes; admit it.

## Required inputs

1. **Items being compared** — your product + 1-3 competitors, OR your tiers (Free/Pro/Enterprise)
2. **Categories** — group features into 3-6 categories (e.g., Collaboration, Security, Pricing)
3. **Features** — 10-30 rows. Each: name, helper text, value per item
4. **Value types** — boolean (✓ / —), text ("Up to 10"), number (10), or unique cell content (logos, badges)
5. **Mobile strategy** — card-per-item (recommended) or horizontal scroll

If 90%+ of cells favor your product and you're comparing to a real competitor, push back: it's either dishonest or you're comparing to the wrong product.

## Output format

A single component (React/Vue/HTML) with Tailwind styling. Two layouts: desktop table and mobile cards.

## Desktop layout

```
<table class="w-full">
  <thead class="sticky top-0 bg-white border-b">
    <tr>
      <th class="text-left">Feature</th>
      <th>Your Product</th>
      <th>Competitor A</th>
      <th>Competitor B</th>
    </tr>
  </thead>
  <tbody>
    <tr><th colspan="4" class="bg-gray-50 text-left">Collaboration</th></tr>
    <tr class="hover:bg-gray-50">
      <td>Real-time editing</td>
      <td>✓</td>
      <td>✓</td>
      <td>—</td>
    </tr>
    ...
  </tbody>
</table>
```

- Sticky thead under any main nav (`top-14` or `top-16`)
- Category rows: `<tr><th colspan="N">` styled as section break
- Hover: `hover:bg-gray-50` on the row, applied via `<tr>`
- Your column: subtle highlight (`bg-indigo-50/50`) — make it findable, not screaming
- Cells: `text-center` for booleans, `text-left` for text values
- Helper text: tooltip on the feature name (`title="..."` plus a Radix tooltip for non-truncating)

## Cell variants

| Value | Display | A11y |
|-------|---------|------|
| true  | ✓ (green) + `<span class="sr-only">Yes</span>` | "Yes" |
| false | — (gray) + `<span class="sr-only">No</span>` | "No" |
| partial | "Limited" or "Add-on" | text |
| number | `tabular-nums text-right` | text |
| custom | logo, badge | with `aria-label` |

Color is not the only signal: green check + red X reads as "good" / "bad" but fails for color-blind users. Always pair with shape (✓ vs —).

## Mobile pattern

Below `md:`, transform to per-item cards:

```
[Your Product]
  Collaboration
    ✓ Real-time editing
    ✓ Comments
    — Whiteboard

[Competitor A]
  Collaboration
    ✓ Real-time editing
    ...
```

Implementation: hide `<table>` below `md:`, render an alternative `<div>` with the card layout. Or use CSS `display: block` and reflow. Both are valid; cards-via-divs are easier to control.

## Category collapse (optional)

For 30+ rows, collapsible categories help. Use `<details><summary>` for accessibility — no JS needed.

```
<details open>
  <summary class="cursor-pointer text-lg font-semibold py-2">Collaboration</summary>
  <table>...</table>
</details>
```

## Honesty heuristics

- **Don't list features only YOU have**: feels like cherry-picking
- **Include 1-2 features the competitor wins on**: builds credibility
- **Use the competitor's exact feature naming**: don't relabel to make yours look better
- **Date the comparison**: features change. `<p class="text-xs text-gray-500">Last updated: April 2026</p>` covers you.
- **Link to the competitor's page** for verification: shows confidence

If you can't follow these, the comparison is marketing, not information — and readers will sense it.

## Accessibility

- `<caption class="sr-only">Comparison of [items]</caption>` describes the table
- Sticky header doesn't break tab order — `thead th` is focusable for screen readers via headers/scope
- `scope="col"` on column headers, `scope="row"` on row headers (feature names)
- Color + shape — never just color
- `aria-label` on icon-only cells: `<span aria-label="Included">✓</span>`
- For `<details>`: works with keyboard natively

## Anti-patterns

- **All green for you, all red for them**: nobody believes it
- **Misleading row labels**: "Modern UI" — subjective, reads as marketing
- **Tooltips that hide critical info**: anything important goes in the cell
- **Tiny mobile horizontal scroll**: 7-column tables on mobile are unreadable. Cards instead.
- **Comparison without dates**: outdated comparisons get screenshotted and blow up on Twitter
- **No "Notes" column for caveats**: forces oversimplification

## Output

Return the table component + mobile card variant + category data structure. Top comment lists:
- Items compared
- Categories and row counts
- Mobile pattern (cards / scroll)
- Honesty notes (which features the competitor wins; date stamp)