@stoovles/gap-kit 1.0.0

package/guidelines/components/filter-sort.md

@@ -0,0 +1,108 @@
+# Filter & Sort
+
+A two-part filtering system for PLPs: **FilterControls** (horizontal chip bar with active filters) and **FilterDrawer** (a slide-out drawer with accordion sections).
+
+## Usage
+
+### FilterControls
+
+```jsx
+import { FilterControls } from "@stoovles/gap-kit";
+
+<FilterControls
+  chips={[
+    { label: "Filter & Sort", value: "filter-sort" },
+    { label: "Category", value: "category" },
+    { label: "Size", value: "size" },
+    { label: "Color", value: "color" },
+    { label: "Model Size", value: "model-size", hasDropdown: true },
+  ]}
+  activeChip="filter-sort"
+  onChipClick={(val) => openFilter(val)}
+  activeFilters={[
+    { label: "Blue", value: "color-blue" },
+    { label: "Medium", value: "size-m" },
+  ]}
+  onRemoveFilter={(val) => removeFilter(val)}
+  onClearAll={() => clearFilters()}
+  resultCount="128 Results"
+/>
+```
+
+### FilterDrawer
+
+```jsx
+import { FilterDrawer, Checkbox, CheckboxGroup } from "@stoovles/gap-kit";
+
+<FilterDrawer
+  open={drawerOpen}
+  title="Filter & Sort"
+  onClose={() => setDrawerOpen(false)}
+  sections={[
+    {
+      title: "Category",
+      count: 12,
+      subtitle: "Tops, Dresses",
+      children: (
+        <CheckboxGroup>
+          <Checkbox label="Tops" />
+          <Checkbox label="Dresses" />
+          <Checkbox label="Jeans" />
+        </CheckboxGroup>
+      ),
+    },
+    {
+      title: "Size",
+      count: 8,
+      subtitle: "S, M, L",
+      children: <Selector options={sizeOptions} />,
+    },
+  ]}
+  onApply={() => applyFilters()}
+/>
+```
+
+## Props — FilterControls
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `chips` | `FilterChip[]` | `[]` | Available filter chips |
+| `activeChip` | `string` | — | Currently active chip value |
+| `onChipClick` | `(value: string) => void` | — | Chip click handler |
+| `activeFilters` | `ActiveFilter[]` | `[]` | Active filter tags |
+| `onRemoveFilter` | `(value: string) => void` | — | Remove a filter |
+| `onClearAll` | `() => void` | — | Clear all filters |
+| `resultCount` | `string` | — | Result count text |
+
+## Props — FilterDrawer
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | **required** | Whether the drawer is visible |
+| `title` | `string` | `"Filter & Sort"` | Drawer header title |
+| `onClose` | `() => void` | **required** | Close handler |
+| `sections` | `FilterSection[]` | `[]` | Accordion filter sections |
+| `applyLabel` | `string` | `"Apply"` | Apply button label |
+| `onApply` | `() => void` | — | Apply callback (renders button) |
+
+## Visual reference
+
+### FilterControls
+- **Chips:** Bordered pills, 16px text; active chip gets 2px accent border
+- **"Filter & Sort" chip:** Includes a small filter icon to the left
+- **Active tags:** Compact pills with accent border + X close icon
+- **"Clear all":** Underlined text link
+- **Result count:** Small 10px secondary text
+
+### FilterDrawer
+- **Width:** 320px, slides in from the right
+- **Header:** 20px bold title + close X, 24px padding
+- **Sections:** Each has a subtle divider, bold title with optional (count) and subtitle, chevron toggle
+- **Apply button:** Full-width primary button at the bottom
+
+## Rules
+
+- FilterControls and FilterDrawer are separate components; use them together for the full filtering experience.
+- The drawer sections accept any `children` — compose with Checkbox, Selector, SelectorSwatch, RangeSlider, etc.
+- Always show `resultCount` so the user knows how many items match the current filters.
+- The "Filter & Sort" chip value should be `"filter-sort"` to trigger the filter icon rendering.

package/guidelines/components/fulfillment.md

@@ -0,0 +1,100 @@
+# Fulfillment
+
+## When to use
+
+Use `Fulfillment` to let customers choose between shipping and in-store pickup. Each option is a `FulfillmentTile` — a card with a title, description, and availability status. Wrap them in a `Fulfillment` container for side-by-side layout.
+
+```tsx
+import { Fulfillment, FulfillmentTile } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### FulfillmentTile
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Tile heading (e.g. "Free shipping", "In-store pickup") |
+| `selected` | `boolean` | `false` | Whether this tile is the active fulfillment method |
+| `availability` | `string` | — | Status text (e.g. "In Stock") |
+| `children` | `ReactNode` | — | Subtext, links, store name, etc. |
+| `onClick` | `() => void` | — | Selection handler |
+| `className` | `string` | — | Additional CSS class |
+
+### Fulfillment
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `FulfillmentTile` elements |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Border | Availability color |
+|---|---|---|
+| Unselected | 1px subtle gray (`--color-border-subtle`) | Primary (#000) |
+| Selected | 2px accent blue (`--color-border-accent`) | Success green (`--color-type-success`) |
+
+## Sizing
+
+- Tile min-height: 124px
+- Padding: 16px (`--spacing-utk-l`)
+- Border radius: 0px (Gap square-corner identity)
+- Title: Gap Sans, 16px, weight 400 (`--text-selector-header-tile-font-weight`)
+- Subtext / availability: Gap Sans, 16px, weight 400
+- Gap between tiles: 8px (`--spacing-utk-s`)
+- Tiles are equal-width (flex: 1 1 0)
+
+## Examples
+
+```tsx
+{/* Basic shipping vs. pickup */}
+<Fulfillment>
+  <FulfillmentTile
+    title="Free shipping"
+    selected={method === "ship"}
+    availability="In Stock"
+    onClick={() => setMethod("ship")}
+  >
+    <span>on $50+ for Rewards Members. </span>
+    <a href="/rewards">Sign in</a>
+  </FulfillmentTile>
+  <FulfillmentTile
+    title="In-store pickup"
+    selected={method === "pickup"}
+    onClick={() => setMethod("pickup")}
+  >
+    <a href="/store-locator">Find a store</a>
+  </FulfillmentTile>
+</Fulfillment>
+
+{/* With store selected */}
+<Fulfillment>
+  <FulfillmentTile
+    title="Free shipping"
+    availability="In Stock"
+    onClick={() => setMethod("ship")}
+  >
+    on $50+ for Rewards Members.
+  </FulfillmentTile>
+  <FulfillmentTile
+    title="In-store pickup"
+    selected
+    availability="In Stock"
+    onClick={() => setMethod("pickup")}
+  >
+    <span>Walnut Creek</span>
+    <br />
+    <a href="/change-store">Change store</a>
+  </FulfillmentTile>
+</Fulfillment>
+```
+
+## Rules
+
+- Always provide two tiles: shipping and pickup — they sit side by side
+- Use `selected` to highlight the active fulfillment method
+- When selected, the "In Stock" availability text turns green (`--color-type-success`)
+- Place links (e.g. "Sign in", "Find a store") inside `children`
+- The component is a `<button>` for keyboard accessibility
+- Each tile flexes to fill available width equally

package/guidelines/components/global-footer.md

@@ -0,0 +1,71 @@
+# Global Footer
+
+The site-wide footer containing promotional blocks (email sign-up, rewards credit card, app download), navigation columns, social links, and legal text.
+
+## Usage
+
+```jsx
+import { GlobalFooter } from "@stoovles/gap-kit";
+
+<GlobalFooter />
+```
+
+All sections ship with Gap-branded defaults, so a bare `<GlobalFooter />` renders a fully populated footer.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `blocks` | `FooterBlock[]` | Email, Credit Card, App | Top-row promotional blocks |
+| `navColumns` | `FooterNavColumn[]` | Customer Support, Rewards, About Us, Find Us | Navigation link columns |
+| `socialLinks` | `SocialLink[]` | TikTok, Instagram, YouTube, Spotify | Social icons below the last nav column |
+| `legalLines` | `(string \| ReactNode)[]` | Gap Inc. legal boilerplate | Bottom legal text lines |
+
+### FooterBlock
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Block heading |
+| `content` | `ReactNode` | Free-form block body (email form, links, copy, etc.) |
+
+### FooterNavColumn
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Column heading |
+| `links` | `{ label, href }[]` | List of footer links |
+
+### SocialLink
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string` | Accessible name |
+| `href` | `string` | Link URL |
+| `icon` | `ReactNode` | 32×32 SVG icon |
+
+## Visual reference
+
+- **Background:** White (`--global-footer-background`)
+- **Top blocks:** 3-column layout with border-right dividers, 18px bold titles
+- **Nav columns:** 4-column row, 16px bold headers, 16px secondary gray links
+- **Social icons:** 32×32px dark circular icons (TikTok, Instagram, YouTube, Spotify)
+- **Legal text:** 12px body, pipe-separated items across two lines
+
+## Examples
+
+Override just the nav columns:
+
+```jsx
+<GlobalFooter
+  navColumns={[
+    { title: "Help", links: [{ label: "FAQ", href: "/faq" }] },
+    { title: "About", links: [{ label: "Careers", href: "/careers" }] },
+  ]}
+/>
+```
+
+## Rules
+
+- Always render at the bottom of every page layout.
+- The footer is full-width; inner content is constrained to 1264px.
+- Do not remove the legal section in production prototypes.

package/guidelines/components/global-header.md

@@ -0,0 +1,67 @@
+# Global Header
+
+The top-level navigation bar present on every page. Contains the sister-brand bar, a promotional banner (EDFS — Everyday Free Shipping), and account/bag action icons.
+
+## Usage
+
+```jsx
+import { GlobalHeader } from "@stoovles/gap-kit";
+
+<GlobalHeader
+  promoText="Free shipping on $50+ for Rewards Members"
+  promoLinks={[
+    { label: "Sign In or Join", href: "/signin" },
+    { label: "Details", href: "/shipping-details" },
+  ]}
+  bagCount={3}
+  onBagClick={() => openBag()}
+  onAccountClick={() => openAccount()}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `brands` | `BrandLink[]` | Gap, Gap Factory, Old Navy, Banana Republic, Athleta, Banana Republic Factory | Sister-brand links in the top-left bar |
+| `promoText` | `string` | `"Free shipping on $50+ for Rewards Members"` | Promotional text in center |
+| `promoLinks` | `{ label, href }[]` | Sign In or Join, Details | Underlined links after promo text |
+| `bagCount` | `number` | — | Items in the shopping bag; shows a badge when > 0 |
+| `onBagClick` | `() => void` | — | Callback for bag icon click |
+| `onAccountClick` | `() => void` | — | Callback for account icon click |
+| `onLogoClick` | `() => void` | — | Callback for logo click |
+
+## Visual reference
+
+- **Background:** Solid black (`--global-header-brand-bar-bg`)
+- **Brand links:** Gray text at 10px, white on hover
+- **Promo area:** White text centered, underlined links
+- **Icons:** White 24px person + 18×24px bag outlines
+- **Badge:** 16×16px white circle with black count text, positioned inside the bag icon
+- **Height:** 48px fixed
+
+## Examples
+
+Minimal header with no bag items:
+
+```jsx
+<GlobalHeader bagCount={0} />
+```
+
+Custom brands:
+
+```jsx
+<GlobalHeader
+  brands={[
+    { label: "Gap", href: "/gap" },
+    { label: "Old Navy", href: "/oldnavy" },
+  ]}
+/>
+```
+
+## Rules
+
+- Always render the header at the very top of every page layout.
+- The sister-brand bar scrolls horizontally if the viewport is too narrow.
+- The promo text should reflect the current promotion; override via `promoText`.
+- Do not put the header inside another container that constrains its width.

package/guidelines/components/hamburger-nav.md

@@ -0,0 +1,79 @@
+# Hamburger Navigation
+
+A mobile-style slide-out navigation drawer that covers the viewport with a dark overlay. Contains the sister-brand bar, a search field, department links with right chevrons, and secondary utility links on a subtle gray background.
+
+## Usage
+
+```jsx
+import { HamburgerNav } from "@stoovles/gap-kit";
+
+const [navOpen, setNavOpen] = useState(false);
+
+<HamburgerNav
+  open={navOpen}
+  onClose={() => setNavOpen(false)}
+  sections={[
+    {
+      items: [
+        { label: "New", hasChildren: true, onClick: () => {} },
+        { label: "Women", hasChildren: true, onClick: () => {} },
+        { label: "Men", hasChildren: true, onClick: () => {} },
+        { label: "Sale", hasChildren: true, onClick: () => {} },
+      ],
+    },
+    {
+      secondary: true,
+      items: [
+        { label: "Customer Service" },
+        { label: "Orders & Returns" },
+        { label: "Gift Cards", hasChildren: true },
+        { label: "Find a Store" },
+        { label: "Sign In" },
+      ],
+    },
+  ]}
+  onSearch={(q) => navigate(`/search?q=${q}`)}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | **required** | Whether the drawer is visible |
+| `onClose` | `() => void` | **required** | Called to close the drawer |
+| `sections` | `HamburgerNavSection[]` | **required** | Nav sections |
+| `headerSlot` | `ReactNode` | — | Content above the search (e.g. brand bar, promo) |
+| `searchPlaceholder` | `string` | `"Search Gap"` | Search input placeholder |
+| `onSearch` | `(value: string) => void` | — | Fires on Enter in search |
+
+### HamburgerNavSection
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | `HamburgerNavItem[]` | Nav items in this section |
+| `secondary` | `boolean` | Gray background for utility links |
+
+### HamburgerNavItem
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string` | Display text |
+| `href` | `string` | Optional link URL (renders `<a>` vs `<button>`) |
+| `hasChildren` | `boolean` | Shows a right chevron |
+| `onClick` | `() => void` | Click callback |
+
+## Visual reference
+
+- **Overlay:** 30% dark transparent background covering the full viewport
+- **Panel:** 350px wide, white, slides in from the left
+- **Search:** 44px bordered input with magnifying glass icon
+- **Nav rows:** 16px text, 24px top padding per row, right chevron for expandable items
+- **Secondary section:** subtle gray background (#f7f7f7)
+- **Close button:** White X icon positioned to the right of the panel
+
+## Rules
+
+- The hamburger nav is a fixed-position overlay — it blocks all content behind it.
+- Always provide `onClose`; the overlay click and X button both trigger it.
+- Split navigation into primary (departments) and secondary (utility) sections.

package/guidelines/components/handle.md

@@ -0,0 +1,49 @@
+# Handle
+
+## When to use
+
+Use the `Handle` component as a draggable thumb for sliders, range selectors, and similar interactive controls. This is a visual primitive — pair it with your own drag logic.
+
+```tsx
+import { Handle } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"large" \| "small"` | `"large"` | Large is 24px, small is 20px |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Ring | Thumb |
+|---|---|---|
+| Default | 32px invisible ring | White circle with drop shadow |
+| Hover | 48px, gray (#757575) at 30% opacity | White circle with drop shadow |
+| Press | 48px, gray (#757575) at 50% opacity | White circle with drop shadow |
+
+## Sizing
+
+| Size | Thumb diameter | Default ring | Hover/press ring |
+|---|---|---|---|
+| `large` | 24px | 32px | 48px |
+| `small` | 20px | 32px | 48px |
+
+## Examples
+
+```tsx
+{/* Default large handle */}
+<Handle />
+
+{/* Small handle for compact sliders */}
+<Handle size="small" />
+```
+
+## Rules
+
+- Always use within a slider or range control context
+- The handle uses `cursor: grab` by default and `cursor: grabbing` when active
+- The hover ring provides a generous touch target — do not override its size
+- Background is always white; the drop shadow provides visual lift
+- Do not add borders or outlines to the handle — it relies on shadow for definition

package/guidelines/components/icons.md

@@ -0,0 +1,147 @@
+# Icon
+
+## When to use
+
+Use the `Icon` component for all iconography. Never use raw SVGs, emoji, or Unicode symbols. Always import from `@stoovles/gap-kit`.
+
+```tsx
+import { Icon } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `IconName` | required | Icon identifier (see catalog below) |
+| `size` | `12 \| 16 \| 24 \| 32` | `16` | Pixel size of the icon |
+| `color` | `"dark" \| "light"` | `"dark"` | Dark renders in `--color-icon-default` (#000), Light renders in `--color-icon-inverse` (#fff) |
+| `className` | `string` | — | Additional CSS class |
+| `aria-label` | `string` | — | Accessible label; when set, icon has `role="img"` |
+
+## Icon catalog
+
+### Navigation
+
+| Name | Purpose | Common sizes |
+|---|---|---|
+| `chevron-left` | Navigate back, collapse | 12, 16 |
+| `chevron-right` | Navigate forward, expand | 12, 16 |
+| `chevron-down` | Expand dropdown, accordion | 12, 16 |
+| `chevron-up` | Collapse dropdown, accordion | 12, 16 |
+| `menu` | Hamburger menu toggle | 16, 24 |
+| `x` | Close, dismiss, remove | 12, 16, 24 |
+
+### Actions
+
+| Name | Purpose | Common sizes |
+|---|---|---|
+| `search` | Search trigger or input icon | 16, 24 |
+| `filter` | Filter controls toggle | 16 |
+| `bag` | Shopping bag | 16, 24 |
+| `profile` | User account | 16, 24 |
+| `quickadd` | Add to bag (bag + plus) | 16, 24 |
+
+### Status & feedback
+
+| Name | Purpose | Common sizes |
+|---|---|---|
+| `checkmark-filled` | Confirmed, completed (solid circle) | 12, 16 |
+| `checkmark-outlined` | Selected, checked (stroke only) | 12, 16 |
+| `alert-circle` | Warning or error (solid circle) | 16 |
+| `info-circle` | Informational (solid circle) | 16 |
+| `info` | Informational (outlined circle) | 12, 16, 24 |
+| `loader` | Loading animation dots | 16, 24 |
+
+### Media
+
+| Name | Purpose | Common sizes |
+|---|---|---|
+| `play` | Play video/audio | 12, 16 |
+| `pause` | Pause video/audio | 12, 16 |
+| `volume-on` | Audio on/unmuted | 16 |
+| `volume-off` | Audio off/muted | 16 |
+| `star-filled` | Full rating star | 16 |
+| `star-half` | Half rating star | 16 |
+| `star-empty` | Empty rating star | 16 |
+
+### Content
+
+| Name | Purpose | Common sizes |
+|---|---|---|
+| `fire` | Trending, hot | 16 |
+| `show` | Eye/visibility toggle | 16 |
+| `email-outlined` | Email, contact | 16 |
+| `location-outlined` | Store locator (outlined) | 16 |
+| `location-filled` | Current location (solid) | 16 |
+| `phone` | Phone, call | 16 |
+| `swatch` | Color swatch circle | 16 |
+
+## Size decision tree
+
+```
+Which icon size should I use?
+
+├─ Inline with small text (captions, badges)?
+│  └─ 12
+│
+├─ Standard UI element (buttons, inputs, cards)?
+│  └─ 16 (default)
+│
+├─ Prominent action (header icons, primary actions)?
+│  └─ 24
+│
+└─ Social media badge or large display?
+   └─ 32
+```
+
+## Color decision tree
+
+```
+Which icon color should I use?
+
+├─ On a light background (white, gray, brand-tertiary)?
+│  └─ color="dark" (default)
+│
+└─ On a dark background (black, brand fill, dark overlay)?
+   └─ color="light"
+```
+
+## Examples
+
+```tsx
+{/* Standard navigation chevron */}
+<Icon name="chevron-right" size={16} />
+
+{/* Search icon in header (on dark background) */}
+<Icon name="search" size={24} color="light" />
+
+{/* Rating stars */}
+<div style={{ display: 'flex', gap: '2px' }}>
+  <Icon name="star-filled" size={16} />
+  <Icon name="star-filled" size={16} />
+  <Icon name="star-filled" size={16} />
+  <Icon name="star-half" size={16} />
+  <Icon name="star-empty" size={16} />
+</div>
+
+{/* Close button with accessible label */}
+<button>
+  <Icon name="x" size={24} aria-label="Close dialog" />
+</button>
+
+{/* Bag icon with count */}
+<div style={{ position: 'relative' }}>
+  <Icon name="bag" size={24} color="light" />
+  <span className="bag-count">3</span>
+</div>
+```
+
+## Rules
+
+- Always use `name` prop with a valid icon name from the catalog — do not guess names
+- Default size is 16 — only change when a larger or smaller icon is specifically needed
+- Use `color="light"` only on dark backgrounds — never on white or light gray surfaces
+- For clickable icons, wrap in a `<button>` element and add `aria-label` to the Icon
+- Icons inherit the container's alignment — use flexbox to center if needed
+- Do not apply custom fill or stroke colors via className — use the `color` prop
+- Star rating always uses exactly 5 icons: a combination of `star-filled`, `star-half`, and `star-empty`

package/guidelines/components/link.md

@@ -0,0 +1,70 @@
+# Link
+
+## When to use
+
+Use the `Link` component for navigational text that routes to another page or section. Renders a semantic `<a>` element.
+
+```tsx
+import { Link } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"inline" \| "subtle"` | `"inline"` | Inline is underlined and blue; subtle is plain gray |
+| `children` | `ReactNode` | — | Link label text |
+| `href` | `string` | — | Destination URL |
+| `className` | `string` | — | Additional CSS class |
+
+All standard `<a>` HTML attributes are also supported (e.g. `target`, `rel`, `aria-label`).
+
+## Variant decision tree
+
+```
+What context is this link in?
+
+├─ Within body copy, or a primary navigational action?
+│  └─ variant="inline" (underlined blue)
+│
+└─ Secondary or de-emphasized link (footer, breadcrumb, supporting text)?
+   └─ variant="subtle" (plain gray, underlines on hover)
+```
+
+## Visual reference
+
+| Variant | Default | Hover / Active | Visited |
+|---|---|---|---|
+| `inline` | Blue text, blue 1px underline | Blue text, blue underline | Gray text (#757575), gray underline |
+| `subtle` | Gray text (#757575), no underline | Blue text, blue 1px underline | Gray text, no underline |
+
+## Sizing
+
+- Font: Gap Sans, 16px, weight 400, letter-spacing 0.32px
+- Underline: 1px solid bottom border
+- Focus ring: 2px blue (#031ba1) outline, 2px offset
+
+## Examples
+
+```tsx
+{/* Inline link in body text */}
+<p>
+  Check our <Link href="/returns">return policy</Link> for details.
+</p>
+
+{/* Subtle link in footer */}
+<Link variant="subtle" href="/privacy">Privacy Policy</Link>
+
+{/* External link */}
+<Link href="https://gap.com" target="_blank" rel="noopener noreferrer">
+  Gap.com
+</Link>
+```
+
+## Rules
+
+- Always use `inline` for links within body copy so they are clearly identifiable
+- Use `subtle` only where context already implies navigation (e.g. footer link lists)
+- Never use a `Link` for actions — use `Button` instead
+- Always provide an `href` — for click-only actions without navigation, use `Button`
+- For external links, include `target="_blank"` and `rel="noopener noreferrer"`