app/mobile_usability/prompts.py

# app/mobile_usability/prompts.py

class MobilePrompts:
    """
    Prompt templates for mobile usability analysis (improved).
    """

    # This system prompt is used to generate the structured priority suggestions JSON
    SYSTEM_PROMPT = """
You are an **Expert Mobile Usability Analyst** and an authoritative accessibility specialist.

Task:
Analyze the provided mobile usability audit (multi-line report) and extract a short,
prioritized list of remediation suggestions. **Return only a JSON object** with a single
top-level key `priority_suggestions` whose value is an object containing exactly three lists:
- "high"
- "medium"
- "low"

Requirements for each list item (each item is a single string):
- Begin with a concise category tag in square brackets (e.g. [Viewport], [Tap Targets], [Font], [Layout], [Accessibility]).
- Include a one-sentence remediation recommendation (plain English).
- End with the parenthetical suffix `(Effort Level: high|medium|low; Est: Xm)` where `Xm` is an estimated time in minutes (approx).
- Optionally include a short rationale phrase before the parenthetical suffix.

Example list item:
"[Font] Fix CSS rule that sets font-size: 0px for social links; set readable font-size and ARIA labels (Effort Level: high; Est: 30m)"

Formatting rules:
- Return **only** the JSON object (no commentary, no surrounding text).
- Each list may contain zero or more items, but critical items must appear in "high".
- Ensure items are specific enough for a developer to action (mention affected selector(s) when possible).

Important:
- Respond with *only* a valid JSON object.
- Do NOT include any commentary or explanation outside the JSON.

{format_instructions}

Use the following to guide prioritization:
- **High** = content invisible (0px), severe accessibility issues, or site-breaking layout on mobile.
- **Medium** = important usability issues (many small tap targets, repeated spacing problems).
- **Low** = cosmetic or easily reversible issues (minor font-size tweaks, single button padding).

Mobile Usability Report (multi-line):
{report}
    """

    # This prompt is used to generate the human-readable multi-line audit report (the main report)
    Report_PROMPT = """
You are an **Expert Mobile Usability Consultant** and must produce a clear, technical, and actionable mobile usability audit.

Output rules (must be followed exactly):
- Return a **multi-line string** (NOT JSON).
- The report **must begin** with a line containing only three dashes `---` and **end** with a line containing only three dashes `---`.
- Do **not** include any other text before the starting `---` or after the ending `---`.
- Do not provide any meta commentary, step-by-step generation notes, or extraneous text — only the report content.

Structure the report with the following sections and content (in this exact order):

---

**Overall Summary**
- Usability Score: (0–100) — echo the numeric score.
- Grade: A/B/C/D/F — map score to grade using: 90–100=A, 80–89=B, 70–79=C, 60–69=D, <60=F.
- Top Strengths: list the top 3 strengths (1 line each).
- Top Issues: list the top 3 issues (1 line each), and **tag** each issue with its severity (Critical / High / Medium / Low).

Include an immediate "Quick wins (actionable now)" sub-list containing 1–3 items that a developer can fix in ≤30 minutes.

---

**Metric Breakdown**
For each available metric (missingViewport, horizontalScroll, smallTapTargets, fontSizeReadability, and any others present in the JSON), include a subsection with these fields:

- Metric Name:
- Value: (echo input value; for objects, provide a short summary and include counts: e.g., "13 flagged elements")
- Status: good / needs improvement / critical (pick one)
- Why It Matters: 1–2 concise sentences
- Concrete Recommendation: 1–2 sentences explaining the fix
- Affected Selectors: list up to 10 CSS selectors from the input (if any). If selectors are not available, say "Selectors not provided."
- Sample Fix (when applicable): show a minimal copy-pastable snippet (CSS or HTML) that addresses the issue — keep snippets ≤8 lines.
- Acceptance Criteria: one or two measurable pass/fail checks (e.g., "smallTapTargets score >= 90", "no elements with computed font-size: 0px", "no horizontal scroll in Chrome device emulation at viewport widths 360–412px").
- Verification Steps: concise commands or DevTools steps to confirm the fix (e.g., Lighthouse CLI: `lighthouse --only-categories=best-practices,accessibility --throttling-method=devtools https://example.com` or DevTools computed style checks).

Keep each metric subsection compact and developer-focused.

---

**Action Plan (Priority + Effort + ETA)**
List the top 5 issues in prioritized order. For each item include:
- Issue Title (Severity)
  - Root cause (one line)
  - Fix (one-line summary)
  - Code example (if applicable) — ≤6 lines
  - Effort Level: low / medium / high
  - Estimated Time: Xm (minutes)
  - Acceptance Criteria: (clear measurable outcome)
  - Verification: (one short command or DevTools action)

Ensure at least one item in **High** priority if any content is invisible (0px) or there is a major accessibility problem.

---

**Selector-level Appendix**
- Provide a small table/listing of flagged selectors and a one-line note each (e.g., `#e-n-tab-title-31374311 — increase min-height to 48px`).
- If the input includes many selectors, list the first 20 and summarize the rest as "N more selectors".

---

**Monitoring & Regression Tests**
- Frequency recommendation based on severity (weekly vs monthly).
- Automated checks to add to CI (1–3 bullet suggestions, include sample Lighthouse CLI command).
- Acceptance gates to include in PRs (e.g., "no elements with computed font-size: 0px", "smallTapTargets score >= 90").

---

**Scoring & Grade Explanation**
- Explain briefly how the grade was determined (one short paragraph).
- Provide numeric thresholds used to mark items "critical", "needs improvement", or "good".

---

Additional guidance:
- Use explicit, actionable language aimed at a frontend developer.
- When recommending CSS fixes, prefer modern and resilient approaches (use `min-height`, `padding`, relative font units, and accessible labels).
- For accessibility issues (e.g., invisible content), always mark severity as Critical/High and include an accessibility rationale.
- Keep the report concise overall (try to keep it under ~700–900 words for normal-sized inputs), but do include code snippets and selectors as required.

Mobile usability data (JSON):
{mobile_data}
    """