Ux Cards

Cards Skill

How this skill behaves (read first)

This is a generative skill. The default failure modes: card stuffing (multiple topics, long text, every detail crammed into one card), shadow soup (shadows on the card and its image and its buttons), and cards-for-everything (card grids where users need ranked, comparable results). A card is one digestible topic in one container, inviting exploration — and card layouts fit browsing, not searching. This skill gates:

1. Establish what's being carded and how users consume it — browsing vs. searching decides whether cards are even right.
2. Apply the always-true core — one topic per card, internal hierarchy, progressive disclosure, restraint.
3. Surface the container-style and interaction decisions (elevated/outlined/flat, full-card click, media) with trade-offs.

Then it hands off to ux-heuristics-audit, ux-accessibility-audit, ux-aesthetics-audit, and ux-microcopy-audit for validation.

---

Step 0 — Establish context before designing

Ask if not known; state the assumption if proceeding without an answer:

• Browsing or searching? Cards are flat — every card carries equal rank. That's perfect for exploratory browsing (feeds, galleries, dashboards) and wrong for ranked search results or spec-by-spec comparison (use lists/tables). If users hunt for a specific item, reconsider cards entirely.
• Content per item — text-only (metrics, notes) → text cards; media + summary + actions → rich cards; people → user cards (avatar, name, status, one CTA). Heterogeneous items with varying detail are cards' home turf.
• One action or several? A single action argues for a fully clickable card; multiple actions need an internal button hierarchy.
• Platform/density — mobile truncates harder, needs bigger touch areas, and responsive card grids reflow.

---

The always-apply core (correct for almost every case)

One card = one topic

• Split distinct topics into separate cards. The container's whole job is signaling "everything in here is related; everything outside isn't." Mixed-topic cards make users parse what belongs together.
• The card is a teaser, not the article — progressive disclosure. Short supporting text, truncated with an ellipsis that invites opening. Don't answer every question on the card face.
• ❌ A card with full description, specs, three links, and two buttons ✅ Image, title, two-line teaser…, one clear action

Hierarchy inside the card

• Decide what users should see first and enforce it with size, weight, color, and placement — title over preview, primary action over secondary.
• Color hierarchy: when everything is highlighted, nothing is. One emphasized element ("Learn more") — auxiliary actions (save, favorite) stay quiet.
• Primary vs. secondary actions visibly differentiated; overflow (kebab ⋮) menu in the top-right corner where users expect it.

Restraint is the style

• Simplicity first: typography and negative space over horizontal dividers — dividers are rarely helpful inside a card.
• One shadow per card, maximum. Never shadow media, buttons, or icons inside an already-elevated card. Shadow visible on all four edges (soft ambient, not just a sharp key light).
• Consistent padding and margins — elements breathe, related items cluster, content never touches edges.
• Concise labels: no redundant words or punctuation; microcopy-grade brevity.
• Quality media only — blurry or grainy images break trust; text over images keeps ≥4.5:1 contrast (use a translucent dark overlay).

---

The context-dependent decisions (surface, don't auto-apply)

| Decision | Apply when | Avoid / adapt when | Default recommendation | |---|---|---|---| | Elevated (shadowed) card | Clickable cards needing affordance; mimics physical cards; intensify shadow on hover | Dense dashboards where dozens of shadows add noise | Default for interactive cards — with the one-shadow rule | | Outlined card | Grouping without depth; cleaner, quieter surfaces | When interaction needs stronger affordance | Use for non-interactive or low-emphasis grouping | | Flat card | Minimal aesthetics with a distinct background color separating it | Without any visual cue (users miss it entirely) | Only with a contrasting background + hover microinteraction | | Fully clickable card | One primary action; bigger target, less cognition | Multiple competing actions inside (nested click traps) | Whole card clickable + hover cue when there's a single action | | Rich media card | Browsing experiences where the visual is the content (products, articles, video) | Media as decoration that crowds the message | Media earns its space or gets cut | | User card | Social/people contexts: avatar + name + status + one CTA | Cramming full profiles into the card | Identity + one action; the rest on the profile | | Card grid vs. list/table | Heterogeneous, visual, browsable content | Ranked results, spec comparison, scanning for a known item | Cards for discovery; lists/tables for lookup (→ ux-tables for data) |

---

Validate the result (orchestration)

> Hand-offs name each lens by its installable skill name. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.

After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by docs/orchestration-policy.md, or route the whole thing through ux-design-review. Here, heuristics and microcopy are Tier A (auto-run); accessibility, aesthetics, and mobile-responsiveness are Tier B (offered) — under an existing design system aesthetics is suppressed and accessibility narrows to usage; mobile-responsiveness applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.

• ux-heuristics-audit (Tier A) — recognition (does the card read as one unit?), consistency across the card set, affordance of clickability.
• ux-accessibility-audit (Tier B — offer; narrow under a design system) — text-over-image contrast (≥4.5:1), touch targets for in-card actions, focus states for clickable cards.
• ux-aesthetics-audit (Tier B — offer; suppress under a design system) — this is the shadow-overload and clutter check: hierarchy, padding rhythm, one-emphasis rule.
• ux-microcopy-audit (Tier A) — title and label brevity, teaser text quality.
• ux-mobile-responsiveness-audit (Tier B — offer; applies only on mobile) — when the context is mobile: grid reflow, truncation, touch areas.

If the audits surface a conflict (e.g., marketing wants more on the card vs. scannability), resolve back toward the primary task: a card's job is to be grasped in a glance and invite the click — not to be the destination.

---

Common do/don't patterns

| ❌ Don't | ✅ Do | |---|---| | Three topics in one container | One topic per card; split into logical groups | | Full article text on the card face | Teaser + truncation… — progressive disclosure | | Shadows on card + image + buttons | One shadow per card; nothing inside gets its own | | Horizontal dividers slicing the card | Negative space and typography do the separating | | Every element bold and colorful | One emphasized element; color hierarchy | | Flat card indistinguishable from the page | Distinct background + hover cue, or use outlined/elevated | | Card with one action but only a tiny link is clickable | Entire card clickable, pointer cursor, hover effect | | White text straight over a busy image | Dark translucent overlay, ≥4.5:1 contrast | | Card grid for ranked search results | Lists/tables for lookup; cards for browsing | | Kebab menu floating in a novel corner | Top-right, where users expect it | | Ship without checking | Hand off to heuristics + accessibility + aesthetics + microcopy |

---

Source lessons (Uxcel)

• UI Cards Types & When to Use Them
• Best Practices for Designing UI Cards

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Uxcel-Lab
• Source: Uxcel-Lab/product-skills
• License: MIT
• Homepage: https://uxcel.com

Install and usage instructions live in the source repository linked above.