# Model Landing Pages — Reasoning & Recommendations

**Companion to:** [feature-design-guidelines.md](feature-design-guidelines.md), [USAClean_Sitemap_Recommendations.md](USAClean_Sitemap_Recommendations.md), [install-repair-guides-concepts.md](install-repair-guides-concepts.md)
**Live preview:** [Phase 1 build](https://demo.thecxlabs.com/v2/model-tennant-t500e-phase1.html) · [full hub (Phase 2/3 target)](https://demo.thecxlabs.com/v2/model-tennant-t500e.html)
**Decision of record:** [PD-008](decisions.md) — Phase 1 scope cut to four elements
**Date:** May 2026 · **Phase 1 scope revised** August 2026 (PD-008)

This document explains the Model Landing Page pattern — one rich hub per machine model — and the content-management plan for scaling it across USA Clean's catalog.

---

## TL;DR

Build a **per-model landing page** — one rich hub per machine model, replacing the current pattern of model-specific URLs that dead-end on a filtered parts list with no equipment or documentation context. Production URL pattern follows the sitemap recommendation: **`/parts/by-machine/{brand}/{model}/`** (e.g., `/parts/by-machine/tennant/t500e/`).

**Phase 1 ships four elements** ([PD-008](decisions.md)): the model info header, the documentation library, a dispatch-a-tech CTA, and related models. Those four are the subset that has **no dependency on catalog-wide data work** — merch can populate every one of them per model on day one. The parts grids, the specs card, and the interactive diagram are the page's other half, and each is held for the phase that owns its data.

| Phase | Surface | Effort |
|---|---|---|
| **Phase 1** _(Pilot)_ | Top 20 model landing pages on the BC native Category page pattern + Custom Fields, carrying **four elements**: model info header, documentation library, dispatch-a-tech CTA, related models. No parts grid, no specs card. | **Low–Medium** — one template build, then roughly half a day of content per model |
| **Phase 2** _(Iterate)_ | Top 100 models, and the **full hub layout** — most-bought parts, compatible-parts grid, specs card. Template-driven generation from a model database (CSV → admin import). Compatible-parts join automated via `compatible_models[]` field on each part. | Higher — admin tooling + content ops (the ~12k-part tagging effort) |
| **Phase 3** _(Future)_ | All 500+ models. Self-serve content management for the merch team. Interactive parts diagrams (click → add). Personalized "your fleet's other models" suggestions. | Highest — Catalyst-replatform candidate |

**Two prototypes.** [`v2/model-tennant-t500e-phase1.html`](../v2/model-tennant-t500e-phase1.html) is the Phase 1 build — what actually ships first. [`v2/model-tennant-t500e.html`](../v2/model-tennant-t500e.html) is the full hub, kept as the Phase 2/3 target; the sections Phase 1 leaves out are marked `DECISION PD-008` in its source.

---

## Current state

USA Clean currently has model pages at URLs like `/parts-and-supplies/tennant/t500/` — flat filtered parts lists with no machine context. Each is a category-page-with-filter-applied; no hero, no docs, no specs, no service entry. The pattern works for "I know exactly what I want" but fails the buyer who's still orienting (which model is mine? what manual covers it? is service available?).

The Clarity sessions show 100% of organic browse sessions go through a brand→model traversal, and the existing Tennant T5 / TASKI Swingo 750B / Nilfisk-Advance pages are among the highest-traffic non-search pages on the site. **Model is the dominant mental model for parts discovery; the page should reflect that.**

---

## References

### Sweepscrub
70+ Tennant model-specific parts pages. Each page is a filtered parts list. No hero, no docs, no specs — exactly the limitation USA Clean's current site has.

### Grainger
Item-level pages are strong (rich specs, docs, alternates), but Grainger doesn't have machine-model landings — they sell consumables, not equipment, so the use case is different.

### Tennant.com (the OEM)
Model pages have a hero with the machine, spec sheet, video walk-through, dealer lookup. **But no parts-purchase path** — Tennant is the manufacturer; parts are sold via distributors like USA Clean. This is exactly the gap USA Clean's model landing page closes.

### HD Supply
Equipment listings have basic spec sheets but no rich documentation library. Service entry is buried.

### Tractor Supply (`/c/parts/`) and Lowe's "Find My Parts" tools
Strong machine-finder UIs that route to a manufacturer's parts catalog, but the landing pages they route TO are mostly OEM (John Deere, Stihl, etc.) — not aggregator-controlled. USA Clean's opportunity is to BE the rich landing for every machine the customer might own.

---

## What BC Stencil gives us

The Model Landing Page is a **Category page** in BC terminology — but with a much richer template than the stock category page provides.

- **Categories** can have a `description` field with HTML, custom-field children, and an associated set of products. The category page template renders all of these.
- **Custom Fields on the Category** ([BC Help](https://support.bigcommerce.com/s/article/Adding-Custom-Fields)) — populate per-model metadata: `hero_image_url`, `cleaning_path`, `tank_capacity`, `run_time`, `weight`, `warranty`, `operator_manual_url`, `service_manual_url`, etc. (~20 fields total). Free, native, queryable.
- **Category template overrides** in Stencil — `templates/pages/category/{handle}.html` lets us build a custom category-page template that reads the custom fields and renders the rich layout.
- **Product compatibility via Custom Fields on products** — each product has a `compatible_models[]` field listing the model handles it fits. The model landing page queries products where the field contains the page's model handle. Native; no app required.
- **Storefront API** — `/api/storefront/categories/{id}/products` for the parts grid, filtered server-side.

**Sources:** [BC Categories](https://support.bigcommerce.com/s/article/Categories), [BC Category Custom Fields](https://support.bigcommerce.com/s/article/Adding-Custom-Fields), [Stencil Category Template](https://developer.bigcommerce.com/docs/storefront/stencil/themes/category).

---

## Stencil limitations

- **No native UI for the rich hero / spec card / doc grid layout.** All custom theme work. The reusable composites (`.doc-card`, `.mini-part`, `.specs-card`, `.related-model`) become part of Caster. The [PD-008](decisions.md) Phase 1 cut narrows this to four of them, which is why the pilot template is a smaller build than first scoped.
- **No native cross-model parts auto-discovery.** The `compatible_models[]` join works for direct fits, but BC doesn't surface "parts that fit *similar* models" — that requires an explicit `also_fits` field or a custom service.
- **Diagrams as static images only.** The interactive "click a part in the exploded view to add to cart" pattern (Phase 3) is not a Stencil feature. Needs an app or Catalyst. Phase 1 therefore ships the exploded view as a PDF download in the documentation grid, and the prototype says so — no "click to add" affordance the platform cannot back.
- **No native "personalized for your fleet" prioritization.** If Maria's fleet has 6 T500e and 3 Nilfisk SC500, the parts grid should highlight what *her* fleet has bought historically. That requires joining product views to her account — possible in Stencil with custom JS but cleaner in Catalyst.
- **Bulk admin management for 100+ model pages is painful.** Each category page's custom fields are edited individually in admin. Phase 2 needs a CSV import or a small custom admin app.
- **Auto-redirecting old URLs.** The current `/parts-and-supplies/tennant/t500/` URLs need 301 redirects to the new `/parts/by-machine/tennant/t500e/` paths. BC supports this via the URL redirect manager, but at 500+ models this is a lot of clicks. Plan for bulk redirect import.

---

## App marketplace shortlist

| App | What it does | Worth it now? |
|---|---|:---:|
| **(Native) Categories + Custom Fields + custom template** | The default path. Fully shippable. | ✅ Use this. |
| **[Category Page Builder](https://www.bigcommerce.com/apps/category/page-builder/)** apps | WYSIWYG editor for rich category pages. | Skip — Caster template is the design system; we don't want WYSIWYG drift. |
| **[Klevu / Searchspring](https://www.bigcommerce.com/apps/category/search/)** | Smart product filtering on category pages. | Maybe Phase 2 — useful when "parts that fit this model" exceeds 200 items and basic facet filters aren't enough. |
| **[3D Cloud / 3DProductPlatform](https://3dcloud.com/)** | Interactive parts diagrams (Phase 3). | Phase 3 only — expensive integration; needs to prove ROI on top-10 models first. |
| **Marketing-content apps** (Page Builder, Shogun) | Drag-and-drop landing-page builders. | Skip — same WYSIWYG-drift concern. The model landing is a structured-data page, not a marketing page. |

---

## Caster impact

**New patterns to promote to Caster once a second consumer exists.** The [PD-008](decisions.md) scope cut splits these across two phases — Phase 1 only needs four of them, which is most of why it is cheap:

_Phase 1 set:_
- **`.model-hero`** — 2-col machine hero with image + title + dual CTAs (the stat-bar variant arrives with Phase 2)
- **`.doc-grid` / `.doc-card`** — see below; full-width in Phase 1 because the specs sidecar it shares a row with is deferred
- **`.service-block`** — full-width gradient banner with CTA
- **`.related-model`** — square grid card with icon + name + meta
- **`.section-head`** — title + sub + "more →" link pattern (reusable across model landing + dashboard sections)

_Phase 2 set:_
- **`.mini-part`** — condensed product card (smaller than PLP `.product-card`, no add-to-cart, hero-grid usage)
- **`.specs-card`** — sticky 2-col key/value spec table
- **`.model-hero__statbar`** — the derived-count strip (compatible parts / manuals / videos / diagrams)

**Doc-grid + doc-card** (from [install-repair-guides-concepts.md](install-repair-guides-concepts.md)) are reused here — this is the second consumer, so the pattern graduates to Caster `/patterns/`.

**Stock-badge** (`stock-in`, `stock-low`) usage convention from [inventory-urgency-concepts.md](inventory-urgency-concepts.md) is applied to the parts grid — Phase 2, since the grid is.

**Volume-badge** (from [volume-discount-concepts.md](volume-discount-concepts.md)) appears as `.mini-part__badge--volume` on relevant parts — likewise Phase 2.

**Narrow-viewport note.** `.section-head` is a flex row whose "more →" link is `white-space: nowrap`; below ~640px it pushes past the container. Both model-landing prototypes now stack the section head at that breakpoint. Carry the correction into Caster when `.section-head` graduates — it will bite any page that adopts the pattern.

**Downstream impact:** when Caster promotes these patterns, the model landing page's inline CSS becomes a reference to the system — the page collapses to mostly markup.

---

## Phased recommendation

**Decision of record: [PD-008](decisions.md)** — Phase 1 is scoped to four elements.

### Phase 1 — Top 20 models, four elements, hand-built

**Prototype: [`v2/model-tennant-t500e-phase1.html`](../v2/model-tennant-t500e-phase1.html).**

The page ships with exactly four things on it:

| # | Element | Where the content comes from |
|---|---|---|
| 1 | **Model info header** — photo, machine class, name, description, and two CTAs (buy-or-quote, shop parts for this machine) | OEM-supplied photo and copy; both CTAs point at destinations that already exist today |
| 2 | **Documentation, manuals & videos** | OEM PDFs plus the USA Clean Tech Tips channel — assets merch already holds |
| 3 | **Dispatch a tech** | One CTA into the existing service-request flow |
| 4 | **Related models** | Brand-level taxonomy; no parts data involved |

For each of the top 20 models by part-search-traffic-and-equipment-sales-volume:
1. Create a Category at `/parts/by-machine/{brand}/{model}/`
2. Populate the Phase 1 custom fields — roughly **eight**, not the full twenty: `hero_image_url`, `machine_class`, `description`, `operator_manual_url`, `service_manual_url`, `parts_catalog_url`, `video_playlist_url`, `related_models`
3. Apply the custom category template (one template, 20 instances)

Models likely in the top 20: Tennant T500 / T500e / T300e / T600 / T600e / T7 / T16; Nilfisk SC500 / SC800 / SC1500; Kärcher BR 47/35; Clarke MA50; Advance SC8000; TASKI Swingo 1850.

#### What Phase 1 deliberately leaves out, and why

Each of these is held for a **named data reason**, not for lack of design — the layouts are all worked in the full-hub prototype and marked `DECISION PD-008` in its source:

| Deferred | Blocked on | Returns in |
|---|---|---|
| **Most-bought parts grid** | Order history aggregated per model, refreshed weekly | Phase 2 |
| **Compatible-parts grid** and the "142 compatible parts" count | `compatible_models[]` populated across the ~12k-part catalog — the largest content-ops task in this brief | Phase 2 |
| **Specs card** | The other ~12 custom fields per model, and the two-column template that houses it | Phase 2 |
| **Hero stat bar** | Every figure in it is derived from the two rows above | Phase 2 |
| **Machine-lookup band** | Nothing — but it is a navigation affordance, not per-model content; it ships with [search](search-experience-concepts.md) Phase 1 and appears here for free once it does | Search Phase 1 |
| **Interactive parts diagram** (click a hotspot → add to cart) | React-grade state; Stencil can fake it but not at scale | Phase 3 (Catalyst) |

The exploded-view diagram still ships in Phase 1 — as a **static PDF download** in the documentation grid. That distinction matters: the full-hub prototype's diagram card advertises "click parts to add to cart," which is a Phase 3 promise. Phase 1 must not make it.

**Why this is the right cut.** The four surviving elements share one property: nothing about them scales with catalog size. Twenty model pages need twenty hero images and twenty document lists — bounded, parallelizable content work that a merch team can finish in a sprint. The two parts grids scale with the *catalog* (~12k SKUs to tag), which is a 2–3 month structured effort. Binding the pilot to that effort means no model landing page ships for a quarter. Cutting them means the top-20 ship in weeks and generate the traffic data that justifies the tagging spend.

**What Phase 1 gives up.** A buyer who arrives to buy a part gets a link, not a grid — one extra click to the existing filtered parts list. That is the honest cost, and it is small: that filtered list is exactly what the current model URLs already deliver, so Phase 1 is strictly additive to what exists today.

**What "winning" looks like:** measurable traffic shift from the old `/parts-and-supplies/{brand}/{model}/` URLs to the new ones (via 301), reduced bounce rate, increased session depth (buyers click through to docs / service / the parts list), doc-download rate per model, and "dispatch a tech" / "buy or quote this machine" CTA click-through.

### Phase 2 — Top 100, automated, and the full hub layout

Two things happen at once in Phase 2: the page **widens** to the full hub, and the build **automates**.

Build admin tooling: a CSV-import script that takes (`brand`, `model`, `display_name`, hero+spec+doc fields…) and generates Categories with custom-field values populated. Reduces the per-model build cost from days to hours.

Compatible-parts join is automated via the `compatible_models[]` field — merch tags each part once with the models it fits, and the model landing pages auto-populate. The most-bought list, the specs card, and the hero stat bar land with it. The reference layout is the full-hub prototype at [`v2/model-tennant-t500e.html`](../v2/model-tennant-t500e.html).

**Trigger:** Phase 1 data shows the top-20 are paying off (traffic shift + session depth) **and** `compatible_models[]` tagging is underway — the same data investment [search](search-experience-concepts.md) Phase 2 and [recently-purchased](recently-purchased-concepts.md) Phase 2 are waiting on. Sequence the tagging once for all three.

### Phase 3 — All models, self-serve, interactive

500+ model landings, fully self-serve for merch (a small admin app), with interactive parts diagrams (click → add to cart) on the highest-traffic models and personalized parts prioritization for signed-in buyers ("parts your fleet has bought before for this model first").

**Catalyst-replatform candidate.** Interactive diagrams + personalized rendering are heavy on React state; Stencil templates struggle with both at scale.

---

## Implementation notes

### URL structure & redirects

- Production URLs: `/parts/by-machine/{brand-slug}/{model-slug}/`
- Existing URLs to 301: `/parts-and-supplies/{brand-slug}/{model-slug}/` → new path
- BC redirect manager handles this; bulk-import the mapping for all migrated models
- Sitemap.xml regenerated to point to new URLs

### Content-management plan

For each model, merch needs:

**Phase 1 — bounded, ~half a day per model:**
- **OEM-provided:** hero image (PNG/JPG), operator + service manuals (PDFs), illustrated parts catalog (PDF), exploded-view diagrams (PDF)
- **USA Clean-authored:** description (1–2 paragraphs), machine-class line, video walkthroughs (USA Clean Tech Tips channel)
- **Taxonomy-derived:** related-models grid (brand-level; no parts data)

**Phase 2 — adds the catalog-scale work:**
- **OEM-provided:** spec sheet extracted into the remaining ~12 custom fields, product photography for parts
- **Auto-populated:** most-bought parts list (from order history aggregated weekly), compatible-parts grid (from `compatible_models[]` joins)

The split is the whole point of the [PD-008](decisions.md) cut: everything in the Phase 1 list is *per-model* work that finishes when the twentieth model is done. Everything in the Phase 2 list is *per-catalog* work that does not finish until ~12k SKUs are tagged.

### Compatible-parts data model

Each Product has a custom field `compatible_models` of type Multiple Choice (or comma-separated text in a single field, depending on admin convenience). Values are model handles: `tennant-t500e,tennant-t500,tennant-t300e`. The category template queries products where `compatible_models` contains the current page's handle.

For the prototype, the parts grid is hand-curated. Production needs the field populated across the ~12k parts catalog. **This is the largest content-ops task in Phase 2** — plan for a 2-3 month structured tagging effort, probably with OEM cross-reference data as the input. It is also precisely why [PD-008](decisions.md) took the parts grids out of Phase 1: binding the pilot to this effort delays every model landing page by a quarter.

### Accessibility

- The hero image carries a meaningful `alt` describing the machine ("Tennant T500e walk-behind floor scrubber with yellow control panel"). In the Phase 1 prototype the illustrative SVG carries `role="img"` plus `aria-label` to the same effect.
- The spec table (Phase 2) is a real `<dl>` (definition list) or `<table>` with `<caption>` for screen readers.
- "Buy or quote this machine" and "Shop parts for this machine" CTAs have explicit text labels.
- Doc-card thumbnails are decorative (`aria-hidden`); the doc title is the accessible label.
- `.section-head` stacks below 640px so the "more →" link cannot push the row past the viewport.

### Analytics

**Phase 1 signals** — these are what decide whether Phase 2 is worth funding, so instrument them from day one:
- Traffic shift: old URLs (post-redirect) vs. new URLs (direct + search). Should see the new URLs dominate within 30 days.
- Doc download rates per model: which models need richer documentation?
- **"Shop parts for this machine" click-through** — the Phase 1 stand-in for the parts grid. A high rate is the direct evidence that embedding the grid in Phase 2 pays for the tagging effort; a low one says the page is working as a documentation-and-service hub and the grid can wait.
- "Buy or quote this machine" CTA click-through rate: drives equipment-sales pipeline.
- "Dispatch a tech" CTA click-through: drives service-revenue attribution.
- Bounce rate and session depth vs. the old filtered-list URLs.

**Phase 2 signals** — available only once the grids are on the page:
- Conversion path: model landing → PDP → cart. Compare to model landing → bounce.
- Per-model parts-grid engagement: which parts get clicks? Feeds the most-bought weekly refresh.

---

## Catalyst / replatform candidacy

**Phase 1 + Phase 2 ship in Stencil.** Native Categories + Custom Fields + a custom category template are well-suited. The build cost is real, but it's all Stencil-native work — and the [PD-008](decisions.md) cut makes Phase 1 markedly cheaper than first scoped: four elements, ~8 custom fields, no catalog-wide tagging, roughly half a day of content per model once the template exists.

**Phase 3 is Catalyst.** Two reasons:

1. **Interactive parts diagrams** — click-a-hotspot-to-add-to-cart is React's sweet spot. Stencil can do it but the code becomes fragile at scale.
2. **Personalized parts prioritization** — sorting the parts grid by *this signed-in account's* buying history requires a server-side join between the customer's order history and the catalog. Stencil templates with JS-driven re-sort work but feel jittery; Catalyst's server components render the right order on first paint.

**Recommendation:** ship Phase 1 + 2 in Stencil. When Phase 3 starts, plan it as the first piece of a Catalyst replatform — interactive diagrams alone are not the right reason to replatform, but combined with personalization, performance demands at the top 10 models, and the eventual headless commerce strategy, they tip the scale.

---

## Sources

- [BC Help — Categories](https://support.bigcommerce.com/s/article/Categories)
- [BC Help — Adding Custom Fields](https://support.bigcommerce.com/s/article/Adding-Custom-Fields)
- [BC Help — URL Redirects](https://support.bigcommerce.com/s/article/URL-Redirects)
- [BC Stencil — Category Template](https://developer.bigcommerce.com/docs/storefront/stencil/themes/category)
- [BC Dev — Categories API](https://developer.bigcommerce.com/docs/rest-management/catalog/categories)
- [Tennant.com — model page reference (OEM)](https://www.tennantco.com/en_us/machines/scrubbers/walk-behind-scrubbers/T500e.html)
- [Sweepscrub.com — model-page filtered-parts pattern](https://www.sweepscrub.com/)
- [USAClean_Sitemap_Recommendations.md](USAClean_Sitemap_Recommendations.md) — URL structure + IA placement
- [USAClean_IA_Search_Roadmap.md](USAClean_IA_Search_Roadmap.md) — brand→model insight (100% of organic browse sessions)
- [feature-design-guidelines.md](feature-design-guidelines.md) — operating manual
- [install-repair-guides-concepts.md](install-repair-guides-concepts.md) — doc-card pattern reuse
- [decisions.md](decisions.md) — PD-008, the Phase 1 scope cut to four elements