From 162ba0b5705d396b9c2762537c815268ec22b7e3 Mon Sep 17 00:00:00 2001
From: GitHub Copilot <copilot@example.com>
Date: Sat, 15 Aug 2026 13:00:56 +0200
Subject: [PATCH] [DOC] skills: update odoo-javascript skill documentation

---
 .claude/skills/odoo-javascript/SKILL.md       |   2 +-
 .claude/skills/odoo-web-design/SKILL.md       | 182 +++++++++++++
 .../references/accessibility.md               | 245 ++++++++++++++++++
 .../references/css-architecture.md            | 160 ++++++++++++
 .../references/finish-checklist.md            |  96 +++++++
 .../odoo-web-design/references/responsive.md  | 191 ++++++++++++++
 6 files changed, 875 insertions(+), 1 deletion(-)
 create mode 100644 .claude/skills/odoo-web-design/SKILL.md
 create mode 100644 .claude/skills/odoo-web-design/references/accessibility.md
 create mode 100644 .claude/skills/odoo-web-design/references/css-architecture.md
 create mode 100644 .claude/skills/odoo-web-design/references/finish-checklist.md
 create mode 100644 .claude/skills/odoo-web-design/references/responsive.md

diff --git a/.claude/skills/odoo-javascript/SKILL.md b/.claude/skills/odoo-javascript/SKILL.md
index f9e8489..7afdccb 100644
--- a/.claude/skills/odoo-javascript/SKILL.md
+++ b/.claude/skills/odoo-javascript/SKILL.md
@@ -10,7 +10,7 @@ metadata:
 ## Style and conventions
 - ES6+ (`let`/`const`, arrow functions). Linting with ESLint (`.eslintrc.js` at root).
 - Odoo pattern: AMD modules (`odoo.define`).
-- **No business logic in JS, only UI and events.** Business logic lives in Python.
+- **No business logic in JS (pricing rules, stock/availability decisions, permission checks)** — these belong in Python. JS handles only rendering, DOM events, and calling Python endpoints via `ajax.jsonRpc`.
 - Comments to explain hacks or workarounds.
 
 ## Key patterns
diff --git a/.claude/skills/odoo-web-design/SKILL.md b/.claude/skills/odoo-web-design/SKILL.md
new file mode 100644
index 0000000..25d3c68
--- /dev/null
+++ b/.claude/skills/odoo-web-design/SKILL.md
@@ -0,0 +1,182 @@
+---
+name: odoo-web-design
+description: Professional finish for the Odoo frontend of this repo — visual polish, responsive layout and WCAG accessibility across CSS, QWeb/HTML and JS. Use when styling or reviewing website/portal pages (website_sale_aplicoop), adding UI components, or fixing responsive/a11y/design-consistency issues.
+metadata:
+    type: reference
+---
+
+# Web design & finish (Odoo 18 frontend)
+
+Covers the three layers together: `static/src/css/`, `static/src/js/`, and the QWeb templates in
+`views/*.xml`. For language-level conventions see `odoo-qweb-html`, `odoo-javascript`,
+`odoo-xml-views`; this skill is about the **finish**: does it look designed, does it work at 320 px,
+does it work without a mouse.
+
+## Inherited non-negotiables
+
+- No logic in QWeb — prepare everything in the controller.
+- No business logic in JS — UI and events only.
+- **No inline `style="..."`** in templates. A style needs a class, and the class needs a token.
+- Every user-visible string is translatable (see §4).
+
+## 1. Work order
+
+Never start by editing a component. Always:
+
+1. **Audit** with the commands in §7. Write down what is inconsistent before touching anything.
+2. **Tokens first** (`base/variables.css`). Every value a component needs must already exist as a token.
+3. **Component by component**, one file each, media queries co-located at the bottom of that file.
+4. **Accessibility pass** per template, top to bottom.
+5. **Verify** — lint, contrast, keyboard-only, 320 px, 200 % zoom.
+
+Doing 3 before 2 is how a codebase ends up with 61 `!important` and three shades of the same blue.
+
+## 2. Design tokens
+
+Odoo 18 ships Bootstrap 5.3 with `$variable-prefix: ''`
+(`/media/snt/data/odoo/ocb/addons/web/static/src/scss/bootstrap_overridden.scss:51`), so Bootstrap's
+root custom properties are emitted **unprefixed** into `web.assets_frontend` (via
+`import_bootstrap.scss` → `@import "root"`). Available in plain CSS, no SCSS needed:
+
+```
+--primary --secondary --success --danger --warning --info --light --dark
+--body-color --body-bg --emphasis-color --secondary-bg --tertiary-bg --border-color
+--border-radius --border-radius-sm --border-radius-lg --border-radius-xl --border-radius-pill
+--link-color --link-hover-color --focus-ring-color --focus-ring-width
+--box-shadow --box-shadow-sm --box-shadow-lg --font-sans-serif --gray-100 … --gray-900
+```
+
+Rules:
+
+- **Alias, don't copy.** `--ac-color-primary: var(--primary, #007bff);` keeps the website theme
+  editor in control of the palette. A hardcoded brand hex breaks theming silently.
+- **Hex literals live only in `base/variables.css`.** A hex anywhere else is a defect.
+- **Prefix new tokens** (`--ac-…`, aplicoop). Bare names like `--primary-color` sit in Bootstrap's
+  unprefixed namespace and will collide as Odoo adds tokens.
+- **Never redefine a token inside a media query** to shrink it — use `clamp()` so it scales
+  continuously instead of jumping at one width.
+- Space and radius come from the scale, never from a typed-in number. If you need a value the scale
+  doesn't have, the scale is wrong — fix the scale.
+
+## 3. Responsive
+
+- **Mobile-first, `min-width` only.** Bootstrap 5 breakpoints exclusively: **576 / 768 / 992 / 1200 /
+  1400**. No 480/720/1600 one-offs — a private breakpoint is a design decision nobody else knows about.
+- **One range per rule.** Pairing `min-width` and `max-width` to carve a band is almost always a
+  symptom of desktop-first thinking leaking in.
+- **Media queries belong with their component**, at the bottom of its file. A central
+  `responsive.css` drifts out of sync with the components it overrides and forces `!important`.
+  Don't add to it; empty it as you touch each component.
+  If a rule in `responsive.css` spans multiple components or has no clear owner, move it to the
+  relevant layout partial (e.g. `layout/grid.css`) rather than duplicating it per component; note
+  any such moves in the audit output.
+- **Prefer intrinsic layout to breakpoints**: `repeat(auto-fill, minmax(min(100%, 16rem), 1fr))`,
+  `clamp()`, `flex-wrap`. Most grids need zero media queries.
+- `rem` for everything; `px` only for hairlines, borders and shadow offsets.
+- Touch targets: **24×24 px is the AA floor** (WCAG 2.2 §2.5.8); **44×44 px is §2.5.5, level AAA**,
+  and the size a thumb actually needs — apply it under `@media (pointer: coarse)`. Quantity steppers
+  and icon buttons are the usual offenders.
+- Must survive **320 px wide** and **200 % zoom** with no horizontal scroll.
+
+Details and recipes: `references/responsive.md`.
+
+## 4. Accessibility — WCAG 2.2 AA baseline
+
+- **Semantics before ARIA**: `<button>`, `<nav>`, `<ul>`, `<label for>`. ARIA only when no element
+  expresses the meaning. A `<div onclick>` is never acceptable.
+- **Contrast**: 4.5:1 body text, 3:1 for ≥24 px (or bold ≥19 px), 3:1 for form-control borders,
+  icon-only buttons and focus rings.
+- **Focus**: never `outline: none` without a replacement. Style `:focus-visible`, not `:focus` — the
+  latter also fires on mouse click and gets removed out of frustration.
+- Every input has a real `<label>`. A placeholder is not a label.
+- Icon-only control → translatable `aria-label`, or `.visually-hidden` text (Bootstrap ships the class).
+- Dynamic updates (cart total, quantity, result count) → `aria-live="polite"` region.
+- Images: meaningful `alt`, or `alt=""` when decorative. Never omit the attribute.
+- Status is never conveyed by colour alone — pair it with text or an icon.
+- Every animation you add needs a `@media (prefers-reduced-motion: reduce)` escape.
+
+**Translatable QWeb attributes** (auto-extracted, `odoo/tools/translate.py:163`), plus their
+`t-attf-` forms:
+
+```
+string  help  placeholder  alt  title  label  data-tooltip  confirm
+aria-label  aria-keyshortcuts  aria-placeholder  aria-roledescription  aria-valuetext
+```
+
+`aria-description` is **not** translated — use `aria-label` or visually-hidden text instead.
+Strings injected from JS go through `window.i18nManager.get(key)` (served by `/eskaera/i18n`), with
+the key added server-side — never a hardcoded literal, including in live-region announcements.
+
+Per-component patterns: `references/accessibility.md`.
+
+## 5. JS for finish (UI only)
+
+- **Delegated events** — content is lazy-loaded and infinite-scrolled, direct listeners die.
+- After injecting nodes: move or restore focus deliberately, announce the new count in the live
+  region, and set `aria-busy` on the container while fetching.
+- Check `matchMedia("(prefers-reduced-motion: reduce)")` before animating or smooth-scrolling.
+- Toggle **classes**, don't write `element.style.*` — inline styles from JS are the same defect as
+  inline styles in templates, just later.
+- Debounce search input ≥ 200 ms and announce "N results" politely.
+- Batch DOM reads and writes; never read `offsetHeight` inside a loop that also writes.
+
+## 6. Asset delivery
+
+`website_sale.css` pulls its 17 partials with `@import`. Odoo rewrites those to absolute URLs and
+hoists them to the top of the bundle (`odoo/addons/base/models/assetsbundle.py:909` and `:525`), so
+they ship as ~17 extra render-blocking requests **outside** the minified bundle. For a production
+finish, prefer listing each file in the manifest's `web.assets_frontend` (order: variables →
+utilities → layout → components → sections). Only rename them to `.scss` if the maintainer
+explicitly requests SCSS compilation so Odoo inlines the imports at compile time.
+
+## 7. Audit & verify
+
+If `/media/snt/data/addons-cm/website_sale_aplicoop` does not exist, run the audit commands from the
+repository root of the current workspace instead, and report which path was used.
+
+```bash
+cd /media/snt/data/addons-cm/website_sale_aplicoop
+
+# Breakpoint sprawl — should only ever list 576/768/992/1200/1400, all min-width
+grep -rho "@media[^{]*" static/src/css | sort | uniq -c | sort -rn
+
+# Hardcoded colours outside the token file (expect: none)
+grep -rn "#[0-9a-fA-F]\{3,8\}\b" static/src/css --include="*.css" | grep -v "base/variables.css"
+
+# Specificity debt
+grep -rc "!important" static/src/css/*/*.css | grep -v ':0'
+
+# Focus handling: :focus-visible should dominate, outline:none must be paired with a replacement
+grep -rn ":focus-visible\|outline: *none\|outline: *0" static/src/css
+
+# Motion safety (expect at least one per animating component)
+grep -rn "prefers-reduced-motion" static/src/css
+
+# Inline styles in templates (expect: none)
+grep -rn 'style="' views/*.xml
+
+# Images without alt
+grep -o "<img[^>]*" views/*.xml | grep -v "alt="
+
+# Interactive divs/spans (expect: none)
+grep -rn "<div[^>]*t-on-click\|<span[^>]*t-on-click\|<div[^>]*onclick" views/*.xml
+```
+
+Then, always:
+
+```bash
+pre-commit run --all-files          # prettier (width 100, indent 4) over css/js/xml + eslint
+docker-compose up -d                # http://localhost:8070 — check at 320/768/1280 and 200% zoom
+```
+
+Manual passes that no grep replaces: **Tab through the whole page** (visible focus everywhere, order
+matches visual order, no trap), and check contrast on the actual rendered colours.
+
+## 8. References
+
+- `references/accessibility.md` — WCAG AA patterns as QWeb snippets, per component.
+- `references/responsive.md` — breakpoints, intrinsic layout, images, test matrix.
+- `references/css-architecture.md` — file layout, naming, specificity, killing `!important`.
+- `references/finish-checklist.md` — the polish pass: states, rhythm, empty/loading/error.
+
+Repo docs: `docs/QWEB_BEST_PRACTICES.md`, `docs/LAZY_LOADING.md`.
diff --git a/.claude/skills/odoo-web-design/references/accessibility.md b/.claude/skills/odoo-web-design/references/accessibility.md
new file mode 100644
index 0000000..e9af392
--- /dev/null
+++ b/.claude/skills/odoo-web-design/references/accessibility.md
@@ -0,0 +1,245 @@
+# Accessibility patterns (QWeb + CSS + JS)
+
+WCAG 2.2 AA. Snippets use this repo's conventions: 4-space indent, Bootstrap 5.3 utilities,
+translatable attributes, `window.i18nManager.get(key)` for JS strings.
+
+## Page skeleton
+
+```xml
+<t t-call="website.layout">
+    <a href="#eskaera-main" class="visually-hidden-focusable btn btn-primary m-2">
+        Skip to main content
+    </a>
+    <div id="wrap" class="eskaera-shop-page">
+        <main id="eskaera-main" tabindex="-1">
+            <h1 class="eskaera-page-title" t-esc="page_title"/>
+            ...
+        </main>
+    </div>
+</t>
+```
+
+- Exactly one `<h1>` per page; never skip heading levels to get a font size — that's what classes are for.
+- `<main>`, `<nav aria-label="...">`, `<aside>` instead of anonymous `<div>`s.
+- `tabindex="-1"` on the skip-link target so focus actually lands there.
+
+## Buttons vs links
+
+| Intent | Element |
+| --- | --- |
+| Navigates to a URL | `<a href="...">` |
+| Changes state on this page | `<button type="button">` |
+| Submits a form | `<button type="submit">` |
+
+Never `<div t-on-click>` / `<span onclick>` — no keyboard, no role, no focus.
+
+Icon-only:
+
+```xml
+<button type="button" class="btn btn-outline-secondary qty-decrease"
+        aria-label="Decrease quantity">
+    <i class="fa fa-minus" aria-hidden="true"/>
+</button>
+```
+
+`aria-label` is auto-translated; `aria-hidden` on the icon stops the screen reader announcing
+"minus icon" twice. Alternative when the label is long: visible `<span class="visually-hidden">`.
+
+## Quantity stepper (live-announced)
+
+```xml
+<div class="qty-control" role="group" aria-label="Quantity">
+    <button type="button" class="btn qty-decrease" aria-label="Decrease quantity">
+        <i class="fa fa-minus" aria-hidden="true"/>
+    </button>
+    <input type="number" class="form-control qty-input"
+           t-att-value="line.qty" min="0" step="1"
+           aria-label="Quantity" inputmode="numeric"/>
+    <button type="button" class="btn qty-increase" aria-label="Increase quantity">
+        <i class="fa fa-plus" aria-hidden="true"/>
+    </button>
+</div>
+<p class="visually-hidden" aria-live="polite" id="qty_status"/>
+```
+
+```js
+// after the server confirms the new qty
+const status = document.getElementById("qty_status");
+status.textContent = window.i18nManager.get("qty_updated_announcement");
+```
+
+Buttons must stay ≥ 24×24 px (WCAG 2.2 AA §2.5.8) everywhere, and ≥ 44×44 px under
+`@media (pointer: coarse)` — including at 320 px width.
+
+## Forms and errors
+
+```xml
+<div class="mb-3">
+    <label class="form-label" for="delivery_note">Delivery note</label>
+    <textarea id="delivery_note" name="delivery_note" class="form-control"
+              t-att-aria-invalid="'true' if errors.get('delivery_note') else None"
+              t-att-aria-describedby="'delivery_note_help delivery_note_error'
+                                      if errors.get('delivery_note')
+                                      else 'delivery_note_help'"/>
+    <small id="delivery_note_help" class="form-text">Optional, visible to the group manager.</small>
+    <p t-if="errors.get('delivery_note')" id="delivery_note_error"
+       class="invalid-feedback d-block" t-esc="errors['delivery_note']"/>
+</div>
+```
+
+- The `for`/`id` pair is mandatory; wrapping alone is not enough for every AT.
+- Error text is referenced by `aria-describedby`, and never colour-only — keep the message.
+- The error summary at the top of a failed form should be focused on submit
+  (`container.focus()` on a `tabindex="-1"` heading).
+- Required fields: `required` + a visible "(required)" or `*` with a legend explaining it.
+
+## Product card — one link, no duplicates
+
+```xml
+<article class="product-card">
+    <img class="product-card-img" t-att-src="product['image_url']"
+         t-att-alt="product['name']" loading="lazy" width="400" height="400"/>
+    <h3 class="product-card-title">
+        <a t-att-href="product['url']" class="stretched-link" t-esc="product['name']"/>
+    </h3>
+    <p class="product-card-price">
+        <span class="visually-hidden">Price</span>
+        <span t-esc="product['price_formatted']"/>
+    </p>
+</article>
+```
+
+- `stretched-link` makes the whole card clickable with a **single** link in the a11y tree — do not
+  also wrap the image in an `<a>`, that produces two identical stops.
+- `width`/`height` reserve space (no layout shift); CSS `object-fit: cover` handles the ratio.
+- Decorative product placeholder → `alt=""`.
+
+## Filters as toggle buttons
+
+```xml
+<div class="tag-filter" role="group" aria-label="Filter by category">
+    <button t-foreach="categories" t-as="cat" t-key="cat['id']"
+            type="button" class="tag-filter-badge"
+            t-att-aria-pressed="'true' if cat['active'] else 'false'"
+            t-att-data-category-id="cat['id']">
+        <span t-esc="cat['name']"/>
+    </button>
+</div>
+```
+
+JS flips `aria-pressed` together with the active class — the class alone announces nothing.
+If the filters are a true multi-select set, `<fieldset><legend>` + checkboxes is better still.
+
+## Search with results announcement
+
+```xml
+<label class="visually-hidden" for="product_search">Search products</label>
+<input id="product_search" type="search" class="form-control"
+       placeholder="Search products…" autocomplete="off"
+       aria-describedby="search_results_count"/>
+<p id="search_results_count" class="visually-hidden" aria-live="polite" aria-atomic="true"/>
+```
+
+Debounce ≥ 200 ms, then set the text once per settled query — announcing on every keystroke makes
+the page unusable with a screen reader.
+
+## Loading, infinite scroll, empty states
+
+```xml
+<div id="products_grid" class="products-grid" aria-busy="false">…</div>
+<p class="visually-hidden" aria-live="polite" id="load_status"/>
+<button type="button" id="load_more" class="btn btn-outline-primary">Load more products</button>
+```
+
+- Set `aria-busy="true"` on the grid while fetching, back to `false` when done.
+- Announce `"N more products loaded"` via `load_status`; don't move focus mid-scroll.
+- **Always keep a real "Load more" button** alongside scroll-triggered loading — infinite scroll
+  alone is unreachable by keyboard and traps users away from the footer.
+- Empty state is content, not a blank div: heading + explanation + the action that fixes it.
+
+## Modals
+
+Use Bootstrap's modal (focus trap, Esc, `aria-modal` come free) and give it a label:
+
+```xml
+<div class="modal fade" id="confirm_order_modal" tabindex="-1"
+     aria-labelledby="confirm_order_title" aria-hidden="true">
+    <div class="modal-dialog modal-dialog-centered">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h2 class="modal-title fs-5" id="confirm_order_title">Confirm your order</h2>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"/>
+            </div>
+            …
+        </div>
+    </div>
+</div>
+```
+
+Return focus to the trigger on close (Bootstrap does this if the trigger is a real button).
+
+## Order tables
+
+```xml
+<table class="table checkout-summary-table">
+    <caption class="visually-hidden">Order lines</caption>
+    <thead>
+        <tr>
+            <th scope="col">Product</th>
+            <th scope="col" class="text-end">Quantity</th>
+            <th scope="col" class="text-end">Subtotal</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr t-foreach="lines" t-as="line" t-key="line['id']">
+            <th scope="row" t-esc="line['name']"/>
+            <td class="text-end" t-esc="line['qty']"/>
+            <td class="text-end" t-esc="line['subtotal_formatted']"/>
+        </tr>
+    </tbody>
+</table>
+```
+
+Never use a table for layout, and never drop `<thead>`/`scope` when stacking to cards on mobile —
+restyle, don't restructure.
+
+## Focus and motion in CSS
+
+```css
+/* One ring, everywhere, on keyboard focus only. */
+.eskaera-page :focus-visible {
+    outline: 2px solid var(--ac-color-focus, var(--focus-ring-color, #0d6efd));
+    outline-offset: 2px;
+    border-radius: var(--ac-radius-sm);
+}
+
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        scroll-behavior: auto !important;
+    }
+}
+```
+
+This is the one legitimate `!important` in the codebase — a user preference must beat every component.
+
+## Multilingual
+
+The addon runs es / eu / ca. `website.layout` sets `<html lang>`; when a string stays in another
+language inside a translated page (a supplier name, a product origin), mark it: `<span lang="eu">`.
+Never build a sentence by concatenating translated fragments — pass the whole string with `%s`
+placeholders so translators can reorder.
+
+## Verification
+
+1. **Keyboard only**: Tab through the page. Visible focus at every stop, order matches the visual
+   order, no trap, every action reachable, Esc closes overlays.
+2. **Zoom 200 %** and **320 px width**: no horizontal scroll, nothing clipped.
+3. **Contrast**: check rendered colours, including disabled states and placeholder text.
+4. **Screen reader** smoke test on the cart flow (Orca on Linux, NVDA on Windows).
+5. Lighthouse/axe in DevTools catches the mechanical half — it does not catch focus order,
+   announcement quality, or a label that lies.
diff --git a/.claude/skills/odoo-web-design/references/css-architecture.md b/.claude/skills/odoo-web-design/references/css-architecture.md
new file mode 100644
index 0000000..3083f06
--- /dev/null
+++ b/.claude/skills/odoo-web-design/references/css-architecture.md
@@ -0,0 +1,160 @@
+# CSS architecture
+
+## File layout
+
+```
+static/src/css/
+├── website_sale.css        # index only: @import list, no rules of its own
+├── base/
+│   ├── variables.css       # :root tokens — the ONLY file with hex literals
+│   └── utilities.css       # tiny single-purpose helpers, when Bootstrap lacks one
+├── layout/
+│   ├── pages.css           # page shells, containers, backgrounds
+│   └── header.css
+├── components/             # one file per reusable component
+│   ├── product-card.css
+│   ├── order-card.css
+│   ├── cart.css
+│   ├── buttons.css
+│   ├── quantity-control.css
+│   ├── forms.css
+│   ├── alerts.css
+│   └── tag-filter.css
+└── sections/               # page-specific composition only
+    ├── products-grid.css
+    ├── order-list.css
+    ├── checkout.css
+    └── info-cards.css
+```
+
+Rules of placement:
+
+- A rule that could appear on two pages is a **component**, never a section.
+- A **section** file may only position and space components — if it restyles a component's internals,
+  the component is missing a modifier.
+- Each component file owns its own media queries, at the bottom. There is no global responsive file
+  in a healthy tree; a legacy `layout/responsive.css` should shrink to zero as components are touched.
+- `website_sale.css` contains imports and comments only.
+
+## Naming
+
+Prefix everything with `eskaera-` (the product name already used for page-level classes). Unprefixed
+names like `.product-card`, `.cart-header`, `.qty-control` sit in the same namespace as Bootstrap,
+Odoo core and every other installed addon — that collision is what forces `!important` later.
+
+```
+.eskaera-product-card                 /* block */
+.eskaera-product-card__title          /* element */
+.eskaera-product-card--out-of-stock   /* modifier */
+.is-loading  .is-active  .has-error   /* state, always paired with a block class */
+```
+
+`js-` prefix for hooks JS queries, and never style a `js-` class — that way markup can be restyled
+without breaking behaviour, and behaviour can move without breaking styles.
+
+When renaming existing classes, do it component by component: template + CSS + JS selectors + tests
+in the same commit, then grep for the old name across `views/`, `static/src/`, and `README*`.
+
+## Specificity — how to stop writing `!important`
+
+Overriding Bootstrap globally (`.list-group-item { … }`, `.alert-warning { … }`) is a fight you win
+only with `!important`, and it leaks into every other addon. Scope the override under the page root
+instead: equal specificity plus one class always wins, no escape hatch needed.
+
+```css
+/* ❌ global override, needs !important to beat Bootstrap's own later rules */
+.list-group-item {
+    border-radius: 0 !important;
+}
+
+/* ✅ scoped: higher specificity, no !important, no leakage */
+.eskaera-checkout-page .list-group-item {
+    border-radius: 0;
+}
+```
+
+Other rules:
+
+- Max **3** levels of nesting in a selector. Deeper means the markup is doing the work the class
+  should do.
+- No ID selectors for styling; IDs are for anchors and `aria-*` references.
+- No element selectors outside `base/` (`div.product-card` locks the markup).
+- `!important` is allowed in exactly two places: the `prefers-reduced-motion` reset, and a documented
+  override of a core rule you cannot scope — with a comment saying which rule and why.
+
+## Ordering inside a file
+
+```css
+.eskaera-product-card {
+    /* 1. layout */
+    display: flex;
+    flex-direction: column;
+    /* 2. box */
+    padding: var(--ac-space-md);
+    border: 1px solid var(--ac-border-light);
+    border-radius: var(--ac-radius-lg);
+    /* 3. typography */
+    font-size: var(--ac-text-base);
+    color: var(--ac-text-primary);
+    /* 4. paint & motion */
+    background: var(--ac-surface);
+    box-shadow: var(--ac-shadow-sm);
+    transition: box-shadow var(--ac-transition-fast);
+}
+```
+
+Then, in order: `:hover` (inside `@media (hover: hover)`), `:focus-visible`, `:active`, `:disabled`,
+state classes, modifiers, media queries.
+
+## Tokens
+
+Full rules in `SKILL.md` §2. In short:
+
+```css
+:root {
+    /* alias Odoo/Bootstrap's unprefixed custom properties so theming still works */
+    --ac-color-primary: var(--primary, #007bff);
+    --ac-color-danger: var(--danger, #dc3545);
+    --ac-surface: var(--body-bg, #fff);
+    --ac-text-primary: var(--body-color, #1a202c);
+    --ac-border-light: var(--border-color, #e2e8f0);
+
+    /* own scales */
+    --ac-space-xs: 0.25rem;
+    --ac-space-sm: 0.5rem;
+    --ac-space-md: 1rem;
+    --ac-space-lg: 1.5rem;
+    --ac-space-xl: 2rem;
+
+    --ac-radius-sm: 0.25rem;
+    --ac-radius-md: 0.5rem;
+    --ac-radius-lg: 0.75rem;
+
+    --ac-shadow-sm: 0 2px 8px rgb(0 0 0 / 8%);
+    --ac-shadow-md: 0 4px 12px rgb(0 0 0 / 10%);
+
+    --ac-transition-fast: 200ms ease;
+}
+```
+
+Migrating a legacy token set: add the `--ac-` token aliased to the old name, move consumers file by
+file, delete the old token when `grep -rn "\-\-old-name" static/src/` is empty. Don't rename all at once.
+
+## Anti-patterns seen in Odoo addons
+
+| Smell | Fix |
+| --- | --- |
+| `!important` to beat Bootstrap | scope under the page root class |
+| Same colour as `#28a745` in six files | one token in `variables.css` |
+| `responsive.css` overriding twelve components | move each query into its component |
+| `style="margin-top:20px"` in QWeb | utility class or component spacing |
+| `.card .body .row .col span` | give the span a class |
+| `px` for font sizes | `rem`, so browser zoom and user font size work |
+| Colour hardcoded instead of `var(--primary)` | breaks the website theme editor silently |
+| Both `@import` chain **and** manifest entries | double download; pick one (see SKILL.md §6) |
+
+## Formatting
+
+Prettier handles `.css` via pre-commit: `printWidth: 100`, `tabWidth: 4`. Run
+`pre-commit run --all-files` (or `make format`) before committing; never hand-align properties, it
+will be reformatted.
diff --git a/.claude/skills/odoo-web-design/references/finish-checklist.md b/.claude/skills/odoo-web-design/references/finish-checklist.md
new file mode 100644
index 0000000..02ed81d
--- /dev/null
+++ b/.claude/skills/odoo-web-design/references/finish-checklist.md
@@ -0,0 +1,96 @@
+# The finish pass
+
+What separates "it works" from "it looks designed". Go through this per screen, not per file.
+
+## 1. Every interactive element has all its states
+
+For each button, link, card, input, filter chip:
+
+| State | Must be | Common miss |
+| --- | --- | --- |
+| default | on the token scale | — |
+| `:hover` | inside `@media (hover: hover)` | sticks after tap on touch |
+| `:focus-visible` | visible ring, 3:1 contrast | removed via `outline: none` |
+| `:active` | perceptible press | missing entirely |
+| `:disabled` | dimmed **and** `cursor: not-allowed`, still 4.5:1 if it carries text | unreadable grey |
+| loading | spinner + `aria-busy`, size unchanged | layout jumps |
+
+The element must not resize between states — animate `box-shadow`, `background`, `transform`, never
+`padding`, `border-width` or `font-size`.
+
+## 2. Vertical rhythm and spacing
+
+- All spacing from `--ac-space-*`. A `margin: 13px` anywhere is a defect.
+- Space belongs to **one** side consistently (block-end margins, or `gap` — pick one per container).
+  Prefer `gap` in flex/grid; it doesn't collapse and doesn't need `:last-child` cleanups.
+- Related things sit closer than unrelated things. If the label is as far from its input as from the
+  previous field, the form reads as noise.
+- Cards in a grid must be equal height (`align-items: stretch` + the price pinned with `margin-top: auto`).
+
+## 3. Typography
+
+- One scale (`--ac-text-*`), max 3 weights, max 2 sizes per card.
+- Headings are structural (`h1`→`h2`→`h3`); size comes from a class, never from picking `h4` because
+  it looks right.
+- `max-width: 65ch` on paragraphs of real prose.
+- Numbers in tables: `font-variant-numeric: tabular-nums` and right-aligned so columns line up.
+- Long product names truncate predictably: `text-overflow: ellipsis` with `title` attribute, or
+  `-webkit-line-clamp: 2` with a fixed `min-height` so cards don't stagger.
+
+## 4. Colour
+
+- Semantic, not decorative: success/danger/warning always the same hue for the same meaning.
+- Status never colour-only — icon or text alongside (colour blindness, and grayscale printing).
+- Max ~2 accent colours per screen. Everything else is surface, border, text.
+- Check the rendered contrast, including: placeholder text, disabled buttons, badges on coloured
+  backgrounds, white text on `--warning` (this one almost always fails).
+
+## 5. The states people forget
+
+Every list, grid and total needs four designs, not one:
+
+1. **Loading** — skeletons matched to the real layout (not a centred spinner that collapses the page).
+2. **Empty** — heading, one sentence explaining why it's empty, and the button that fixes it.
+   "No products found" alone is a dead end; offer "Clear filters".
+3. **Error** — what failed, in the user's language, and what to do now. Never a raw traceback or code.
+4. **Partial / stale** — an order past its cutoff, an out-of-stock line, a price that changed. Say it
+   inline, next to the affected row, not only in a toast that disappears.
+
+## 6. Feedback and motion
+
+- Any action taken by the user gets a response within 100 ms — disable the button, show the spinner,
+  optimistic-update the quantity. Silence reads as "broken", and users double-submit.
+- Toasts: `aria-live="polite"`, dismissible, never the only place an error is shown.
+- Motion is 150–250 ms and eases out. Anything above 400 ms feels slow; anything that moves the page
+  under the cursor is a bug.
+- Everything animated respects `prefers-reduced-motion`.
+
+## 7. Content and copy
+
+- Sentence case for buttons and labels; imperative verbs ("Add to cart", not "Adding products").
+- Prices always formatted server-side with the currency and locale (`i18nManager.formatCurrency`),
+  never string-concatenated in the template.
+- Dates: locale-formatted, and relative only when the absolute date is also available (`title`).
+- Nothing user-visible is a hardcoded English literal — templates get translatable text, JS gets
+  `window.i18nManager.get(key)`.
+
+## 8. Cross-cutting checks before "done"
+
+```
+[ ] 320 px: no horizontal scroll on any page
+[ ] 200 % zoom: nothing clipped or overlapping
+[ ] Tab through the whole flow: visible focus, logical order, no trap
+[ ] All actions reachable without a mouse, Esc closes overlays
+[ ] No hex outside base/variables.css
+[ ] No inline style="" in views/*.xml
+[ ] No new !important (except the reduced-motion reset)
+[ ] Every <img> has alt and width/height
+[ ] Every icon-only control has aria-label
+[ ] Empty / loading / error states exist for each list
+[ ] es, eu and ca render without overflow (German-length strings break tight buttons)
+[ ] pre-commit run --all-files is clean
+[ ] Lighthouse a11y ≥ 95 on shop, cart, checkout
+```
+
+The last three matter as much as the rest: a layout tuned only against Spanish copy usually breaks in
+Basque, and a11y regressions land silently.
diff --git a/.claude/skills/odoo-web-design/references/responsive.md b/.claude/skills/odoo-web-design/references/responsive.md
new file mode 100644
index 0000000..a15f609
--- /dev/null
+++ b/.claude/skills/odoo-web-design/references/responsive.md
@@ -0,0 +1,191 @@
+# Responsive layout
+
+## Breakpoints — Bootstrap 5, and only these
+
+| Name | `min-width` | Typical device |
+| --- | --- | --- |
+| (base) | — | phones, 320–575 px |
+| `sm` | 576px | large phones |
+| `md` | 768px | tablets |
+| `lg` | 992px | small laptops |
+| `xl` | 1200px | desktops |
+| `xxl` | 1400px | large desktops |
+
+Mobile-first, `min-width` only:
+
+```css
+/* ✅ base = mobile, enhance upwards */
+.products-grid {
+    display: grid;
+    gap: var(--ac-space-md);
+    grid-template-columns: 1fr;
+}
+
+@media (min-width: 768px) {
+    .products-grid {
+        grid-template-columns: repeat(2, 1fr);
+    }
+}
+
+@media (min-width: 1200px) {
+    .products-grid {
+        grid-template-columns: repeat(4, 1fr);
+    }
+}
+```
+
+```css
+/* ❌ desktop-first bands: overlapping ranges, unclear cascade, private breakpoints */
+@media (max-width: 1599px) and (min-width: 1400px) { … }
+@media (max-width: 720px) { … }
+```
+
+## Prefer intrinsic layout — most grids need no media query at all
+
+```css
+.products-grid {
+    display: grid;
+    gap: var(--ac-space-md);
+    grid-template-columns: repeat(auto-fill, minmax(min(100%, 16rem), 1fr));
+}
+```
+
+`min(100%, 16rem)` is what keeps it from overflowing at 320 px. Reach for a media query only when the
+layout must genuinely *change* (sidebar moves, table becomes cards), not merely resize.
+
+## Fluid type and space
+
+```css
+:root {
+    --ac-text-sm: clamp(0.875rem, 0.85rem + 0.1vw, 0.9375rem);
+    --ac-text-base: clamp(1rem, 0.96rem + 0.2vw, 1.125rem);
+    --ac-text-lg: clamp(1.25rem, 1.15rem + 0.5vw, 1.5rem);
+    --ac-text-xl: clamp(1.5rem, 1.3rem + 1vw, 2.25rem);
+    --ac-space-md: clamp(1rem, 0.9rem + 0.5vw, 1.5rem);
+}
+```
+
+One continuous scale beats three step-changes at breakpoints. Never redefine a token inside a media
+query to make it smaller.
+
+Body copy: 1rem minimum, line-height ≥ 1.5, measure 45–75 characters (`max-width: 65ch`).
+
+## Touch targets and pointer
+
+WCAG 2.2 AA (§2.5.8 Target Size, Minimum) asks for **24×24 px**. The familiar **44×44 px** is §2.5.5,
+level **AAA** — treat it as the house rule for anything a thumb hits, applied by pointer type rather
+than by viewport width: a 1024 px tablet needs the big target, a 1024 px laptop doesn't.
+
+```css
+.qty-control .btn,
+.tag-filter-badge {
+    min-width: 2.25rem; /* 36px — comfortable with a mouse */
+    min-height: 2.25rem;
+}
+
+@media (pointer: coarse) {
+    .qty-control .btn,
+    .tag-filter-badge {
+        min-width: 2.75rem; /* 44px */
+        min-height: 2.75rem;
+    }
+}
+
+@media (hover: hover) and (pointer: fine) {
+    .product-card:hover {
+        transform: translateY(-2px);
+        box-shadow: var(--ac-shadow-md);
+    }
+}
+```
+
+Hover effects belong inside `@media (hover: hover)` — on touch they stick after a tap and look broken.
+
+## Tables → cards, without restructuring
+
+```css
+@media (max-width: 767.98px) {
+    .checkout-summary-table thead {
+        /* keep it in the a11y tree; hide visually only */
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+    }
+    .checkout-summary-table tr {
+        display: grid;
+        grid-template-columns: 1fr auto;
+        gap: var(--ac-space-xs);
+        padding: var(--ac-space-sm) 0;
+        border-bottom: 1px solid var(--ac-border-light);
+    }
+}
+```
+
+This is the one place a `max-width` query is honest: it's an override of the desktop table. Keep the
+markup semantic — never emit different HTML per viewport.
+
+## Sticky bars (cart / checkout actions on mobile)
+
+```css
+.checkout-actions {
+    position: sticky;
+    bottom: 0;
+    z-index: var(--ac-z-sticky);
+    padding: var(--ac-space-sm);
+    padding-bottom: calc(var(--ac-space-sm) + env(safe-area-inset-bottom, 0px));
+    background: var(--ac-surface, #fff);
+    box-shadow: 0 -2px 8px rgb(0 0 0 / 8%);
+}
+```
+
+`env(safe-area-inset-bottom)` keeps the button above the iOS home indicator. Sticky elements must not
+eat more than ~20 % of a 568 px-tall viewport.
+
+## Images
+
+```xml
+<img class="product-card-img" t-att-src="product['image_url']" t-att-alt="product['name']"
+     loading="lazy" decoding="async" width="400" height="400"/>
+```
+
+- `width`/`height` always — they reserve the box and prevent layout shift (CLS).
+- `loading="lazy"` for everything below the fold; **never** on the LCP image (first product row,
+  hero) — that delays the largest paint.
+- CSS: `max-width: 100%; height: auto;` plus `object-fit: cover` with a fixed `aspect-ratio` when
+  cards must align.
+- Odoo serves resized variants: `/web/image/product.product/<id>/image_256` etc. Ask for the size you
+  render, not `image_1920` scaled down in CSS.
+
+## Container and page rhythm
+
+```css
+.eskaera-page {
+    width: 100%;
+    max-width: 75rem;
+    margin-inline: auto;
+    padding-inline: clamp(1rem, 4vw, 2rem);
+}
+```
+
+Use logical properties (`margin-inline`, `padding-block`, `inset-inline-start`) — Odoo auto-generates
+an RTL stylesheet, and logical properties survive the flip without a second rule.
+
+## Test matrix
+
+| Width | Why |
+| --- | --- |
+| 320 px | smallest supported; the one that breaks first |
+| 360 / 390 px | real Android / iPhone |
+| 768 px | tablet portrait, first breakpoint |
+| 1024 px | tablet landscape / small laptop |
+| 1280 / 1440 px | desktop |
+| 1280 px @ 200 % zoom | WCAG 1.4.4 reflow — equivalent to 640 px |
+
+Run the stack (`docker-compose up -d`, http://localhost:8070) and check, per viewport: no horizontal
+scroll, no clipped text, touch targets still ≥ 44 px on coarse pointers, sticky bars not covering
+content, images not stretched.
+
+DevTools device toolbar is enough for layout; check touch targets by actually tapping on a phone once
+before calling it done.