@stoovles/gap-kit 1.0.0

package/guidelines/components/search-input.md

@@ -0,0 +1,63 @@
+# Search Input
+
+A minimal search bar designed for the global header. Features a bottom-border style, inline clear action, a vertical divider, and a search magnifying-glass icon.
+
+## Usage
+
+```jsx
+import { SearchInput } from "@stoovles/gap-kit";
+
+<SearchInput
+  placeholder="Search"
+  onSubmit={(term) => console.log("Search:", term)}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Controlled value |
+| `defaultValue` | `string` | `""` | Initial uncontrolled value |
+| `placeholder` | `string` | `"Search"` | Placeholder text |
+| `onChange` | `(value: string) => void` | — | Fires on every keystroke |
+| `onSubmit` | `(value: string) => void` | — | Fires on Enter or search icon click |
+| `onClear` | `() => void` | — | Fires when the Clear button is clicked |
+
+## Visual reference
+
+- **Background:** Semi-transparent light gray (`--search-input-background`)
+- **Bottom border:** 1px, shifts to accent blue when focused
+- **Caret:** Accent blue (`--search-cursor-color`)
+- **Clear action:** 10px helper text + 1px vertical divider + 24×24 search icon
+- **Size:** 270×32px default, minimum 228px
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| Default (empty) | "Search" placeholder, search icon right |
+| Active (empty) | Accent bottom border, dimmed placeholder, blinking caret |
+| Active (filled) | Search term + caret, "Clear | 🔍" on right |
+| Default (filled) | Search term, "Clear | 🔍" on right |
+
+## Examples
+
+Controlled search:
+
+```jsx
+const [term, setTerm] = useState("");
+
+<SearchInput
+  value={term}
+  onChange={setTerm}
+  onSubmit={(t) => navigate(`/search?q=${t}`)}
+  onClear={() => setTerm("")}
+/>
+```
+
+## Rules
+
+- Place the search input inside the Global Header actions area.
+- Always provide `onSubmit`; users expect Enter to trigger search.
+- The "Clear" button only appears when the field has content.

package/guidelines/components/selector-swatch.md

@@ -0,0 +1,78 @@
+# Selector Swatch
+
+## When to use
+
+Use `SelectorSwatch` to let customers choose a product color. Each swatch is a circular button filled with the color value. Wrap multiple swatches in a `SwatchGrid` for proper layout.
+
+```tsx
+import { SelectorSwatch, SwatchGrid } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### SelectorSwatch
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `string` | — | CSS color value for the circle fill |
+| `active` | `boolean` | `false` | Whether the swatch is selected |
+| `focused` | `boolean` | `false` | Whether the swatch has keyboard focus (thicker ring) |
+| `unavailable` | `boolean` | `false` | Shows a diagonal strikethrough over the color |
+| `label` | `string` | — | Optional text label below the swatch |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Swatch diameter |
+| `aria-label` | `string` | — | Accessible name for the color |
+| `onClick` | `() => void` | — | Click handler |
+| `className` | `string` | — | Additional CSS class |
+
+### SwatchGrid
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `SelectorSwatch` elements |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Ring | Circle border |
+|---|---|---|
+| Default (inactive) | Transparent | 1px subtle gray |
+| Active (selected) | 1px accent blue | 1px subtle gray |
+| Active + Focused | 2px accent blue | 1px subtle gray |
+| Unavailable | — | 1px subtle gray + diagonal slash |
+
+### Sizes
+
+| Size | Circle diameter | Total with ring |
+|---|---|---|
+| `xl` | 36px | 44px |
+| `lg` | 32px | 40px |
+| `md` | 28px | 36px |
+| `sm` | 24px | 32px |
+| `xs` | 20px | 28px |
+
+## Examples
+
+```tsx
+{/* Color swatch grid */}
+<SwatchGrid>
+  <SelectorSwatch color="#000" active label="Black" onClick={() => setColor("black")} />
+  <SelectorSwatch color="#fff" label="White" onClick={() => setColor("white")} />
+  <SelectorSwatch color="#031ba1" label="Navy" onClick={() => setColor("navy")} />
+  <SelectorSwatch color="#d00000" unavailable label="Red" />
+</SwatchGrid>
+
+{/* Small swatches without labels */}
+<SwatchGrid>
+  <SelectorSwatch color="#000" size="sm" active />
+  <SelectorSwatch color="#595959" size="sm" />
+  <SelectorSwatch color="#fff" size="sm" />
+</SwatchGrid>
+```
+
+## Rules
+
+- Always pass a meaningful `aria-label` or `label` for accessibility
+- Use `unavailable` for out-of-stock colors — the slash clearly communicates unavailability
+- The `active` ring uses `--color-border-accent` (brand blue in Gap 1.0.0)
+- The circle border uses `--color-border-subtle` for a clean, light outline
+- Use `SwatchGrid` to wrap swatches — it provides flex-wrap layout with proper spacing

package/guidelines/components/selector.md

@@ -0,0 +1,95 @@
+# Selector
+
+## When to use
+
+Use `Selector` for picking a single value from a set of discrete options — most commonly product sizes. Use `SelectorGroup` to add a header label above a set of selectors.
+
+```tsx
+import { Selector, SelectorGroup } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### Selector
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `options` | `SelectorOption[]` | — | Array of selectable options |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Uncontrolled initial value |
+| `onChange` | `(value: string) => void` | — | Selection change callback |
+| `className` | `string` | — | Additional CSS class |
+
+### SelectorOption
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Display text inside the pill |
+| `value` | `string` | Unique value |
+| `unavailable` | `boolean` | Shows diagonal slash — still clickable |
+| `disabled` | `boolean` | Grayed out — not clickable |
+
+### SelectorGroup
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Group header text (e.g. "Size") |
+| `selectedLabel` | `string` | — | Currently selected value shown after header |
+| `children` | `ReactNode` | — | A `Selector` or other content |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Background | Border | Text |
+|---|---|---|---|
+| Default | White | 2px gray (`--selector-size-border-default`) | Black |
+| Selected | White | 2px black (`--selector-size-border-selected`) | Black |
+| Hover | White | 2px black (`--selector-size-border-hover`) | Black |
+| Unavailable | White | 2px gray | Black + diagonal slash |
+| Disabled | Gray (`--selector-size-unavailable-disabled`) | 2px light gray | Gray (`--selector-size-font-disabled`) |
+
+## Sizing
+
+- Pill: min-width 44px, min-height 44px
+- Padding: 8px vertical, 12px horizontal
+- Border radius: 0px (Gap square-corner identity)
+- Font: Gap Sans, 16px (`--selector-size-font-size`), weight 400
+- Gap between pills: 8px
+- Group header: 16px, weight 400 (`--font-weight-base-heavier`)
+
+## Examples
+
+```tsx
+{/* Basic size selector */}
+<SelectorGroup label="Size" selectedLabel="M">
+  <Selector
+    value="m"
+    onChange={setSize}
+    options={[
+      { label: "XS", value: "xs" },
+      { label: "S", value: "s" },
+      { label: "M", value: "m" },
+      { label: "L", value: "l" },
+      { label: "XL", value: "xl" },
+      { label: "XXL", value: "xxl", unavailable: true },
+    ]}
+  />
+</SelectorGroup>
+
+{/* Multi-size selector (e.g. waist + length) */}
+<SelectorGroup label="Waist" selectedLabel="32">
+  <Selector value="32" onChange={setWaist} options={waistOptions} />
+</SelectorGroup>
+<SelectorGroup label="Length" selectedLabel="30">
+  <Selector value="30" onChange={setLength} options={lengthOptions} />
+</SelectorGroup>
+```
+
+## Rules
+
+- Use `unavailable` for sizes that are out of stock but still viewable (e.g. for waitlist)
+- Use `disabled` for sizes that cannot be interacted with at all
+- The selected pill shows a heavier border but keeps a white background in Gap 1.0.0
+- `SelectorGroup` uses a `<fieldset>` + `<legend>` for accessibility
+- Each pill has `role="radio"` and `aria-checked` for screen readers
+- Support both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) patterns

package/guidelines/components/slider.md

@@ -0,0 +1,116 @@
+# Slider / Price Filter
+
+## When to use
+
+Use `RangeSlider` for any dual-handle range selection. Use `PriceFilter` as a ready-made composition that pairs the slider with Min/Max text inputs and a Reset link — ideal for filtering product listings by price.
+
+```tsx
+import { RangeSlider, PriceFilter } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### RangeSlider
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `min` | `number` | — | Minimum possible value |
+| `max` | `number` | — | Maximum possible value |
+| `low` | `number` | — | Controlled lower bound |
+| `high` | `number` | — | Controlled upper bound |
+| `defaultLow` | `number` | `min` | Uncontrolled initial lower bound |
+| `defaultHigh` | `number` | `max` | Uncontrolled initial upper bound |
+| `step` | `number` | `1` | Step increment |
+| `onChange` | `(low, high) => void` | — | Callback when either handle moves |
+| `aria-label` | `string` | `"Range"` | Accessible label for the slider group |
+| `className` | `string` | — | Additional CSS class |
+
+### PriceFilter
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `min` | `number` | — | Minimum possible price |
+| `max` | `number` | — | Maximum possible price |
+| `low` | `number` | — | Controlled lower price |
+| `high` | `number` | — | Controlled upper price |
+| `defaultLow` | `number` | `min` | Uncontrolled initial lower price |
+| `defaultHigh` | `number` | `max` | Uncontrolled initial upper price |
+| `step` | `number` | `1` | Price step |
+| `onChange` | `(low, high) => void` | — | Callback when range changes |
+| `onReset` | `() => void` | — | If provided, shows a "Reset" link |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+### RangeSlider
+
+| Element | Style |
+|---|---|
+| Track | 2px height, gray (`--color-gray-3`) |
+| Active fill | 2px height, dark gray (`--slider-default-color`) |
+| Handles | 24px white circles with drop shadow |
+| Focus ring | Expanded shadow on keyboard focus |
+
+### PriceFilter layout
+
+| Element | Description |
+|---|---|
+| Slider | Full-width `RangeSlider` |
+| Text inputs | Two 96px-wide number fields with "Min"/"Max" floating labels |
+| Reset link | Centered below inputs, secondary color |
+
+## Sizing
+
+- Slider height: 48px (touch target)
+- Handle: 24px diameter, white, drop shadow
+- Focus ring: additional 4px shadow spread
+- Text inputs: 44px height, 96px width, 2px focused border
+- Floating labels: 10px, positioned above border
+- Gap between slider and inputs: 16px
+- Gap between inputs row and reset: 24px
+- Max width (PriceFilter): 342px
+
+## Examples
+
+```tsx
+{/* Standalone range slider */}
+<RangeSlider
+  min={0}
+  max={200}
+  defaultLow={25}
+  defaultHigh={150}
+  onChange={(low, high) => console.log(low, high)}
+/>
+
+{/* Full price filter */}
+<PriceFilter
+  min={0}
+  max={500}
+  step={5}
+  defaultLow={0}
+  defaultHigh={500}
+  onChange={(low, high) => applyPriceFilter(low, high)}
+  onReset={() => clearPriceFilter()}
+/>
+
+{/* Controlled price filter */}
+const [range, setRange] = useState({ low: 10, high: 100 });
+<PriceFilter
+  min={0}
+  max={200}
+  low={range.low}
+  high={range.high}
+  onChange={(low, high) => setRange({ low, high })}
+  onReset={() => setRange({ low: 0, high: 200 })}
+/>
+```
+
+## Rules
+
+- The low handle cannot exceed the high handle (enforced with a minimum `step` gap)
+- The text inputs in `PriceFilter` are synced with the slider — changing one updates the other
+- The "Reset" link only renders when `onReset` is provided
+- Uses native `<input type="range">` elements for accessibility (keyboard arrows work)
+- Each handle has its own `aria-label` ("Minimum value" / "Maximum value")
+- Supports both controlled and uncontrolled patterns
+- The track and handles use CSS-only styling — no images

package/guidelines/components/switch.md

@@ -0,0 +1,108 @@
+# Switch
+
+## When to use
+
+Use the `Switch` component for binary on/off toggles that take immediate effect — no form submission needed. For boolean choices within a form, prefer `Checkbox`.
+
+```tsx
+import { Switch } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Controlled on/off state |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial state |
+| `onChange` | `(checked: boolean) => void` | — | Called with the new state when toggled |
+| `showLabel` | `boolean` | `false` | Shows "ON" / "OFF" text inside the track |
+| `disabled` | `boolean` | `false` | Prevents interaction |
+| `aria-label` | `string` | — | Accessible label (required when no visible label is adjacent) |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Track | Handle |
+|---|---|---|
+| Off | Gray (#ededed) | Gray circle (#757575), left-aligned |
+| On | Gray (#ededed) | Blue circle (#031ba1), right-aligned |
+
+## Sizing
+
+- Track: 54px wide, pill-shaped (999px border-radius)
+- Handle: 24px circle with drop shadow
+- Padding: 2px
+- Label (optional): 10px, 0.2px letter-spacing
+
+## Examples
+
+```tsx
+{/* Controlled switch */}
+<Switch
+  checked={darkMode}
+  onChange={setDarkMode}
+  aria-label="Dark mode"
+/>
+
+{/* With ON/OFF label */}
+<Switch
+  checked={notifications}
+  onChange={setNotifications}
+  showLabel
+  aria-label="Notifications"
+/>
+
+{/* Uncontrolled */}
+<Switch defaultChecked aria-label="Auto-save" />
+```
+
+## Rules
+
+- Always provide an `aria-label` or an adjacent visible label for accessibility
+- Use `role="switch"` and `aria-checked` (built in) — do not override these
+- The switch takes immediate effect — do not use inside forms that require submit
+- Pair with a text label to the left when the context is not obvious
+
+---
+
+# BopisSwitch
+
+## When to use
+
+Use the `BopisSwitch` component for the "Buy Online, Pick Up In Store" toggle on product pages. It combines a `Switch` with a header, description, and optional store link.
+
+```tsx
+import { BopisSwitch } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | `false` | Whether store pickup is enabled |
+| `onChange` | `(checked: boolean) => void` | — | Called when toggled |
+| `storeName` | `string` | — | Name of the selected store (shown when on) |
+| `storeHref` | `string` | — | Link to store details page |
+| `description` | `string` | `"Find items available for pickup"` | Description text shown when off |
+| `className` | `string` | — | Additional CSS class |
+
+## Examples
+
+```tsx
+{/* Off state — shows description */}
+<BopisSwitch onChange={handleToggle} />
+
+{/* On state — shows store link */}
+<BopisSwitch
+  checked
+  onChange={handleToggle}
+  storeName="Broadway Plaza, Walnut Creek"
+  storeHref="/stores/broadway-plaza"
+/>
+```
+
+## Rules
+
+- Always provide `storeName` and `storeHref` when `checked` is true
+- The component includes a subtle divider at the top — do not add an extra one above it
+- Place below the product price and above the size selector on PDP

package/guidelines/components/tabs.md

@@ -0,0 +1,83 @@
+# Tabs
+
+## When to use
+
+Use the `Tabs` component to switch between related views or filter categories within the same context — for example, product fit options (Regular, Tall, Petite, Plus) or content sections.
+
+```tsx
+import { Tabs } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### Tabs
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Optional header text above the tab bar |
+| `tabs` | `Tab[]` | — | Array of tab items |
+| `value` | `string` | — | Controlled selected tab value |
+| `defaultValue` | `string` | First tab | Uncontrolled initial selection |
+| `onChange` | `(value: string) => void` | — | Callback when a tab is selected |
+| `className` | `string` | — | Additional CSS class |
+
+### Tab
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Display text |
+| `value` | `string` | Unique identifier |
+
+## Visual reference
+
+| State | Bottom border | Text color |
+|---|---|---|
+| Unselected | 1px light gray (`--tabs-border-color`) | Gray (`--tabs-font-color`) |
+| Selected | 2px accent blue (`--color-border-accent`) | Accent/primary (`--color-type-accent`) |
+
+## Sizing
+
+- Tab padding: 12px (`--spacing-utk-m`)
+- Tabs are equal-width (flex: 1)
+- Title-to-tabs gap: 8px (`--spacing-s`)
+- Font: Gap Sans, 16px, weight 400, 0.32px letter-spacing
+- Title font: 16px, weight 400, primary color
+- Background: white for all tabs
+
+## Examples
+
+```tsx
+{/* Basic fit tabs */}
+<Tabs
+  title="Fit"
+  tabs={[
+    { label: "Regular", value: "regular" },
+    { label: "Tall", value: "tall" },
+    { label: "Petite", value: "petite" },
+    { label: "Plus", value: "plus" },
+  ]}
+  defaultValue="regular"
+  onChange={(fit) => setFit(fit)}
+/>
+
+{/* Controlled tabs without title */}
+<Tabs
+  tabs={[
+    { label: "Description", value: "desc" },
+    { label: "Reviews", value: "reviews" },
+    { label: "Size & Fit", value: "size" },
+  ]}
+  value={activeTab}
+  onChange={setActiveTab}
+/>
+```
+
+## Rules
+
+- Always provide at least two tabs
+- Each tab spans equal width across the container
+- The selected tab has a prominent bottom border in the accent color; unselected tabs have a subtle gray underline
+- Use `title` for a section label above the tabs when context is needed (e.g. "Fit")
+- Each tab has `role="tab"` and `aria-selected` for screen readers
+- Only the selected tab is in the tab order (`tabIndex={0}`); others are `tabIndex={-1}`
+- Supports both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) patterns

package/guidelines/components/text-input.md

@@ -0,0 +1,80 @@
+# TextInput
+
+## When to use
+
+Use the `TextInput` component for single-line text entry — names, emails, search queries, etc. It features a floating label that rises above the field when focused or filled.
+
+```tsx
+import { TextInput } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Field label (shown as placeholder when empty, floats when focused/filled) |
+| `error` | `boolean` | `false` | Renders the field in error state with red border and error text |
+| `helperText` | `string` | — | Assistive text below the field (default state) |
+| `errorText` | `string` | — | Error message shown below the field when `error` is true |
+| `maxLength` | `number` | — | Maximum character count, displays a counter in the helper row |
+| `disabled` | `boolean` | `false` | Grays out the field and prevents input |
+| `value` | `string` | — | Controlled input value |
+| `defaultValue` | `string` | — | Uncontrolled initial value |
+| `onChange` | `(e) => void` | — | Change handler |
+| `className` | `string` | — | Additional CSS class |
+
+All standard `<input>` HTML attributes are also supported (e.g. `type`, `name`, `placeholder`, `autoComplete`).
+
+## Visual reference
+
+| State | Border | Label | Background |
+|---|---|---|---|
+| Default (empty) | 1px subtle gray | Inline as placeholder | Light transparent gray |
+| Focused (empty) | 2px black | Floating above field | Light transparent gray |
+| Filled | 1px subtle gray | Floating above field | Light transparent gray |
+| Error | 1px red (#d00000) | Floating, red text | Light transparent gray |
+| Error + focus | 2px red (#d00000) | Floating, red text | Light transparent gray |
+| Disabled | 1px gray (#ededed) | Grayed out | Gray (#ededed) |
+
+## Sizing
+
+- Height: 44px
+- Horizontal padding: 16px
+- Border radius: 0px (Gap square-corner identity)
+- Input font: Gap Sans, 16px, weight 400, 0.32px letter-spacing
+- Floating label: 10px, positioned above the border
+- Helper text: 10px, below the field
+
+## Examples
+
+```tsx
+{/* Basic text input */}
+<TextInput label="First Name" />
+
+{/* With helper text */}
+<TextInput label="Email" type="email" helperText="We'll never share your email" />
+
+{/* With character limit */}
+<TextInput label="Bio" helperText="Brief description" maxLength={150} />
+
+{/* Controlled with error */}
+<TextInput
+  label="Zip Code"
+  value={zip}
+  onChange={(e) => setZip(e.target.value)}
+  error={!isValidZip}
+  errorText="Please enter a valid zip code"
+/>
+
+{/* Disabled */}
+<TextInput label="Country" value="United States" disabled />
+```
+
+## Rules
+
+- Always provide a `label` — it acts as both placeholder and floating label
+- Use `helperText` for guidance and `errorText` for validation messages
+- Set `maxLength` when a character limit exists — the counter updates automatically
+- Never show both `helperText` and `errorText` — error takes precedence
+- Use `type="password"` for password fields, `type="email"` for email, etc.
+- The floating label requires a background color to cover the border — this uses `--text-input-label-fill`