Add comprehensive template conversion plan (PLAN.md)

9-phase plan covering all ~125 customer-facing WooCommerce templates, organized by priority: globals, archive, single product, cart, checkout, my account, orders, emails, and supplementary. Includes Bootstrap 5 component mappings, CSS/JS strategy, reusable components, accessibility checklist, and per-file tracking. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 10:05:58 +01:00
parent 0b4f136674
commit 9592b8cae5
1 changed files with 668 additions and 0 deletions
--- a/PLAN.md
+++ b/PLAN.md
@@ -0,0 +1,668 @@
+# WooCommerce to Bootstrap 5 -- Template Conversion Plan
+
+This document outlines the full plan for converting WooCommerce's default templates into Bootstrap 5 themed Twig overrides within the `wc-bootstrap` child theme.
+
+## Scope
+
+**Source:** 233 WooCommerce PHP/HTML templates in `wp-content/plugins/woocommerce/templates/`
+**Target:** Twig template overrides in `wp-content/themes/wc-bootstrap/templates/`
+**Design system:** Bootstrap 5.3 (loaded via parent theme `wp-bootstrap`)
+
+The plugin is **read-only** -- we never modify WooCommerce source. All customisation happens through Twig template overrides via `TemplateOverride::prependPath()` and WordPress hooks in `functions.php`.
+
+---
+
+## Existing Scaffold (v0.1.0)
+
+Already in place:
+
+| File | Purpose |
+| ---- | ------- |
+| `templates/base.html.twig` | Conditional wrapper (`_theme_wrapped` detection) |
+| `templates/layouts/account.html.twig` | My Account layout shell |
+| `templates/layouts/archive.html.twig` | Product archive / search layout |
+| `templates/layouts/form.html.twig` | Centered form layout (card + shadow) |
+| `templates/layouts/page.html.twig` | Generic content page |
+| `templates/layouts/single.html.twig` | Detail page (8+4 grid) |
+| `templates/components/card.html.twig` | Reusable product/post card |
+| `templates/components/pagination.html.twig` | Bootstrap pagination nav |
+| `inc/TemplateOverride.php` | Twig loader hook |
+| `functions.php` | Style chain, render filter, wrapping signal |
+| `assets/css/wc-bootstrap.css` | Button/alert/dark-mode overrides |
+
+---
+
+## Conversion Phases
+
+### Phase 1 -- Global & Notices (Foundation)
+
+Templates that appear on every WooCommerce page. Must be done first because all other templates depend on them.
+
+#### 1.1 Global Templates
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `global/wrapper-start.php` | `global/wrapper-start.html.twig` | `<div class="container my-4">` (or skip if `_theme_wrapped`) |
+| `global/wrapper-end.php` | `global/wrapper-end.html.twig` | Closing `</div>` |
+| `global/breadcrumb.php` | `global/breadcrumb.html.twig` | `nav[aria-label] > ol.breadcrumb > li.breadcrumb-item` |
+| `global/sidebar.php` | `global/sidebar.html.twig` | `aside.col-lg-3` with `offcanvas-lg` for mobile |
+| `global/quantity-input.php` | `global/quantity-input.html.twig` | `input-group` with `btn-outline-secondary` +/- buttons |
+| `global/form-login.php` | `global/form-login.html.twig` | Extend `layouts/form.html.twig`, `form-control`, `form-label` |
+
+#### 1.2 Notice Templates
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `notices/notice.php` | `notices/notice.html.twig` | `alert alert-info alert-dismissible fade show` |
+| `notices/error.php` | `notices/error.html.twig` | `alert alert-danger alert-dismissible fade show` |
+| `notices/success.php` | `notices/success.html.twig` | `alert alert-success alert-dismissible fade show` |
+
+**Notes:**
+
+- Notices must support multiple messages (WooCommerce passes arrays)
+- Include `btn-close` with `data-bs-dismiss="alert"`
+- Respect dark mode via Bootstrap's adaptive colour utilities
+
+---
+
+### Phase 2 -- Product Archive & Shop Loop (Storefront)
+
+The shop page, category pages, and product grid. This is the main entry point for customers.
+
+#### 2.1 Archive Container
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `archive-product.php` | `archive-product.html.twig` | Extend `layouts/archive.html.twig`; 3+9 grid (filter sidebar + products) |
+| `content-product.php` | `content-product.html.twig` | Extend `components/card.html.twig`; product card in grid |
+| `content-product-cat.php` | `content-product-cat.html.twig` | Category card with thumbnail |
+| `product-searchform.php` | `product-searchform.html.twig` | `input-group` with `form-control` + `btn btn-outline-primary` |
+
+#### 2.2 Loop Components
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `loop/loop-start.php` | `loop/loop-start.html.twig` | `<div class="row row-cols-1 row-cols-md-2 row-cols-lg-3 g-4">` |
+| `loop/loop-end.php` | `loop/loop-end.html.twig` | `</div>` |
+| `loop/header.php` | `loop/header.html.twig` | Flex row: result-count left, orderby right |
+| `loop/result-count.php` | `loop/result-count.html.twig` | `<p class="text-body-secondary mb-0">` |
+| `loop/orderby.php` | `loop/orderby.html.twig` | `form-select form-select-sm` in flex container |
+| `loop/pagination.php` | `loop/pagination.html.twig` | Delegate to `components/pagination.html.twig` |
+| `loop/no-products-found.php` | `loop/no-products-found.html.twig` | `alert alert-info` with icon |
+| `loop/add-to-cart.php` | `loop/add-to-cart.html.twig` | `btn btn-primary btn-sm w-100` |
+| `loop/price.php` | `loop/price.html.twig` | `<span class="fs-5 fw-semibold">` (sale: `text-decoration-line-through text-body-secondary` + `text-danger`) |
+| `loop/rating.php` | `loop/rating.html.twig` | Bootstrap Icons stars (`bi-star-fill`, `bi-star`) |
+| `loop/sale-flash.php` | `loop/sale-flash.html.twig` | `badge bg-danger position-absolute top-0 start-0 m-2` |
+
+---
+
+### Phase 3 -- Single Product Page
+
+The product detail page, including gallery, variations, tabs, and related products.
+
+#### 3.1 Product Layout
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `single-product/product-image.php` | `single-product/product-image.html.twig` | Main image + thumbnail row; `img-fluid rounded`; lightbox via PhotoSwipe or Bootstrap modal |
+| `single-product/title.php` | `single-product/title.html.twig` | `<h1 class="mb-2">` |
+| `single-product/price.php` | `single-product/price.html.twig` | `fs-3 fw-bold`; sale styling as in loop |
+| `single-product/short-description.php` | `single-product/short-description.html.twig` | `<div class="lead text-body-secondary mb-3">` |
+| `single-product/meta.php` | `single-product/meta.html.twig` | `<dl class="row mb-3">` with `col-sm-3`/`col-sm-9` pairs |
+| `single-product/rating.php` | `single-product/rating.html.twig` | Stars + link to reviews tab |
+| `single-product/stock.php` | `single-product/stock.html.twig` | `badge bg-success` (in stock) / `badge bg-danger` (out of stock) |
+| `single-product/sale-flash.php` | `single-product/sale-flash.html.twig` | `badge bg-danger fs-6` |
+| `single-product/share.php` | `single-product/share.html.twig` | `btn-group` with Bootstrap Icon buttons |
+| `single-product/product-attributes.php` | `single-product/product-attributes.html.twig` | `table table-sm table-striped` |
+| `single-product/related.php` | `single-product/related.html.twig` | Section heading + `row row-cols-2 row-cols-lg-4 g-4` of cards |
+| `single-product/up-sells.php` | `single-product/up-sells.html.twig` | Same grid as related |
+
+#### 3.2 Add to Cart Forms
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `single-product/add-to-cart/simple.php` | `single-product/add-to-cart/simple.html.twig` | `input-group` (quantity) + `btn btn-primary btn-lg` |
+| `single-product/add-to-cart/variable.php` | `single-product/add-to-cart/variable.html.twig` | `form-select` per attribute + quantity + button |
+| `single-product/add-to-cart/grouped.php` | `single-product/add-to-cart/grouped.html.twig` | `table table-borderless` with quantity inputs per item |
+| `single-product/add-to-cart/external.php` | `single-product/add-to-cart/external.html.twig` | `btn btn-outline-primary btn-lg` with external link icon |
+| `single-product/add-to-cart/variation.php` | `single-product/add-to-cart/variation.html.twig` | Variation data container (hidden, JS-driven) |
+| `single-product/add-to-cart/variation-add-to-cart-button.php` | `single-product/add-to-cart/variation-add-to-cart-button.html.twig` | Same as simple but variation-aware |
+
+#### 3.3 Product Tabs
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `single-product/tabs/tabs.php` | `single-product/tabs/tabs.html.twig` | `nav nav-tabs` + `tab-content` with `tab-pane fade` |
+| `single-product/tabs/description.php` | `single-product/tabs/description.html.twig` | `tab-pane` with prose content |
+| `single-product/tabs/additional-information.php` | `single-product/tabs/additional-information.html.twig` | `tab-pane` with attributes table |
+
+---
+
+### Phase 4 -- Cart
+
+The cart page with item management, shipping calculator, and totals.
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `cart/cart.php` | `cart/cart.html.twig` | `row`: `col-lg-8` (items table) + `col-lg-4` (totals sidebar) |
+| `cart/cart-empty.php` | `cart/cart-empty.html.twig` | Centred `alert alert-info` + `btn btn-primary` to shop |
+| `cart/cart-item-data.php` | `cart/cart-item-data.html.twig` | `<dl class="small text-body-secondary mb-0">` |
+| `cart/cart-totals.php` | `cart/cart-totals.html.twig` | `card` with `list-group list-group-flush` rows |
+| `cart/cart-shipping.php` | `cart/cart-shipping.html.twig` | `form-check` radio buttons per shipping method |
+| `cart/cross-sells.php` | `cart/cross-sells.html.twig` | Section below cart; `row row-cols-2 row-cols-md-4 g-3` of small cards |
+| `cart/mini-cart.php` | `cart/mini-cart.html.twig` | `offcanvas offcanvas-end` slide-in panel |
+| `cart/proceed-to-checkout-button.php` | `cart/proceed-to-checkout-button.html.twig` | `btn btn-primary btn-lg w-100` |
+| `cart/shipping-calculator.php` | `cart/shipping-calculator.html.twig` | Collapsible form (`collapse`) with `form-select` for country/state |
+
+**Cart Table Structure:**
+
+```html
+<div class="table-responsive">
+  <table class="table align-middle">
+    <thead class="table-light">
+      <tr>
+        <th>Product</th>
+        <th>Price</th>
+        <th>Quantity</th>
+        <th>Subtotal</th>
+        <th></th><!-- Remove -->
+      </tr>
+    </thead>
+    <tbody><!-- cart items --></tbody>
+  </table>
+</div>
+```
+
+---
+
+### Phase 5 -- Checkout
+
+The checkout flow including billing/shipping forms, order review, and payment.
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `checkout/form-checkout.php` | `checkout/form-checkout.html.twig` | `row`: `col-lg-7` (forms) + `col-lg-5` (order review, sticky) |
+| `checkout/form-billing.php` | `checkout/form-billing.html.twig` | `card mb-4` with `form-control`, `form-label`, `form-select` fields |
+| `checkout/form-shipping.php` | `checkout/form-shipping.html.twig` | Same card style; `form-check` for "ship to different address" toggle |
+| `checkout/form-coupon.php` | `checkout/form-coupon.html.twig` | `input-group` inline: `form-control` + `btn btn-outline-secondary` |
+| `checkout/form-login.php` | `checkout/form-login.html.twig` | Collapsible (`collapse`) login form above checkout |
+| `checkout/review-order.php` | `checkout/review-order.html.twig` | `card` with `table table-sm` for items + `list-group` for totals |
+| `checkout/payment.php` | `checkout/payment.html.twig` | `list-group` of `form-check` radio items per gateway; `btn btn-primary btn-lg w-100` place order |
+| `checkout/payment-method.php` | `checkout/payment-method.html.twig` | `list-group-item` with radio + label + description collapse |
+| `checkout/terms.php` | `checkout/terms.html.twig` | `form-check` checkbox with link to terms page |
+| `checkout/thankyou.php` | `checkout/thankyou.html.twig` | `alert alert-success` + order details card |
+| `checkout/order-received.php` | `checkout/order-received.html.twig` | Confirmation message with order summary |
+| `checkout/cart-errors.php` | `checkout/cart-errors.html.twig` | `alert alert-danger` list |
+
+---
+
+### Phase 6 -- My Account Dashboard
+
+The customer account area with orders, addresses, and account management.
+
+#### 6.1 Account Shell
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `myaccount/my-account.php` | `myaccount/my-account.html.twig` | Extend `layouts/account.html.twig`; 3+9 grid (nav + content) |
+| `myaccount/navigation.php` | `myaccount/navigation.html.twig` | `list-group` in sticky sidebar (desktop) / `nav nav-pills` (mobile) |
+| `myaccount/dashboard.php` | `myaccount/dashboard.html.twig` | Welcome card + quick links as `row row-cols-1 row-cols-md-3 g-3` |
+
+#### 6.2 Orders
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `myaccount/orders.php` | `myaccount/orders.html.twig` | `table-responsive` > `table table-hover` with status badges |
+| `myaccount/view-order.php` | `myaccount/view-order.html.twig` | Order details card + address cards row |
+
+#### 6.3 Addresses & Account
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `myaccount/my-address.php` | `myaccount/my-address.html.twig` | `row row-cols-1 row-cols-md-2 g-4`; billing + shipping cards |
+| `myaccount/form-edit-address.php` | `myaccount/form-edit-address.html.twig` | `card` form with `form-control`, `form-select` |
+| `myaccount/form-edit-account.php` | `myaccount/form-edit-account.html.twig` | `card` form for name, email, password change |
+| `myaccount/downloads.php` | `myaccount/downloads.html.twig` | `table table-striped` with download links |
+| `myaccount/payment-methods.php` | `myaccount/payment-methods.html.twig` | `list-group` of saved methods with delete button |
+| `myaccount/form-add-payment-method.php` | `myaccount/form-add-payment-method.html.twig` | `card` form |
+
+#### 6.4 Authentication
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `myaccount/form-login.php` | `myaccount/form-login.html.twig` | `row row-cols-1 row-cols-md-2 g-4`: login card + register card side-by-side |
+| `myaccount/form-lost-password.php` | `myaccount/form-lost-password.html.twig` | Extend `layouts/form.html.twig`; centered card |
+| `myaccount/form-reset-password.php` | `myaccount/form-reset-password.html.twig` | Extend `layouts/form.html.twig`; centered card |
+| `myaccount/lost-password-confirmation.php` | `myaccount/lost-password-confirmation.html.twig` | `alert alert-success` |
+
+---
+
+### Phase 7 -- Order Details
+
+Order display used on thank-you page, view-order, and emails.
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `order/order-details.php` | `order/order-details.html.twig` | `card` > `table-responsive` > `table` |
+| `order/order-details-item.php` | `order/order-details-item.html.twig` | `<tr>` with product image thumbnail, name, quantity, price |
+| `order/order-details-customer.php` | `order/order-details-customer.html.twig` | `row row-cols-1 row-cols-md-2`: billing + shipping address cards |
+| `order/form-tracking.php` | `order/form-tracking.html.twig` | Extend `layouts/form.html.twig`; order ID + email fields |
+| `order/order-again.php` | `order/order-again.html.twig` | `btn btn-outline-primary` |
+
+---
+
+### Phase 8 -- Email Templates
+
+Email templates require special treatment: no external CSS, no Bootstrap JS, inline styles only.
+
+**Strategy:** Use Bootstrap's colour palette as CSS custom properties mapped to inline styles. Prefix all classes with `wc-email-` to avoid email client conflicts (per architecture decision in CLAUDE.md).
+
+#### 8.1 Email Shell
+
+| WooCommerce Template | Theme Override | Purpose |
+| -------------------- | -------------- | ------- |
+| `emails/email-header.php` | `emails/email-header.html.twig` | Table-based header with logo, store name |
+| `emails/email-footer.php` | `emails/email-footer.html.twig` | Table-based footer with store info |
+| `emails/email-styles.php` | `emails/email-styles.html.twig` | Inline CSS aligned to Bootstrap colour palette |
+
+#### 8.2 Email Content Components
+
+| WooCommerce Template | Theme Override | Purpose |
+| -------------------- | -------------- | ------- |
+| `emails/email-order-details.php` | `emails/email-order-details.html.twig` | Order items table |
+| `emails/email-order-items.php` | `emails/email-order-items.html.twig` | Single order item row |
+| `emails/email-customer-details.php` | `emails/email-customer-details.html.twig` | Customer info section |
+| `emails/email-addresses.php` | `emails/email-addresses.html.twig` | Billing + shipping addresses |
+| `emails/email-downloads.php` | `emails/email-downloads.html.twig` | Downloads table |
+
+#### 8.3 Transactional Emails (Priority Order)
+
+High-traffic emails first:
+
+1. `emails/customer-processing-order.php` -- Order confirmation
+2. `emails/customer-completed-order.php` -- Order shipped/complete
+3. `emails/customer-on-hold-order.php` -- Awaiting payment
+4. `emails/customer-new-account.php` -- Welcome email
+5. `emails/customer-reset-password.php` -- Password reset
+6. `emails/customer-invoice.php` -- Invoice/receipt
+7. `emails/customer-note.php` -- Order note
+8. `emails/customer-refunded-order.php` -- Refund notification
+9. `emails/customer-cancelled-order.php` -- Cancellation
+10. `emails/customer-failed-order.php` -- Payment failure
+
+Admin emails:
+
+11. `emails/admin-new-order.php` -- New order notification
+12. `emails/admin-cancelled-order.php` -- Cancellation alert
+13. `emails/admin-failed-order.php` -- Payment failure alert
+
+#### 8.4 Plain Text Emails
+
+The `emails/plain/` directory contains plain-text variants. These need minimal conversion -- mainly ensuring consistent formatting and branding text. Lower priority; can be done as a batch after HTML emails.
+
+---
+
+### Phase 9 -- Supplementary Templates
+
+Lower-traffic pages and edge cases.
+
+#### 9.1 Brands
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `brands/brand-description.php` | `brands/brand-description.html.twig` | `<div class="mb-4">` with prose |
+| `brands/taxonomy-product_brand.php` | `brands/taxonomy-product_brand.html.twig` | Extend `layouts/archive.html.twig` |
+| `brands/shortcodes/brands-a-z.php` | `brands/shortcodes/brands-a-z.html.twig` | Letter nav + `row` grid of brand cards |
+| `brands/shortcodes/single-brand.php` | `brands/shortcodes/single-brand.html.twig` | Brand card |
+
+#### 9.2 Auth (OAuth)
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `auth/form-login.php` | `auth/form-login.html.twig` | Extend `layouts/form.html.twig` |
+| `auth/form-grant-access.php` | `auth/form-grant-access.html.twig` | `card` with scope list + approve/deny buttons |
+
+#### 9.3 Back-in-Stock
+
+| WooCommerce Template | Theme Override | Bootstrap 5 Mapping |
+| -------------------- | -------------- | -------------------- |
+| `single-product/back-in-stock-form.php` | `single-product/back-in-stock-form.html.twig` | `card card-body` with email `input-group` |
+
+---
+
+## CSS Strategy
+
+### File: `assets/css/wc-bootstrap.css`
+
+Additions needed per phase:
+
+| Phase | CSS Additions |
+| ----- | ------------- |
+| 1 | Quantity input-group sizing; notice icon spacing |
+| 2 | Product card hover lift effect; sale badge positioning; star rating colours |
+| 3 | Product gallery thumbnail grid; tab content transitions; variation swatches |
+| 4 | Cart item thumbnail sizing; mini-cart offcanvas width |
+| 5 | Checkout sticky sidebar offset; payment method description animation |
+| 6 | Account navigation active state; order status badge colours |
+| 8 | Email inline styles (separate `wc-email-*` classes, no Bootstrap dependency) |
+
+### WooCommerce CSS Overrides
+
+WooCommerce ships its own CSS that conflicts with Bootstrap. Key overrides:
+
+```css
+/* Reset WooCommerce grid in favour of Bootstrap */
+.woocommerce ul.products { display: contents; }
+
+/* Ensure Bootstrap form styles take precedence */
+.woocommerce .form-row input.input-text { /* inherit from .form-control */ }
+
+/* Price styling consistency */
+.woocommerce .price del { @extend .text-decoration-line-through, .text-body-secondary; }
+.woocommerce .price ins { text-decoration: none; @extend .text-danger, .fw-bold; }
+```
+
+### Dark Mode
+
+All templates use Bootstrap's adaptive utilities (`bg-body-tertiary`, `text-body-secondary`, `border-*`) which automatically adapt via `data-bs-theme="dark"`. No manual dark-mode CSS should be needed except for:
+
+- Custom sale badge colours
+- Star rating fill colour
+- Email templates (separate palette)
+
+---
+
+## JavaScript Strategy
+
+Minimal custom JS. Bootstrap 5 JS (from parent theme) handles:
+
+- Offcanvas (mini-cart, mobile sidebar)
+- Collapse (shipping calculator, coupon form, login form)
+- Tabs (product tabs)
+- Modal (image lightbox, if replacing PhotoSwipe)
+- Tooltips/popovers (optional)
+- Alert dismiss (notices)
+
+Custom JS needed for:
+
+| Feature | Location | Purpose |
+| ------- | -------- | ------- |
+| Quantity +/- buttons | `assets/js/quantity.js` | Increment/decrement input value, trigger `change` event for WC JS |
+| Variation swatches | `assets/js/variations.js` | Sync Bootstrap form-select with WC variation JS (if needed) |
+| Mini-cart AJAX | `assets/js/mini-cart.js` | Update offcanvas cart count after add-to-cart |
+| Sticky cart totals | Inline or CSS-only | `position: sticky; top: 1rem` on checkout/cart sidebar |
+
+---
+
+## Template Naming Convention
+
+All theme overrides mirror the plugin's directory structure exactly:
+
+```txt
+woocommerce/templates/cart/cart.php
+  --> wc-bootstrap/templates/cart/cart.html.twig
+
+woocommerce/templates/single-product/tabs/tabs.php
+  --> wc-bootstrap/templates/single-product/tabs/tabs.html.twig
+```
+
+---
+
+## Component Reuse Map
+
+Common Bootstrap patterns extracted into reusable Twig components:
+
+| Component | File | Used By |
+| --------- | ---- | ------- |
+| Product card | `components/card.html.twig` | Archive, related, cross-sells, up-sells |
+| Pagination | `components/pagination.html.twig` | Archive, orders, downloads |
+| Price display | `components/price.html.twig` | Loop, single product, cart, order details |
+| Star rating | `components/rating.html.twig` | Loop, single product |
+| Address card | `components/address-card.html.twig` | My Account addresses, order details, checkout |
+| Status badge | `components/status-badge.html.twig` | Orders list, view order |
+| Quantity input | `components/quantity-input.html.twig` | Cart, single product add-to-cart |
+| Form field | `components/form-field.html.twig` | Checkout, account forms, address forms |
+
+---
+
+## Order Status Badge Colours
+
+| Status | Bootstrap Class |
+| ------ | --------------- |
+| Pending | `bg-warning text-dark` |
+| Processing | `bg-info text-dark` |
+| On Hold | `bg-secondary` |
+| Completed | `bg-success` |
+| Cancelled | `bg-danger` |
+| Refunded | `bg-dark` |
+| Failed | `bg-danger` |
+
+---
+
+## Accessibility Checklist
+
+Every template must meet:
+
+- [ ] Semantic HTML (`<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`)
+- [ ] ARIA labels on interactive elements (`aria-label`, `aria-expanded`, `aria-current`)
+- [ ] `sr-only` / `visually-hidden` for icon-only buttons
+- [ ] Focus-visible styles (Bootstrap default)
+- [ ] Keyboard navigation for custom widgets (quantity buttons, variation selects)
+- [ ] Colour contrast ratio >= 4.5:1 (Bootstrap defaults meet this)
+- [ ] Form labels associated with inputs (`for`/`id` pairs)
+- [ ] Error messages linked to fields via `aria-describedby`
+
+---
+
+## Testing Strategy
+
+Since Docker is not yet available, testing follows a manual / staged approach:
+
+### Per-Template Checklist
+
+1. **Visual review** -- Load page in browser, verify Bootstrap 5 styling applied
+2. **Responsive check** -- Test at 320px, 768px, 1024px, 1440px breakpoints
+3. **Dark mode** -- Toggle `data-bs-theme="dark"`, verify all elements adapt
+4. **Functionality** -- All forms submit, AJAX works, WC JS hooks fire
+5. **Accessibility** -- Tab through page, check screen reader output
+6. **No regressions** -- Existing WooCommerce features still work (add to cart, checkout flow, etc.)
+
+### Integration Test Flow
+
+Once multiple phases are complete, test the full customer journey:
+
+1. Browse shop archive --> filter --> view product
+2. Select variation --> add to cart --> view cart
+3. Update quantity --> apply coupon --> proceed to checkout
+4. Fill billing/shipping --> select payment --> place order
+5. View thank-you page --> check email
+6. Log in to My Account --> view order --> manage addresses
+
+---
+
+## Estimated Template Count by Phase
+
+| Phase | Templates | Priority |
+| ----- | --------- | -------- |
+| 1 -- Global & Notices | 9 | Critical |
+| 2 -- Archive & Loop | 15 | Critical |
+| 3 -- Single Product | 21 | Critical |
+| 4 -- Cart | 9 | High |
+| 5 -- Checkout | 12 | High |
+| 6 -- My Account | 17 | Medium |
+| 7 -- Order Details | 5 | Medium |
+| 8 -- Emails | ~30 | Low |
+| 9 -- Supplementary | 7 | Low |
+| **Total** | **~125** | |
+
+New reusable components to create: **8**
+
+**Note:** Not all 233 WooCommerce templates need overrides. Block templates (`templates/templates/`, `parts/`), block-notice variants, and email plain-text variants are excluded or deferred. The ~125 count covers all customer-facing PHP templates that produce visible HTML.
+
+---
+
+## Dependencies & Blockers
+
+| Dependency | Status | Impact |
+| ---------- | ------ | ------ |
+| Docker environment | Not set up | Cannot test WP-CLI, i18n extraction; use local PHP server |
+| WooCommerce plugin Twig layer | Required | `TemplateOverride` depends on `Magdev\Woocommerce\Frontend\Template` |
+| Parent theme Twig functions | Available | `__()`, `esc_html()`, `esc_attr()`, etc. registered by `TwigService` |
+| Bootstrap 5 CSS/JS | Available | Loaded by parent theme `wp-bootstrap` |
+| Composer autoloader | Available | PSR-4 for `WcBootstrap\` namespace |
+
+---
+
+## File Checklist
+
+Track completion per file. Mark with `[x]` when done.
+
+### Phase 1 -- Global & Notices
+
+- [ ] `global/wrapper-start.html.twig`
+- [ ] `global/wrapper-end.html.twig`
+- [ ] `global/breadcrumb.html.twig`
+- [ ] `global/sidebar.html.twig`
+- [ ] `global/quantity-input.html.twig`
+- [ ] `global/form-login.html.twig`
+- [ ] `notices/notice.html.twig`
+- [ ] `notices/error.html.twig`
+- [ ] `notices/success.html.twig`
+
+### Phase 2 -- Archive & Loop
+
+- [ ] `archive-product.html.twig`
+- [ ] `content-product.html.twig`
+- [ ] `content-product-cat.html.twig`
+- [ ] `product-searchform.html.twig`
+- [ ] `loop/loop-start.html.twig`
+- [ ] `loop/loop-end.html.twig`
+- [ ] `loop/header.html.twig`
+- [ ] `loop/result-count.html.twig`
+- [ ] `loop/orderby.html.twig`
+- [ ] `loop/pagination.html.twig`
+- [ ] `loop/no-products-found.html.twig`
+- [ ] `loop/add-to-cart.html.twig`
+- [ ] `loop/price.html.twig`
+- [ ] `loop/rating.html.twig`
+- [ ] `loop/sale-flash.html.twig`
+
+### Phase 3 -- Single Product
+
+- [ ] `single-product/product-image.html.twig`
+- [ ] `single-product/title.html.twig`
+- [ ] `single-product/price.html.twig`
+- [ ] `single-product/short-description.html.twig`
+- [ ] `single-product/meta.html.twig`
+- [ ] `single-product/rating.html.twig`
+- [ ] `single-product/stock.html.twig`
+- [ ] `single-product/sale-flash.html.twig`
+- [ ] `single-product/share.html.twig`
+- [ ] `single-product/product-attributes.html.twig`
+- [ ] `single-product/related.html.twig`
+- [ ] `single-product/up-sells.html.twig`
+- [ ] `single-product/add-to-cart/simple.html.twig`
+- [ ] `single-product/add-to-cart/variable.html.twig`
+- [ ] `single-product/add-to-cart/grouped.html.twig`
+- [ ] `single-product/add-to-cart/external.html.twig`
+- [ ] `single-product/add-to-cart/variation.html.twig`
+- [ ] `single-product/add-to-cart/variation-add-to-cart-button.html.twig`
+- [ ] `single-product/tabs/tabs.html.twig`
+- [ ] `single-product/tabs/description.html.twig`
+- [ ] `single-product/tabs/additional-information.html.twig`
+
+### Phase 4 -- Cart
+
+- [ ] `cart/cart.html.twig`
+- [ ] `cart/cart-empty.html.twig`
+- [ ] `cart/cart-item-data.html.twig`
+- [ ] `cart/cart-totals.html.twig`
+- [ ] `cart/cart-shipping.html.twig`
+- [ ] `cart/cross-sells.html.twig`
+- [ ] `cart/mini-cart.html.twig`
+- [ ] `cart/proceed-to-checkout-button.html.twig`
+- [ ] `cart/shipping-calculator.html.twig`
+
+### Phase 5 -- Checkout
+
+- [ ] `checkout/form-checkout.html.twig`
+- [ ] `checkout/form-billing.html.twig`
+- [ ] `checkout/form-shipping.html.twig`
+- [ ] `checkout/form-coupon.html.twig`
+- [ ] `checkout/form-login.html.twig`
+- [ ] `checkout/review-order.html.twig`
+- [ ] `checkout/payment.html.twig`
+- [ ] `checkout/payment-method.html.twig`
+- [ ] `checkout/terms.html.twig`
+- [ ] `checkout/thankyou.html.twig`
+- [ ] `checkout/order-received.html.twig`
+- [ ] `checkout/cart-errors.html.twig`
+
+### Phase 6 -- My Account
+
+- [ ] `myaccount/my-account.html.twig`
+- [ ] `myaccount/navigation.html.twig`
+- [ ] `myaccount/dashboard.html.twig`
+- [ ] `myaccount/orders.html.twig`
+- [ ] `myaccount/view-order.html.twig`
+- [ ] `myaccount/my-address.html.twig`
+- [ ] `myaccount/form-edit-address.html.twig`
+- [ ] `myaccount/form-edit-account.html.twig`
+- [ ] `myaccount/downloads.html.twig`
+- [ ] `myaccount/payment-methods.html.twig`
+- [ ] `myaccount/form-add-payment-method.html.twig`
+- [ ] `myaccount/form-login.html.twig`
+- [ ] `myaccount/form-lost-password.html.twig`
+- [ ] `myaccount/form-reset-password.html.twig`
+- [ ] `myaccount/lost-password-confirmation.html.twig`
+
+### Phase 7 -- Order Details
+
+- [ ] `order/order-details.html.twig`
+- [ ] `order/order-details-item.html.twig`
+- [ ] `order/order-details-customer.html.twig`
+- [ ] `order/form-tracking.html.twig`
+- [ ] `order/order-again.html.twig`
+
+### Phase 8 -- Emails
+
+- [ ] `emails/email-header.html.twig`
+- [ ] `emails/email-footer.html.twig`
+- [ ] `emails/email-styles.html.twig`
+- [ ] `emails/email-order-details.html.twig`
+- [ ] `emails/email-order-items.html.twig`
+- [ ] `emails/email-customer-details.html.twig`
+- [ ] `emails/email-addresses.html.twig`
+- [ ] `emails/email-downloads.html.twig`
+- [ ] `emails/customer-processing-order.html.twig`
+- [ ] `emails/customer-completed-order.html.twig`
+- [ ] `emails/customer-on-hold-order.html.twig`
+- [ ] `emails/customer-new-account.html.twig`
+- [ ] `emails/customer-reset-password.html.twig`
+- [ ] `emails/customer-invoice.html.twig`
+- [ ] `emails/customer-note.html.twig`
+- [ ] `emails/customer-refunded-order.html.twig`
+- [ ] `emails/customer-cancelled-order.html.twig`
+- [ ] `emails/customer-failed-order.html.twig`
+- [ ] `emails/admin-new-order.html.twig`
+- [ ] `emails/admin-cancelled-order.html.twig`
+- [ ] `emails/admin-failed-order.html.twig`
+
+### Phase 9 -- Supplementary
+
+- [ ] `brands/brand-description.html.twig`
+- [ ] `brands/taxonomy-product_brand.html.twig`
+- [ ] `brands/shortcodes/brands-a-z.html.twig`
+- [ ] `brands/shortcodes/single-brand.html.twig`
+- [ ] `auth/form-login.html.twig`
+- [ ] `auth/form-grant-access.html.twig`
+- [ ] `single-product/back-in-stock-form.html.twig`
+
+### Reusable Components
+
+- [ ] `components/price.html.twig`
+- [ ] `components/rating.html.twig`
+- [ ] `components/address-card.html.twig`
+- [ ] `components/status-badge.html.twig`
+- [ ] `components/quantity-input.html.twig`
+- [ ] `components/form-field.html.twig`