@stoovles/gap-kit 1.0.0

package/guidelines/components/accordion.md

@@ -0,0 +1,99 @@
+# Accordion
+
+## When to use
+
+Use the `Accordion` to present a vertically stacked list of sections that can be individually expanded or collapsed. Common uses include FAQs, filter panels, product detail sections, and settings groups.
+
+```tsx
+import { Accordion, AccordionItem } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### Accordion
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | One or more `AccordionItem` elements |
+| `className` | `string` | — | Additional CSS class |
+
+### AccordionItem
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Header text for the section |
+| `count` | `string \| number` | — | Optional count displayed after the title, e.g. `(3)` |
+| `subtitle` | `string` | — | Secondary text shown below the title when collapsed |
+| `attributes` | `string` | — | Summary text shown below the title when expanded (e.g. selected filter values) |
+| `defaultExpanded` | `boolean` | `false` | Whether the item starts expanded |
+| `children` | `ReactNode` | — | Content revealed when expanded |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Chevron | Subtitle | Content |
+|---|---|---|---|
+| Collapsed | Points down | Visible (if provided) | Hidden |
+| Expanded | Points up | Hidden | Visible |
+
+Each item is separated by a subtle divider. The chevron rotates 180 degrees with a smooth transition on expand/collapse.
+
+## Sizing
+
+- Item bottom padding: 24px (`--spacing-l`)
+- Header-to-content gap: 24px (`--spacing-l`)
+- Title-to-subtitle gap: 8px (`--spacing-s`)
+- Title font: Gap Sans, 16px (`--text-header-font-size`), weight 700 (`--font-weight-base-heavier`), letter-spacing 0.28px
+- Count font: same as title
+- Subtitle font: Gap Sans, 14px (`--text-subhead-font-size`), weight 400, secondary color (`--color-type-secondary`)
+- Chevron: 10 × 6px, stroked, `currentColor`
+
+## Examples
+
+```tsx
+{/* Basic accordion with static content */}
+<Accordion>
+  <AccordionItem title="Shipping & Returns">
+    <p>Free shipping on orders over $50. Returns accepted within 30 days.</p>
+  </AccordionItem>
+  <AccordionItem title="Size Guide">
+    <p>Refer to our size chart for the perfect fit.</p>
+  </AccordionItem>
+  <AccordionItem title="Product Details">
+    <p>100% organic cotton. Machine wash cold.</p>
+  </AccordionItem>
+</Accordion>
+
+{/* With counts and subtitles (e.g. filter panel) */}
+<Accordion>
+  <AccordionItem title="Color" count={3} subtitle="Blue, Red, Green">
+    {/* Checkbox filters here */}
+  </AccordionItem>
+  <AccordionItem title="Size" count={2} subtitle="M, L">
+    {/* Checkbox filters here */}
+  </AccordionItem>
+</Accordion>
+
+{/* With expanded attributes summary */}
+<Accordion>
+  <AccordionItem
+    title="Color"
+    count={3}
+    subtitle="3 selected"
+    attributes="Blue, Red, Green"
+    defaultExpanded
+  >
+    {/* Filter chips or checkboxes */}
+  </AccordionItem>
+</Accordion>
+```
+
+## Rules
+
+- Always provide a `title` for each `AccordionItem`
+- Use `subtitle` for a brief collapsed-state summary and `attributes` for an expanded-state summary — only one is visible at a time
+- Place any content type inside the expanded area: text, form controls, images, other components
+- Use `count` to communicate the number of items or selections within a section
+- Each item manages its own open/closed state independently — multiple items can be open at once
+- The subtle divider at the top of each item comes from the existing `Divider` component styles
+- Do not nest accordions inside accordions

package/guidelines/components/breadcrumb.md

@@ -0,0 +1,74 @@
+# Breadcrumb
+
+## When to use
+
+Use the `Breadcrumb` component to show the user's current location within a site hierarchy and provide quick navigation back to parent pages. Common on product detail pages, category pages, and multi-step flows.
+
+```tsx
+import { Breadcrumb } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### Breadcrumb
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `BreadcrumbItem[]` | — | Ordered list of links from root to current page |
+| `className` | `string` | — | Additional CSS class |
+
+### BreadcrumbItem
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Display text for the crumb |
+| `href` | `string` | URL the crumb links to |
+
+## Visual reference
+
+| Element | Style |
+|---|---|
+| Link text | Gap Sans, 16px, weight 400, link color (`--color-type-link`), underlined |
+| Last link (multi-level) | Same color, no underline, `aria-current="page"` |
+| Separator `/` | Gap Sans, 16px, weight 400, primary color (`--color-type-primary`) |
+
+## Sizing
+
+- Vertical padding: 16px (`--spacing-utk-l`)
+- Gap between crumbs and separators: 4px (`--spacing-xs`)
+- Font size: 16px (`--text-link-regular-font-size`)
+- Letter spacing: 0.32px (`--font-letter-spacing-0`)
+
+## Examples
+
+```tsx
+{/* Single-level breadcrumb */}
+<Breadcrumb items={[{ label: "Women", href: "/women" }]} />
+
+{/* Two-level breadcrumb */}
+<Breadcrumb
+  items={[
+    { label: "Women", href: "/women" },
+    { label: "Dresses", href: "/women/dresses" },
+  ]}
+/>
+
+{/* Deep navigation */}
+<Breadcrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Women", href: "/women" },
+    { label: "Clothing", href: "/women/clothing" },
+    { label: "Dresses", href: "/women/clothing/dresses" },
+  ]}
+/>
+```
+
+## Rules
+
+- Always provide at least one item — the component renders nothing for an empty array
+- Order items from the broadest category (root) to the most specific (current page)
+- The last item in a multi-level breadcrumb receives `aria-current="page"` and no underline
+- The component renders inside a `<nav aria-label="Breadcrumb">` with a semantic `<ol>` for accessibility
+- Use concise labels — breadcrumb text should match the target page's title or heading
+- Do not use breadcrumbs as the primary navigation; they supplement the main nav

package/guidelines/components/buttons.md

@@ -0,0 +1,90 @@
+# Button
+
+## When to use
+
+Use the `Button` component for all interactive actions — form submissions, confirmations, navigation triggers, and destructive operations. Never use a `<div>` or `<a>` when a semantic `<button>` is needed.
+
+```tsx
+import { Button } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"critical" \| "primary" \| "secondary"` | `"primary"` | Visual style of the button |
+| `loading` | `boolean` | `false` | Shows a dot loader and disables interaction |
+| `fullWidth` | `boolean` | `false` | Stretches button to fill its container |
+| `disabled` | `boolean` | `false` | Grays out the button and prevents clicks |
+| `children` | `ReactNode` | — | Button label text |
+| `className` | `string` | — | Additional CSS class |
+
+All standard `<button>` HTML attributes are also supported (e.g. `type`, `onClick`, `aria-label`).
+
+## Variant decision tree
+
+```
+What action does this button perform?
+
+├─ A destructive or high-stakes action (delete, cancel order, remove)?
+│  └─ variant="critical"
+│
+├─ The primary call-to-action on the page (add to bag, checkout, submit)?
+│  └─ variant="primary"
+│
+└─ A secondary or supporting action (save for later, continue shopping)?
+   └─ variant="secondary"
+```
+
+## Visual reference
+
+| Variant | Default | Hover | Active | Disabled |
+|---|---|---|---|---|
+| `critical` | Blue fill (#031ba1), white text | Black fill, white text | Blue fill, white text | Gray fill (#ededed), gray text |
+| `primary` | White fill, gray border (#ccc), black text | Blue fill (#031ba1), black border, white text | White fill, black border, black text | White fill, gray border (#ededed), gray text |
+| `secondary` | Black fill, black border, white text | Blue fill (#031ba1), blue border, white text | Blue fill, blue border, white text | Gray fill (#ededed), gray text |
+
+## Sizing
+
+- Minimum height: 44px (touch target compliance)
+- Horizontal padding: 48px
+- Border radius: 0px (Gap's square-corner identity)
+- Font: Gap Sans, 16px, weight 400, letter-spacing 0.32px
+
+## Examples
+
+```tsx
+{/* Primary CTA */}
+<Button variant="primary">Add to Bag</Button>
+
+{/* Secondary action */}
+<Button variant="secondary">Save for Later</Button>
+
+{/* Destructive action */}
+<Button variant="critical">Remove Item</Button>
+
+{/* Loading state (e.g. during form submission) */}
+<Button variant="secondary" loading>
+  Processing
+</Button>
+
+{/* Disabled */}
+<Button variant="primary" disabled>
+  Select a Size
+</Button>
+
+{/* Full-width in a narrow container */}
+<Button variant="secondary" fullWidth>
+  Checkout
+</Button>
+```
+
+## Rules
+
+- Every page should have at most one `critical` button visible at a time
+- Prefer `primary` for the main CTA; use `secondary` for supporting actions
+- Never place two `critical` buttons side by side
+- Always provide a text label — icon-only actions should use a different component
+- Use `loading` during async operations instead of manually disabling and re-enabling
+- Do not override the 44px minimum height — it ensures touch accessibility
+- When pairing buttons, place `primary` or `critical` on the right, `secondary` on the left

package/guidelines/components/checkbox.md

@@ -0,0 +1,86 @@
+# Checkbox
+
+## When to use
+
+Use `Checkbox` when the user needs to select zero or more options from a list, or toggle a single boolean setting (e.g. "Remember me"). For mutually-exclusive choices use a radio group instead.
+
+```tsx
+import { Checkbox, CheckboxGroup } from '@stoovles/gap-kit'
+```
+
+## Checkbox Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Text label displayed next to the checkbox |
+| `error` | `boolean` | `false` | Renders the checkbox in the error state (red border / fill) |
+| `disabled` | `boolean` | `false` | Grays out the checkbox and prevents interaction |
+| `checked` | `boolean` | — | Controlled checked state |
+| `defaultChecked` | `boolean` | — | Uncontrolled initial checked state |
+| `onChange` | `(e) => void` | — | Change handler |
+| `className` | `string` | — | Additional CSS class |
+
+All standard `<input>` HTML attributes are also supported (e.g. `name`, `value`, `required`).
+
+## CheckboxGroup Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `Checkbox` components |
+| `label` | `string` | — | Group legend (optional) |
+| `error` | `boolean` | `false` | Applies error styling to the group wrapper |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Unchecked | Checked |
+|---|---|---|
+| Default | White fill, black 1px border | Dark gray fill (#595959), black border, white checkmark |
+| Error | White fill, red border | Red fill (#d00000), red border, white checkmark |
+| Disabled | White fill, gray border (#ededed) | Gray fill (#ededed), gray border, white checkmark |
+
+## Sizing
+
+- Checkbox box: 22×22px inside a 24×24px touch target
+- Border radius: 0px (Gap square-corner identity)
+- Gap between box and label: 8px
+- Group spacing between items: 24px
+- Font: Gap Sans, 16px, weight 400
+
+## Examples
+
+```tsx
+{/* Single checkbox */}
+<Checkbox label="I agree to the terms" />
+
+{/* Controlled checkbox */}
+<Checkbox
+  label="Subscribe to newsletter"
+  checked={subscribed}
+  onChange={(e) => setSubscribed(e.target.checked)}
+/>
+
+{/* Checkbox group */}
+<CheckboxGroup label="Select sizes">
+  <Checkbox label="XS" name="size" value="xs" />
+  <Checkbox label="S" name="size" value="s" />
+  <Checkbox label="M" name="size" value="m" />
+  <Checkbox label="L" name="size" value="l" />
+  <Checkbox label="XL" name="size" value="xl" />
+</CheckboxGroup>
+
+{/* Error state */}
+<Checkbox label="Required field" error />
+
+{/* Disabled */}
+<Checkbox label="Out of stock" disabled checked />
+```
+
+## Rules
+
+- Always provide a `label` — a checkbox without visible text needs an `aria-label`
+- Use `CheckboxGroup` with a `label` (rendered as `<legend>`) when presenting related options
+- Never use a checkbox for a single mutually-exclusive choice — use a radio button instead
+- Place the checkbox to the left of its label
+- In error states, validate on form submission or blur, not on every keystroke
+- Do not mix error and disabled states on the same checkbox

package/guidelines/components/chip.md

@@ -0,0 +1,77 @@
+# Chip
+
+## When to use
+
+Use `Chip` to display an active filter or attribute that the user can dismiss. Chips are typically shown in a `ChipGroup` after filter selections on product listing and search results pages.
+
+```tsx
+import { Chip, ChipGroup } from '@stoovles/gap-kit'
+```
+
+## Chip Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | The filter attribute text (e.g. "Blue", "Size M") |
+| `onDismiss` | `() => void` | — | Callback when the dismiss (×) button is clicked. Omit to hide the dismiss button. |
+| `swatch` | `string` | — | CSS color value for an optional color swatch circle (e.g. `"#031ba1"`) |
+| `className` | `string` | — | Additional CSS class |
+
+## ChipGroup Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `Chip` components |
+| `onClearAll` | `() => void` | — | Callback for the "Clear all" link. Omit to hide the link. |
+| `clearAllLabel` | `string` | `"Clear all"` | Label for the clear-all action |
+| `className` | `string` | — | Additional CSS class |
+
+## Visual reference
+
+| State | Appearance |
+|---|---|
+| Default | Semi-transparent gray background, blue text (#031ba1), no visible border |
+| Hover | 1px border appears |
+| Focus | Gray background (#ccc), 1px border |
+| Active | Darker gray background (#afafaf) |
+
+## Sizing
+
+- Min height: 32px, min width: 48px
+- Padding: 8px vertical, 12px horizontal
+- Gap between chip elements: 8px
+- Border radius: 0px (Gap square-corner identity)
+- Font: Gap Sans, 16px, letter-spacing 0.24px
+- Dismiss icon: 9×9px × in a 16px touch target
+- Swatch: 16px circle (fully round)
+- Group chip gap: 12px row, 8px column
+
+## Examples
+
+```tsx
+{/* Single dismissible chip */}
+<Chip label="Blue" onDismiss={() => removeFilter('blue')} />
+
+{/* Chip with color swatch */}
+<Chip label="Navy" swatch="#031ba1" onDismiss={() => removeFilter('navy')} />
+
+{/* Chip without dismiss (read-only display) */}
+<Chip label="On Sale" />
+
+{/* ChipGroup with clear-all */}
+<ChipGroup onClearAll={() => clearAllFilters()}>
+  <Chip label="Size M" onDismiss={() => removeFilter('size-m')} />
+  <Chip label="Blue" swatch="#031ba1" onDismiss={() => removeFilter('blue')} />
+  <Chip label="Under $50" onDismiss={() => removeFilter('under-50')} />
+</ChipGroup>
+```
+
+## Rules
+
+- Always include a meaningful `label` — do not use chips with only a swatch
+- Provide `onDismiss` for every chip when the user should be able to remove individual filters
+- Use `ChipGroup` with `onClearAll` when displaying 2 or more active filters
+- Place the `ChipGroup` above the product grid, below the filter bar
+- Use the `swatch` prop only for color-based filters
+- Keep labels concise — one or two words maximum
+- Do not use chips for navigation or as toggle buttons; use them only for applied filters

package/guidelines/components/divider.md

@@ -0,0 +1,52 @@
+# Divider
+
+## When to use
+
+Use the `Divider` component to visually separate sections of content. It renders a semantic `<hr>` element.
+
+```tsx
+import { Divider } from '@stoovles/gap-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"default" \| "subtle"` | `"default"` | Default is dark (#595959), subtle is light (#ccc) |
+| `className` | `string` | — | Additional CSS class |
+
+## Variant decision tree
+
+```
+How prominent should the separation be?
+
+├─ Clear visual break between major sections?
+│  └─ variant="default" (dark line)
+│
+└─ Gentle separation between related items (e.g. list rows)?
+   └─ variant="subtle" (light line)
+```
+
+## Sizing
+
+- Width: 100% of parent container
+- Border width: 2px (`--divider-border-width`)
+- Default color: #595959 (`--divider-color`)
+- Subtle color: #ccc (`--color-border-subtle`)
+
+## Examples
+
+```tsx
+{/* Default dark divider */}
+<Divider />
+
+{/* Subtle divider between list items */}
+<Divider variant="subtle" />
+```
+
+## Rules
+
+- Use `default` for major section breaks (e.g. between content blocks)
+- Use `subtle` for lighter separations (e.g. between list items, accordion rows)
+- Do not stack multiple dividers — one is sufficient
+- Spacing above and below the divider should be controlled by the parent layout, not the divider itself

package/guidelines/components/dropdown.md

@@ -0,0 +1,125 @@
+# Dropdown
+
+## When to use
+
+Use the `Dropdown` component when the user needs to select a single value from a predefined list of options. Appropriate for form fields like country, size, sort order, or any finite set of choices.
+
+```tsx
+import { Dropdown } from '@stoovles/gap-kit'
+```
+
+## Props
+
+### Dropdown
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Field label (shown as placeholder when empty, floats when filled) |
+| `options` | `DropdownOption[]` | — | List of selectable options |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Uncontrolled initial value |
+| `onChange` | `(value: string) => void` | — | Callback when selection changes |
+| `error` | `boolean` | `false` | Renders the field in error state with red border |
+| `disabled` | `boolean` | `false` | Grays out the field and prevents interaction |
+| `className` | `string` | — | Additional CSS class |
+| `id` | `string` | — | HTML id for the trigger button |
+
+### DropdownOption
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Display text shown in the menu and trigger |
+| `value` | `string` | Unique value passed to `onChange` |
+
+## Visual reference
+
+| State | Border | Label | Background |
+|---|---|---|---|
+| Empty (closed) | 1px gray (`--dropdown-border-color`) | Inline as placeholder (subtle color) | White |
+| Open | 2px gray (`--dropdown-border-color`) | Inline or floating | White |
+| Filled (closed) | 1px gray | Floating above field | White |
+| Error | 1px or 2px red (`--color-border-error`) | Floating, red text | White |
+| Disabled | No visible border | Floating, subtle color | Gray (`--color-fill-disabled`) |
+
+### Menu rows
+
+| State | Background | Text color |
+|---|---|---|
+| Default | White | Primary (`--color-type-primary`) |
+| Hover / Active | Light gray (`--color-gray-2`) | Primary |
+| Selected | Dark blue (`--dropdown-fill-selected`) | White (`--dropdown-font-color`) |
+
+## Sizing
+
+- Trigger height: 44px
+- Horizontal padding: 16px (`--spacing-utk-l`)
+- Border radius: 0px (Gap square-corner identity)
+- Font: Gap Sans, 16px, weight 400, 0.32px letter-spacing
+- Floating label: 10px, positioned above the border
+- Menu row height: 42px, padding 12px vertical / 16px horizontal
+- Menu max-height: 252px (scrollable)
+- Menu shadow: 2px 4px 8px rgba(0,0,0,0.08)
+
+## Examples
+
+```tsx
+{/* Basic dropdown */}
+<Dropdown
+  label="Size"
+  options={[
+    { label: "Small", value: "s" },
+    { label: "Medium", value: "m" },
+    { label: "Large", value: "l" },
+    { label: "X-Large", value: "xl" },
+  ]}
+/>
+
+{/* Controlled dropdown */}
+const [sort, setSort] = useState("");
+<Dropdown
+  label="Sort By"
+  value={sort}
+  onChange={setSort}
+  options={[
+    { label: "Newest", value: "newest" },
+    { label: "Price: Low to High", value: "price-asc" },
+    { label: "Price: High to Low", value: "price-desc" },
+  ]}
+/>
+
+{/* Error state */}
+<Dropdown
+  label="Country"
+  options={countries}
+  error={!selectedCountry}
+/>
+
+{/* Disabled */}
+<Dropdown
+  label="Region"
+  defaultValue="us"
+  options={[{ label: "United States", value: "us" }]}
+  disabled
+/>
+```
+
+## Keyboard navigation
+
+| Key | Action |
+|---|---|
+| `Enter` / `Space` | Open menu or select focused option |
+| `ArrowDown` | Open menu or move focus down |
+| `ArrowUp` | Move focus up |
+| `Escape` | Close menu |
+| `Tab` | Close menu and move focus |
+
+## Rules
+
+- Always provide a `label` — it acts as both placeholder and floating label
+- Each option must have a unique `value`
+- The menu appears directly below the trigger and matches its width
+- The selected option is highlighted with the brand blue background
+- Use `error` for validation — the border and floating label turn red
+- Do not use a dropdown for fewer than 3 options — use `Radio` instead
+- Do not use a dropdown for more than ~15 options — consider a searchable input
+- The component supports both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) patterns