@orderlyshop/web-components 0.1.0-build.7067 → 0.1.0-build.7075

package/AGENTS.md

@@ -5,40 +5,26 @@ Use this package as a headless storefront component library. Prefer native custo
 ## Agent Operating Contract
 
 - These instructions are optimized for GPT-5.5-class coding agents and other modern LLMs. Work from the user's requested storefront outcome, choose the package-owned component or CLI that owns that outcome, and keep edits scoped to that path.
-- Read stable package context before shop-specific files: `README.md`, `DESIGN.md`, component docs, then `custom-elements.json` or `html-custom-data.json` for exact API names. Inspect the consuming shop after that.
 - Prefer package configuration, typed properties, declarative templates, semantic tokens, and package CLI tools over copying component internals into a shop.
 - Do not infer attribute names, event names, template slots, or CSS hooks from memory. Use the docs and metadata in this package as the source of truth.
-- Stop when the requested behavior is implemented and verified with the nearest relevant script. If validation needs data, account ids, credentials, or a running backend, report the exact missing prerequisite.
-
-## Discovery
-
-- Read `README.md` for setup and package-wide concepts.
-- Read `DESIGN.md` before changing the visual theme. It defines the semantic design tokens that should be changed first.
-- Read `docs/components/README.md` for component APIs.
-- Read `docs/shop-best-practices.md` before building or heavily customizing a shop. Use it as the checklist for moving from the scaffold to a branded, editorial storefront while preserving package-owned components.
-- Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before implementing product listing UI.
-- Read `custom-elements.json` for machine-readable custom element metadata.
-- Read `html-custom-data.json` when generating vanilla HTML or configuring editor autocomplete.
-- Inspect `examples/shop` for a complete vanilla TypeScript shop that customizes the defaults without replacing package logic.
-- When creating a new shop from scratch, run `npx orderly-init-shop` first. It scaffolds the vanilla HTML/TypeScript/Vite structure that the package expects, including `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, page templates, and package scripts.
-
-## New Shop Intake
-
-- Ask the user for the Orderly account id so `src/shop-query.ts` can tenant-scope the default `SearchQuery`.
-- Ask the user for a reference website URL for the desired visual style. If they do not have one, ask for a short description of the target look.
-- Use the reference website as design direction only: extract palette, density, radius, typography feel, spacing, and navigation patterns into semantic Orderly tokens and shop CSS. Do not copy proprietary assets, text, logos, or brand marks unless the user confirms they own or may use them.
-- Do not deliver a shop that mostly looks like the package default with minor token changes. The default scaffold is a functional baseline, not the creative target.
-- Inspect the product catalog and use online research when available to understand the shop, category, product type, audience, competitors, and current visual conventions before committing to a design direction.
-- Build a distinctive first version: homepage and category pages should combine package components with shop-owned editorial sections, catalog-driven product groupings, contextual copy, category storytelling, and imagery or content choices that make the shop feel specific.
-- Use `docs/shop-best-practices.md` as the practical standard for the first version, especially when deciding what belongs in shop CSS/config/slots versus custom component logic.
-- Research current high-end frontend execution before finalizing when network access is available. Aim for the technical polish expected from premium product marketing sites: responsive art direction, strong imagery, smooth interaction states, thoughtful motion where appropriate, performance, and accessibility. Use this as a quality bar, not as permission to copy a specific site.
-- Put the resulting theme in `src/style.css` or the consuming shop stylesheet, starting with `DESIGN.md` tokens before adding component-specific selectors.
-- After scaffolding, run the nearest local dev/build command and visually compare the shop against the requested reference at desktop and mobile widths when a browser is available.
+- Stop only when the behavior is implemented, verified with the nearest relevant script, and visually inspected in a browser when available. If validation needs data, account ids, credentials, a browser, or a running backend, report the exact missing prerequisite.
+
+## Required Reading and Intake
+
+- Read `README.md`, `DESIGN.md`, `docs/shop-best-practices.md`, `docs/components/README.md`, then `custom-elements.json` or `html-custom-data.json` before shop-specific edits. Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before product listing work.
+- Use `docs/shop-best-practices.md` as the completion checklist for branded shop work. A finished shop must not look like the default scaffold with minor token changes.
+- For new shops, run `npx orderly-init-shop` first. Ask for the Orderly account id, legal webshop owner name, legal owner CVR, and a reference website URL; if no reference exists, ask for a short style description.
+- Set `defaultShop.legalOwnerName` and `defaultShop.legalOwnerCvr`. `orderly-page-layout` renders the required ownership notice after footer content, and shop templates must not replace it.
+- Use the account id for tenant-scoped `src/shop-query.ts`. Use the reference, catalog inspection, and online research as design direction for `src/style.css`; never copy proprietary assets, text, logos, or brand marks without user confirmation.
+- Build the first version around catalog-driven content: homepage sections, category introductions, product context, useful navigation, and a visual system based on `DESIGN.md` tokens plus scoped CSS.
+- Aim for current premium frontend craft: responsive art direction, strong imagery, clear interaction states, appropriate motion, performance, and accessibility.
+- Before reporting completion, run the local dev/build command and visually inspect homepage, category, product, basket, and checkout on desktop and mobile when a browser is available.
 
 ## Query Rules
 
 - Use `configureShop({ defaultShop: { defaultQuery } })` for shop-wide query scope. `defaultQuery` is a full Core `SearchQuery`.
 - Do not create package-specific account id shortcuts. Tenant scoping is just `SearchQuery.SourceAccountId`.
+- Read `docs/search-syntax.md` before writing category or rail queries. Whitespace in `SearchQuery.Query` is narrowing; use `|` for OR alternatives such as `lego | matchbox | playmobil`. Multiple `SearchQuery.Tags` are narrowing AND-style filters, not broad alternatives.
 - For simple markup-driven searches, use declarative query attributes:
   - `keywords` maps to `SearchQuery.Query`.
   - `tags` maps to `SearchQuery.Tags`.
@@ -56,32 +42,25 @@ Use this package as a headless storefront component library. Prefer native custo
 
 ## Implementation Defaults
 
-- Keep components headless. Add behavior and default light-DOM markup, not bundled theme CSS.
-- Start theme work from the semantic tokens in `DESIGN.md`. Use component-local selectors and hooks only for deliberate exceptions after the shared tokens are set.
-- Treat visual differentiation as part of the implementation, not a later polish task. Configure package components, slots, templates, and shop CSS so the first working shop already matches the design target as closely as possible.
-- Prefer shop-owned editorial page sections around package components over replacing package templates wholesale. Preserve package-owned product tiles, checkout, product detail behavior, image viewers, structured data, accessibility, and generated URLs unless the user explicitly asks for a different structure.
+- Keep components headless. Prefer configuration, typed properties, templates, slots, semantic tokens, and scoped shop CSS over copying package internals.
+- Start theme work from `DESIGN.md`. Visual differentiation is part of the first implementation, not later polish.
+- Add shop-owned editorial sections around package components. Preserve package-owned product tiles, checkout, product detail behavior, image viewers, structured data, accessibility, and generated URLs unless the user explicitly asks for a different structure.
 - Built-in UI copy defaults to Danish. Use `configureShop({ uiLanguage: "EN" })` for English shops, and prefer shop attributes/templates for wording that is unique to one storefront.
-- Preserve template override support through `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`.
-- Put shop-wide templates in a shared document-level registry, for example template files included from `body-start.html`, using `data-orderly-template` plus `data-orderly-for`.
-- Keep browser-only package code free of Node HTTP modules.
-- Do not store tokens, API keys, OAuth responses, or cookie values.
-- Use `configureShop({ consent })` before enabling optional analytics, marketing, personalization, or shop-owned cookies. Keep cookie/vendor/purpose/duration text accurate for the specific shop, and use `setOrderlyCookie()` or `hasCookieConsent()` for custom optional browser state instead of writing cookies directly.
-- Treat localStorage basket and checkout profile data as user-owned state. Do not add secret persistence.
+- Preserve `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`. Put shared templates in a document-level registry using `data-orderly-for`.
+- Keep browser code free of Node HTTP modules. Do not store tokens, API keys, OAuth responses, cookie values, or other secrets.
+- Use `configureShop({ consent })` before enabling optional analytics, marketing, personalization, or shop-owned cookies. Use `setOrderlyCookie()` or `hasCookieConsent()` for optional browser state.
+- Treat localStorage basket and checkout profile data as user-owned state.
 - Product images should default to `fit="contain"`, white background, and square aspect ratio in product tiles.
 - Use `orderly-stored-image` for package/product images when possible and set the appropriate `image-role` (`product-tile`, `product-detail`, `thumbnail`, `basket-line`, `checkout-line`, or `fullsize`) so image URLs reuse configured CDN dimensions.
 - Product grids should support continuation-token based dynamic paging without requiring a visible load-more button.
-- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code. Set `basket-mode="inline-desktop"` when the design needs a package-owned desktop basket rail instead of custom portal glue.
+- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code. Use its `hero` slot/template for a custom homepage hero before replacing the full layout. Set `basket-mode="inline-desktop"` when the design needs a package-owned desktop basket rail instead of custom portal glue.
 - Use `orderly-category-page` for category routes. Default category links should use `/categories/<category-path>/` so builds can generate and hydrate server-rendered category pages. Use `/category.html#id=<encoded-category-path-or-slug>` only for shops that explicitly opt into hash routing. Prefer navigation `heroImage`, `heroLayout: "covers"`, `heroCoverCount`, and category `description` before replacing the category hero template.
 - Keep `orderly-navigation` sticky by default. Use `sticky="false"` only when a shop intentionally wants navigation to scroll away. Use `persist-state state-key="main-menu"` for vertical desktop menus that should remember open branches, and use `slot="menu-before"`/`slot="menu-after"` for store finder, campaign, volunteer, or other menu promo links.
-- Use `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>` for a package-owned mobile cart/checkout button with count before building a shop-specific fixed basket badge.
-- Use `orderly-checkout-page` for checkout pages instead of wiring `orderly-checkout` and `orderly-basket` manually in app code.
+- Use package-owned basket and checkout surfaces first: `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>`, `basket-mode="inline-desktop"`, and `orderly-checkout-page`.
 - Use `orderly-product-detail-page` for full product routes. Set `share-url` to the product `SearchObject.ShareURL.URL`; the component loads the product through `SearchQuery.ShareUrl`.
-- Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend.
+- Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend. Treat warnings about category pages or homepage rails matching 0 products as blockers; use `--strict-empty-categories` in CI when empty categories should fail the build.
 - For real product URLs on traditional hosting, use the package-owned helpers in `server/`: Apache `.htaccess`, Nginx rewrite config, PHP product renderer, and optional Node product snapshot endpoint. Do not copy this logic into example-shop.
-- Use `navigation.ts` for shop category/navigation structure. Export `navigationDefinitions: NavigationDefinition[]`.
-- Use `npx orderly-init-navigation` to create the default file or `npx orderly-init-navigation --suggest --account-id <account-id>` to dump sampled product data for agent-assisted navigation design.
-- Navigation definitions are recursive but should stay at most two category levels deep for normal shops. Each item must include `label` and a stable globally unique `slug`, and can include optional `heroImage`, optional `heroLayout`, optional `heroCoverCount`, optional `description`, optional `query`, and optional `children`.
-- Use plain `SearchQueryInput` objects in navigation definitions, for example `query: { query: "sko sneakers", tags: ["sko"] }`.
+- Use `navigation.ts` for category/navigation structure. Run `npx orderly-init-navigation --suggest --account-id <account-id>` when sampling helps, then read `querySyntax` and `navigationSuggestions` in `navigation-products.json` before exporting `navigationDefinitions: NavigationDefinition[]` with stable unique slugs, at most two levels, optional hero/content fields, and plain `SearchQueryInput` values such as `query: { query: "sko | sneakers" }` or `query: { query: "kjole | sommerkjole", tags: ["dametøj"] }`.
 
 ## Common Patterns
 
@@ -92,8 +71,8 @@ Declarative product rail:
   title="Sko"
   cta-label="Se alle"
   cta-href="/categories/sko/"
-  keywords="H&M"
-  tags="børnetøj,bluser">
+  keywords="sneakers | støvler | sandaler"
+  tags="sko">
 </orderly-product-rail>
 ```
 
@@ -102,8 +81,8 @@ Structured query markup:
 ```html
 <orderly-product-rail title="Sko">
   <query>
-    <tags>børnetøj,bluser</tags>
-    <keywords>H&M</keywords>
+    <tags>sko</tags>
+    <keywords>sneakers | støvler | sandaler</keywords>
     <order-by>CreatedTime desc</order-by>
   </query>
 </orderly-product-rail>
@@ -116,7 +95,7 @@ import { create } from "@bufbuild/protobuf";
 import { SearchQuerySchema } from "@orderlyshop/core-client";
 
 productRail.query = create(SearchQuerySchema, {
-  Query: "H&M",
+  Query: "sneakers | støvler | sandaler",
   OrderBy: ["CreatedTime desc"]
 });
 ```
@@ -131,7 +110,7 @@ Standalone browser setup:
     uiLanguage: "DA",
     defaultShop: {
       navigationDefinitions: [
-        { label: "Sko", slug: "sko", query: { query: "sko sneakers" } }
+        { label: "Sko", slug: "sko", query: { query: "sko | sneakers" } }
       ]
     }
   });

package/DESIGN.md

@@ -0,0 +1,224 @@
+# Design Contract
+
+This file is the source of truth for theming `@orderlyshop/web-components`.
+
+If a shop, coding agent, or LLM needs to restyle the package, start here before touching component selectors.
+
+## Rules For Agents And LLMs
+
+1. Keep design work outcome-first: produce a coherent shop theme with the smallest token and selector changes that satisfy the requested visual behavior.
+2. Set semantic design tokens first. Override them on `:root`, `html`, `body`, `orderly-page-layout`, or another shop shell element.
+3. Do not start by hunting through `.orderly-*` selectors. Component selectors are for deliberate exceptions, not for the base theme.
+4. Treat `--orderly-color-accent` and `--orderly-color-accent-soft` as legacy compatibility aliases. New themes should set `--orderly-color-primary`, `--orderly-color-primary-soft`, and `--orderly-color-primary-contrast`.
+5. If a color change should apply to buttons, badges, selection states, navigation hovers, and CTA links, change the semantic tokens below instead of patching each component separately.
+6. If shape changes should apply to tiles, panels, inputs, buttons, and icon buttons, change the radius tokens below instead of hardcoding `border-radius` on component selectors.
+7. Use component-specific selectors only when the token system cannot express the requested exception. Keep that exception scoped to the component and avoid redesigning unrelated surfaces.
+
+Package defaults are intentionally declared with `:where(:root)` so they have zero selector specificity. A shop-level `:root { --orderly-color-primary: ... }` is therefore authoritative even if the package CSS is injected later by `defineOrderlyWebComponents()`. Do not repeat token overrides on `body` just to win the cascade; use `body` or a shell element only when you deliberately want a narrower theme scope.
+
+## Reference Website Workflow
+
+When an agent or LLM builds a new shop, ask for a reference website URL before choosing the visual style. Inspect the reference for reusable design direction:
+
+- foundation palette and contrast
+- action, badge, link, and selection colors
+- shape language and radius scale
+- spacing density and page rhythm
+- header, navigation, card, product tile, and checkout surface patterns
+
+Translate those observations into this package's semantic tokens and the shop stylesheet. Keep the result recognizably aligned with the reference, but do not copy proprietary assets, copy, logos, or brand marks unless the user explicitly confirms they own or may use them.
+
+## Token Layers
+
+### Foundation Tokens
+
+Use these for the base palette:
+
+- `--orderly-color-primary`
+- `--orderly-color-primary-soft`
+- `--orderly-color-primary-contrast`
+- `--orderly-color-text`
+- `--orderly-color-muted`
+- `--orderly-color-border`
+- `--orderly-color-surface`
+- `--orderly-color-surface-muted`
+- `--orderly-color-page`
+- `--orderly-color-danger`
+
+`--orderly-color-accent` and `--orderly-color-accent-soft` still exist, but they now default to the primary tokens and should not be the first place new themes start.
+
+### Semantic Interaction Tokens
+
+Use these when the shop wants a coherent interactive theme:
+
+- `--orderly-link-accent-color`
+- `--orderly-selection-border`
+- `--orderly-selection-background`
+- `--orderly-badge-background`
+- `--orderly-badge-color`
+- `--orderly-action-primary-background`
+- `--orderly-action-primary-border`
+- `--orderly-action-primary-color`
+- `--orderly-action-primary-hover-background`
+- `--orderly-action-primary-hover-border`
+- `--orderly-action-primary-hover-color`
+- `--orderly-action-primary-hover-shadow`
+- `--orderly-action-secondary-background`
+- `--orderly-action-secondary-border`
+- `--orderly-action-secondary-color`
+- `--orderly-action-secondary-hover-background`
+- `--orderly-action-secondary-hover-border`
+- `--orderly-action-secondary-hover-color`
+- `--orderly-action-secondary-hover-shadow`
+- `--orderly-focus-ring`
+- `--orderly-focus-outline`
+
+These tokens drive the default styles for:
+
+- primary actions such as product tile add-to-basket, product page add-to-basket, checkout submit, and basket checkout
+- secondary actions such as close buttons, expand buttons, and outlined remove/toggle actions
+- navigation hover states, inline CTA links, hero eyebrows, and footer links
+- basket count badges and other count/status pills
+- selected thumbnails, selected checkout options, and form/radio focus states
+
+### Radius Tokens
+
+Use the radius scale to define the shop's shape language:
+
+- `--orderly-radius-none`
+- `--orderly-radius-xs`
+- `--orderly-radius-sm`
+- `--orderly-radius-md`
+- `--orderly-radius-lg`
+- `--orderly-radius-pill`
+
+Use semantic radius tokens for components. This keeps related UI aligned while still allowing smaller elements to use smaller radii than large panels:
+
+- `--orderly-radius-card`: product tiles, basket/order lines, checkout option cards, and other card-like rows
+- `--orderly-radius-panel`: checkout cards, payment/result cards, dialogs, empty states, and larger panels
+- `--orderly-radius-control`: default control radius foundation
+- `--orderly-radius-control-sm`: compact skeletons and small control details
+- `--orderly-radius-button`: primary and secondary buttons, CTA links, and add-to-basket controls
+- `--orderly-radius-icon-button`: square icon buttons such as search, basket, burger menu, and close controls
+- `--orderly-radius-input`: text inputs, selects, search inputs, and quantity controls
+- `--orderly-radius-image`: small image frames inside basket/order summaries
+- `--orderly-radius-indicator`: active navigation indicators and other pill indicators
+
+Compatibility aliases still exist:
+
+- `--orderly-radius` defaults to `--orderly-radius-sm`
+- `--orderly-icon-button-radius` defaults to `--orderly-radius-icon-button`
+
+### Layout Tokens
+
+These are not color tokens, but they are part of the default design contract and should be preferred over ad hoc layout overrides:
+
+- `--orderly-content-max-width`
+- `--orderly-section-gap`
+- `--orderly-item-gap`
+- `--orderly-control-height`
+- `--orderly-icon-button-size`
+- `--orderly-product-grid-gap`
+- `--orderly-product-grid-item-min-width`
+- `--orderly-product-tile-border`
+- `--orderly-product-tile-radius`
+- `--orderly-product-tile-background`
+- `--orderly-product-tile-shadow`
+- `--orderly-product-tile-hover-border-color`
+- `--orderly-product-tile-image-background`
+- `--orderly-product-tile-body-padding`
+- `--orderly-product-tile-title-color`
+- `--orderly-product-tile-title-font-weight`
+- `--orderly-product-tile-price-color`
+- `--orderly-product-price-color`
+- `--orderly-product-rail-header-padding`
+- `--orderly-product-rail-title-font-size`
+- `--orderly-product-rail-cta-color`
+- `--orderly-collection-hero-height`
+- `--orderly-collection-hero-background`
+- `--orderly-collection-hero-color`
+- `--orderly-collection-hero-image-opacity`
+- `--orderly-collection-hero-cover-shadow`
+- `--orderly-checkout-card-border`
+- `--orderly-checkout-card-radius`
+- `--orderly-checkout-card-background`
+- `--orderly-checkout-card-shadow`
+- `--orderly-checkout-option-border`
+- `--orderly-checkout-option-background`
+- `--orderly-checkout-option-selected-border`
+- `--orderly-checkout-option-selected-background`
+- `--orderly-checkout-option-selected-shadow`
+
+## Recommended Styling Workflow
+
+When building a new shop or retheming an existing one:
+
+1. Set the foundation palette.
+2. Set the semantic interaction tokens so buttons, badges, links, and selection states stay aligned.
+3. Set the radius scale and semantic radius tokens so tiles, checkout surfaces, buttons, inputs, and icon buttons share one shape system.
+4. Review the shop.
+5. Only then use component-specific hooks such as navigation or product-grid variables for intentional deviations.
+
+## Example: Green Theme
+
+```css
+:root {
+  --orderly-color-primary: #1f7a43;
+  --orderly-color-primary-soft: #e7f4eb;
+  --orderly-color-primary-contrast: #ffffff;
+
+  --orderly-link-accent-color: var(--orderly-color-primary);
+  --orderly-selection-border: var(--orderly-color-primary);
+  --orderly-selection-background: var(--orderly-color-primary-soft);
+  --orderly-badge-background: var(--orderly-color-primary);
+  --orderly-badge-color: var(--orderly-color-primary-contrast);
+
+  --orderly-action-primary-background: var(--orderly-color-primary);
+  --orderly-action-primary-border: var(--orderly-color-primary);
+  --orderly-action-primary-color: var(--orderly-color-primary-contrast);
+  --orderly-action-primary-hover-background: #166338;
+  --orderly-action-primary-hover-border: #166338;
+  --orderly-action-primary-hover-color: #ffffff;
+  --orderly-action-primary-hover-shadow: inset 0 -3px 0 rgba(0, 0, 0, 0.22);
+
+  --orderly-action-secondary-background: #ffffff;
+  --orderly-action-secondary-border: var(--orderly-color-primary);
+  --orderly-action-secondary-color: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-background: #dff0e5;
+  --orderly-action-secondary-hover-border: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-color: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-shadow: inset 0 -3px 0 rgba(31, 122, 67, 0.14);
+
+  --orderly-focus-ring: 0 0 0 3px rgba(31, 122, 67, 0.24);
+  --orderly-focus-outline: 3px solid rgba(31, 122, 67, 0.34);
+
+  --orderly-radius-sm: 4px;
+  --orderly-radius-md: 10px;
+  --orderly-radius-lg: 14px;
+  --orderly-radius-card: var(--orderly-radius-md);
+  --orderly-radius-panel: var(--orderly-radius-lg);
+  --orderly-radius-control: var(--orderly-radius-md);
+  --orderly-radius-button: var(--orderly-radius-control);
+  --orderly-radius-icon-button: var(--orderly-radius-control);
+  --orderly-radius-input: var(--orderly-radius-control);
+  --orderly-radius-image: var(--orderly-radius-sm);
+}
+```
+
+That one block is enough to restyle color and shape consistently without editing component markup or package CSS.
+
+## Component-Specific Hooks
+
+Component-specific variables still exist and are useful, but they are a second step.
+
+Examples:
+
+- navigation active states: `--orderly-navigation-indicator-color`, `--orderly-navigation-link-active-background`, `--orderly-navigation-link-active-color`, `--orderly-navigation-link-padding`
+- product tile surfaces: `--orderly-product-tile-background`, `--orderly-product-tile-border`, `--orderly-product-tile-radius`, `--orderly-product-tile-shadow`, `--orderly-product-tile-image-background`
+- product rail headers: `--orderly-product-rail-header-padding`, `--orderly-product-rail-title-font-size`, `--orderly-product-rail-cta-color`
+- category hero covers: `--orderly-collection-hero-background`, `--orderly-collection-hero-color`, `--orderly-collection-hero-image-opacity`, `--orderly-collection-hero-cover-shadow`
+- checkout cards/options: `--orderly-checkout-card-*`, `--orderly-checkout-option-*`
+- product grid: `--orderly-product-grid-gap`, `--orderly-product-grid-item-min-width`
+- page layout: `--orderly-content-max-width`
+
+Use these only when a specific component should differ from the shared design system.