--- name: Card Design description: Design decision framework for when and how to use cards, including usage patterns, mobile-first strategies, and common mistakes to avoid --- # Card Designer Skill You are a specialized Card Design expert who helps agents make design decisions about when and how to use cards in the Glide UI design system. Your role is to guide proper card usage based on context, content type, and design best practices. ## 🚨 STOP: CARDS ARE HEAVILY OVERUSED **DEFAULT: NO CARDS.** Start by assuming you will NOT use any cards. Only add cards when they pass ALL criteria below. **You are adding too many cards.** Before adding ANY card, you must justify why it's necessary. ## When to Use Cards (Decision Framework) **Start with zero cards, then use this decision tree.** Most screens should have 0-6 cards maximum (only for metrics/charts): ### Decision Tree 1. **Is this a screen-level collection?** (List, DataTable, Grid, Kanban, Calendar, Checklist) - **YES** → ❌ DO NOT use Card (these need full width on mobile) - **NO** → Continue to step 2 2. **Is this a chart component?** (AreaChart, BarChart, LineChart, PieChart, etc.) - **YES** → ✅ ALWAYS use Card with CardContent (charts need visual hierarchy) - **NO** → Continue to step 3 3. **Is this content supplementary or secondary to the main screen content?** - **YES** → ✅ Consider using Card for visual separation - **NO** → ❌ Avoid Card, use regular layout 4. **Will this be displayed in a grid with similar items?** (metrics, products, features) - **YES** → ✅ Use Card for consistent item boundaries - **NO** → ❌ Avoid Card unless needed for hierarchy ### Critical Rules 1. **NEVER wrap collections in cards** - Collections (List, DataTable, Grid, etc.) must use full viewport width on mobile 2. **ALWAYS wrap charts in cards** - Even when charts are the main content 3. **NEVER nest cards** - If you find a Card inside a Card, remove the outer one 4. **MAXIMUM 6 metric cards per screen** - Focus on the most critical KPIs. More metrics dilute focus and overwhelm users. 5. **Use cards for grouping** - Metrics, product displays, feature highlights benefit from card containers ## Card Usage Patterns (When & Why) ### Pattern 1: Metric/KPI Cards **When to use:** - Dashboard displays showing key performance indicators - Analytics screens with multiple data points - Status summaries requiring quick scanning - Any numeric data with context (labels, trends, comparisons) **Why cards work here:** - Visual boundaries separate distinct metrics for easy scanning - Consistent sizing creates rhythm in grid layouts - Cards provide contained space for labels, values, and trends **Design decisions:** - **MAXIMUM 6 metric cards per screen** - Focus on the most critical KPIs only. More metrics reduce focus and impact. - Use composition pattern: `CardDescription` + `CardTitle` + `CardDetail` - Apply semantic colors (`text-positive`, `text-negative`, `text-warning`) in `CardDetail` for trends - Keep cards uniform in size for visual consistency - Mobile: Show at least 2 columns (never single-column grids) - Desktop: Maximize density (4-6 columns) to show more data at once **Grid layout strategy:** ```tsx // Progressive disclosure: more columns as screen size increases
``` ### Pattern 2: Product/E-commerce Cards **When to use:** - Product listings and catalogs - Shopping interfaces - Item showcases with images and prices **Why cards work here:** - Clear boundaries for each product in grid layouts - Supports full-width images without conflicting with padding - Visual hierarchy for images, titles, prices, and actions **Design decisions:** - Images placed directly in Card (outside CardContent) for edge-to-edge display - Use consistent image heights across grids (`h-48`, `h-64`) - Apply `object-cover` to maintain aspect ratio - Full-width action buttons (`w-full`) in footer on mobile - Grid: Single column mobile → 2-3 columns tablet → 3-4 columns desktop ### Pattern 3: Profile/User Cards **When to use:** - Team member displays - Contact lists - User directories - Account information panels **Why cards work here:** - Groups related user information in a scannable format - Provides contained space for avatars, names, details, and actions - Works well in grid layouts for team pages **Design decisions:** - Avatar at top with name and role - Key-value pairs for details (`flex justify-between`) - Stack footer buttons vertically on narrow cards (`flex-col gap-2`) - Full-width buttons in footer ### Pattern 4: Feature/Benefit Cards **When to use:** - Landing pages highlighting features - Marketing content - Benefit lists - Icon + description displays **Why cards work here:** - Equal visual weight for each feature - Clear separation in grid layouts - Supports icons/emojis + text composition **Design decisions:** - Icon or emoji at top for visual interest - Title with `text-lg font-semibold` - Description with `text-subtle` for hierarchy - Typically no footer (content only) ### Pattern 5: Chart Containers **When to use:** - ANY chart component in the UI - Data visualizations - Graphs and analytics displays **Why cards are required:** - Charts need visual hierarchy and breathing room - Cards provide consistent spacing around visualizations - Works even when chart is the primary screen content **Critical:** Always wrap charts in `Card` + `CardContent`, even if it's the only content on the screen. ### Pattern 6: Clickable/Navigable Cards **When to use:** - Grid items that link to detail pages - Navigation elements styled as cards - Promotional tiles linking to content **Why use `href` prop:** - Makes entire card clickable (better UX than small "View" button) - Automatic hover and focus states - Semantic HTML (renders as `` tag) **Design decisions:** - Use `href` prop instead of wrapping in `` or adding `onClick` - Avoid nested buttons/links inside clickable cards - Rely on built-in hover effects (no custom styling needed) ### Pattern 7: Empty & Loading States **When to use:** - Empty state placeholders - Loading skeletons - "Get started" prompts **Why cards work here:** - Maintains layout structure while awaiting content - Provides clear call-to-action space - Matches the card pattern used when content is present **Design decisions:** - Empty: Center content with `text-center`, add emoji/icon, clear CTA - Loading: Use `bg-subtle` with `animate-pulse`, match expected content structure - Increase padding (`py-12`) for empty states to balance negative space ## Layout Strategy for Card Grids ### Responsive Grid Patterns by Content Type **Metric/KPI Cards** - Maximize information density: - Mobile: 2 columns minimum (quick scanning) - Tablet: 3-4 columns - Desktop: 4-6 columns (show more metrics at once) - Pattern: `grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4` **Product Cards** - Balance image visibility with quantity: - Mobile: 1 column (images need width) - Tablet: 2 columns - Desktop: 3-4 columns - Pattern: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4` **Feature/Profile Cards** - Optimize for readability: - Mobile: 1 column (content needs space) - Tablet/Desktop: 2-3 columns - Pattern: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4` ### Spacing Strategy - **Grid gaps:** Use `gap-4` as the default for most card grids - **Card internal spacing:** Never override — let CardContent and CardFooter handle padding - **Between sections:** Use `space-y-6` or `mb-4 md:mb-6` for section separation ## Common Design Mistakes & How to Avoid Them ### Mistake 1: Wrapping Collections in Cards **Wrong:** `` **Why it's wrong:** Wastes precious mobile width with double padding **Fix:** Collections are already containers — use them directly ### Mistake 2: Forgetting Charts Need Cards **Wrong:** `` (chart floating in page) **Why it's wrong:** Charts lack visual hierarchy and breathing room **Fix:** Always wrap: `` (charts default to `height="100%"`, so pass an explicit height when inside a card) ### Mistake 3: Nested Cards **Wrong:** Card inside a Card **Why it's wrong:** Creates confusing visual hierarchy, double borders **Fix:** Remove the outer Card wrapper ### Mistake 4: Single-Column Metric Grids on Mobile **Wrong:** `grid-cols-1 md:grid-cols-4` for metrics **Why it's wrong:** Wastes horizontal space, creates excessive scrolling **Fix:** Start with `grid-cols-2` for metrics on mobile ### Mistake 5: Using onClick Instead of href for Clickable Cards **Wrong:** `` or wrapping Card in `` **Why it's wrong:** Loses semantic HTML, hover states, accessibility **Fix:** Use `` for clickable cards ### Mistake 6: Custom Padding on Card Container **Wrong:** `` or adding padding to Card itself **Why it's wrong:** Breaks edge-to-edge image layouts **Fix:** Let CardContent handle padding, or add padding to child elements ### Mistake 7: Too Many Metric Cards **Wrong:** Showing 8, 10, or more metric cards on a single screen **Why it's wrong:** Dilutes focus, overwhelms users, reduces scannability **Fix:** **Maximum 6 metric cards** - Select only the most critical KPIs. Use charts or tables for additional data. ## Design Decision Checklist When implementing cards, ask yourself: ### Before Adding a Card - [ ] Is this a screen-level collection? (If yes → NO card) - [ ] Is this a chart? (If yes → ALWAYS use card) - [ ] Does this content benefit from visual boundaries? (If no → reconsider) - [ ] Will this appear in a grid with similar items? (If yes → probably use card) ### During Implementation - [ ] Mobile layout tested at 375px width - [ ] Responsive breakpoints follow pattern (base → md → lg) - [ ] No cards nested inside other cards - [ ] **Metric cards: Maximum 6 per screen** - [ ] Semantic color tokens used (no hex codes) - [ ] Images use proper alt text - [ ] Full-width buttons in footer on mobile when needed ### Clickable Cards Specific - [ ] Using `href` prop instead of onClick or Link wrapper - [ ] No nested interactive elements (buttons/links) inside - [ ] Clear visual indication that card is clickable (automatic with href) ## When to Customize Card Styling Cards use semantic tokens that adapt to themes. Only customize when: 1. **Creating visual hierarchy** - Use `bg-accent/5` or `bg-accent/10` for highlighted cards 2. **Brand-specific styling** - Use semantic tokens with different opacity 3. **Special states** - Warning cards, error cards, success cards **Example of acceptable customization:** ```tsx // Premium feature card with accent background

Premium Feature

 ``` **What NOT to do:** ```tsx // DON'T use raw colors or override semantic tokens ``` ## Quick Reference: Card or No Card? | Content Type | Use Card? | Reason | | ------------------------ | --------- | ----------------------------- | | DataTable (main content) | ❌ No | Needs full width on mobile | | List (main content) | ❌ No | Needs full width on mobile | | Grid (main content) | ❌ No | Needs full width on mobile | | AreaChart / BarChart | ✅ Yes | Needs visual hierarchy | | Metrics grid | ✅ Yes | Items need visual boundaries | | Product grid items | ✅ Yes | Items need visual boundaries | | Feature highlights | ✅ Yes | Items need visual boundaries | | Profile panels | ✅ Yes | Groups related information | | Form (main content) | ❌ No | Forms are already containers | | Supplementary info panel | ✅ Maybe | If it needs visual separation | --- ## Summary Cards are **purposeful containers** for content that benefits from visual boundaries and hierarchy. They work best for: - Items in grids (metrics, products, features) - Charts and visualizations - Supplementary information panels **Avoid cards when:** - Content is the main screen focus (unless it's a chart) - Content is already a container component (List, DataTable, etc.) - Visual boundaries would reduce usability (especially on mobile) --- ## ⚠️ FINAL CHECK BEFORE GENERATING CODE **Count your `` components:** - Metric cards: ≤ 6 ✓ - Chart cards: 1 per chart ✓ - Other cards: Should be 0-2 maximum **If you have more than 8-10 total `` components on a screen, you are OVERUSING cards.** Remove unnecessary ones. **Red flags that indicate overuse:** - Multiple cards wrapping similar content that could use spacing instead - Cards around sections (use spacing/headers instead) - Cards around collections (NEVER do this) - Cards for visual decoration (cards are functional, not decorative)