Teach Engineering Wireframes

Problem Statement

Teach Engineering has known usability issues documented across multiple usability studies. The site needs a redesign, and the wireframes ensure that usability findings are systematically incorporated into the new design from the start.

The goal is to produce functional wireframes that:

• Serve as a contract between design and engineering, aligning both teams before either begins full implementation
• Encode usability fixes with documented rationale so design decisions aren't arbitrary
• Give the design team a structural foundation to build on
• Allow engineering to begin structural work before final designs are delivered

Deliverables

• ~10 functional mid-fi wireframes (one per site template), deployed as static HTML/CSS/JS on GitHub Pages
• Per-template usability summaries synthesizing study findings
• Per-template wireframe specs documenting layout decisions and their rationale
• Cross-template navigation so wireframes are clickable end-to-end

Workflow

Phase 1: Usability Synthesis

1. Download usability study materials from Google Drive to local machine
2. Analyze materials using AI-assisted synthesis to identify patterns and prioritize findings
3. For each template, produce a prioritized usability summary:
   • Specific issues identified, with severity (critical/major/minor) and source citation
   • Proposed fixes with rationale
   • Alternatives considered and rejected
   • AI-assisted analysis challenges assumptions, suggests alternatives, and flags potential new issues introduced by fixes

Output: One usability summary doc per template, stored in /docs/usability/

Phase 2: Wireframe Specs

1. Translate usability fixes into concrete wireframe specifications
2. Each spec is designed to serve double duty as both documentation and Lovable prompt input
3. Identify sample data to scrape from the live site for wireframe population
4. Define navigation map connecting all templates

Output: One spec doc per template, stored in /docs/specs/

Phase 3: Wireframe Generation & Refinement

1. Feed each spec into Lovable to generate initial wireframe HTML/CSS/JS
2. Scrape sample data from teachengineering.org to populate wireframes with real content
3. Review output against specs and usability goals
4. Use a code editor for surgical edits in the same repo when Lovable can't handle precise requests
5. Lovable syncs bidirectionally with GitHub — changes made locally and pushed to the repo are incorporated into the Lovable project, and vice versa
6. Deploy to GitHub Pages

Output: Functional wireframes in /public/, live on GitHub Pages

Template Inventory & Data Strategy

Template Audit

Before beginning usability work, catalog all distinct page templates on teachengineering.org (estimated ~10):

• Homepage
• Search/browse results
• Lesson detail
• Activity detail
• Unit overview
• Collection page
• Others TBD from site audit

Map usability findings to templates. Prioritize by severity of issues and user traffic. Templates without usability coverage are designed using best-practice heuristics and patterns established by the templates that do have coverage.

If the audit reveals significantly more than 10 templates, wireframe the highest-priority ones and let remaining templates inherit patterns from their closest match.

Sample Data

• Lovable scrapes real content from the live site via its built-in Firecrawl connector during wireframe generation
• Content is populated directly into the wireframe HTML — no intermediate JSON files needed
• Includes real titles, descriptions, metadata — enough to make wireframes feel authentic
• Specs identify what content to scrape so Lovable knows what to pull

Cross-Template Navigation

• Wireframes link to each other to simulate real site navigation
• Navigation map defined in specs before rendering begins

Per-Template Spec Format

Each template spec follows this structure:

1. Template name & URL — page type and link to live example
2. Usability issues — findings from studies with severity and source citation
3. Proposed changes — what's changing, why, and alternatives rejected
4. Layout spec — content zones top-to-bottom (header, nav, main content, sidebar, footer), contents of each zone, relative sizing
5. Interactions — clickable elements, behaviors (filtering, sorting, navigation)
6. Sample data reference — which JSON file to pull content from
7. Links to other templates — how this page connects to the wireframe set

Sections 4-7 are extracted as the Lovable prompt. Sections 2-3 remain as rationale documentation for humans.

Tools & Roles

Role	Tool	Rationale
UX analysis	AI-assisted synthesis	Synthesize usability data, challenge assumptions, design solutions
Primary renderer	Lovable	Generates mid-fi HTML/CSS/JS wireframes, GitHub sync
Surgical edits	Code editor	Precise code fixes in the shared repo
Hosting	GitHub Pages	Free, static, shareable URL
Data population	Lovable + Firecrawl	Scrapes real content from live site during wireframe generation
Version control	GitHub	Lovable syncs natively; code editor commits directly

Tools Explicitly Not Used

• Figma — adds a translation layer between specs and code; wireframes need to be functional HTML for engineering handoff
• Relume — no HTML export; adds pipeline complexity without matching deliverable format
• Google Stitch — unreliable with URL-based generation

Wireframe Style

• Mid-fidelity: real UI components (buttons, cards, nav bars), not low-fi boxes
• Grayscale: no colors to argue over — focus is on structure and flow
• Populated with real scraped content, not lorem ipsum
• Clickable navigation between all templates
• Desktop viewport only — responsive behavior is out of scope for this phase
• Semantic HTML with basic accessibility (landmarks, heading hierarchy, keyboard-navigable links)
• Not polished enough to be mistaken for final design — clearly a structural starting point

Repository Structure

teachengineering.org/
  docs/
    source-materials/ # Input docs from the existing team (gitignored)
    usability/        # Per-template usability summaries
    specs/            # Per-template wireframe specs, Lovable prompts, workflow design
  public/             # Static wireframe HTML/CSS/JS pages (served by Vite)
  src/                # React app shell (Lovable-generated)

Sequencing

Phases overlap on a per-template basis: once a template's usability summary is complete (Phase 1), its spec can begin (Phase 2) while other templates are still in Phase 1. Similarly, rendering (Phase 3) can begin for a template as soon as its spec is done.

Suggested approach: work through 1-2 templates end-to-end first to validate the workflow before parallelizing the rest.

Review & Handoff

• The wireframe author reviews each wireframe against the spec before it's considered done
• The wireframe author and the engineering team review wireframes together — engineers flag feasibility issues and contribute their deeper familiarity with the site's existing problems; wireframes are revised as needed until both agree
• Design team receives the GitHub Pages URL and the spec docs; they design on top of the wireframe structure
• Engineering receives the same URL and specs; they can begin building page templates and components
• If the design team proposes changes to the wireframe structure, those are discussed against the documented usability rationale — the specs are the basis for the conversation

Success Criteria

1. Design and engineering teams can both review the wireframes and agree on structure
2. Every layout decision traces back to a documented usability finding or rationale
3. The design team has a clear starting point grounded in usability evidence
4. Engineering can begin structural implementation before final designs are delivered
5. Wireframes are accessible via a shared GitHub Pages URL