Aetheria-Labs1/storefront-skills / skills/cart
cart
VerifiedCreate, design, compose, preview and manage Lexsis cart profiles. Edit promotion drafts, inspect readiness, and publish exact approved versions. Supports custom module state, commands and conditional visibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.1 KB |
| agents/openai.yaml | config | 404 B |
| references/cart-composition.md | markdown | 7.2 KB |
| references/cart-profile-management.md | markdown | 17.1 KB |
| references/module-authoring.md | markdown | 9.0 KB |
| references/styling-hooks.md | markdown | 7.8 KB |
references/cart-composition.md
View on GitHub# Cart Profile Composition
A cart profile is a renderer-managed surface backed by a published profile.
Custom cart interactions, batch add flows, and controls selecting multiple
products use the documented `lx:cart:add-items` renderer command.
## Page contract
Cart V2 is enabled by default for every storefront. New source omits the
deprecated `use_cart_v2` compatibility field. Existing `true` values remain
valid; `false` fails validation because Cart V2 cannot be disabled.
The page must not contain `CartDrawer`, `DrawerShell`, or cart child islands.
The renderer resolves and injects the cart after the page sections.
Resolution order:
```text
page assignment > campaign assignment > store default > legacy fallback
```
Page metadata does not select a profile.
## Profile modules
The profile snapshot owns:
- Cart mode and responsive behavior
- Ordered layout modules
- Cart sections and rules
- Free-shipping progress
- Shopify selling-plan presentation
- Manual and Shopify-powered offers
- Checkout behavior
- Cart design settings and scoped CSS
Cart lines, order summary, and checkout are required. Optional modules include
shipping progress, purchase options, payment methods, and product offers.
## Offers and subscriptions
Offer placements:
- `header`
- `after_line`
- `after_lines`
- `before_checkout`
Manual offers use Shopify product GIDs. Recommendation offers use Shopify
`RELATED` or `COMPLEMENTARY` intent.
Selling-plan options are line-item capabilities. A profile can choose cards or
a select menu, but it cannot make an ineligible product subscribable.
## Trigger protocol
Add-to-cart controls and the site header emit `cart:open`. The hydrator bridges
DOM events into the cart event bus. The injected `DrawerShell` listens for the
event and lazily hydrates its children on first open.
Use the selected island's supported cart trigger for normal product controls.
For a custom interaction that owns a dynamic product selection, use the
renderer-managed `lx:cart:add-items` command instead of hidden BuyBoxes,
programmatic clicks, or a parallel Shopify/cart mutation. This is the custom
cart and batch add contract for controls that select multiple products.
See `references/module-authoring.md` for a complete compiler-tested upsell,
including its registered add control and request-scoped state handling.
Dispatch from `section`, the `[data-cart-custom-module="<id>"]` wrapper.
Responses return to that wrapper and bubble: `lx:cart:add-items:pending`,
`:accepted`, `:confirmed`, `:success`, and `:error`. Listen on the wrapper and
filter by requestId; a listener on an authored child section will not receive
an event dispatched from its parent.
No trigger should carry or infer a profile ID.
## Styling
Page `theme_css` provides brand defaults. Cart profile design values and
`custom_css` apply only under the cart profile root.
Custom CSS is sanitized and scoped at render time. Do not put profile CSS in
page sections or page metadata. See `references/styling-hooks.md` for the full
part map and inline-style exceptions.
## Patch and module identity contract
- `custom_css` replaces all CSS, including named blocks; null clears it.
Use `css_ops` to upsert/remove named blocks without resending other blocks.
- `design_patch` is JSON Merge Patch: omitted fields remain, null removes a
stored override, arrays replace arrays. Removing an override can expose a default.
- `composition_ops.upsert` with source replaces the whole module source.
Omit source to preserve it during visibility/placement changes.
New modules honour `before_module_id` or `after_module_id` on the first upsert.
Without an explicit region, the module inherits its anchor's region,
including header and before-checkout offer placements.
- `data-module` equals the layout ID, including `offer-<uuid>` and custom IDs.
`data-module-type` equals the layout type, such as `product_offer` or `custom`.
Generated sections before `default@13` used `data-module="product-offer"`;
recompile a draft to get consistent IDs. After-line offers repeat their slot
ID under each qualifying line; use the line group to distinguish instances.
- Layout enabled flags are authoritative; offer-slot enabled flags are mirrored.
Disabled optional modules are absent. `visible_when` keeps a module mounted
with `hidden` while its cart-state predicate is false.
Built-in module DOM is identical in the sandbox and published renderer:
`[data-module="cart-lines"] [data-lx-island-runtime] > [data-part="root"]`.
The island can share its module frame or sit inside it. Use a module descendant
selector, or explicitly include the runtime wrapper in child
selectors. Gift rows follow paid rows.
Reward messages accept `{remaining}`, `{next_title}`, `{threshold}`,
`{unlocked_title}` and `{unlocked_list}`. Amounts are formatted money; unlocked
titles describe applied rewards and are empty before the first application.
`{reward_title}` is the triggering reward's title in `toast.template` only.
Use `{unlocked_title|Your rewards}` for a literal fallback, or
`{#if unlocked}{unlocked_title} unlocked. {/if}{remaining} more gets you {next_title}.`
for an optional clause. Conditional blocks cannot nest.
`compact_bar` applies state `text_color` to icons and labels and state
`border_color`/`background` to dots. Labels, icons and dots expose `data-state`.
Summary copy exposes separate `subtotal-label` and muted `subtotal-hint` spans.
Celebration particles start at the unlocked dot (or panel top). Cart scope
stays in the panel; viewport scope renders above the sheet and overlay.
Toasts fit the panel and clear close controls. Positions are `top` (below the
header), `bottom`, `above_header` (falls below the header when no space).
`toast.duration_ms` overrides the inherited celebration duration.
## Current cart workflow
The recent cart changes include paid-price reward eligibility/readiness,
page-to-cart CSS isolation, typed settings that reach the DOM, custom module
snapshots/commands/conditions, approved MCP lifecycle and promotion writes,
and compact edits with signed sample carts. The type-only component cleanup
adds no authoring API. Local source support does not upgrade an immutable
published runtime: verify the deployed capability/schema and preview.
Read `references/cart-profile-management.md` for the create, design, promotion,
preview, approved publish and rollback flow. `lexsis_cart.promotions` accepts a
profile ID alone and infers the store. Use `lexsis_discover` with
`query:"publish cart"` for up to 10 ranked results (schemas for the top 3), or
exact router/action discovery for an authoritative schema.
## Anti-patterns
| Anti-pattern | Correct behavior |
|---|---|
| Inline `DrawerShell` on a storefront page | Remove it and configure the effective profile |
| Cart selected through title or SEO metadata | Use a page assignment |
| Agent publishes a draft automatically | Review the exact draft; publish through approved `lexsis_live_ops.cart_publish` or the app |
| Fabricated products or selling plans | Use real store catalog data |
| Page-wide selectors in cart CSS | Use profile-scoped CSS |
| Hidden BuyBox plus `.click()` for a custom selection | Dispatch `lx:cart:add-items` from the registered section control |
| Direct `/cart/add.js` or Storefront API request | Let the renderer perform the managed GraphQL cart mutation |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |