# 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.
