@stoovles/gap-kit 1.0.0

package/guidelines/composition/buy-box.md

@@ -0,0 +1,132 @@
+# Buy Box
+
+The Buy Box is the core purchase area on a Product Detail Page (PDP). It is **not** a single component — it is a composition of existing atoms and components arranged in a specific vertical layout.
+
+## Structure
+
+Build a Buy Box by stacking the following components top-to-bottom:
+
+1. **Breadcrumb** — navigation context (e.g. "Women / Jeans / Slim Fit")
+2. **Product Name** — plain text styled with `--text-header-font-size` (16px) and `--font-weight-base-heavier`
+3. **Price** — use the `Price` component to show original, sale, and discount pricing
+4. **Notification** (optional) — inline variant for promotional messaging (e.g. "Extra 40% off with code SAVE40")
+5. **SelectorSwatch + SwatchGrid** — color selection with swatches; show the selected color label
+6. **SelectorGroup + Selector** — size selection pills with a "Size Guide" link
+7. **Fulfillment** — shipping/pickup tiles for delivery options
+8. **Button (primary)** — "Add to Bag" full-width CTA
+9. **BopisSwitch** — buy online, pick up in store toggle with store info
+10. **Accordion** — collapsible sections for Product Details, Fit & Sizing, Shipping & Returns
+
+## Example
+
+```jsx
+import {
+  Breadcrumb,
+  Price,
+  Notification,
+  SelectorSwatch,
+  SwatchGrid,
+  SelectorGroup,
+  Selector,
+  FulfillmentTile,
+  Fulfillment,
+  Button,
+  BopisSwitch,
+  Accordion,
+  AccordionItem,
+} from "@stoovles/gap-kit";
+
+function BuyBox() {
+  return (
+    <div style={{ maxWidth: 400, display: "flex", flexDirection: "column", gap: 16 }}>
+      <Breadcrumb items={[
+        { label: "Women", href: "/women" },
+        { label: "Jeans", href: "/women/jeans" },
+        { label: "Slim Fit", href: "/women/jeans/slim" },
+      ]} />
+
+      <h1 className="gap-buy-box-name">Mid Rise Vintage Slim Jeans</h1>
+
+      <Price
+        original="$79.95"
+        sale="$49.99"
+        discount="38% off"
+      />
+
+      <Notification type="info" variant="inline">
+        Extra 40% off with code SAVE40
+      </Notification>
+
+      <SelectorGroup label="Color" selectedLabel="Dark Wash">
+        <SwatchGrid>
+          <SelectorSwatch color="#2C3E50" label="Dark Wash" active />
+          <SelectorSwatch color="#8BA3C7" label="Light Wash" />
+          <SelectorSwatch color="#1A1A1A" label="Black" />
+        </SwatchGrid>
+      </SelectorGroup>
+
+      <SelectorGroup label="Size" selectedLabel="8">
+        <Selector options={[
+          { label: "4", value: "4" },
+          { label: "6", value: "6" },
+          { label: "8", value: "8" },
+          { label: "10", value: "10" },
+          { label: "12", value: "12", unavailable: true },
+        ]} value="8" />
+      </SelectorGroup>
+
+      <Fulfillment>
+        <FulfillmentTile
+          title="Shipping"
+          availability="In Stock"
+          selected
+        >
+          Free on orders $50+
+        </FulfillmentTile>
+        <FulfillmentTile
+          title="Pick Up"
+          availability="Available nearby"
+        >
+          Ready in 2 hours
+        </FulfillmentTile>
+      </Fulfillment>
+
+      <Button variant="primary" fullWidth>Add to Bag</Button>
+
+      <BopisSwitch
+        storeLabel="Union Square"
+        storeSubtext="0.3 mi"
+        availability="In Stock - Few Left"
+      />
+
+      <Accordion>
+        <AccordionItem title="Product Details">
+          <p>Mid rise. Slim through hip and thigh. Premium stretch denim.</p>
+        </AccordionItem>
+        <AccordionItem title="Fit & Sizing">
+          <p>Model is 5'10" and wearing a size 8.</p>
+        </AccordionItem>
+        <AccordionItem title="Shipping & Returns">
+          <p>Free shipping on $50+. Free returns within 30 days.</p>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  );
+}
+```
+
+## Layout guidelines
+
+- The Buy Box should be placed to the **right** of the product image gallery on desktop, or **below** on mobile.
+- Maximum width: ~400px on desktop; full-width on mobile.
+- Use consistent 16px vertical spacing between sections.
+- The "Add to Bag" button should always be the most prominent element.
+- Promotional notifications should appear above the color selector.
+- Accordion sections at the bottom should default to collapsed.
+
+## Rules
+
+- Do NOT create a standalone Buy Box component — compose it from existing atoms.
+- Ensure the `SelectorGroup` label shows the currently selected value (e.g. "Color: Dark Wash").
+- Size pills with `unavailable: true` get the diagonal slash treatment.
+- Use the `Fulfillment` component for ship/pickup options, not radio buttons.

package/guidelines/composition/recommendations.md

@@ -0,0 +1,100 @@
+# Recommendations
+
+A horizontal carousel of product cards used for "You may also like", "Recently viewed", "Complete the look", and other recommendation placements. This is a **composition** — not a standalone component — built from existing atoms.
+
+## Structure
+
+1. **Section header** — Bold title (e.g. "You May Also Like") styled with `--text-header-font-size` and optional "View All" link
+2. **Horizontal scroll container** — A flex row with `overflow-x: auto` containing multiple `ProductCard` components
+3. **Navigation arrows** (optional) — Left/right buttons using the `Handle` component or simple chevron icons to scroll the carousel
+
+## Example
+
+```jsx
+import { ProductCard, Link } from "@stoovles/gap-kit";
+
+function Recommendations({ title, products, viewAllHref }) {
+  return (
+    <section style={{ width: "100%", display: "flex", flexDirection: "column", gap: 16 }}>
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+        <h2 className="gap-section-title">{title}</h2>
+        {viewAllHref && <Link href={viewAllHref}>View All</Link>}
+      </div>
+
+      <div style={{
+        display: "flex",
+        gap: 16,
+        overflowX: "auto",
+        scrollSnapType: "x mandatory",
+        paddingBottom: 8,
+      }}>
+        {products.map((product) => (
+          <div key={product.id} style={{ flex: "0 0 220px", scrollSnapAlign: "start" }}>
+            <ProductCard
+              imageUrl={product.imageUrl}
+              name={product.name}
+              originalPrice={product.originalPrice}
+              salePrice={product.salePrice}
+              discount={product.discount}
+              rating={product.rating}
+              reviewCount={product.reviewCount}
+              swatches={product.swatches}
+              moreSwatches={product.moreSwatches}
+              onClick={() => navigate(product.href)}
+            />
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+```
+
+### Mini variant for recently viewed
+
+```jsx
+function RecentlyViewed({ products }) {
+  return (
+    <section>
+      <h3 className="gap-section-title">Recently Viewed</h3>
+      <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {products.map((product) => (
+          <ProductCard
+            key={product.id}
+            variant="mini"
+            imageUrl={product.imageUrl}
+            name={product.name}
+            originalPrice={product.originalPrice}
+            salePrice={product.salePrice}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}
+```
+
+## Placement guidelines
+
+| Placement | Where | Product card variant |
+|-----------|-------|---------------------|
+| "You May Also Like" | Below PDP buy box | Default (220px) |
+| "Complete the Look" | PDP, below main content | Default (220px) |
+| "Recently Viewed" | PDP sidebar or footer | Mini (326px) |
+| "Trending Now" | Homepage, PLP | Default (220px) |
+
+## Layout guidelines
+
+- Show 4–6 cards visible on desktop; the rest scroll horizontally.
+- Use `scroll-snap-type: x mandatory` for smooth snapping.
+- On mobile, show 1.5 cards to hint at scrollability.
+- The section header and "View All" link should not scroll — only the card row scrolls.
+- Use 16px gap between cards (matching `--spacing-utk-l`).
+
+## Rules
+
+- Do NOT create a standalone Recommendations component — compose using `ProductCard`.
+- Each card should be wrapped in a fixed-width container (220px for default, 326px for mini) to prevent flex stretching.
+- Always include an `onClick` on each card for navigation.
+- Use the mini variant for compact placements like sidebars.
+- The horizontal scroll container should hide the scrollbar on desktop (`::-webkit-scrollbar { display: none }`).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@stoovles/gap-kit",
+  "version": "1.0.0",
+  "description": "Gap 1.0.0 MakeKit for Figma Make",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "guidelines"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && node scripts/bundle-css.mjs",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}