category-page-filter/

This skill documents the end-to-end process for building interactive category page filter sidebars from a product category URL. It covers research, filter selection, label writing, and widget implementation.

The user provides a category page URL (and optionally a buying guide URL or reference screenshot). The output is a fully interactive filter sidebar widget rendered inline in chat, plus a clear rationale for every filter chosen.

Step 1: Fetch and Analyze the Category URL

Use web_fetch on the provided URL. Extract:

• Product names and count: how many SKUs are on the page?
• Key differentiating attributes: what varies most across products? (size, material, price, features, turnaround)
• Price range: lowest and highest prices listed
• Turnaround times: are rush options mentioned?
• Product subcategories: are there named sub-types or tiers?
• Technical specs: pixel pitch, material weight, dimensions, etc.

If a buying guide URL is also provided, fetch it too. Buying guides reveal the customer's decision sequence (which questions they ask first), and that should directly inform filter ordering and label language.

Key insight: The category page tells you what exists. The buying guide tells you how customers think about it. Use both.

Step 2: Select 4-6 Filters

Target 4-6 filters per category page, never more than 10. Use this standard taxonomy as a starting point, then adapt to the specific category:

Filter selection rules:

• Less is more. A 7-product page needs 4-5 filters, not 10.
• Skip filters where all products are the same. If every product ships in 4-5 days, don't show an in-hand filter.
• Prefer outcome-framing over spec-framing. "Clean full-graphic look" beats "poles hidden." "Photo-ready seamless" beats "9oz polyester fabric."
• Pixel pitch and other technical specs belong on LED/video wall categories only, paired with plain-English context (viewing distance, use case).
• Never add a filter for accessories or add-ons unless the page explicitly mixes accessories and primary products.

Step 3: Write Filter Labels and Sub-labels

Every filter option should have:

1. A primary label: short, scannable, 1-5 words
2. A sub-label (optional but recommended for technical or unfamiliar options): one sentence explaining what it means or when to choose it

Label writing principles:

• Frame around the customer's question, not the spec. A customer doesn't think "I need 3.9mm pixel pitch." They think "I need something for a large outdoor booth." Translate specs into situations.
• Use the buying guide's own language when available. If the guide says "most popular size for photo ops," use that phrase.
• For size filters, describe the use case alongside the measurement: 8ft-10ft wide: Most popular, ideal for photo ops and entrances
• For material filters, call out the practical difference: Fabric: poles fully hidden vs. Vinyl: side poles visible
• For model tier filters, lead with the differentiating outcome: Premium: 5-year hardware warranty, poles hidden vs. Standard: budget-friendly, 1-year warranty
• For price filters, use clean round-number brackets anchored to actual prices. Don't invent brackets that no product falls into.

Outcome-framing examples (step and repeat backdrops):

Step 4: Determine Filter Ordering

Order filters by decision priority: the question the customer asks first goes on top.

General ordering logic:

1. Type or size: the first cut (what kind of product, how big)
2. Key differentiating feature: what makes products meaningfully different within the type
3. Material: if it affects look, durability, or price significantly
4. Price range: usually mid-priority, since customers narrow by type before price
5. In-hand date: usually last, since only urgent customers filter by this first

Exception: If urgency is the primary driver (e.g. rush event products), move in-hand date to position 2 or 3.

Step 5: Assign Product Counts

Every filter option should show a product count badge. These serve two purposes:

1. Tell customers how many results they'll see before clicking
2. Prevent zero-result dead ends

For real implementations: pull counts from the product catalog database filtered by that attribute value.

For prototypes/mockups: assign plausible counts based on the number of products on the page, distributed across options. Ensure no option shows 0. If a value maps to zero products, remove it from the filter entirely.

Step 6: Build the Interactive Widget

Render the filter as an HTML widget using the show_widget tool. The widget must include:

Required UI elements:

• Section headers with collapse/expand chevron toggle
• Checkboxes for each filter option with product count badge
• Active filter tags bar above the filters, showing selected filters as removable pills
• Clear all button that appears in the tags bar when any filter is selected
• Result count / summary that updates to show "X filters applied" when active

Required interactions:

• Clicking a checkbox adds it to active tags and increments the selected count on the section header
• Clicking × on a tag deselects the corresponding checkbox
• Clear all resets all checkboxes and clears all tags
• Section headers collapse/expand the option list independently

CSS variables to use (theme-aware):

var(--color-text-primary)        /* main labels */
var(--color-text-secondary)      /* sublabels, counts */
var(--color-text-tertiary)       /* count badges, notes */
var(--color-text-info)           /* selected count highlight on section header */
var(--color-background-secondary) /* count badge backgrounds, notes */
var(--color-border-tertiary)     /* section dividers */
var(--color-border-secondary)    /* tag borders */
var(--font-sans)                 /* font family */

Widget code template structure:

<style>/* scoped styles using CSS vars */</style>

<div class="sidebar">
  <div class="filters-label">
    Filters
    <span class="result-summary" id="result-count">Showing all products</span>
  </div>
  <div class="active-filters" id="active-tags"></div>
  <div id="filter-sections"></div>
</div>

<script>
const filtersData = [
  {
    id: "unique-id",
    label: "Filter section label",
    note: "Optional helper note shown at bottom of options",
    options: [
      { value: "value-key", label: "Primary label", sublabel: "One sentence description", count: N },
    ]
  },
  // ... more sections
];

// State management, render functions, event handlers
</script>

Optional enhancements:

• Visual scale bar: for numeric ranges like pixel pitch, a gradient bar from "fine/close" to "coarse/far" helps orient customers
• Section notes: a small italic note at the bottom of a filter section for important context (e.g. "All adjustable frames range 6-10ft; extension kit adds 2ft increments")
• Sub-labels on options: strongly recommended for any technical spec or unfamiliar product attribute

Step 7: Write the Rationale

After rendering the widget, briefly explain:

1. Which filters were chosen and why (1 sentence each)
2. Which filters were deliberately skipped and why
3. Any category-specific decisions (e.g. why size is framed by use case rather than inches)

This rationale helps the team validate the logic before implementation and makes the reasoning transparent for stakeholders.

Full Example Walkthrough

Input: https://meridiandisplay.example/step-and-repeat-backdrops/ + buying guide URL

Research findings:

• 7 products (including 1 extension kit accessory)
• Size range: adjustable 6-10ft wide, fixed 8x8ft and 10x10ft
• Two models: Premium (fabric, poles hidden, 5-year warranty) and Standard (vinyl, poles visible, 1-year warranty)
• Price range: ~$350-$1,200+
• Buying guide decision sequence: event type → size → material/model → accessories

Filters selected (5):

1. Backdrop width, framed as event use cases (small/medium/large)
2. Model tier: Premium vs. Standard vs. Fixed size vs. Extension kit
3. Graphic material: Fabric (poles hidden) vs. Vinyl (poles visible)
4. Price range: $0-600 / $600-900 / $900-1200 / $1200+
5. In-hand date: Rush / 4-5 / 6-10 / 11+ days

Filters skipped:

• Shape: all products are rectangular, so there is no variation
• Single/double sided: not applicable to backdrops
• Features: too few products to justify a features filter

Label decisions:

• Width options include use-case sublabels taken from the buying guide verbatim ("Most popular: photo ops, entrances, sponsor walls")
• Material options describe the pole-visibility outcome, not the material weight ("poles fully hidden" vs. "side poles visible")
• Model tier leads with the warranty and visual outcome, not the tier name

Quick Reference Checklist

Before delivering the filter widget, verify:

• Fetched the category URL (and buying guide if available)
• Counted the products on the page
• Selected 4-6 filters from the taxonomy
• Skipped filters where all products are identical
• Used outcome-framing language, not spec-only labels
• Added sub-labels to any technical or unfamiliar options
• Ordered filters by customer decision priority
• Assigned plausible product counts to every option
• Built widget with: checkboxes, active tags, clear-all, collapse/expand, count badges
• Wrote rationale explaining inclusions and exclusions