data-display-and-selection

Files (1)

• SKILL.md

SKILL.md (first lines)

# Data Display and Selection

Complex data collections — products, files, users, orders, tasks — have no single correct view. Different tasks call for different views. Browsing benefits from grid; comparing details benefits from list or table; bulk management benefits from a dense table with mass actions. Give users the choice.

---

## View Modes

Offer multiple views when the data has both visual and detailed dimensions.

| View | Best for | When to default |
|---|---|---|
| **Grid** | Visual items: products, images, files, cards | When items are visually distinct and browsing is the primary task |
| **List** | Moderate detail: tasks, emails, articles | When a key piece of text or metadata drives selection |
| **Table** | Dense data: orders, reports, user management | When multiple columns of data must be compared |

**View toggle placement:** top-right of the collection, adjacent to sort/filter controls. Use icon buttons with tooltips (`grid`, `list`, `table`). Persist the user's choice in localStorage.

```
[Filter ▾]  [Sort ▾]          [⊞ Grid]  [☰ List]  [⊟ Table]
```

On mobile, collapse to the view that works best for the content — grid for visual items, list for text. Do not offer a view toggle on small screens unless both views are genuinely usable.

### Past a Handful of Items, Cards Become a Table

A card earns its border when it is one of a few things a reader compares side by side. Repeat that border fifteen times down a page and it separates nothing: every row is boxed, so the boxes carry no information and the reader pays for them in noise.

**Past roughly six items, drop to a table.** Keep a horizontal rule between rows or stripe them, and drop the side and outer rules entirely. Vertical edges do no work in a list already bounded by the page's own column, and the eye groups by proximity and alignment long before it needs a drawn line.

**The exception is a card that contains something a row cannot.** An image, a chart, a per-item control set, a body of text that has to wrap: those keep their card at any count, because the border is holding a composition together rather than separating one line from the next. A product grid, a gallery, a set of dashboard tiles are not covered by this rule. The test is what the border encloses. If it encloses a line of text and a value, it is decoration on a table row. If it encloses a layout, it is a card.

Then give the header the emphasis the boxes were pretending to provide: a heavier weight, or a smaller size in caps with letterspacing, or a darker ground. Choose by how much the reader needs to navigate the list. A long reference table wants a header that anchors scanning; a short one can let the first column do it.

---

## Selection: Prefer Large Hit Areas

Checkboxes are small targets. Requiring users to hit a 16×16px checkbox to select a row is unnecessary friction — especially on touch devices.

**Default: the entire row or card is the selection target.**

- Click anywhere on the row → selects the row (background shifts, checkbox checks)
- The checkbox is a visual indicator of selection state, not the only way to select
- Keyboard: Space selects the focused row; Shift+click extends selection; Ctrl/Cmd+click toggles individual items

```css
.row {
  cursor: pointer;
  background: var(--color-surface);
  transition: background 100ms ease-out;
}
.row:hover {
  background: var(--color-grey-50);
}
.row.selected {
  background: var(--color-primary-subtle); /* subtle brand tint */
}
```

For cards in a grid, the entire card is the selection area — not just a checkbox in the corner.

---

## Selected State Visual Language

Selected items communicate their state through a background colour shift — not just a checkbox tick.

**Background:** `--color-primary-subtle` — the brand primary colour heavily desaturated and lightened to ~5–8% opacity. Perceptible but not jarring.

**Left border accent (optional):** A 3px left border in `--color-primary` reinforces the selected state for list and table rows.

**Checkbox:** Checked and filled with `--color-primary`. The checkbox is a secondary signal, not the primary one.

```css
.row.selected {
  background: var(--color-primary-subtle);    /* e.g. hsl(224, 21%, 94%) */
  border-left: 3px solid var(--color-primary);
}
```

**Do not** use a high-contrast or saturated background for selection — it competes with content and makes dense tables hard to read.

---

## Mass Actions

When one or more items are selected, mass actions appear. They disappear when nothing is selected.

**Placement:** A contextual toolbar that appears at the top of the collection (replacing or supplementing the standard toolbar) when selection is active.

```
[✓ 3 selected]  [Delete]  [Archive]  [Export]  [Move to ▾]  [× Clear]
```

- Lead with the selection count: "3 selected" — confirms the scope before any action
- Show only actions applicable to the selection — if some actions require a single item, disable them for multi-select
- "Clear" deselects everything and dismisses the toolbar
- Destructive mass actions (Delete) always trigger a confirm dialog naming the count: "Delete 3 projects? This cannot be undone."

**Select all:** A checkbox in the table header selects all items on the current page. A secondary action "Select all 247" extends to the full dataset.

```
[☑ Select all on page]  →  [Select all 247 results]
```

---

## Sorting and Filtering

### Column sorting (table view)
- Click a column header to sort ascending; click again for descending; third click clears sort
- Active sort column shows a directional arrow (↑ ↓)
- Only sortable columns are clickable — non-sortable columns have no hover state on header

### Filters
- **Fetch parameters and result filters live in different places.** A form holds what needs a new fetch (date range, owner, location) and its submit button. A toolbar directly above the results holds what narrows rows already loaded: toggles, segmented filters, the visible-of-total count, and actions that use the results. Mixed together, the user cannot tell which controls need the submit button, and result actions read as part of the search.
- Persistent filters belong in a sidebar or filter bar above the collection
- Active filters should be visible as chips/tags that can be individually removed

From dembrandt/dembrandt-skills, MIT.

More from dembrandt/dembrandt-skills