--- name: product-card-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit ProductCard for product summaries with image adapter, name, price, stock, badges, rating, actions, and card button variants. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux framework-consumer-integration app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/molecules/product-card.tsx libs/ui/src/tokens/components/molecules/_product-card.css libs/ui/stories/molecules/product-card.stories.tsx libs/ui/src/molecules/product-card.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit ProductCard Usage Use ProductCard for product listing and recommendation surfaces. It is a compound component; do not rebuild product card structure with generic divs. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `ProductCard`. **Use it when** - Products in listings, search results, recommendations and carousels. **Use something else when** | Need | Use instead | | --- | --- | | Product detail page | the detail layout with Gallery | | Admin product rows | DataTable | **Do** - Show, in this order: image, name, key variant info, price (formatted, with the previous price when discounted), availability, one action. - Make the name the link to the product; keep one primary action (`Add to cart`). - Confirm `Add to cart` with a toast (`Added to cart`) and update the cart count. - Keep card heights consistent in a grid; clamp long names to two lines with the full name available. **Don't** - Stack more than two badges. - Hide the price until hover. **Copy and states** - Price via `Intl.NumberFormat` currency; discounts as `−20 %` badge plus struck-through old price. **Behaviour (from the UX spec)** - Image, name, price, stock and actions describe the same variant. A nested cart or wishlist action never also triggers the card's link, and stays its own tab stop. - `ProductCard.Stock` has three states; don't map the six `AvailabilityStatus` states onto it automatically — compose `AvailabilityStatus` for unknown, preorder or pending. - `cart` adds this offer (glyph `token-icon-cart-button`), `detail` opens the same product, `wishlist` (`token-icon-wishlist-button` / heart) changes interest and never shows "saved" before the app confirms. `token-icon-cart` alone means "open the cart", not "add". - A purely informational card shows no action button; an out-of-stock card never offers a purchase that can't succeed. **Figma → code** | Figma | Code | | --- | --- | | `layout=column` / `row` | `layout` | | ProductCardButton `buttonVariant=cart…wishlist` | `ProductCard.Button buttonVariant` (+ code-only `custom`) | | ProductCardStock `status=in-stock…out-of-stock` | `ProductCard.Stock status` | | ProductCardImage, Name, Price, Badges, Rating, Actions | `ProductCard.Image`, `.Name`, `.Price`, `.Badges`, `.Rating`, `.Actions` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/ProductCard → UX guidelines*. ## Setup ```tsx {product.title} {price} In stock Add ``` Supported parts: ```text Root layout: column | row Image as adapter Stock status: in-stock | limited-stock | out-of-stock Button buttonVariant: cart | detail | wishlist | custom Badges, Rating, Actions, Name, Price ``` `ProductCard.Name` is an `h3` by default; set `as` (or `nameAs` on `ProductCardTemplate`) so it follows the page outline, e.g. `as="h2"` for cards directly under the page `h1`. ## Core Patterns ### Use slots for meaning Name, Price, Stock, Rating, Badges, Actions and Button each map to component tokens. Do not replace them with local headings and paragraphs. ### Use NextImage adapter in Next apps Pass `as={NextImage}` to `ProductCard.Image`. ### Choose buttonVariant by action Use `cart` for add-to-cart, `detail` for details, `wishlist` for wishlist actions, and `custom` only when tokens/API cannot express the action. ## Common Mistakes ### HIGH Custom product card Wrong: ```tsx

{name}

``` Correct: ```tsx {name} ``` Source: libs/ui/src/molecules/product-card.tsx ### HIGH Wrong stock status Wrong: ```tsx Available ``` Correct: ```tsx Available ``` Source: libs/ui/src/molecules/product-card.tsx ### HIGH Inline card styling Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_product-card.css ## Validation Commands ```sh rg -U -n "]*className=.*(rounded-|border-|p-|shadow-)" apps rg -n "status=\"(available|sold-out|low-stock)\"|buttonVariant=\"(primary|danger)\"" apps rg -P -n "]*as=\\{?NextImage)" apps ``` ## Shared contracts Aggregate ratings in ProductCardTemplate and ProductCard.Rating with `rating.readOnly=true` are static accessible summaries, not editable controls or tab stops. An explicitly interactive ProductCard.Rating keeps the underlying Rating API; supply a meaningful label/name and use the standalone Rating story for form-capture guidance. Card images use a consistent 4:3 aspect ratio in column layouts. Detail and wishlist actions keep their own hover/pressed colors rather than inheriting primary Button pressed styling. ProductCard is a content layout, not a single interactive field: it has no root sm/md/lg axis. Its actions use Button's canonical sm height and explicit action-specific foreground/background tokens. Images reserve a consistent aspect ratio; names reserve two text lines for row-to-row comparison. Public media/layout changes need a Figma-sync follow-up. Keep custom row/grid demos responsive with standard grid utilities and constrain their parent width. Every demo action must update local state or give explicit local-only feedback; wishlist buttons expose their toggle through aria-pressed. ## Template and adapter contracts ProductCard.Image preserves required `src`, `alt` and selected adapter props; select an adapter with `as`. Use `alt=""` only for deliberately decorative images. ProductCard.Button inherits Button loadingText/isLoading, native click events, disabled, type, ARIA and ref props; its size and visual variant are owned by the card. ProductCardTemplate accepts ReactNode names, `href`, `linkAs` and `linkProps` using the kit Link adapter pattern. A destination makes the name a link inside its heading, not a wrapper around cart/wishlist buttons. Without a destination it stays a nonlinked heading. Preserve normal modified-click behavior in applications; intercept navigation only in demos. Pass localized `originalPriceLabel` and `currentPriceLabel` (English defaults) for sale-price meaning. Previous amounts use deletion markup plus an actual visually hidden label. Badge objects are forwarded in full, including attributes, size, styles and passive handlers; give changing or duplicate-label badges stable `key` values. Row cards respond to their container width: narrow cards stack media and content so ratings and primary actions are not squeezed.