@fracazo/design-system 0.6.0 → 0.7.0

package/DESIGN.md

@@ -220,7 +220,7 @@ Source order is reading order; landmarks and heading levels are real;
 
 ## Components
 
-The package ships seventeen shadcn-based components under
+The package ships eighteen components, seventeen shadcn-based and one house primitive, under
 `@fracazo/design-system/ui/*`. Each carries an intent block at the top of
 its source (one line, then Use for, Avoid when, Variants); that block is
 the contract and is updated whenever variants change. In brief:
@@ -250,6 +250,11 @@ the contract and is updated whenever variants change. In brief:
   bespoke. **Calendar** exists for range selection; a single date uses a
   native input. **SortableList** ranks a small capped set with drag,
   touch and keyboard.
+- **OfferCard** is the one house primitive: a linked offer surface with
+  a media slot, tag, title, description and a source footer, for a grid
+  of peer offers. The whole card is one link; `highlighted` is its single
+  emphasis signal; hover motion is CSS transitions under motion-safe.
+  It lays out in a grid, never a carousel.
 
 A component that must import app code (stores, data clients, routes)
 does not belong in the package; it stays in the product, like

package/README.md

@@ -10,7 +10,7 @@ It lives in three places.
 
 **Lint.** Eight ESLint rules catch what a reviewer would: colour literals, radius literals, stock palette, dark pairs, arbitrary sizes, focus rings, text on dark surfaces. The build fails before anyone posts a screenshot.
 
-**Components.** Each of the seventeen components carries its own guidance in JSDoc: use for, avoid when, variants. The decision sits where it gets made, not in a doc nobody opens.
+**Components.** Each of the eighteen components carries its own guidance in JSDoc: use for, avoid when, variants. The decision sits where it gets made, not in a doc nobody opens.
 
 **The agent skill.** AI tools load the design rules before they build or review any UI, route to the reference that applies, and cite rules by stable ID. The system proposes, the human commits.
 
@@ -26,7 +26,7 @@ Built for BirthGuide and birthplans.app, and designed to start the next product
 | `ds-build-brand-css` | Composes the plain-CSS token file a product serves publicly (e.g. `/brand.css`) |
 | `ds-init` and `template/` | Writes a new product: Next 16, Tailwind v4, this package, a blank brand file and the guardrails on, pinned to the package version that wrote it |
 | `css/motion.css` | The animation vocabulary the components use (enter, exit, accordion, the fade, zoom, blur and slide utilities); `roles.css` imports it |
-| `@fracazo/design-system` and `./ui/*` | `cn` and seventeen shadcn-based components (button, card, dialog, form, select, sortable-list and the rest), each with intent JSDoc: use for, avoid when, variants |
+| `@fracazo/design-system` and `./ui/*` | `cn` and eighteen components (button, card, dialog, form, select, sortable-list, offer-card and the rest), each with intent JSDoc: use for, avoid when, variants |
 | `@fracazo/design-system/eslint` | Eight guardrails as an ESLint plugin, one per rule ID: colour literals, arbitrary clamp sizes, dark pairs, radius literals, stock palette, `focus:` rings, text on always-dark surfaces, em dashes |
 | `demo/index.html` | A showcase page that renders the roles in both modes off a served `/brand.css` |
 | `skills/product-design/` | The agent skill: request modes, routed references, rules with stable IDs, exemplars, coverage gaps. Point your CLAUDE.md or AGENTS.md at its `SKILL.md` |

package/dist/src/index.d.ts

@@ -16,6 +16,7 @@ export * from "./ui/dialog.js";
 export * from "./ui/form.js";
 export * from "./ui/input.js";
 export * from "./ui/label.js";
+export * from "./ui/offer-card.js";
 export * from "./ui/popover.js";
 export * from "./ui/progress.js";
 export * from "./ui/radio-group.js";

package/dist/src/index.js

@@ -16,6 +16,7 @@ export * from "./ui/dialog.js";
 export * from "./ui/form.js";
 export * from "./ui/input.js";
 export * from "./ui/label.js";
+export * from "./ui/offer-card.js";
 export * from "./ui/popover.js";
 export * from "./ui/progress.js";
 export * from "./ui/radio-group.js";

package/dist/src/ui/offer-card.d.ts

@@ -0,0 +1,52 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+/**
+ * A linked offer surface: media on top, a tag, a title, a line of
+ * description and a footer that names the source, with an arrow that
+ * answers hover.
+ *
+ * Use for: a grid of peer offers the reader picks from (deals, price
+ * matches, plans), where the whole card is one link and the footer
+ * carries the source (a retailer, a brand, a promo code, a was-price).
+ * Avoid when: the item has more than one action (use a house card with
+ * Buttons), or when the cards would sit in a carousel; the system rejects
+ * carousels, so lay OfferCards in a grid and let it wrap.
+ * Slots: `media` is a node, not a URL, so a product can pass its own tile
+ * (an initial-letter fallback, a next/image) and it fills a 16:9 area;
+ * `footer.avatar` fills a 40px circle; `footer.meta` is a node so it can
+ * carry a struck-through was-price, not only a code. `tagIcon` defaults to
+ * Lucide's Tag.
+ * States: `highlighted` tints the body with the primary at low opacity, the
+ * one emphasis signal for "cheapest" or "best"; nothing else changes, so a
+ * grid keeps one signal per card. `external` opens in a new tab and says so
+ * in the accessible name.
+ * Motion: hover lifts the card 8px, scales the media and rotates the arrow,
+ * all as CSS transitions on the anchor's hover, and only under
+ * motion-safe; with reduced motion the card sits still and the arrow only
+ * fills. The card fills its column at any width; height follows a grid
+ * row's tallest card because the anchor is h-full and the body flexes.
+ */
+type OfferCardProps = Omit<React.ComponentProps<"a">, "href" | "title" | "media"> & {
+    href: string;
+    /** Opens in a new tab, with rel and an sr-only note on the accessible name. */
+    external?: boolean;
+    /** Fills a 16:9 area; give an image `fill` (next/image) or `size-full object-cover`. */
+    media?: React.ReactNode;
+    tag?: string;
+    tagIcon?: LucideIcon;
+    title: string;
+    description?: string;
+    footer?: {
+        /** Fills a 40px circle. */
+        avatar?: React.ReactNode;
+        name: string;
+        /** Second line under the name: a code, a was-price, a note. */
+        meta?: React.ReactNode;
+    };
+    /** The one emphasis signal: a subtle primary tint on the body. */
+    highlighted?: boolean;
+    /** Heading level for the title; h3 suits a card under a section heading. */
+    titleAs?: "h2" | "h3" | "h4" | "p";
+};
+declare function OfferCard({ href, external, media, tag, tagIcon: TagIcon, title, description, footer, highlighted, titleAs: TitleTag, className, ...props }: OfferCardProps): React.JSX.Element;
+export { OfferCard, type OfferCardProps };

package/dist/src/ui/offer-card.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowRight, Tag } from "lucide-react";
+import { cn } from "../cn.js";
+function OfferCard({ href, external = false, media, tag, tagIcon: TagIcon = Tag, title, description, footer, highlighted = false, titleAs: TitleTag = "h3", className, ...props }) {
+    return (_jsxs("a", { "data-slot": "offer-card", "data-highlighted": highlighted || undefined, href: href, target: external ? "_blank" : undefined, rel: external ? "noopener noreferrer" : undefined, className: cn("group flex h-full flex-col overflow-hidden rounded-2xl bg-card text-card-foreground shadow-card", "transition-[translate,box-shadow] duration-200 ease-out hover:shadow-card-hover motion-safe:hover:-translate-y-2", "outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", className), ...props, children: [media !== undefined && media !== null ? (_jsx("div", { className: "aspect-video overflow-hidden bg-muted", children: _jsx("div", { className: "relative size-full transition-transform duration-300 ease-out *:size-full *:object-cover motion-safe:group-hover:scale-105", children: media }) })) : null, _jsxs("div", { className: cn("flex flex-1 flex-col", highlighted && "bg-primary/5"), children: [_jsxs("div", { className: "flex flex-1 flex-col gap-2 px-5 pt-5 pb-4", children: [tag ? (_jsxs("span", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(TagIcon, { "aria-hidden": "true", className: "size-4 shrink-0" }), tag] })) : null, _jsx(TitleTag, { className: "text-xl font-semibold tracking-tight text-balance", children: title }), description ? (_jsx("p", { className: "text-sm text-muted-foreground text-pretty", children: description })) : null] }), footer ? (_jsxs("div", { className: "mx-5 mb-4 flex items-center gap-3 border-t border-border pt-4", children: [footer.avatar !== undefined && footer.avatar !== null ? (_jsx("span", { className: "size-10 shrink-0 overflow-hidden rounded-full *:size-full *:object-cover", children: footer.avatar })) : null, _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-sm font-semibold", children: footer.name }), footer.meta !== undefined && footer.meta !== null ? (_jsx("span", { className: "block truncate text-sm text-muted-foreground", children: footer.meta })) : null] }), _jsx("span", { "aria-hidden": "true", className: "flex size-11 shrink-0 items-center justify-center rounded-full bg-secondary text-secondary-foreground transition-[background-color,color,rotate] duration-200 ease-out group-hover:bg-primary group-hover:text-primary-foreground motion-safe:group-hover:-rotate-45", children: _jsx(ArrowRight, { className: "size-4" }) })] })) : null] }), external ? _jsx("span", { className: "sr-only", children: " (opens in a new tab)" }) : null] }));
+}
+export { OfferCard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fracazo/design-system",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "An agent-native design system. Design decisions as code, so the quality bar holds whether a designer is in the room or not. Lint guardrails, components with intent docs, and an agent skill. One brand file per product, the system stays the same.",
   "license": "MIT",
   "author": "Alex Fracazo",

package/skills/product-design/references/components.md

@@ -26,6 +26,7 @@ Components, has the one-paragraph digest.
 | Secondary detail under a heading | `Accordion` | Tabs |
 | Ranking a small capped set | `SortableList` | drag on a plain list |
 | Long free text | `Textarea` (auto-grows) | Input |
+| A grid of peer offers, each one link | `OfferCard` in a grid | a carousel, a house card with a Button per offer |
 
 ## Composing