# 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-to-Twig bridge | Implemented | `TemplateOverride` intercepts `wc_get_template()` via before/after hooks; `WooCommerceExtension` provides ~50 Twig functions and 7 filters |
| 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

- [x] `global/wrapper-start.html.twig`
- [x] `global/wrapper-end.html.twig`
- [x] `global/breadcrumb.html.twig`
- [x] `global/sidebar.html.twig`
- [x] `global/quantity-input.html.twig`
- [x] `global/form-login.html.twig`
- [x] `notices/notice.html.twig`
- [x] `notices/error.html.twig`
- [x] `notices/success.html.twig`

### Phase 2 -- Archive & Loop

- [x] `archive-product.html.twig`
- [x] `content-product.html.twig`
- [x] `content-product-cat.html.twig`
- [x] `product-searchform.html.twig`
- [x] `loop/loop-start.html.twig`
- [x] `loop/loop-end.html.twig`
- [x] `loop/header.html.twig`
- [x] `loop/result-count.html.twig`
- [x] `loop/orderby.html.twig`
- [x] `loop/pagination.html.twig`
- [x] `loop/no-products-found.html.twig`
- [x] `loop/add-to-cart.html.twig`
- [x] `loop/price.html.twig`
- [x] `loop/rating.html.twig`
- [x] `loop/sale-flash.html.twig`

### Phase 3 -- Single Product

- [x] `single-product/product-image.html.twig`
- [x] `single-product/title.html.twig`
- [x] `single-product/price.html.twig`
- [x] `single-product/short-description.html.twig`
- [x] `single-product/meta.html.twig`
- [x] `single-product/rating.html.twig`
- [x] `single-product/stock.html.twig`
- [x] `single-product/sale-flash.html.twig`
- [x] `single-product/share.html.twig`
- [x] `single-product/product-attributes.html.twig`
- [x] `single-product/related.html.twig`
- [x] `single-product/up-sells.html.twig`
- [x] `single-product/add-to-cart/simple.html.twig`
- [x] `single-product/add-to-cart/variable.html.twig`
- [x] `single-product/add-to-cart/grouped.html.twig`
- [x] `single-product/add-to-cart/external.html.twig`
- [x] `single-product/add-to-cart/variation.html.twig`
- [x] `single-product/add-to-cart/variation-add-to-cart-button.html.twig`
- [x] `single-product/tabs/tabs.html.twig`
- [x] `single-product/tabs/description.html.twig`
- [x] `single-product/tabs/additional-information.html.twig`

### Phase 4 -- Cart

- [x] `cart/cart.html.twig`
- [x] `cart/cart-empty.html.twig`
- [x] `cart/cart-item-data.html.twig`
- [x] `cart/cart-totals.html.twig`
- [x] `cart/cart-shipping.html.twig`
- [x] `cart/cross-sells.html.twig`
- [x] `cart/mini-cart.html.twig`
- [x] `cart/proceed-to-checkout-button.html.twig`
- [x] `cart/shipping-calculator.html.twig`

### Phase 5 -- Checkout

- [x] `checkout/form-checkout.html.twig`
- [x] `checkout/form-billing.html.twig`
- [x] `checkout/form-shipping.html.twig`
- [x] `checkout/form-coupon.html.twig`
- [x] `checkout/form-login.html.twig`
- [x] `checkout/review-order.html.twig`
- [x] `checkout/payment.html.twig`
- [x] `checkout/payment-method.html.twig`
- [x] `checkout/terms.html.twig`
- [x] `checkout/thankyou.html.twig`
- [x] `checkout/order-received.html.twig`
- [x] `checkout/cart-errors.html.twig`

### Phase 6 -- My Account

- [x] `myaccount/my-account.html.twig`
- [x] `myaccount/navigation.html.twig`
- [x] `myaccount/dashboard.html.twig`
- [x] `myaccount/orders.html.twig`
- [x] `myaccount/view-order.html.twig`
- [x] `myaccount/my-address.html.twig`
- [x] `myaccount/form-edit-address.html.twig`
- [x] `myaccount/form-edit-account.html.twig`
- [x] `myaccount/downloads.html.twig`
- [x] `myaccount/payment-methods.html.twig`
- [x] `myaccount/form-add-payment-method.html.twig`
- [x] `myaccount/form-login.html.twig`
- [x] `myaccount/form-lost-password.html.twig`
- [x] `myaccount/form-reset-password.html.twig`
- [x] `myaccount/lost-password-confirmation.html.twig`

### Phase 7 -- Order Details

- [x] `order/order-details.html.twig`
- [x] `order/order-details-item.html.twig`
- [x] `order/order-details-customer.html.twig`
- [x] `order/form-tracking.html.twig`
- [x] `order/order-again.html.twig`

### Phase 8 -- Emails (SKIPPED)

Skipped: WooCommerce email templates use `wc_get_template_html()` which bypasses
the Twig rendering pipeline. Email overrides would require traditional PHP files
in `woocommerce/emails/`, breaking the Twig-only pattern. Default WooCommerce
email templates are sufficient; email customization can be handled via plugins
(e.g., Kadence WooCommerce Email Designer) or the WooCommerce block email editor.

### Phase 9 -- Supplementary

- [x] `brands/brand-description.html.twig`
- [x] `brands/taxonomy-product_brand.html.twig`
- [x] `brands/shortcodes/brands-a-z.html.twig`
- [x] `brands/shortcodes/single-brand.html.twig`
- [x] `auth/form-login.html.twig`
- [x] `auth/form-grant-access.html.twig`
- [x] `single-product/back-in-stock-form.html.twig`

### Reusable Components

- [x] `components/price.html.twig`
- [x] `components/rating.html.twig`
- [x] `components/address-card.html.twig`
- [x] `components/status-badge.html.twig`
- [x] `components/quantity-input.html.twig`
- [x] `components/form-field.html.twig`