Skip to content
SiteSwarm Platform Documentation

Client App Review

Client Application Review & Editorial Rubric Runbook (CLIENT_APP_REVIEW.md)

1. Executive Summary & Review Framework

Unstructured design feedback (“make it pop”, “looks a bit AI-generated”, “doesn’t feel right”) creates subjective friction, inconsistent quality, and layout drift. This runbook establishes an objective, repeatable protocol for reviewing client applications (apps/*) and pre-awareness prototypes (apps/proto-*) across SiteSwarm.

This runbook is referenced directly within the Prototype skill (.agents/skills/prototype/SKILL.md) and client intake workflows to enforce visual restraint, quiet craftsmanship, and sub-second edge ergonomics before prospect demonstrations or production promotion.

2. The 4-Axis “Red Pen” Editorial Rubric

Every client storefront section is evaluated across four orthogonal axes on a 1-to-5 calibration scale:

  1. Axis 1: Tone & Authenticity — Does the voice reflect humble, quiet authority, or synthetic corporate PR / cheerleader hype?
  2. Axis 2: Visual Restraint & Typographic Hierarchy — Is there typographic discipline and spatial breathing room, or visual noise from pill badges, neon borders, and competing font weights?
  3. Axis 3: Content Genuineness — Are claims backed by concrete craft details, authentic photography, and verifiable facts, or generic platitudes and invented statistics?
  4. Axis 4: Information Architecture & Ergonomics — Does the narrative flow linearly and effortlessly, or are visitors forced to click through accordions and multi-step modal hurdles?

Heuristic Signals Across the Four Axes

Evaluation Axis Defect Signals (Scores 1–2) Restrained Standard (Scores 4–5)
1. Tone & Authenticity Superlatives (“world-class”, “revolutionizing”), adverb stuffing (“seamlessly”), exclamation marks in headings, detached corporate jargon. Grounded practitioner voice, concrete physical or technical details, plainspoken nouns and active verbs.
2. Visual Restraint Stacked multi-colored pill badges above headings, neon glow borders, 4+ font weights in one section, cramped padding. Maximum 2 font families, clear scale hierarchy, generous whitespace rhythm, borders used only for semantic separation.
3. Content Genuineness Invented round-number metrics (“99.999% happiness”), generic 6-card adjective grids (“Fast, Secure, Scalable”), stock handshake clichés. Specific provenance (e.g., fermentation hours, OEM diagnostic tools, real architectural mechanisms) and authentic client facts.
4. IA & Ergonomics Core hours, menus, or case studies hidden inside <details> accordions; multi-step modal wizards for simple inquiries; <44px mobile tap targets. Linear top-to-bottom scannability, zero-click visibility for primary content, one-tap tel: links, and single-step inline inquiry forms.

Scoring & Calibration Scale (1 to 5)

Score Classification Operational Meaning & Gate Action
1 Immediate Veto Blatant AI marketing slop, visual gimmicks, or broken mobile ergonomics. Blocks staging/preview. Strip decorative chrome and rewrite from raw intake facts.
2 Distracting Clutter Contains factual substance but burdened by buzzwords, accordion traps, or badge noise. Requires revision before client review.
3 Acceptable Baseline Factually accurate and responsive, but reads generic or lacks typographic refinement. Passable for early check-in; polish before launch.
4 Polished Professional Grounded voice, disciplined typography, substantiated claims, and frictionless linear flow. Approved for production deployment.
5 Editorial Benchmark Exemplar of quiet mastery, visual restraint, and effortless ergonomics across mobile and desktop. Reference blueprint for the fleet.

3. The Six Universal Negative Constraints (Do’s & Don’ts)

When generating web copy or layouts without explicit boundaries, models regress toward synthetic hype and template clutter. The following negative constraints are strictly enforced:

3.1 Constraint 1: No Corporate Parody or Sycophantic Buzzwords

Copy must read like a seasoned practitioner describing real craft, never like a satirical executive press release.

Banned Phrase / Pattern Restrained Replacement
“Flagship Architecture” / “Mission-Critical Paradigm” Name the system, topology, or service directly
“Master Engineer” / “World-Class Thought Leader” State the actual role (“Software engineer”, “Baker”, “ASE Master Technician”)
“Initiate Direct Dialogue” / “Transmit Inquiry” “Contact us”, “Send an email”, “Get in touch”
“Bespoke Enterprise Solutions” / “Cutting-Edge Synergy” Describe the concrete product or work performed
“Seamlessly Orchestrating” / “Empowering Next-Gen…” Use plain active verbs (“routing”, “baking”, “diagnosing”)

3.2 Constraint 2: No “Badge Disease” (Visual Pill Clutter)

  • Maximum 1 Badge per Card: A card container may contain at most one subtle category tag or eyebrow.
  • No Stacked Multi-Color Pills: Never render clusters of candy-colored technology or status pills on teaser cards.
  • No Pulsing Green Dots on Static Content: Pulsing indicators are reserved strictly for live real-time telemetry streams, never static portfolio cards, menus, or pricing tiers.

3.3 Constraint 3: No Faux-Terminal Chrome or Raw ASCII Boxes

  • No Simulated OS Window Controls: Fake macOS traffic-light dots (🔴 🟡 🟢) and simulated bash prompts are forbidden in editorial and commercial layouts unless a client’s VIBE.md explicitly mandates a CLI theme.
  • No Raw ASCII Box Diagrams in UI: Use semantic HTML tables, clean SVG graphics, or structured typography rather than ragged monospace ASCII borders that break on mobile screens and screen readers.

3.4 Constraint 4: No Hidden Content / Accordion Mazes

  • Primary narratives, service menus, operating hours, and case studies must be laid out directly on the page for effortless linear scanning.
  • Collapsible <details> accordions are restricted to optional secondary FAQs or lengthy legal disclosures—never bury the core story behind clicks.

3.5 Constraint 5: No Security Theater Banners on Forms

  • Bot defense (Cloudflare Turnstile), rate limiting, and encryption run silently in the background.
  • Never surround customer contact or quote forms with paranoid cryptographic war banners (“SHIELDED BY AES-256 ZERO-KNOWLEDGE BOT DEFENSE”). Keep form copy warm, clear, and human.

3.6 Constraint 6: No Synthetic Metrics or Hallucinated Claims

  • Never invent fabricated latency numbers (“< 3ms worldwide”), fake SLA percentages (“99.999% uptime”), or unverified customer counts.
  • Every quantitative claim must trace to verified client facts or empirical measurements; otherwise, state the qualitative architectural property directly.

4. Automated Quality & Accessibility Pre-Flight Gates

Before submitting a client application or prototype for editorial scoring, automated quality gates must be satisfied:

  1. Accessibility (WCAG 2.1 Level AA):
    • Evaluated via headless @axe-core/playwright across canonical mobile (390x844) and desktop (1920x1080) viewports.
    • Zero critical or serious violations permitted across contrast, image alt text, accessible control labels, and keyboard focus order.
  2. Mobile Core Web Vitals Thresholds:
    • Lighthouse Mobile Performance: $\ge 95$
    • First Contentful Paint (FCP): $\le 1.0\text{s}$
    • Largest Contentful Paint (LCP): $\le 1.8\text{s}$
    • Cumulative Layout Shift (CLS): $\le 0.05$
    • Payload Budgets: $\le 50\text{ KB}$ gzipped client JS, $\le 40\text{ KB}$ gzipped CSS.
  3. Semantic HTML & Schema.org:
    • Single <h1> per page with logical hierarchy (<h1> $\to$ <h2> $\to$ <h3>).
    • Validated LocalBusiness Schema.org JSON-LD structured data and OpenGraph metadata.

5. In-Situ Overlay & Critique Tags (@siteswarm/critique)

During live review in staging or preview environments, defects are pinned using the @siteswarm/critique review overlay (CRITIQUE_CAPABILITY.md). Standard tags map directly to the four rubric axes:

  • Too Buzzwordy $\to$ Axis 1 (Tone & Authenticity)
  • Remove Badge / Needs Restraint $\to$ Axis 2 (Visual Restraint & Hierarchy)
  • Copy Edit $\to$ Axis 3 (Content Genuineness)
  • Formatting Issue $\to$ Axis 4 (Information Architecture & Ergonomics)
  • Love This $\to$ Positive anchor preserving high-scoring sections from modification.

Critique defects transition through: open $\to$ addressed $\to$ resolved.

6. Step-by-Step Review Execution Procedure

  1. Run Local Pre-Flight Check:
    Terminal window
    pnpm --filter=@siteswarm/<app> run check
    pnpm run lint:arch
  2. Inspect Dual Viewports: Launch local preview or staging server and verify both viewports:
    • Desktop: 1920x1080 (typography rhythm, column layout, hero hierarchy)
    • Mobile: 390x844 (touch targets $\ge 44\text{px}$, linear scrolling, zero horizontal overflow)
  3. Perform Red Pen Scoring: Evaluate all sections against the 4 axes. If any section scores $\le 2$, flag for remediation before client demonstration.
  4. Enforce Negative Constraints: Search copy for banned buzzwords, count badges per container (max 1), and ensure primary content is not trapped in accordions.
  5. Pin & Track In-Situ Defects: In preview mode, press Ctrl+Shift+C (or mobile floating badge) to open the Critique dock, pin elements, tag defects, and submit review.

Decisions Intentionally Deferred

  • Automated LLM-assisted Red Pen evaluation tooling is tracked for future integration in @siteswarm/governance.