DES-374: Add lotus-audit-web skill (customer-facing web only)

[OJBoon]

Jira: DES-374 — Lotus Design System (Epic)

Summary

Mirrors lotus-audit-ios for JustPark's customer-facing web surfaces. Same single Figma source of truth, same four-stage pipeline (parallel extract → parallel analyse → optional sub-agents → assembly), same gitignored repo-relative output with optional vault mirror.

Customer-facing scope (per [[JustPark Jargon]])

• frontend/web — main consumer SSR SPA (primary B2C)
• frontend/pay — Quick Pay, no-login payment flow
• justpark/resources/views/{mobile,site,bookings,listings,referrals,auth,static,npp} — legacy PHP/Blade still serving consumer pages
• justpark/public/assets/scss/{app,site} — legacy SCSS asset pipeline

Explicitly out of scope (deferred / different audit)

• Operator portals — Luna (host portal), Solar (internal ops), Terra (business accounts), Enforcement. Future lotus-audit-web-portals.
• B2B components, browser-extension, qr — internal utilities.
• Admin/dashboard/call centre Blade views, email templates (343 files — different styling rules, future audit).
• justpark-ui itself — it defines tokens, doesn't consume them.

Storyblok callout (in the report)

Storyblok-hosted marketing pages + brand partner themes (NCP, O2) can't be scanned via code. Notably: Storyblok intentionally allows Lotus token overrides at runtime via the CSS-custom-property surface exposed in _colors.scss — that's the designed partner-theming mechanism. The report's Scope section flags this as a future token-architecture question (which CSS variables are public override surface vs. internal).

Architecture

.claude/skills/lotus-audit-web/
├── SKILL.md              ← procedure (4-stage mermaid diagram)
├── apps.yaml             ← scan-target manifest, primary/secondary tiers
└── scripts/
    ├── fetch-figma-tokens.mjs   (identical to iOS — single Figma source)
    ├── parse-web-tokens.mjs     NEW: parses justpark-ui SCSS Lotus files
    │                              with CSS-var override-surface detection
    ├── colour-parity.mjs        NEW: Figma ↔ web _colors.scss diff
    ├── scan-web.mjs             NEW: per-app, per-file scanner for
    │                              .tsx / .scss / .css / .blade.php
    ├── token-candidates.mjs     NEW: web-flavoured candidate finder
    │                              (CSS px detection + JSX inline styles)
    └── build-report.mjs         NEW: assembles markdown report

Smoke-test (live repos + Figma)

Full pipeline ran end-to-end against frontend HEAD + justpark HEAD with the Lotus Figma file focused. 353-line report, key headlines:

• 1,210 files scanned across customer-facing surfaces
• 13% Lotus compliance at the top line (vs iOS's 37%)
• 14,329 hardcoded violations dominated by 5,299+ raw Npx SCSS values and 633+ hardcoded font-size: declarations

Findings already surfaced

• 10px × 997 and 20px × 712 uses across web — both already exist on iOS (spacingSemiSmall, spacingXMedium) but not in Figma's Padding collection. Same cross-platform gap iOS already surfaced for 10pt.
• 51 Figma semantic colour tokens have no web equivalent (mostly the expanded Tertiary / Tapped / Link-* semantic layer — same gap iOS has).
• Web radius scale is a perfect match with Figma (vs iOS's broken radiusFull=32).
• Web is sRGB throughout — no P3 conversion needed (one less complexity vs iOS).
• No typography tokens on web yet — biggest single-investment Lotus opportunity per the Recommendations section.

Test plan

• parse-web-tokens.mjs parses 26 primitives + 22 semantic + 9 spacing + 7 radius from @justpark/ui/src/scss/lotus/.
• colour-parity.mjs correctly identifies match / mismatch / missing-web / web-only.
• scan-web.mjs correctly counts compliant + legacy + hardcoded across .tsx + .scss + .blade.php in customer-facing apps.
• token-candidates.mjs surfaces 10px × 997 as a "new-candidate" relative to existing Figma + web tokens.
• build-report.mjs assembles all sections, mermaid diagrams, Storyblok callout, recommendations.
• Mirror to vault works; index updated.
• Sub-agent (Stage 3) flow — documented in SKILL.md but not exercised in this PR; runs on first invocation of /lotus-audit-web.

Followups

• Sub-agent fix proposals on first real run — same architecture as iOS; will trigger automatically when the skill is invoked.
• Operator-portals skill (lotus-audit-web-portals) — Luna + Solar + Terra + Enforcement.
• Email template audit — resources/views/emails/ (343 files) needs its own scanner with inline-CSS-aware rules.
• Drift comparison between consecutive audits (still open from iOS too).
• Web typography parity — once web Lotus adds typography tokens, run the same atom-level parity as iOS.

🤖 Generated with Claude Code

[gitstream-cm]

🚨 gitStream Monthly Automation Limit Reached 🚨

Your organization has exceeded the number of pull requests allowed for automation with gitStream.
Monthly PRs automated: 250/250

To continue automating your PR workflows and unlock additional features, please contact LinearB.