mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

SKILL.md

Language Markdown11.4 KB235 lines

skills/category-page-filter/SKILL.md

---
name: category-page-filter
description: >-
Build interactive category page filter sidebars from a product category URL. Use this skill when
asked to create, design, or document filters for an ecommerce or product category page. Triggers
include: "build filters for this category", "create a filter sidebar", "what filters should this
page have", or any request involving a product URL and filter/facet UI. The skill covers the full
process: fetching and analyzing the URL, selecting the right 4-6 filters from a standard taxonomy,
writing the filter labels with sub-labels, and rendering an interactive HTML widget with checkbox
state, active tags, clear-all, and collapsible sections.
license: Internal use, Meridian Display Co.
---
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 Type | Notes |
|---|---|---|
| 1 | **Size / Width / Height / Space** | Use the most relevant dimension for the category. Frame as ranges, not exact values. |
| 2 | **Price range** | Always category-specific brackets. Anchor to actual product prices on the page. |
| 3 | **In-hand date / Turnaround** | Standard ranges: Rush (1-4 days), 4-5 days, 6-10 days, 11+ days. Adjust rush label based on what the category actually supports. |
| 4 | **Material** | Only include if it meaningfully affects the buying decision (e.g. fabric vs. vinyl, LED vs. SEG). Skip if all products use the same material. |
| 5 | **Product type / Model tier** | Use when subcategories exist within the page (e.g. Premium vs. Standard, Backlit vs. Lightbox). |
| 6 | **Critical feature** | One binary or multi-option feature that is category-specific and high-impact for the decision (e.g. poles visible vs. hidden, single vs. dual sided, LED backlit vs. not). |
### 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):
| Spec language ❌ | Outcome language ✓ |
|---|---|
| Poles visible | Classic step & repeat look (poles visible) |
| Poles hidden | Clean full-graphic look (poles hidden) |
| 9oz polyester fabric | Fabric: matte, wrinkle-resistant, seamless |
| 13oz vinyl | Vinyl: vibrant color, easy-clean |
| Premium model | Premium: 5-year warranty, poles fully hidden |
---
## 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):
```css
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:
```html
<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