---
name: skill-storefront-merchandising
type: skill
description: >-
  Pixel's commerce-design skill — score a storefront against standard-storefront,
  then design and merchandise each surface (homepage, collection, product page,
  cart and checkout, order comms) against that bar and the convention-retail
  touchpoint chain. Encodes the merchandising judgement: what to feature and
  where (hero, best-sellers, new-in, gift), collection sequencing from
  skill-retail-strategy's range tiers, cross-sell and bundle placement, how a
  thematic collection sits under its parent brand, the imagery direction per
  product page, and a seasonal or drop refresh procedure with its checklist.
  Use whenever a store needs visual or merchandising work, a new store is being
  built (BARA, Keroma, any that follows), or an existing store needs scoring.
  Hands theme specs to Forge and reusable sections to skill-brand-system;
  design and specify only, never edits theme or store data. Promoted from
  placeholder under APP-1080 / APP-1085; first full draft 2026-09-04.
license: CC BY-NC-SA 4.0
---

# storefront-merchandising

Pixel's commerce-design skill. It makes a storefront look and sell well: it scores the store against `standard-storefront`, designs each surface to clear that bar in the venture's identity, decides what is featured where, directs the imagery, and specifies the result for Forge to build. `standard-storefront` holds the bar, `convention-retail` the touchpoint chain and KPI vocabulary, `convention-shopify` the tooling and the human-action boundary, and the venture's `convention-brand` instance the look — this skill reads all four and restates none. Promoted from placeholder under APP-1085; first full draft 2026-09-04.

## Trigger

- A storefront needs visual or merchandising work: a homepage section, a collection, a product page, cart or order-comms design, or a seasonal or drop refresh.
- A new store is being built (Keroma's Printify launch, the BARA relaunch on `assoc-one/mbn-theme`) — called from `playbook-store-launch` at the storefront step.
- A store Pixel did not build needs scoring, on its own or as the App layer of a `skill-discovery-audit`.
- `skill-conversion-diagnostic` or `skill-campaign-report` names a step of the touchpoint chain that is not doing its job.

Run by Pixel for the vertical's operator (`operator-bara`; Keroma's when it gains one).

## Behaviour

Five steps; the first is the opening move on every store, new or live.

### Step 1 — Score the store against the bar

Score every surface and every check in `standard-storefront` pass / partial / fail, each finding tagged known, assumed or unknown, mapped to the `convention-audit` App categories as that standard prescribes. For a store not yet built, score the design against the bar instead and mark the trust checks unknown until there is something to run. Read the live picture through `convention-shopify`'s queries — sessions and conversion, top products, AOV — so the merchandising goal is a number at a named step of the chain, not a preference. The score is the brief: the work below fixes the fails and partials in severity order (`standard-prioritisation`), and a refresh never restarts from a blank page because the last score is the baseline.

### Step 2 — Merchandise: what goes where

Read the range tiers and collection logic from `skill-retail-strategy` (hero, core, entry, gift, limited) and the calendar it set; where no strategy exists yet, ask for one rather than inventing the tiers. Then place:

- **Homepage** — the hero slot carries the current story (a drop, a season, an edit), never a rotating carousel; one path into the range; a best-sellers or core row from the top-products query; a new-in row only while something is new; a gift entry point in the eight weeks before each gifting peak on the retail calendar.
- **Collection order** — a decision, not the default sort. Working rule: hero and current-story lines first, then core by sell-through, entry lines within the first two rows so the price band reads early, limited lines where their window is live.
- **Cross-sell and bundles** — goes-with, never more-of-the-same: on the product page below the buy area, and one line in the cart. A bundle or set appears where the customer is choosing between singles. AOV levers are `convention-retail`'s; place them one at a time so `skill-campaign-report` can read the effect.
- **Thematic collections** — a seasonal edit, collaboration or drop sits under the parent brand with its own name, window and lead imagery, and the parent's voice, palette, card anatomy and price band. Its own template is a fail; its own hero is expected.
- **Order comms** — the transactional emails and the account page carry the same voice and imagery as the store; the copy is Reach's via `skill-content-studio`, the layout is here.

### Step 3 — Design each surface

Design homepage, collection, product page, cart and checkout configuration, account and order status, search and navigation, and the empty states, each to the anatomy and bar in `standard-storefront`, in the venture's identity per `convention-brand` and `convention-aesthetic`, on the design system where one exists (`skill-brand-system`; BARA's is in progress, so mark what is designed ahead of the system). Mobile first, then desktop. For Shopify the checkout is the platform's and is designed as configuration only.

### Step 4 — Direct the imagery

For every product, specify the PDP minimum set from `standard-storefront` (hero, packshot, detail, lifestyle, scale, in that order) and the consistency rules — one ground and lighting recipe per shot type, one crop ratio per slot. Working ratio across a collection: lifestyle-led heroes on cards and the homepage, packshot-led galleries on the product page, so the range compares and the brand argues. Where the set does not exist, file the photography need as a brief via `skill-creative-brief` or to `skill-visual-production`; never lower the bar to fit the assets. Alt text follows the shared-asset rule in `convention-shopify`: describe the frame, never the product name.

### Step 5 — Specify and hand off

- **To Forge** — a build-ready spec per Shopify section and template: the section, its settings, the data it reads (collection handles, metafields, tags), and the states (empty, out-of-stock, variant change). Theme code lives in the theme repo and is built by Forge and reviewed by Prism (`convention-shopify`); the spec is filed as a ticket per `convention-ticket`, never applied through the connector. For Keroma, the spec names the Printify variant data the product template reads (variant axes, mockup images, production lead time on the product page).
- **To `skill-brand-system`** — any section designed here that the next store or page could reuse (card anatomy, review block, drop banner), so the design system grows from the storefront rather than beside it.
- **To the operator** — product-data needs (missing dimensions, materials, care, lead time) as a list against the products, since store data is the connector's and the operator's.
- **To Reach** — the merchandising placements and the calendar slots they serve, so `skill-lifecycle`, `skill-newsletter` and `skill-launch-campaign` point at the pages this skill built.

## Seasonal and drop refresh

A refresh is a bounded pass, not a redesign. Checklist, in order:

- [ ] Re-score the surfaces the refresh touches (Step 1); note anything that regressed since the last score.
- [ ] Read the calendar slot from `skill-retail-strategy` and the launch brief from `skill-launch-campaign`: what is the story, what is featured, for how long.
- [ ] Homepage hero, the current-story row and the collection order updated for the window; the previous story retired, not stacked beneath.
- [ ] New lines carry the full imagery set before they are placed; a line without it launches in the grid only, never in the hero.
- [ ] Gift entry point on or off according to the calendar.
- [ ] Empty states and out-of-stock messaging checked against lines that will sell out (a dated drop should end cleanly, on-voice).
- [ ] Spec to Forge filed as one refresh ticket; nothing changed through the connector; the go-live is the operator's.
- [ ] An end-of-window note: what returns to the standing merchandising, and when.

## Reads and feeds

Reads: `standard-storefront`, `convention-retail`, `convention-shopify`, the venture's `convention-brand` instance and `convention-aesthetic`, `skill-retail-strategy`'s range tiers and calendar, live analytics and product data, the design system and Figma library. Feeds: Forge (theme specs), `skill-brand-system` (reusable sections), `skill-discovery-audit` (the scored inventory), `skill-lifecycle`, `skill-newsletter` and `skill-launch-campaign` (placements and pages), `skill-packaging-unboxing` (the imagery system carries through to the parcel).

## Guardrails

- On-brand and on-system; merchandising serves the KPI without cheapening the look — no dark patterns, no manufactured urgency, no pre-ticked upsells (`standard-storefront`). A real dated drop is on-voice for BARA; a countdown timer is not.
- Design and specify only. Theme code is Forge's, store data is the connector's and the operator's; this skill edits neither. Going live is the operator's hand (`convention-shopify`).
- Scores what is observable and marks the rest unknown; never fills a score.
- Never invents product facts, dimensions, lead times or prices; flags the gap to the operator.
- Never lowers the imagery bar to fit the assets available; files the photography need instead.
- One store per run; a thematic collection never becomes a second brand.
- Propose-only.

## Setup

Run on demand by Pixel from an operator brief, a `playbook-store-launch` step, or a scored finding. Not scheduled. Surface: Figma and Cowork with the Shopify connector read-only; no repo access (`agent-pixel`). On finish, run `skill-ops-retro` capture on this run's friction: file a `FRICTION:` note to the Pulse queue for the drain to assess.

Owned by Pixel (P1-XEL).
