287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
# Preview Sites — Agent Rule
|
||
|
||
How to create client preview websites in this repo. Follow this every time you scaffold or expand a proposal.
|
||
|
||
**Canonical feature + pricing catalog:** [`features.md`](features.md)
|
||
**Human overview:** [`README.md`](README.md)
|
||
|
||
---
|
||
|
||
## Goal
|
||
|
||
Ship a **portable static mockup** that sells the Django product: public marketing site + client portal (with UTM) + optional monetized add-ons. Prospects click through screens and pick features on a pricing page.
|
||
|
||
Do **not** invent new product features or prices. Read `features.md` and use those names, deps, and dollar amounts.
|
||
|
||
---
|
||
|
||
## Hard rules
|
||
|
||
1. **Static only** — HTML/CSS/JS; relative asset paths; no backend required to view.
|
||
2. **No secrets** — no API keys, passwords, real customer PII, or live credentials.
|
||
3. **Concept labeled** — fixed “UX Concept Preview” (or proposal) banner on public pages; link to `ux-gallery.html` + `pricing.html`.
|
||
4. **Kebab-case folders** — `proposals/<client-name>/` (e.g. `eds-plumbing-and-sewer`).
|
||
5. **Templates stay generic** — no client names/branding in `templates/`.
|
||
6. **Monetization from catalog** — build + monthly fees and dependency rules come from `features.md` only.
|
||
7. **UTM is base** — every portal includes UTM; never sell it as a separate add-on.
|
||
8. **Deps** — Payments requires Email & SMS; AI social requires Social consolidation (auto-select / block on pricing page).
|
||
9. **Vendor credit in footer** — every preview page footer (marketing, portal, gallery, pricing) must include:
|
||
`Made by [AI ML Operations, LLC](https://aimloperations.com)`
|
||
HTML form:
|
||
```html
|
||
Made by <a href="https://aimloperations.com" rel="noopener noreferrer" target="_blank">AI ML Operations, LLC</a>
|
||
```
|
||
Link the company name only. Do not omit on new pages.
|
||
10. **Lighthouse on first shot** — public homepage must hit these targets before calling the mockup done:
|
||
- **SEO ≥ 100**
|
||
- **Accessibility ≥ 90** (prefer 95+)
|
||
- **Performance ≥ 50** on throttled mobile (prefer 65+; template-heavy sites rarely hit 90 without image rebuild)
|
||
|
||
Follow [SEO](#seo-public-marketing), [Accessibility](#accessibility), and [Performance](#performance) below. Re-run Lighthouse after major homepage changes.
|
||
|
||
---
|
||
|
||
## Product shape (from features.md)
|
||
|
||
```text
|
||
BASE (always on)
|
||
Public: Landing · About · Contact (+ 404 / under construction as needed)
|
||
Portal: Login · Dashboard · Leads · Lead detail · UTM analytics
|
||
|
||
ADD-ONS (build $ + monthly $)
|
||
Email & SMS · Direct mail · Blog · Payments (Stripe)
|
||
Social consolidation · AI social generator (Ollama)
|
||
```
|
||
|
||
Pricing amounts, screen file hints, and checklists: **open `features.md`** — do not hardcode stale numbers in this rule if they drift; copy from the catalog when writing `SCOPE.md` / `pricing.html`.
|
||
|
||
---
|
||
|
||
## New client checklist
|
||
|
||
```text
|
||
proposals/<client-name>/
|
||
├── mockup/
|
||
│ ├── index.html # marketing entry (or public-home.html)
|
||
│ ├── ux-gallery.html # REQUIRED — card per screen, grouped by feature
|
||
│ ├── pricing.html # REQUIRED — interactive picker + live totals
|
||
│ ├── ux-planned.html # stubs for screens not designed yet
|
||
│ ├── assets/css/ux-hub.css # gallery/pricing styles (copy from an existing proposal)
|
||
│ └── …public & portal pages
|
||
└── proposal/
|
||
├── NOTES.md # client facts, sources, contact data status
|
||
└── SCOPE.md # recommended features + quote math from features.md
|
||
```
|
||
|
||
### Steps
|
||
|
||
1. Create folders above.
|
||
2. Copy closest `templates/<name>/` into `mockup/` (omit template docs/junk).
|
||
3. Brand the **public** site (copy, colors, logo, services, contact). Prefer real approved data; mark placeholders clearly.
|
||
4. Apply **SEO + Accessibility + Performance** on public marketing pages (see checklists). Homepage Lighthouse: SEO 100, a11y ≥ 90, perf ≥ 50.
|
||
5. Add **ux-gallery.html** — monica-style hub: eyebrow per feature (`Public · base`, `Portal · base`, `Portal · Email/SMS`, …). Ready screens link to real HTML; unfinished → `ux-planned.html?p=<key>`.
|
||
6. Add **pricing.html** — base rows locked on; add-ons toggleable; enforce deps; show one-time + monthly totals; disclaimer that usage (Stripe/SMS/postage) is extra.
|
||
7. Write **SCOPE.md** — recommend add-ons for *this* business; compute totals from `features.md` prices.
|
||
8. Write **NOTES.md** — client identity, sources, sitemap, preview reminder, next passes.
|
||
9. Banner on marketing pages → gallery + pricing links.
|
||
10. Add the client row to the **Active previews** table in `README.md` (business, phone, email, preview URL). Use `_TBD_` for unknown phone/email.
|
||
11. Smoke-test locally; run Lighthouse SEO + accessibility + performance on the homepage.
|
||
|
||
### Reuse
|
||
|
||
Copy gallery/pricing/stub patterns from:
|
||
|
||
- `proposals/eds-plumbing-and-sewer/mockup/`
|
||
- `proposals/paint-to-please/mockup/`
|
||
- `proposals/select-electrical/mockup/`
|
||
|
||
---
|
||
|
||
## SEO (public marketing)
|
||
|
||
Ship Lighthouse SEO **100** on the public homepage on the first pass. Portal / gallery / pricing pages are secondary (still need titles + footer credit).
|
||
|
||
### Required on every public HTML page
|
||
|
||
| Item | Rule |
|
||
|------|------|
|
||
| `<html lang="en">` | Always set `lang`. |
|
||
| Unique `<title>` | Include business name + page topic + city/region when known. Do **not** reuse one generic title on every page. |
|
||
| Meta description | 1–2 sentences, ~120–160 chars, business + service + locale. Required on homepage; required on About, Contact, Services, and each service page. |
|
||
| Viewport | `width=device-width, initial-scale=1`. **Do not** use `user-scalable=0` or `maximum-scale=1` (hurts a11y; not needed for SEO). |
|
||
| Image `alt` | Meaningful alt on content images; decorative icons may use `alt=""`. |
|
||
| Crawlable links | Real `href` to real pages (or `#section`). Prefer no empty `#` CTAs for primary nav/services. |
|
||
|
||
### Homepage extras (do these on `index.html`)
|
||
|
||
```html
|
||
<meta name="robots" content="index, follow">
|
||
<link rel="canonical" href="https://<client>-preview.aimloperations.com/">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:title" content="…same as title…">
|
||
<meta property="og:description" content="…">
|
||
<meta property="og:url" content="https://<client>-preview.aimloperations.com/">
|
||
<meta property="og:locale" content="en_US">
|
||
<meta name="twitter:card" content="summary">
|
||
<meta name="twitter:title" content="…">
|
||
<meta name="twitter:description" content="…">
|
||
```
|
||
|
||
Add **JSON-LD** (`application/ld+json`) for the local business — use the closest schema.org type (`PlumbingService`, `Electrician`, `HousePainter`, `LocalBusiness`, etc.) with `name`, `url`, `telephone`, `email` (if known), `address`, `areaServed`, and a short `description`. Match phone/email to what’s shown on the page and to the README Active previews row.
|
||
|
||
### Descriptive link text (Lighthouse `link-text`)
|
||
|
||
**Never** use these as the only visible link text:
|
||
|
||
- Learn more / Learn More / LEARN MORE
|
||
- Click here / Click this
|
||
- More / Here / This / Go / Start / Right here
|
||
|
||
**Do** name the destination, e.g.:
|
||
|
||
- `Water heater services` → `water-heaters.html`
|
||
- `Lighting installation details` → `lighting-installation.html`
|
||
- `View plumbing services` → `services.html`
|
||
|
||
Service-card links must point to the **correct** service page (not one shared wrong URL for every card).
|
||
|
||
### Quick Lighthouse check
|
||
|
||
```bash
|
||
npx lighthouse@12 "https://<preview-host>/" \
|
||
--only-categories=seo,accessibility,performance \
|
||
--chrome-flags="--headless --no-sandbox"
|
||
# or local:
|
||
python3 -m http.server 8765
|
||
npx lighthouse@12 "http://127.0.0.1:8765/proposals/<client>/mockup/" \
|
||
--only-categories=seo,accessibility,performance \
|
||
--chrome-flags="--headless --no-sandbox"
|
||
```
|
||
|
||
Fix SEO audits with score < 1. Fix accessibility fails with weight > 0 until ≥ 90. Apply performance checklist until ≥ 50 (prefer 65+).
|
||
|
||
### Reference implementations
|
||
|
||
Homepages that already follow this pattern:
|
||
|
||
- `proposals/eds-plumbing-and-sewer/mockup/index.html`
|
||
- `proposals/paint-to-please/mockup/index.html`
|
||
- `proposals/select-electrical/mockup/index.html`
|
||
|
||
---
|
||
|
||
## Accessibility
|
||
|
||
Target Lighthouse **Accessibility ≥ 90** (prefer 95+) on the public homepage.
|
||
|
||
### Required
|
||
|
||
| Item | Rule |
|
||
|------|------|
|
||
| Icon-only controls | Every icon-only `<a>` / `<button>` needs `aria-label` (social, search, menu, carousel dots, overlay “+” links). Hide decorative icons with `aria-hidden="true"`. |
|
||
| Form controls | Every `<select>` / meaningful `<input>` has a visible `<label>` or `aria-label` / `aria-labelledby`. |
|
||
| Color contrast | Body text, footer links, CTAs, and muted labels must meet WCAG AA vs their background. Lighten footer links on dark footers; darken low-contrast primary buttons. |
|
||
| Links in text | Concept-banner and in-paragraph links need more than color alone — use **underline** (`.preview-concept-banner a { text-decoration: underline }`). |
|
||
| Touch targets | Interactive controls ≥ ~24×24px (carousel dots often fail — enlarge hit area). |
|
||
| Images | Content images have meaningful `alt`; decorative may use `alt=""`. Logo links whose `<img>` is CSS-hidden need `aria-label` on the `<a>`. |
|
||
| Heading order | Prefer sequential `h1 → h2 → h3` without skipping. Template leftovers that skip a level are lower priority than contrast/names, but fix when easy (e.g. section eyebrow as `<p>` not `h4`). |
|
||
|
||
### Carousel / third-party widgets
|
||
|
||
Owl/Swiper dots are often nameless. After init, set `aria-label="Carousel slide N"` on each dot button (small deferred script is fine).
|
||
|
||
---
|
||
|
||
## Performance
|
||
|
||
Target Lighthouse **Performance ≥ 50** on simulated mobile (prefer **65+**). Template kits with Bootstrap + many plugins rarely reach 90 — still apply every item below.
|
||
|
||
### Images (highest ROI)
|
||
|
||
- Compress large JPEGs (quality ~75–80, longest edge ≤ ~1400–1600 for heroes, ≤ ~900 for cards).
|
||
- Shrink oversized logos (often tiny on-screen but hundreds of KB on disk).
|
||
- `loading="lazy"` + `decoding="async"` on **below-fold** images; keep LCP/hero eager.
|
||
- Explicit `width` and `height` on logos and major images to limit CLS.
|
||
- Prefer WebP/AVIF when adding new assets; when stuck with a template JPG/PNG, at least resize + recompress.
|
||
|
||
### CSS / fonts / JS
|
||
|
||
- Keep only critical CSS render-blocking (main `style.css` + layout framework). Load secondary CSS (AOS, Fancybox, Swiper, Font Awesome CDN, etc.) with:
|
||
```html
|
||
<link rel="stylesheet" href="…" media="print" onload="this.media='all'">
|
||
<noscript><link rel="stylesheet" href="…"></noscript>
|
||
```
|
||
- `rel="preconnect"` to CDNs (`cdnjs`, `fonts.googleapis.com`, `fonts.gstatic.com` with `crossorigin`).
|
||
- Google Fonts: `display=swap`. Local `@font-face`: `font-display: swap`.
|
||
- `defer` site scripts at end of body; drop duplicate Bootstrap/Popper bundles (`bootstrap.bundle` **or** `bootstrap`+`popper`, not both).
|
||
- Avoid loading unused heavy plugins on pages that don’t need them when practical.
|
||
|
||
### CLS / LCP
|
||
|
||
- Don’t lock zoom (`user-scalable=0` / `maximum-scale=1`).
|
||
- Reserve space for images and sticky banners (`padding-top` for concept banner).
|
||
- Preload the true LCP image when it’s an `<img>` (not required for CSS background heroes).
|
||
|
||
### Realistic expectations
|
||
|
||
| Site type | Perf target |
|
||
|-----------|-------------|
|
||
| Lean custom homepage | 70–90 |
|
||
| Third-party HTML template (Bootstrap + carousels + many CSS imports) | 50–70 after image + defer work |
|
||
| Untouched stock template + huge photos | often < 40 — not acceptable |
|
||
|
||
---
|
||
|
||
## UX gallery conventions
|
||
|
||
| Do | Don't |
|
||
|----|--------|
|
||
| One card per screen | Dump all content on one mega-page |
|
||
| Group by feature section | Mix portal + public without labels |
|
||
| Mark Ready vs Planned | Leave dead links |
|
||
| Keep marketing `index.html` working | Replace marketing home with only the hub without a link back |
|
||
|
||
Reference pattern: [monica_site proposal hub](https://git.aimloperations.com/ai_ml_operations/monica_site/src/branch/main/proposal/pages/index.html).
|
||
|
||
---
|
||
|
||
## Pricing page conventions
|
||
|
||
- Always show **Public site** + **Client portal + UTM** (checked, disabled).
|
||
- Checkboxes for each add-on with **build** and **/mo** from `features.md`.
|
||
- Selecting Payments → auto-check Email & SMS (+ short helper text).
|
||
- Selecting AI social → auto-check Social (+ helper text).
|
||
- Unchecking a required parent → uncheck dependent child.
|
||
- Sticky summary: one-time total · monthly total · feature count.
|
||
- Label as draft estimate, not a formal contract.
|
||
|
||
---
|
||
|
||
## Design (public marketing)
|
||
|
||
When building/tailoring the public site (not the portal chrome):
|
||
|
||
- Brand-first first viewport; one composition; full-bleed hero when it’s a landing.
|
||
- Expressive type — avoid Inter/Roboto/Arial/system as the only voice.
|
||
- Atmosphere via image/gradient/pattern — not flat single-color only.
|
||
- Prefer no cards in the hero; one job per section.
|
||
- Mobile + desktop must both work.
|
||
- If extending an existing template look, **preserve that template’s visual language**.
|
||
|
||
Portal mocks can be denser/app-like; still match proposal hub styling (`ux-hub.css`).
|
||
|
||
---
|
||
|
||
## Done means
|
||
|
||
- [ ] `NOTES.md` + `SCOPE.md` exist and match `features.md` pricing
|
||
- [ ] `ux-gallery.html` covers base + every add-on screen (ready or planned)
|
||
- [ ] `pricing.html` totals correct; deps work
|
||
- [ ] Public marketing is client-branded and concept-bannered
|
||
- [ ] SEO: homepage Lighthouse SEO 100; unique titles + meta descriptions on public pages; no vague “Learn more” links; OG/Twitter + JSON-LD on homepage
|
||
- [ ] Accessibility: homepage Lighthouse a11y ≥ 90 — named controls, contrast, underlined banner links, labeled forms, lazy-safe alts
|
||
- [ ] Performance: homepage Lighthouse perf ≥ 50 (prefer 65+) — compressed images, lazy below-fold, deferred secondary CSS/JS, `font-display: swap`, preconnect CDNs
|
||
- [ ] `README.md` Active previews table has business, phone, email, preview URL
|
||
- [ ] Footer credit: Made by [AI ML Operations, LLC](https://aimloperations.com)
|
||
- [ ] No secrets committed; relative paths; opens without a server framework
|