ai_ml_operations/preview_sites

Fork 0

Files

T

westfarn b19fdee30d added more preview pages and more templates

2026-07-21 07:10:03 -05:00

14 KiB

Raw Permalink Blame History

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
Human overview: 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

Static only — HTML/CSS/JS; relative asset paths; no backend required to view.
No secrets — no API keys, passwords, real customer PII, or live credentials.
Concept labeled — fixed “UX Concept Preview” (or proposal) banner on public pages; link to ux-gallery.html + pricing.html.
Kebab-case folders — proposals/<client-name>/ (e.g. eds-plumbing-and-sewer).
Templates stay generic — no client names/branding in templates/.
Monetization from catalog — build + monthly fees and dependency rules come from features.md only.
UTM is base — every portal includes UTM; never sell it as a separate add-on.
Deps — Payments requires Email & SMS; AI social requires Social consolidation (auto-select / block on pricing page).
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:
```
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.
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, Accessibility, and Performance below. Re-run Lighthouse after major homepage changes.

Product shape (from features.md)

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

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

Create folders above.
Copy closest templates/<name>/ into mockup/ (omit template docs/junk).
Brand the public site (copy, colors, logo, services, contact). Prefer real approved data; mark placeholders clearly.
Apply SEO + Accessibility + Performance on public marketing pages (see checklists). Homepage Lighthouse: SEO 100, a11y ≥ 90, perf ≥ 50.
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>.
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.
Write SCOPE.md — recommend add-ons for this business; compute totals from features.md prices.
Write NOTES.md — client identity, sources, sitemap, preview reminder, next passes.
Banner on marketing pages → gallery + pricing links.
Add the client row to the Active previews table in README.md (business, phone, email, preview URL). Use _TBD_ for unknown phone/email.
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`)

<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

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:
```
<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.

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
No secrets committed; relative paths; opens without a server framework

14 KiB Raw Permalink Blame History Unescape Escape