01TL;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 follows the sitemap recommendation: /parts/by-machine/{brand}/{model}/ (e.g., /parts/by-machine/tennant/t500e/).
Phase 1 ships four elements (PD-008): the model info header, the documentation library, a dispatch-a-tech CTA, and related models. Those four are the subset with 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 + 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. | Higher — admin tooling + content ops (the ~12k-part tagging effort) |
| Phase 3 Future | All 500+ models. Self-serve content management. Interactive parts diagrams. Personalized "your fleet's other models" suggestions. | Highest — Catalyst-replatform candidate |
Two prototypes. model-tennant-t500e-phase1.html is the Phase 1 build — what actually ships first. 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.
02Current 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.
03References
Sweepscrub
70+ Tennant model-specific parts pages. Each 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.
Tennant.com (the OEM)
Model pages have a hero, 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.
04What 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
descriptionfield with HTML, custom-field children, and an associated set of products. - Custom Fields on the Category (BC Help) — per-model metadata:
hero_image_url,cleaning_path,tank_capacity,run_time,weight,warranty,operator_manual_url, etc. (~20 fields total). Free, native, queryable. - Category template overrides in Stencil —
templates/pages/category/{handle}.htmllets us build a custom 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 model handles it fits. The model landing queries products where the field contains the page's handle. Native; no app required. - Storefront API —
/api/storefront/categories/{id}/productsfor the parts grid, filtered server-side.
05Stencil limitations
- No native UI for the rich hero / spec card / doc grid layout. All custom theme work. The reusable composites become part of Caster. The PD-008 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" — requires an explicitalso_fitsfield or a custom service. - Diagrams as static images only. Interactive exploded-view "click a part to add" is not a Stencil feature. Phase 3 → 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. Reordering the parts grid by Maria's purchase history requires a server-side join — 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. Phase 2 needs a CSV import or small custom admin app.
- Auto-redirecting old URLs. Current
/parts-and-supplies/tennant/t500/URLs need 301 redirects to new paths. BC supports this via URL redirect manager, but at 500+ models this is bulk redirect import territory.
06App 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 apps | WYSIWYG editor for rich category pages. | Skip — drift from Caster |
| Klevu / Searchspring | Smart product filtering on category pages. | Maybe Phase 2 |
| 3D Cloud / 3DProductPlatform | Interactive parts diagrams (Phase 3). | Phase 3 only |
| Marketing-content apps (Page Builder, Shogun) | Drag-and-drop landing-page builders. | Skip — WYSIWYG drift |
07Caster impact
New patterns to promote to Caster once a second consumer exists. The PD-008 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, 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 brief) are reused here — this is the second consumer, so the pattern graduates to Caster /patterns/ now.
Stock-badge (stock-in, stock-low) usage convention from inventory-urgency brief is applied to the parts grid — Phase 2, since the grid is. Volume-badge (from volume-discount brief) appears as .mini-part__badge--volume on relevant parts — likewise Phase 2.
.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.
08Phased recommendation
Decision of record: PD-008 — Phase 1 is scoped to four elements.
Prototype: 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:
- Create a Category at
/parts/by-machine/{brand}/{model}/ - 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 - 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 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.
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 old URLs (via 301) to new ones, 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.
Two things happen at once in Phase 2: the page widens to the full hub, and the build automates.
Build admin tooling: CSV-import script taking (brand, model, display_name, hero+spec+doc fields…) and generating Categories with custom-field values populated. Per-model build cost drops 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 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 Phase 2 and recently-purchased Phase 2 are waiting on. Sequence the tagging once for all three.
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.
09Implementation 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 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). Values are model handles: tennant-t500e,tennant-t500,tennant-t300e. The category template queries products where compatible_models contains the current page's handle.
Production needs the field populated across the ~12k parts catalog. Plan for a 2–3 month structured tagging effort, probably with OEM cross-reference data as the input. This is the single largest piece of work in Phase 2 — and precisely why PD-008 took the parts grids out of Phase 1: binding the pilot to this effort delays every model landing page by a quarter.
Accessibility
- Hero image carries meaningful
alt("Tennant T500e walk-behind floor scrubber with yellow control panel"). In the Phase 1 prototype the illustrative SVG carriesrole="img"plusaria-labelto the same effect. - Spec table (Phase 2) is a real
<dl>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-headstacks 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. Should see 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: 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.
10Catalyst / 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 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:
- 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.
- Personalized parts prioritization — sorting the parts grid by this signed-in account's buying history requires a server-side join. Stencil templates with JS-driven re-sort 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.