Skip to main content

CMP v1 — UI/UX Requirements (Portal + Scanner + Drop-in)

0) Personas & success criteria​

  • Ops/Engineer (primary): needs reliable controls, clear errors, and fast triage.
  • Admin/Account manager: needs “what changed / what to tell the customer” and simple exports.
  • Compliance/Legal (viewer): needs evidence: consent exports, policy copy, scanner “clean” proof.

KPIs

  • 0 pre-consent tracker regressions (CI green rate).
  • < 2 min to publish a config change (P95).
  • < 5 min to triage and classify a new cookie (P95).
  • A11y: no critical axe violations; WCAG 2.1 AA.

1) Information Architecture (Portal)​

Global

  • Left nav (persistent): Sites, Config, Analytics (Overview, Cookies), Overrides, Export, Scanner
  • Top bar: Tenant/Site selector, environment badge, user menu.
  • Footer: build hash, docs links, third-party notices.

Sites

  • Table: SiteKey, host(s), live version, last publish, actions: Open Config, Manage origins, Export, Scanner.
  • Actions: Copy snippet (+ SRI), Rotate key, Manage overrides, Manage origins, Export consents, Cookies.

Config

  • Panels:
    1. Localization & Policy (strings, policy details, preview locale)
    2. Vendors (suggest → add, CSV import)
    3. Publish (version note, diff preview)
    4. Compliance Mode (Consent-Mode-only vs External TCF CMP note/flag)

Analytics

  • Overview: adoption trend (accept/reject/partial), GPC %, dataset freshness card.
  • Cookies (NEW): filters + review queue + all cookies table (see §3).

Overrides

  • Hosts (existing), Cookies (new): search, scope (global/site), CSV import/export, audit columns (who/when/source).

Export

  • Consents: CSV/JSON/JSONL; filters for date range, region, GPC.
  • (Later) Cookie scan exports (CSV).

Scanner

  • Run scan: URL + toggles (GPC, screenshot, trace, wait ms).
  • History: baseline marker, sparkline of new3P/newCookies; artifact links.

2) Cross-cutting UX rules​

Accessibility (WCAG 2.1 AA)

  • Banner/Dialog: role="dialog", aria-labelledby/aria-describedby, focus trap, Escape closes, equal prominence Accept/Reject.
  • Forms: labeled controls, inline error text, keyboard navigation, visible focus.
  • Color contrast ≥ 4.5:1; status tags not color-only (include text).

Localization

  • ui.strings.locale drives copy; RTL when locale starts with ar.
  • Use native dir attributes on panels; flip logical paddings/margins.

Responsive

  • Breakpoints: ≥1280 (full), 1024–1279 (two-column), <1024 stack. Tables become stacked cards on mobile.

Loading & states

  • Use skeleton rows/spinners; empty-state cards with clear CTAs.
  • Errors: toast + inline message with “Try again” / “Copy cURL”.

Performance budgets

  • Portal route TTI < 1.5s P95; table renders < 400ms P95 for 500 rows.
  • Avoid full-page reloads for publish/override; toast on success, optimistic update with rollback.

Security

  • Never show cookie values; names and attributes only.
  • Admin actions require cmp.admin token.
  • Show who/when on seed/override changes (audit metadata).

3) Cookies tab (spec)​

Header & filters

  • Range: 7d | 30d | custom (datetime-local “from/to”)
  • Party: Any | First-party | Third-party
  • Category: Any | essential | analytics | advertising | functional | uncategorized
  • Unknown only (checkbox)
  • Min confidence (0–100%)
  • Search (name/domain)
  • Refresh

Review queue (left column)

  • Sort: unknown first, then low confidence; limit 50.
  • Columns: Cookie (name + domain), Vendor, Category (tag), Confidence (tag), Actions

    • Accept as Definition (global):

      • Pre-fill: namePattern = exact name, category (fallback functional), vendor (if any), purpose default by category, retention = item.retention, confidence ≥ 85.
      • Calls POST /admin/cookies/definitions:batch; success toast; refresh list.

    • Override (this site):

      • Pre-fill: name, domain, vendor/category/purpose, retention; reason = “accepted from review queue”.
      • Calls POST /admin/cookies/overrides; success toast; refresh.

All cookies (right column)

  • Table columns:

    • Cookie (name + domain), Party (1P/3P), Vendor, Category tag, Retention, Flags (Secure/HttpOnly/SameSite), Count, Last seen.

  • Sorting: category then count desc; pagination (50/page) optional.

Empty states

  • Review queue empty: “No items to review 🎉”.
  • All cookies no data: “No data found for filters.”

Bulk actions (v1.1 nice-to-have)

  • Select multiple unknowns → “Accept as Definition” (bulk) | “Override for site” (bulk).
  • Confirm modal with N items; show a sample row.

Evidence viewer (v1.1)

  • Row action “Evidence”: side drawer showing last N evidence rows (host/vendor hints, flags, max-age, timestamps).

4) Overrides admin (cookies)​

List view

  • Filters: site/global, name/domain search, category.
  • Columns: Site/Scope, Name, Domain, Category, Vendor, Purpose, Retention, UpdatedAt, Actions (Edit/Delete).
  • CSV import/export (UTF-8, comma; safe columns only).

Edit modal

  • Fields: Category (select), Vendor (free-text), Purpose (short), Retention (short); Reason (audit).
  • Save → toast + optimistic update.

5) Scanner UX (public page)​

Run scan

  • URL field; toggles: GPC, Screenshot, Trace, Wait(ms).
  • Button: “Scan now” → show progress; disable on running.

Results

  • Cards: Pre vs Post counts (# cookies, # 3P hosts); Violations card if any pre-consent non-essential.
  • Artifacts: JSON download, screenshot preview (if captured), trace link.
  • Copy cURL includes GPC & wait flags; include --site-key query if applicable.

History

  • Rows: when, URL, new3P/newCookies deltas, baseline marker, actions: “Scan again”, “View artifacts”.
  • Pin as baseline (v1.1).

6) Config & Sites UX details​

Localization & Policy

  • Required fields: title, description; optional policy link; policy details per category (description + retention).
  • Preview locale field (non-functional language switch for now; guidance for v2 multi-locale).

Allowed origins (CORS)

  • Table: legacy primary + extra domains; add/remove actions; guard against deleting legacy domain.
  • Copy primary → domains (1-click) action.

Publish

  • Show publish note; surface diff (strings/vendors/origins) if cheap.
  • Post-publish toast; update live version in Sites table.

Sites list

  • “Copy snippet” reveals snippet with data-site-key + data-cookie-domain + SRI if available.
  • “Rotate key” confirmation; update Sites row immediately.

7) Copy & content requirements​

Consent copy (end-user)

  • Plain language; per-site ui.strings.
  • Arabic copy correct & professional; RTL applied; numerals acceptable by font.
  • Equal prominence Accept/Reject; “Manage settings” clear.

Admin copy (portal)

  • Action verbs: “Add”, “Remove”, “Publish”, “Rotate key”, “Accept as Definition”, “Override (this site)”.
  • Error toasts: precise cause + remediation; when possible, include “Copy cURL” for debugging.

8) Telemetry (what to instrument)​

  • Portal events: publish duration, override added, definition accepted, domain added, export download, scanner run.
  • Scanner CI pass/fail, artifact size, run time.
  • Cookies tab: unknowns count over time; accepted definitions vs overrides ratio.

9) Acceptance checklist (v1 UI/UX)​

  • Banner/Dialog: axe passes; RTL Arabic renders; equal prominence Accept/Reject; focus trap works; Escape closes.
  • Sites: copy snippet + rotate key; allowed origins add/remove; config publish updates live version.
  • Analytics → Cookies tab: filters work; review queue actions (definition/override) update list and server; no errors.
  • Scanner page: runs with screenshot/trace toggles; artifacts downloadable; GPC mode runs.
  • Exports: CSV/JSON/JSONL download OK; date filters respected.
  • Performance: route TTI < 1.5s P95; cookies table render < 400ms P95.
  • A11y: no critical axe violations portal-wide.
  • Docs: “Consent Mode only (no TCF)” guardrail visible in Config.

10) Quick backlog (v1.1+)​

  • Cookies: CSV export, evidence drawer, bulk accept, sorting/paging with virtual rows for large datasets.
  • Baseline pin in Scanner history; compare deltas against pinned baseline.
  • SRI fetch in Sites “Copy snippet” (auto-pull from CDN).
  • Tenant scoping: if token has tenantId, filter sites + admin ops.
  • Dark mode (low priority).