# Modernisation phase: brief

Author: Claude Fable 5.2. Implementation: Claude Opus 5.5 agents. Date: 2026-11-17.

The owner reviewed working samples of the eight ideas in `docs/DESIGN_PROPOSALS.md` and answered **Yes to all eight**. The samples they approved are in `docs/samples/design-samples.html` (open it; it is the visual reference for this phase). Build what the samples show, in the real site, with the site's own components and tokens. Do not go beyond the eight ideas: no new sections, palettes or effects the owner has not seen.

`docs/PROJECT_OUTLINE.md` still applies for architecture, the content contract and conventions. Its "identical to the original" rule is now relaxed only for the changes listed here.

## Decisions that are NOT yet made (do not implement)

1. **"iDealers in Virginia"** in the Privacy Policy and Terms stays as it is. It is a legal statement and may be correct (company registration); the owner will be asked.
2. **"Stickers & Buyer Guide"** section on Inventory Management stays hidden.
3. **Pricing FAQ answers** for contract length and setup fee: the owner has not supplied them. Never publish placeholder or invented answers.

## The eight ideas, as approved

### 1. Fewer fonts, one type scale
- Two families only: **Poppins** (headings, buttons, labels, navigation) and **Rubik** (body text). Weights 400, 500, 600, 700 (Poppins) and 400, 500 (Rubik) plus Rubik 400 italic if italic text exists.
- Tokens (defined in `resources/css/site.css`, used everywhere): `--font-display`, `--font-body`. Every `font-family` in the project resolves to one of these two. The old per-family tokens (`--font-roboto`, `--font-ubuntu`, ...) and every literal family, including Arial on the home teal band and the system-font stack on visible text, are replaced. Remove the unused woff2 files from `public/fonts/` and their `@font-face` rules and preloads.
- Type scale tokens: `--text-h1: clamp(2.25rem, 4.2vw, 3.5rem)`, `--text-h2: clamp(1.75rem, 3vw, 2.5rem)`, `--text-h3: 1.5rem`, `--text-h4: 1.25rem`, `--text-body: 1rem`, `--text-small: 0.875rem`. Snap each heading and text style to the nearest step and the nearest allowed weight. This is a consistency pass, not a relayout: where snapping would break a pixel-tuned layout (text overflowing a device frame, a button, a card), keep the layout intact and adjust spacing minimally.
- Minimum body text size 16px; nothing readable below 14px.

### 2. Lighter pages and images
- Component contract (already in place as a stub): `<x-media.img src alt width height sizes eager class>`. Every content `<img>` in Blade goes through it.
- A build command generates AVIF and WebP variants at several widths for every raster image in `public/media/` (GD has WebP and AVIF support here; no Imagick) and writes a manifest; the component renders `<picture>` with `srcset`/`sizes`, explicit width/height, lazy loading below the fold, and high priority for the one hero image of each page.
- Heavy CSS background images get WebP/AVIF siblings and are referenced with `image-set()` with a fallback.
- The 9.6 MB promo video must not download any bytes until play is pressed: `preload="none"` with a lightweight poster; the source is attached on click.
- Measure before and after (transfer size per page from a headless Chrome run, and Lighthouse if it can be run) and record real numbers in `docs/qa/performance.md`. No claimed savings without a measurement.

### 3. Mobile Call and Request A Demo bar (phones only, max-width 767px)
- Fixed bottom bar, frosted (backdrop blur with a solid fallback), two buttons: **Call** (`tel:` link to the site's phone number from global content) and **Request A Demo** (to `/request-demo/`). Touch targets at least 48px high. Respects `env(safe-area-inset-bottom)`. The page gets bottom padding so the bar never covers the footer's last line. Hidden on the request-demo page's own form view if it would overlap the form's submit button; hidden while the menu is open. Does not cover the cookie notice (stack them).
- Full-screen mobile menu sliding up: Products and Company groups as labelled sections (no nested accordions), rows at least 48px, Dealership Login as an outlined button at the bottom, focus trapped while open, Escape and the close button close it, body scroll locked.
- The pre-footer block ("#1 DMS Software", "A MODERN MEANING OF DEALERSHIP", Request Demo, Take a Tour), which is hidden on phones today, shows in a compact form on phones.
- Desktop and tablet are unchanged.
- Add `data-track` attributes (`phone_click`, `request_demo`) with `data-track-location="mobile_bar"`.

### 4. Readability and accessibility
- Every text/background pair meets WCAG AA (4.5:1 normal text, 3:1 large text and UI boundaries). Known failures: body grey `#7a7a7a` on white (use `#666666` or darker), white text on teal `#00a795` buttons and bands (use the dark green `#006056` for the fill, or dark text where the teal must stay), small grey footer links on near-black. Fix through tokens, not one-off values. Audit all 15 pages with a script and record the result in `docs/qa/contrast.md`.
- One `h1` per page and no skipped heading levels. Change the tag only; keep the visual size (style by class, not by tag).
- Real alternative text for every content image, written from what the image shows; `alt=""` for decorative ones. All alt texts live in the content files so the owner can edit them. List every new alt text in `docs/review/alt-texts.md` for the owner to review.
- Visible focus styles on every interactive element; skip link; reduced motion still respected.

### 5. Pricing comparison, FAQ, Talk to Sales (Pricing and Design Studio Tool)
- The existing plan cards stay as they are.
- Below them: a comparison table (features as rows, plans as columns), built from the plans' existing feature lines exactly as in the approved sample for Pricing; do the equivalent for the Design Studio plans from their own feature lines. Table content is a `list` field in the content file so the owner can edit it. Horizontally scrollable inside its own container on phones, sticky first column, real `<table>` markup with `scope`, tick icons with accessible names.
- FAQ: a `list` field (question, answer) rendered as accessible disclosure items, and the whole FAQ block renders only when the list has at least one entry. Seed Pricing with exactly one entry, whose answer restates the plans' own support lines: "What support is included in each plan?" / "Starter: Email / Tickets Support. Premium: Live Chat / Email / Tickets Support. Ultimate: 24/7 All Support Methods." Seed Design Studio with none.
- "Not sure which plan fits? Talk to Sales and we will help you choose." strip with a button to `/talk-to-sales/`.

### 6. Copy corrections (exactly these; nothing else is reworded)
| Where | From | To |
|---|---|---|
| Home | Test Drive Calender | Test Drive Calendar |
| Home / plan lists | Inventory Managements | Inventory Management |
| Footer | Design Studio Tools | Design Studio Tool |
| All buttons labelled "Request Demo" | Request Demo | Request A Demo |
| Menu, footer, home | Leads center | Leads Center |
| Home | it has all of the necessary tools | It has all of the necessary tools |
| Privacy Policy | practicable.Your Rights | practicable. Your Rights |
| Footer | © 2024 iDealers | current year, computed at render time |
| IDMS page | "Watch Video" button linking to `#` | opens the promo video in the existing video modal |

### 7. Search snippets and structured data
- Home description becomes: "Run your whole dealership from one cloud platform: inventory, leads, CRM and website. Call 844-444-9363 for a demo."
- IDMS title becomes: "IDMS - iDealers Management System | iDealers".
- Home `og:title` matches the real title (no "Home - " prefix).
- The other over-length descriptions (Pricing, AI Marketing, Design Studio: 161-163 characters) are shortened to at most 155 characters by trimming words, keeping their meaning and keywords. Record every old and new text in `docs/review/seo-texts.md` for the owner's review.
- `SoftwareApplication` JSON-LD gains `offers` for the three Pricing plans (name, price, `priceCurrency: USD`), read from the plan list so an admin price change updates it. Prices must equal the visible prices. `FAQPage` JSON-LD is emitted only when the FAQ has entries.
- Titles at most 60 characters where they are being changed; do not touch titles that already fit.

### 8. Cookie notice with a real choice
- Text: "We use cookies for analytics so we can improve the site. You can accept or decline." with a "Privacy Policy" link, a **Decline** and an **Accept** button of equal prominence. All four strings editable in Global content.
- Decline stores the choice and dispatches the existing `idealers:consent` event with `analytics: false`; the notice does not reappear. Add a small "Cookie settings" link in the footer that reopens it.

## Team and ownership for this phase

| Role | Owns |
|---|---|
| **Site** | `resources/views/layouts/**`, `components/ui/**`, `components/site/**`, `resources/css/site.css`, `resources/css/site/**`, `resources/js/site.js`, `resources/js/site/**`, `public/fonts/**`, views and content for home, about, contact, request-demo, talk-to-sales, privacy-policy, terms-condition, `_global`, error pages. Ideas 1 (tokens, fonts, own pages), 3, 4 (own pages, shared tokens), 6 (own content), 8. |
| **Products** | `components/product/**`, `resources/css/products.css`, `resources/css/products/**`, `resources/js/products.js`, views and content for the seven product pages and pricing. Ideas 1 and 4 on those pages, 5, 6 (own content). |
| **Performance and SEO** | `components/media/**`, `components/seo/**`, `components/analytics/**`, `app/**`, `config/**`, `routes/**`, `public/.htaccess`, `public/js/analytics.js`, the image pipeline and its outputs, `tests/Feature/Seo/**`, `tests/Feature/Security/**`, `tests/Feature/Media/**`. Ideas 2 and 7, and the back-end side of 8. Meta titles and descriptions live in the content files of the other two roles: this role edits only the `meta` array of those files and nothing else in them. |

Shared rules:
- The token names in idea 1 and the `<x-media.img>` props are fixed contracts. Site defines the tokens first; Products uses them by name (they resolve once Site's CSS is in).
- Each role records every intentional change to visible text, links, images, alt text, titles and descriptions in `docs/handoff/changes-{role}.md` (page, old value, new value, which idea). The QA pass uses these to update the parity baseline's approved differences. Parity failures caused by approved changes are expected until then; any other parity difference is a defect.
- Ports: Site 8101, Products 8102, Performance and SEO 8104. Stop only your own server. `npm run build` shares its output; retry on collision.
- Content-Security-Policy is live: no inline handlers, inline scripts need the nonce, no new third-party hosts.
- New content fields follow the content contract (types `text`, `textarea`, `richtext`, `image`, `video`, `url`, `list`), so they appear in the admin automatically.
- No `git`, no `composer require`, no `migrate:fresh`. Do not leave test users or overrides in the database.
- The browser helper for headless Chrome is `scripts/qa/lib/cdp.php` (screenshots: `scripts/qa/screenshots.php`); keep each command short.
- Final report: what was built per idea, how it was verified, what is not finished, and anything that needs the owner.
