FRD: Product Card

Document Summary

Field	Details
Feature Name	Product Card
Status	Draft
Owner	David Holmes
Contributors	Design, Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #57
Last Updated	2026-05-26

---

Introduction

Overview

Product Card is an e-commerce widget that displays a product with image, name, price, optional badge (e.g., “Sale”, “New”), and an add-to-cart CTA. It is designed for SaaS applications with marketplace, catalog, or storefront features. The existing PricingCard handles subscription plan presentation; Product Card focuses on physical or digital product display with purchase intent. The widget is intentionally compact (size S) and composable.

Goals

• Deliver a <ProductCard> component that displays a product image, name, price, optional badge, and add-to-cart button.
• Use design-system tokens for all visual properties.
• Support variant states: default, on-sale, out-of-stock, featured.
• Ship Storybook stories with realistic e-commerce data.

Non-Goals

• Full product detail page layout.
• Cart management or checkout flow.
• Product search or filtering.
• Image gallery or zoom.
• Reviews or ratings display (separate component).

---

Scope

In Scope

Area	Description
Component	<ProductCard> displaying product image, name, price, badge, and CTA
Image	Product image with aspect-ratio container and fallback placeholder
Name	Product name with optional truncation
Price	Current price with optional original price (strikethrough for sales)
Badge	Optional status badge (“Sale”, “New”, “Sold Out”, custom)
CTA	Add-to-cart button with loading and disabled states
Variants	Default, on-sale (with original price), out-of-stock (disabled CTA), featured (highlighted border)
Stories	Storybook stories for all variants and states

Out of Scope

Area	Reason
Product detail page	Separate layout pattern
Cart management	Application-layer concern
Image gallery/zoom	Separate component
Reviews/ratings	Separate component
Product comparison	Separate widget

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building e-commerce or marketplace features	A composable product card using DS primitives
Designers	Design-system consumers	Consistent product display aligned with DS tokens
End Users	Shoppers browsing products	Clear product info with easy add-to-cart action

Pain Points

User	Pain Point	Impact
Developers	Building product cards from scratch with image containers, price formatting, badge placement, and cart button state	Repeated boilerplate, inconsistent cards across products
End Users	Inconsistent product cards make it hard to scan and compare products	Slower browsing, reduced purchase intent

---

Definitions

Term	Definition
Product Card	A compact display widget showing a product’s key information and purchase action
Original Price	The pre-discount price shown with strikethrough styling during sales
CTA	Call to action; in this context, the “Add to Cart” button
Featured	A visual variant with a highlighted border or background to draw attention

---

Current State

Existing Behavior

PricingCard in src/components/ui/cards/pricing-card.tsx displays a subscription pricing tier with plan name, price, billing period, feature list, and CTA. It is designed for pricing pages, not product catalogs. There is no product-focused card for e-commerce use cases.

Current Limitations

• No e-commerce product card component.
• PricingCard is subscription-focused and does not support product images, sale prices, or stock status.
• No pattern for original/sale price display with strikethrough.

Existing Workarounds

• Developers build custom product cards with ad hoc image containers and inline styles.
• Sale-price display requires manual strikethrough styling.

---

Proposed Solution

Summary

Introduce <ProductCard> that accepts product data (image, name, price, originalPrice, badge, onAddToCart) and renders a compact card. The image fills an aspect-ratio container at the top. Below it, the product name, price (with optional strikethrough original price), and an optional badge display. At the bottom, an “Add to Cart” button fires the onAddToCart callback. Out-of-stock products show a disabled button with “Sold Out” text.

Key Capabilities

• Product image with configurable aspect ratio and placeholder fallback.
• Product name with two-line truncation.
• Current price display with optional original price (strikethrough) for sales.
• Configurable badge (text and tone).
• Add-to-cart button with loading state and disabled state for out-of-stock.
• Featured variant with highlighted border.
• Hover elevation animation.

User Experience

Users see a grid of product cards. Each card shows a product image, name, price, and an “Add to Cart” button. Sale items show the original price crossed out next to the sale price, with a “Sale” badge. Out-of-stock items show a “Sold Out” badge and a disabled button. Hovering a card slightly elevates it.

Developer Experience

<ProductCard
  image="/products/headphones.jpg"
  name="Wireless Noise-Cancelling Headphones"
  price="$249.99"
  originalPrice="$329.99"
  badge={{ text: "Sale", tone: "destructive" }}
  onAddToCart={() => addToCart("headphones-1")}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	ProductCard displays product image, name, and price	Must	-
FR-002	Optional original price renders with strikethrough	Must	-
FR-003	Optional badge renders with configurable text and tone	Must	-
FR-004	Add-to-cart button fires onAddToCart callback	Must	-
FR-005	Out-of-stock variant disables the CTA	Must	-
FR-006	Featured variant applies highlighted border	Should	-
FR-007	Image placeholder renders when image is not provided	Should	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	image prop renders in an aspect-ratio container (default 4:3)	Consistent image display	Must
FUNC-002	When image is not provided, a placeholder with a product icon renders	Graceful fallback	Should
FUNC-003	name renders with two-line truncation (line-clamp-2)	Consistent card heights	Must
FUNC-004	price renders prominently; originalPrice renders with line-through styling	Clear pricing	Must
FUNC-005	badge prop accepts { text: string; tone?: string } and renders a Badge	Flexible status indication	Must
FUNC-006	onAddToCart fires when the CTA button is clicked	Cart integration	Must
FUNC-007	isAddingToCart prop shows loading spinner on the CTA button	Feedback during async add	Should
FUNC-008	outOfStock prop disables CTA and changes button text to “Sold Out”	Clear unavailability	Must
FUNC-009	featured prop adds a highlighted border or ring	Visual emphasis	Should
FUNC-010	Card has hover elevation animation	Interactive feel	Should

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Component renders in under 10ms	Performance	Must
NFR-002	Image lazy-loads with loading="lazy"	Performance	Should
NFR-003	All interactive elements are keyboard-navigable	Accessibility	Must
NFR-004	Works in light and dark themes	Theming	Must
NFR-005	No new runtime dependencies	Maintainability	Must
NFR-006	Image container does not cause layout shift on load	Performance	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
name	string	Product name	Yes
price	string	Display price (pre-formatted)	Yes
image	string	Product image URL	No
imageAlt	string	Image alt text	No (defaults to name)
originalPrice	string	Original price (shown with strikethrough)	No
badge	{ text: string; tone?: string }	Status badge config	No
onAddToCart	() => void	Add-to-cart callback	No
isAddingToCart	boolean	Loading state for CTA	No
outOfStock	boolean	Disable CTA with “Sold Out” text	No
featured	boolean	Highlighted variant	No
aspectRatio	string	Image aspect ratio	No (default: "4/3")
ctaLabel	string	Custom CTA button text	No (default: "Add to Cart")
className	string	Additional CSS classes	No

Example Usage

import { ProductCard } from "@/components/ui/product-card";

<div className="grid grid-cols-3 gap-4">
  <ProductCard
    image="/products/headphones.jpg"
    name="Wireless Noise-Cancelling Headphones"
    price="$249.99"
    originalPrice="$329.99"
    badge={{ text: "Sale", tone: "destructive" }}
    onAddToCart={() => addToCart("sku-001")}
  />
  <ProductCard
    image="/products/speaker.jpg"
    name="Portable Bluetooth Speaker"
    price="$79.99"
    badge={{ text: "New", tone: "info" }}
    onAddToCart={() => addToCart("sku-002")}
  />
  <ProductCard
    name="Limited Edition Earbuds"
    price="$149.99"
    outOfStock
  />
</div>

API Notes

• price and originalPrice are pre-formatted strings; the component does not handle currency formatting.
• badge.tone maps to DS Badge tones (success, warning, destructive, info, default).
• aspectRatio uses CSS aspect-ratio property.
• onAddToCart is optional; cards without it render without a CTA (display-only mode).

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Product image has meaningful alt text (defaults to product name)	-
A11Y-002	Price and original price are conveyed to screen readers	aria-label on price region: “Price $249.99, originally$329.99”
A11Y-003	Badge text is accessible (not just visual)	Badge component handles this
A11Y-004	Add-to-cart button has descriptive label including product name	e.g., “Add Wireless Headphones to cart”
A11Y-005	Out-of-stock state conveyed to screen readers	aria-disabled, “Sold Out” text
A11Y-006	Card is not a focusable link (CTA is the interactive element)	Avoids nested interactive problem

Checklist

• Keyboard support is defined.
• Focus behavior is defined.
• Screen reader behavior is defined.
• Color contrast requirements are met.
• Reduced motion behavior is considered.
• Semantic HTML expectations are documented.
• ARIA usage is defined only where needed.

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page with overview and props table	Storybook	Must
DOC-002	”When to use / When not to use” guidance (vs. PricingCard)	Storybook docs	Must
DOC-003	Stories for default, on-sale, out-of-stock, featured, and no-image variants	Storybook	Must
DOC-004	Grid layout example story showing multiple cards	Storybook	Must

---

Dependencies

Dependency	Type	Owner	Status	Notes
Badge	Engineering	Design System	Ready	Status badges
Button	Engineering	Design System	Ready	Add-to-cart CTA
Design tokens	Design	Design System	Ready	Color, spacing, typography, elevation
PricingCard	Reference	Design System	Ready	Reference for card shell pattern (not composed directly)

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Pre-formatted price strings do not support localization	Prices may display incorrectly for different locales	Document that consumer handles currency formatting; consider adding a formatPrice utility in the future
No product link/href prop	Cards cannot be clickable links to product pages	Add optional href prop that wraps the card in an anchor; or let consumer wrap externally
Two-line name truncation may cut off important information	Product names may be unclear	Consumer should provide concise names; tooltip on hover shows full name

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the card support an href prop to make the entire card a link?	David Holmes	Open	—
Q-002	Should a quantity selector be included alongside the add-to-cart button?	David Holmes	Open	—
Q-003	Should the card support a “quick view” action that opens a detail overlay?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Product image renders in an aspect-ratio container	FUNC-001
AC-002	Image placeholder renders when image is not provided	FR-007, FUNC-002
AC-003	Product name renders with two-line truncation	FUNC-003
AC-004	Price and original price (strikethrough) render correctly	FR-001, FR-002, FUNC-004
AC-005	Badge renders with correct text and tone	FR-003, FUNC-005
AC-006	Add-to-cart button fires onAddToCart	FR-004, FUNC-006
AC-007	Out-of-stock variant shows disabled “Sold Out” button	FR-005, FUNC-008
AC-008	Featured variant applies highlighted border	FR-006, FUNC-009
AC-009	Loading state shows spinner on CTA button	FUNC-007
AC-010	All Storybook stories render without errors	DOC-003
AC-011	Component passes axe accessibility audit	NFR-003

---

LLM Handoff Instructions

Expected LLM Behavior

• Follow the requirements and acceptance criteria in this document.
• Do not expand scope beyond the In Scope section.
• Respect the Out of Scope section.
• Use Badge for status badges, Button for the add-to-cart CTA.
• Use CSS aspect-ratio for the image container.
• Use line-clamp-2 for product name truncation.
• Use line-through styling for original price.
• Reference PricingCard for card shell styling patterns (rounded corners, border, padding) but do not extend it.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Build a full product detail page.
• Add cart management logic.
• Add a quantity selector.
• Modify existing PricingCard or Badge components.
• Add currency formatting logic (prices are pre-formatted strings).

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Separate ProductCard from PricingCard	Different use cases: e-commerce products vs. subscription plans; different data shapes	David Holmes
2026-05-26	Pre-formatted price strings rather than number + currency	Keeps the component simple; currency formatting varies by locale and is consumer responsibility	David Holmes
2026-05-26	No href prop in v1	Keeps interactive pattern simple (button only); wrapping in anchor can be done by consumer	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft