rcf-lite 0.19.0 → 0.21.0

package/blueprints/application-dashboard/assets/guidance/dashboard-design.md

@@ -0,0 +1,124 @@
+# Dashboard design guidance
+
+A packaged asset shipped with the `application-dashboard` blueprint. Read at apply, referenced at project-side review, and cited from every REQ, ADR and pack check that anchors on a design rule. The applying agent honours the eight sections below. Where a section names an AC id, the rule is a runtime-observable AC on this blueprint (the ship gate refuses on failure). Where a section stays operator guidance, the applying agent honours it and the shipping surface is reviewed by hand.
+
+Sources are cited by URL at each section. Five bodies of work anchor this guidance:
+
+- Nielsen Norman Group research on how people read on the web: https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/
+- Stephen Few's dashboard-design library at Perceptual Edge: https://www.perceptualedge.com/library.php
+- Edward Tufte, The Visual Display of Quantitative Information (Wikipedia reference): https://en.wikipedia.org/wiki/The_Visual_Display_of_Quantitative_Information
+- GOV.UK Design System patterns index: https://design-system.service.gov.uk/patterns/
+- WCAG 2.2 Understanding docs: https://www.w3.org/WAI/WCAG22/Understanding/
+
+## 1. Primary KPI placement
+
+The primary KPI is the reader's anchor. Place it top-left on every ratified breakpoint (1440, 1024, 360). NN/g's F-shaped-pattern reading research reports that the top-left region of a text-heavy layout is where a reader's eye lands first; that is the spot the anchor tile has to occupy. On a 360 phone layout the tile row reflows to one column and the primary KPI stays first in DOM order and top of the stack.
+
+The primary KPI kind is one of five values (ADR-2001): `revenue`, `active-users`, `error-rate`, `throughput`, `custom`. A `custom` value carries a short operator name in `data-kpi-name`. A dashboard with no primary KPI fails project-side review.
+
+Sources:
+- NN/g F-shaped pattern of reading: https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/
+- Stephen Few, Dashboard Design for Rich and Rapid Monitoring (Perceptual Edge): https://www.perceptualedge.com/articles/visual_business_intelligence/dd_for_rapid_monitoring.pdf
+
+Hardens into AC-19102-1.
+
+## 2. Tile density and count limits
+
+Keep the tile row to at most eight tiles. Beyond eight the glance value drops sharply; a reader scanning a nine-tile row misses the middle tiles on the first fixation and either scrolls or gives up. If the dashboard needs more metrics, break them into a second view (a drilldown), not a longer row.
+
+A stat tile carries one number. A stat tile that tries to carry a mini-chart and three numbers is a small dashboard inside a dashboard; move it to its own dashboard slot instead.
+
+The primary tile can be visually heavier than the supporting tiles (a larger value, an accent border) but the shape stays a stat tile: one metric, one context line, one state.
+
+Sources:
+- Stephen Few, Dashboard Confusion Revisited (Perceptual Edge): https://www.perceptualedge.com/articles/visual_business_intelligence/dboard_confusion_revisited.pdf
+- Tufte on chartjunk (Wikipedia summary of the concept): https://en.wikipedia.org/wiki/Chartjunk
+
+Stays operator guidance.
+
+## 3. Timeframe and filter chrome
+
+The timeframe picker is one of the most-touched controls on the surface. Ship three presets by recommendedDefault (ADR-2002): `last-7-days`, `last-30-days`, `quarter-to-date`. `last-7-days` is the ship default unless the operator elicits an override. Operators may supply their own preset set (a fiscal-year window, a shift window) at apply; missing presets are ignored, extra presets append.
+
+Filter chrome exposes each operator-configured filter as a labelled interactive control (a `<button>`, a `<select>`, or an `<input>`), keyboard-reachable in reading order before the tile row. A hover-only filter is refused; a dropdown that opens on hover fails the accessibility contract.
+
+Sources:
+- GOV.UK Design System patterns index (the standalone filter pattern page has been retired; the index is the current landing): https://design-system.service.gov.uk/patterns/
+- WCAG 2.2 Understanding SC 2.1.1 Keyboard: https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html
+- WCAG 2.2 Understanding SC 1.4.13 Content on Hover or Focus: https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html
+
+Hardens into AC-19105-1 and the fan-out rule under AC-19104-1.
+
+## 4. Loading, empty and error states
+
+Every tile carries the same four-state contract: `loading`, `empty`, `error`, `populated`. Each state has a distinct visual cue and a distinct accessible name; the state's cue is not colour-only (WCAG 1.4.1). A loading tile renders a skeleton or a spinner; an empty tile renders a labelled empty-state block; an error tile renders a labelled error block with the recorded reason; a populated tile renders the metric.
+
+Every tile wraps its content in a `role="region"` element with `aria-live="polite"` so a state change is announced to assistive tech.
+
+Sources:
+- NN/g on empty states: https://www.nngroup.com/articles/empty-state-interface-design/
+- WCAG 2.2 Understanding SC 1.4.1 Use of Colour: https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html
+- WCAG 2.2 Understanding SC 4.1.3 Status Messages: https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html
+
+Hardens into AC-19103-1 and AC-19103-2.
+
+## 5. Colour and contrast
+
+Dashboard tiles read at a glance; low contrast punishes the reader. Text on a tile carries at least 4.5:1 contrast against its background (WCAG 1.4.3); state-cue graphics carry 3:1 non-text contrast (WCAG 1.4.11). If the shipped chart region reuses the application-charts render shell, the palette contract comes from ADR-1902 on that blueprint; the shipped light and dark categorical palettes are contrast-safe by default.
+
+Colour alone never carries state or series distinction: pair colour with a shape, a pattern or a label. Traffic-light state cues (red, orange, green) recur as a defect on shipped dashboards; pair the colour with an icon, a label or a text state.
+
+Sources:
+- WCAG 2.2 Understanding SC 1.4.3 Contrast Minimum: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+- WCAG 2.2 Understanding SC 1.4.11 Non-text Contrast: https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html
+
+Stays operator guidance for the tile row; hardens for the chart region through application-charts AC-18102-1 and AC-18105-1.
+
+## 6. When a table beats a chart
+
+If the reader's question is what the value is, ship a stat tile. If the reader's question is how the values compare across a small set, ship a stat tile row and a table. If the reader's question is how the values move over time, ship a chart. If the reader wants to sort, filter, page, select, or export a table of records, ship the `application-datatable` blueprint's table; the dashboard's tile row is not a replacement.
+
+A chart with three data points is a table. A pie chart with more than four slices is a table. A dashboard that overuses charts to fill space produces the chartjunk Tufte warned against; a table is often the honest shape.
+
+The dashboard's chart region delegates rendering to the application-charts render shell (TAC-1901); the accessibility, palette, text-alternative and keyboard-traversal ACs on that blueprint apply. The paired text-alternative table is one of those ACs (application-charts AC-18103-1), so the reader always has the table view for the chart.
+
+Sources:
+- The Visual Display of Quantitative Information (Wikipedia reference): https://en.wikipedia.org/wiki/The_Visual_Display_of_Quantitative_Information
+- NN/g Choosing Chart Types (video): https://www.nngroup.com/videos/choosing-chart-types/
+- NN/g Comparison Tables, 5 scenarios (video): https://www.nngroup.com/videos/comparison-tables/
+
+Stays operator guidance; the shell contract enforces the chart-region mount through the render shell (AC-19101-2).
+
+## 7. Refresh cadence and staleness
+
+Every dashboard reader wants to know how fresh the data is. The shell renders one `as of <ISO-8601>` stamp on the shell root and every tile carries the same stamp. On a timeframe or filter change the shell refetches every tile with the same boundary, waits for the batch, and updates the stamp. A tile whose stamp drifts from the shell root is a defect.
+
+Auto-refresh is off by default. An operator elicits a refresh interval at apply if the surface genuinely needs unattended refresh (an ops screen, an event-day dashboard); the elicited interval sets `data-auto-refresh` on the shell root to the elicited seconds. A dashboard that refreshes every 30 seconds without an operator opt-in wastes budget and produces distracting motion; a dashboard that refreshes on a hidden tab drops keystrokes in the operator's active tab.
+
+Sources:
+- Nielsen, Response Times: The 3 Important Limits (NN/g): https://www.nngroup.com/articles/response-times-3-important-limits/
+- Stephen Few, Dashboard Design for Real-Time Situation Awareness (Perceptual Edge): https://www.perceptualedge.com/articles/Whitepapers/Dashboard_Design.pdf
+
+Hardens into AC-19104-1 (fan-out and stamp) and AC-19104-2 (auto-refresh default).
+
+## 8. Anti-patterns
+
+Read this list against the shipped surface; if any of the following applies, fix it before ship.
+
+- The primary KPI is anywhere other than top-left.
+- A tile carries the same number as another tile at a different boundary and the reader compares them.
+- The tile row has more than eight tiles.
+- A state (loading, empty, error) is signalled by colour alone.
+- The dashboard auto-refreshes without an operator opt-in.
+- The export handle is a hover-only dropdown.
+- A canvas-only chart with no text-alternative surface (this is caught by application-charts AC-18103-1 on the chart region).
+- The dashboard renders a chartjunk grid (three overlapping bar charts, a rainbow-gradient donut) to fill space.
+- The dashboard mixes stale tiles and fresh tiles under one `as of` stamp.
+- The dashboard names a "primary KPI" that is not the reader's actual anchor question.
+
+Sources:
+- Stephen Few, Common Pitfalls in Dashboard Design (Perceptual Edge whitepaper): https://www.perceptualedge.com/articles/Whitepapers/Common_Pitfalls.pdf
+- Stephen Few, Why Most Dashboards Fail (Perceptual Edge): https://www.perceptualedge.com/articles/misc/WhyMostDashboardsFail.pdf
+- NN/g Data Visualizations for Dashboards (video): https://www.nngroup.com/videos/data-visualizations-dashboards/
+
+Stays operator guidance; individual patterns harden through the ACs the guidance names above.

package/blueprints/application-dashboard/blueprint.json

@@ -0,0 +1,29 @@
+{
+  "slug": "application-dashboard",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    { "role": "logging", "reason": "Dashboard tile refresh, timeframe change and export activation are the surface's most-touched instrumentation points; a logging companion supplies the factory the tiles and the chart region write records against." },
+    { "role": "errorHandling", "reason": "A tile whose fetch fails renders the error-state visual per REQ-003; the error-state contract needs a project-side error-record factory the application-error-handling companion provides." }
+  ],
+  "contributions": [
+    { "id": "application-dashboard-REQ-001", "kind": "req", "path": "requirements/application-dashboard-req-001.json" },
+    { "id": "application-dashboard-REQ-002", "kind": "req", "path": "requirements/application-dashboard-req-002.json" },
+    { "id": "application-dashboard-REQ-003", "kind": "req", "path": "requirements/application-dashboard-req-003.json" },
+    { "id": "application-dashboard-REQ-004", "kind": "req", "path": "requirements/application-dashboard-req-004.json" },
+    { "id": "application-dashboard-REQ-005", "kind": "req", "path": "requirements/application-dashboard-req-005.json" },
+    { "id": "application-dashboard-US-19101", "kind": "us", "path": "user-stories/application-dashboard-us-19101.json" },
+    { "id": "application-dashboard-US-19102", "kind": "us", "path": "user-stories/application-dashboard-us-19102.json" },
+    { "id": "application-dashboard-US-19103", "kind": "us", "path": "user-stories/application-dashboard-us-19103.json" },
+    { "id": "application-dashboard-US-19104", "kind": "us", "path": "user-stories/application-dashboard-us-19104.json" },
+    { "id": "application-dashboard-US-19105", "kind": "us", "path": "user-stories/application-dashboard-us-19105.json" },
+    { "id": "application-dashboard-US-19106", "kind": "us", "path": "user-stories/application-dashboard-us-19106.json" },
+    { "id": "application-dashboard-US-19107", "kind": "us", "path": "user-stories/application-dashboard-us-19107.json" },
+    { "id": "TAC-2001-application-dashboard-tile-grid", "kind": "tac", "path": "tacs/tac-2001-application-dashboard-tile-grid.json" },
+    { "id": "TAC-2002-application-dashboard-filter-chrome", "kind": "tac", "path": "tacs/tac-2002-application-dashboard-filter-chrome.json" },
+    { "id": "TAC-2003-application-dashboard-export-handle", "kind": "tac", "path": "tacs/tac-2003-application-dashboard-export-handle.json" },
+    { "id": "ADR-2001-application-dashboard-primary-kpi-enum", "kind": "adr", "path": "adrs/adr-2001-application-dashboard-primary-kpi-enum.json", "recommendedDefault": false, "elicited": true, "standardsTraceClause": "NN/g F-scan; Gestalt proximity" },
+    { "id": "ADR-2002-application-dashboard-timeframe-presets", "kind": "adr", "path": "adrs/adr-2002-application-dashboard-timeframe-presets.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "NN/g dashboard design (timeframe defaults)" },
+    { "id": "ADR-2003-application-dashboard-export-formats", "kind": "adr", "path": "adrs/adr-2003-application-dashboard-export-formats.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "GOV.UK Design System (download patterns); WCAG 1.3.1 (info and relationships)" }
+  ]
+}

package/blueprints/application-dashboard/contributions/adrs/adr-2001-application-dashboard-primary-kpi-enum.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2001-application-dashboard-primary-kpi-enum",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Elicit the primary KPI kind from a fixed enum (revenue, active-users, error-rate, throughput, custom)",
+  "context": "The primary KPI is the reader's anchor on the dashboard's first fixation. Every applying project already has a primary KPI in the business sense; the problem is that the surface's `data-kpi-kind` attribute either stays free-form (any string) and cross-project comparisons drift, or hard-picks one KPI at the shelf and forces every applying project to relabel. Neither option lands the runtime discipline the pack needs to prove the primary-KPI-top-left rule.",
+  "decision": "The primary-KPI kind is elicited at apply from a fixed enum: `revenue`, `active-users`, `error-rate`, `throughput`, or `custom`. The elicited value lands on the primary tile as `data-kpi-kind`; a `custom` choice carries a `data-kpi-name` attribute with the operator's own short name. The pack asserts the attribute value is one of the enum values (or `custom` with a `data-kpi-name`), the tile is top-left in DOM order and CSS Grid position at every ratified breakpoint. The five enum values cover the shipped shelf's known cases (SaaS revenue dashboards, product-analytics active-users dashboards, SRE error-rate dashboards, throughput-focused ops dashboards, and the custom escape hatch); a new enum value moves the ADR to v1.1.0 with a shelf-wide review.",
+  "consequences": "Applying projects pick from a small, review-worthy set; the pack has a runtime-observable attribute to check; cross-project comparisons on a shelf-wide dashboard registry are trivial. The `custom` value keeps the escape hatch honest: a project with a KPI outside the five stays within the ADR while documenting its own name on `data-kpi-name`.",
+  "alternativesConsidered": [
+    {
+      "name": "Free-form primary-KPI kind",
+      "summary": "The attribute accepts any string.",
+      "reasonNotChosen": "Every applying project would ship its own label and cross-project reasoning would drift; the pack could not usefully assert a value shape."
+    },
+    {
+      "name": "Hard-pick revenue as the primary KPI",
+      "summary": "Every dashboard on the shelf carries `revenue` as its primary KPI.",
+      "reasonNotChosen": "Product-analytics and SRE dashboards would have to relabel their real primary KPI; the shelf would ship a dishonest attribute."
+    }
+  ],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/adrs/adr-2002-application-dashboard-timeframe-presets.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2002-application-dashboard-timeframe-presets",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Ship three timeframe presets by recommendedDefault with elicited overrides and auto-refresh off unless elicited",
+  "context": "Timeframe presets on a dashboard are the single most-touched control; the wrong default (a rolling 24-hour window on a monthly-cycle business) produces a dashboard that is silently wrong at every open. Operators often want their own presets (a fiscal-year window, a shift window). Auto-refresh is one of the most common accessibility and cost defects on shipped dashboards: an unattended refresh runs the fan-out on a hidden tab all day.",
+  "decision": "The blueprint ships three timeframe presets by recommendedDefault: `last-7-days`, `last-30-days`, and `quarter-to-date`. `last-7-days` is the ship default unless the operator elicits an override at apply. Operators supply their own preset set through the elicited override; missing presets are ignored, extra presets append to the shipped set. Auto-refresh is OFF by default: `data-auto-refresh` on the shell root reads `off`; an operator-elicited refresh interval sets it to the elicited seconds and the shell refetches on the same fan-out contract at that interval. A shell that ships auto-refresh on by default fails project-side review.",
+  "consequences": "The applying project gets a safe timeframe default that matches the most common dashboard-glance case; operators with an unusual cycle (a fiscal-year business) elicit their own set. Auto-refresh stays off unless the operator explicitly turns it on with an interval, and the pack asserts the default state through `data-auto-refresh`.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship five timeframe presets",
+      "summary": "Add `today` and `this-week` to the shipped set.",
+      "reasonNotChosen": "`today` produces an early-morning dashboard that is mostly empty; `this-week` overlaps with `last-7-days` without adding a clear read. The three-preset set is what the shipped surfaces need."
+    },
+    {
+      "name": "Auto-refresh on by default",
+      "summary": "Every dashboard refreshes on a 60-second interval.",
+      "reasonNotChosen": "Unattended refresh is a cost and accessibility defect; the elicited-opt-in path keeps the shell honest."
+    }
+  ],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/adrs/adr-2003-application-dashboard-export-formats.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2003-application-dashboard-export-formats",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Ship three export formats by recommendedDefault (CSV, PDF, PNG-of-chart) with elicited overrides and PNG delegation to the charts render shell",
+  "context": "Export is a legal-and-audit necessity on most shipped dashboards, and the accessibility posture of an export handle is often the last thing anyone reviews. The three most-requested formats are CSV (data extract), PDF (whole-dashboard snapshot), and PNG (one-chart download). SVG, XLSX and a Slack-share button are common project-side additions. A dashboard shell that carries its own PNG generator is a common defect because it produces a chart image that drifts from the shipped chart.",
+  "decision": "The blueprint ships three export formats by recommendedDefault: `csv`, `pdf`, and `png-chart`. Operators supply their own format set through the elicited override; missing formats are ignored, extra formats append to the shipped set with an operator-supplied `label` and `data-export-format` value. PNG-of-chart delegates to the application-charts render shell (TAC-1901): the export handle carries no PNG generator of its own; the charts shell owns the PNG output for every rendered chart on the surface. Applying projects that ship a chart engine outside the render shell either supersede this ADR with a project-authored delegation or lose the PNG-of-chart affordance.",
+  "consequences": "The applying project gets the three most-requested formats out of the box and an elicited override for the rest. The delegation to the charts shell keeps the PNG output consistent with the rendered chart; a project that supersedes the delegation names the residual and owns the chart-drift risk.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship the format list open-ended (no defaults)",
+      "summary": "Every project elicits its own format set at apply.",
+      "reasonNotChosen": "Every project would ship the first-pass format set the operator asked for and the accessibility posture of the format list would move with the operator's brief. The three-format default carries the shelf's discipline."
+    },
+    {
+      "name": "Bake a PNG generator into the dashboard shell",
+      "summary": "The shell owns the PNG output for its rendered charts.",
+      "reasonNotChosen": "The charts shell already renders every chart on the surface; a second PNG path drifts from the rendered chart and duplicates the accessibility contract."
+    }
+  ],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-001.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-dashboard-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The dashboard shell composes a tile row, a chart region, filter chrome, a timeframe picker and an export handle",
+  "description": "A rendered dashboard on the shipped surface composes five regions on one page: a tile row carrying the primary KPI and up to seven supporting stat tiles; a chart region reusing the application-charts render shell for every rendered chart; filter chrome exposing operator-configured filters as accessible controls; a timeframe picker exposing the presets ADR-2002 elicits; and an export handle whose formats ADR-2003 elicits. The five regions are the shell contract; a dashboard that ships fewer regions (a page with no export handle, or no filter chrome) either supersedes this REQ with a project-authored REQ documenting the omitted region or renders the region as empty with a labelled `role=\"region\"` element the pack can inspect.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "A dashboard is a compound surface: the tile row, the chart region and the filter chrome each need their own AC coverage. Naming the five regions on the shell is what lets every subsequent REQ, TAC and pack check anchor onto a stable, inspectable structure rather than a floating layout convention.",
+  "tags": ["blueprint:application-dashboard", "category:01-shell-composition"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-002.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-dashboard-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The primary KPI tile sits top-left in DOM order and in CSS Grid position across the ratified breakpoints",
+  "description": "The tile row's primary KPI carries a top-left placement the reader reaches first, on the NN/g F-scan of the surface, at every ratified breakpoint (1440, 1024, 360). At 1440 and 1024 the primary KPI is the first tile in DOM order and its computed CSS Grid column-start is 1 and row-start is 1; at 360 the tile row reflows to one column and the primary KPI is the first tile in DOM order and its row-start is 1. The tile carries a `data-tile-role=\"primary-kpi\"` attribute and a `data-kpi-kind` attribute whose value is one of the ADR-2001 enum values (revenue, active-users, error-rate, throughput, custom). A dashboard that ships no primary KPI tile fails this REQ at project-side review; a dashboard whose primary KPI is not top-left at any of the three breakpoints fails the pack check AC-19102-1.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The primary KPI is the reader's anchor on a dashboard glance; the F-scan reading pattern (NN/g dashboard design research) puts the top-left tile at the reader's first fixation. Codifying the placement as a runtime-observable CSS Grid position at the three ratified breakpoints turns a design convention into a check a Playwright probe can drive.",
+  "tags": ["blueprint:application-dashboard", "category:02-primary-kpi-hierarchy"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-003.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-dashboard-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Every tile honours a four-state contract with distinct visuals, role region, aria-live polite, and non-colour distinction",
+  "description": "Every tile on the shell renders one of four states at any moment: loading, empty, error, populated. Each state carries a distinct visual (a skeleton stripe or spinner for loading, a labelled empty-state block for empty, a labelled error block with the recorded reason for error, and the actual metric for populated). Each tile wraps its content in `role=\"region\"` with an `aria-live=\"polite\"` announcer that reads the state transition on change. The state distinction combines a visual cue and a text label (non-colour distinction, WCAG 1.4.1): the state's visual is not colour-only, and the state's accessible name reads `<tile title>, <state>` on entry. A tile that renders no visible state (a blank tile) fails REQ-003 at project-side review; a tile that carries state-only through colour fails the pack check AC-19103-1.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The four-state contract is the shelf's most-repeated data-region pattern (see application-datatable REQ-005 for the same shape on the table shell); giving the dashboard tile its own explicit ACs is what stops the state contract from silently drifting between the two surfaces. The aria-live announcer is what makes a tile's state change reachable to a screen-reader user; the non-colour distinction is what makes the state legible to a colour-blind reader.",
+  "tags": ["blueprint:application-dashboard", "category:03-tile-four-state"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-004.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-dashboard-REQ-004",
+  "prdId": "PRD-001",
+  "title": "The timeframe picker and the filter chrome refetch every tile and chart with the same boundary and update the as-of stamp",
+  "description": "A timeframe preset change (from the operator-elicited set: last-7-days, last-30-days, quarter-to-date or an elicited override) issues one refetch per tile and one refetch per rendered chart, and every fetch carries the same `from` and `to` boundary and the same `preset` name. A filter chrome change (operator toggles a filter chip, types into a filter input) issues the same refetch fan-out with the same boundary. Once every fetch has returned (or the timeout has elapsed) the shell updates one `as of <ISO-8601>` stamp on the shell, and every rendered tile carries the same stamp. A shell whose fetches drift boundaries (one tile refetches with the new boundary, another with the old) fails the pack check AC-19104-1; a shell whose as-of stamp does not match every tile's rendered stamp fails the same check.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The fan-out contract is what stops a dashboard from lying to the reader: two tiles at different boundaries render numbers the reader compares as if they were the same period, and the comparison is silently wrong. Codifying the same-boundary rule and pinning it to a single as-of stamp is the runtime check that makes the fan-out contract inspectable.",
+  "tags": ["blueprint:application-dashboard", "category:04-fanout-contract"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-005.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-dashboard-REQ-005",
+  "prdId": "PRD-001",
+  "title": "The export handle exposes an accessible format list and delegates PNG-of-chart to the application-charts render shell",
+  "description": "The export handle is a labelled `<button>` on the shell that opens an operator-navigable list of export formats: CSV of the currently rendered data, PDF of the shipped dashboard surface, and PNG of a specific rendered chart. The list is keyboard-reachable in reading order and closes on Escape without losing focus. PNG-of-chart delegates to the application-charts render shell (TAC-1901): the export handle names the chart the operator picked from the chart region and the charts shell owns the PNG generation. Formats outside the shipped set (SVG, XLSX) are the elicited-override path (ADR-2003) and follow the same accessible-list contract.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Export is one of the shelf's most-requested affordances and one of the most under-reviewed for accessibility: a hover-only dropdown or a mouse-only download button is common. Naming the accessible-list contract explicitly and delegating PNG-of-chart to the charts blueprint is what keeps the export handle honest and prevents a duplicate PNG generator inside the dashboard shell.",
+  "tags": ["blueprint:application-dashboard", "category:05-export-handle"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/tacs/tac-2001-application-dashboard-tile-grid.json

@@ -0,0 +1,47 @@
+{
+  "tacId": "TAC-2001-application-dashboard-tile-grid",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Dashboard tile grid, primary KPI placement, and breakpoint reflow",
+  "purpose": "Owns the dashboard shell's tile row and tile grid: the CSS Grid definition every tile lives on, the primary KPI placement top-left, the four-state region contract on every tile, and the breakpoint reflow to one column at 360. The shell mounts the chart region through the application-charts render shell (TAC-1901's dependency here) and delegates chart rendering to that shell; the tile grid is the substitutable interface the pack asserts on.",
+  "responsibilities": [
+    "Mount the tile row region as a CSS Grid container whose primary tile carries `data-tile-role=\"primary-kpi\"` and lives at grid-column-start 1, grid-row-start 1 at 1440 and 1024, and grid-row-start 1 with a one-column reflow at 360 (AC-19102-1).",
+    "Render every tile with a `role=\"region\"` wrapper, an `aria-live=\"polite\"` announcer, a `data-tile-state` attribute naming the current state, and a non-colour visual cue for each state (skeleton or spinner for loading, labelled block for empty, labelled block with recorded reason for error, metric value for populated) (AC-19103-1).",
+    "Announce state transitions on the aria-live region as `<tile title>, <new state>` (AC-19103-2).",
+    "Mount the chart region through the application-charts render shell (TAC-1901): the chart region contains at least one `section.chartRegion[role=\"region\"]` element carrying the shape the application-charts pack asserts on (AC-19101-2).",
+    "Expose a `data-kpi-kind` attribute on the primary tile whose value is one of ADR-2001's enum (revenue, active-users, error-rate, throughput, custom); a custom value carries a `data-kpi-name` attribute with the operator-elicited name (AC-19102-1)."
+  ],
+  "internalStructure": "One shell module that renders the five labelled regions on the surface, plus small internal helpers per state (loading, empty, error, populated) that render the state's DOM shape into the same region wrapper. The tile grid is a CSS Grid definition with breakpoint-scoped `grid-template-columns` rules; the primary tile carries an explicit `grid-column-start: 1; grid-row-start: 1` at every breakpoint.",
+  "interfaces": [
+    {
+      "name": "renderDashboardShell",
+      "kind": "factory",
+      "description": "renderDashboardShell({ tiles, chartRegion, filters, timeframe, exportHandle, refreshInterval, asOf }) -> { mount(rootElement), unmount() }. The project supplies the tile inventory (elicited at apply per ADR-2001), the chart region declarations, the filter chrome, the timeframe picker (elicited from ADR-2002's presets), the export handle (elicited from ADR-2003's formats), and the optional refresh interval; the shell owns the CSS Grid DOM plumbing, the region wrapping, the aria-live announcers and the state routing."
+    },
+    {
+      "name": "tileStateContract",
+      "kind": "shape",
+      "description": "A tile in each of four states carries `data-tile-state=\"loading|empty|error|populated\"` on its wrapping `role=\"region\"` element; the accessible name reads `<tile title>, <state>`; the state's visual cue is not colour-only."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Chart render shell",
+      "kind": "tac",
+      "tacId": "TAC-1901-application-charts-render-shell",
+      "description": "The dashboard's chart region mounts every chart through the application-charts render shell. The dashboard blueprint does not duplicate the chart accessibility ACs; the charts pack fires on the dashboard's chart route through its own applicability predicate."
+    },
+    {
+      "name": "Timeframe and filter fan-out",
+      "kind": "tac",
+      "tacId": "TAC-2002-application-dashboard-filter-chrome",
+      "description": "The tile grid delegates refetch fan-out to TAC-2002 on timeframe change and filter change; every tile re-renders through the shell factory on refetch."
+    }
+  ],
+  "tradeoffs": "The primary KPI top-left placement is opinionated on a 360 phone layout: the F-scan does not directly apply to a single-column stack, and a project with a very different information hierarchy at mobile may want the primary KPI second (below a sticky header). The reflow rule here favours consistency with the desktop reading position; a project that supersedes it authors its own REQ and names the residual. The shell is framework-agnostic; a project applying it picks React, Vue, Svelte or hand-authored DOM and writes the mount function against the same DOM contract.",
+  "notes": "Known mechanism-reach gap: the shell contract cannot itself prove the applying project's tile factory emits the DOM markers the pack asserts on (`data-tile-role`, `data-kpi-kind`, `data-tile-state`). A build-scan supplement in a v1.1 minor bump would close the class.",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/tacs/tac-2002-application-dashboard-filter-chrome.json

@@ -0,0 +1,41 @@
+{
+  "tacId": "TAC-2002-application-dashboard-filter-chrome",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Timeframe picker and filter chrome with refetch fan-out contract",
+  "purpose": "Owns the shell's timeframe picker and filter chrome, and the refetch fan-out contract: a preset change or a filter change issues one refetch per tile and one per rendered chart, every fetch carrying the same boundary and the same preset name, and once the batch has returned the shell updates one `data-as-of` attribute the tiles inherit. The fan-out contract is the substitutable interface the pack asserts on (AC-19104-1).",
+  "responsibilities": [
+    "Render the timeframe picker as an accessible list of presets (labelled `<button>` elements or a `<select>`) with a keyboard-reachable default from ADR-2002 (`last-7-days` unless elicited) (AC-19104-1).",
+    "Render filter chrome as labelled interactive elements (chips, dropdowns, text inputs) keyboard-reachable in reading order before the tile row; a hover-only control is refused at project-side review (AC-19105-1).",
+    "On a preset change or a filter change, issue one refetch per tile and one per rendered chart; every fetch carries the same `from` and `to` boundary, the same `preset` name and the same active-filters set (AC-19104-1, AC-19105-2).",
+    "Update one `data-as-of` attribute on the shell root once every fetch has returned (or the timeout has elapsed) and propagate the same value to every tile's `data-as-of` attribute (AC-19104-1).",
+    "Expose a request log on `window.__dashboardFetches` (an append-only array of `{ from, to, preset, filters, tileId, chartId, at }` records) so the pack can read every fetch after each preset change (AC-19104-1)."
+  ],
+  "internalStructure": "One preset-picker module and one filter-chrome module composed on the shell factory. The fan-out contract is implemented as a fetch dispatcher that receives the boundary and the active-filters set, invokes a per-tile fetcher and a per-chart fetcher, and awaits the batch before updating the shell's `data-as-of` attribute.",
+  "interfaces": [
+    {
+      "name": "onTimeframeChange",
+      "kind": "function",
+      "description": "onTimeframeChange({ preset, from, to }) -> Promise<void>. Called by the preset picker on activation; issues the fan-out and updates the shell's data-as-of."
+    },
+    {
+      "name": "onFilterChange",
+      "kind": "function",
+      "description": "onFilterChange({ filters }) -> Promise<void>. Called by the filter chrome on activation; issues the fan-out with the current boundary and updates the shell's data-active-filters and data-as-of."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Tile grid",
+      "kind": "tac",
+      "tacId": "TAC-2001-application-dashboard-tile-grid",
+      "description": "The fan-out dispatcher calls back into TAC-2001 to re-render each tile through the shell factory on refetch."
+    }
+  ],
+  "tradeoffs": "The single as-of stamp on the shell root is opinionated: a project whose per-tile freshness differs (a slow-cached tile at 5 minutes, a live tile at 15 seconds) may want a per-tile stamp instead. This TAC insists on the shell-level stamp because it is the reader's mental model of the dashboard's coherence; a per-tile stamp is a project-authored override that supersedes REQ-004 and names the residual. Auto-refresh is off by default (AC-19104-2) because unattended refresh is the most common defect on shipped dashboards.",
+  "notes": "Known mechanism-reach gap: filter fan-out (AC-19105-2) is a runtime-observable clause the shipped pack does not itself check today (the pack asserts the timeframe fan-out on AC-19104-1). A v1.1 minor bump would add a filter-fan-out check on the pack; the README names it individually.",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/tacs/tac-2003-application-dashboard-export-handle.json

@@ -0,0 +1,35 @@
+{
+  "tacId": "TAC-2003-application-dashboard-export-handle",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Export handle with format list and delegation to the charts render shell",
+  "purpose": "Owns the shell's export handle: a labelled `<button>` that on activation opens an accessible list of formats (CSV, PDF, PNG-of-chart by default; ADR-2003 elicits overrides), and delegates PNG-of-chart generation to the application-charts render shell (TAC-1901). The handle is the substitutable interface the shell exposes to export tooling; the PNG-of-chart delegation stops the dashboard shell from carrying its own PNG generator.",
+  "responsibilities": [
+    "Render the export handle region as a labelled `<button>` element with accessible name reading `Export` or an operator-configured equivalent (AC-19106-1).",
+    "On activation, open an accessible format list (a menu, a listbox or a set of `<button>` elements) that is keyboard-reachable in reading order and closes on Escape without losing focus on the export button (AC-19106-1).",
+    "Render each format entry with a `data-export-format` attribute whose value is one of `csv`, `pdf`, `png-chart` or ADR-2003's elicited override; the shipped default set is CSV, PDF and PNG-of-chart (AC-19106-1).",
+    "Delegate PNG-of-chart generation to the application-charts render shell (TAC-1901): the export handle references the chosen chart through a `data-chart-id` attribute (or a runtime prompt) and the charts shell owns the PNG output (AC-19106-2)."
+  ],
+  "internalStructure": "One export-handle button plus one format-list component (a menu or listbox pattern per the WAI-ARIA APG). The button owns the open and close semantics and the focus contract; the format list owns the reading-order navigation and the delegation to the charts shell.",
+  "interfaces": [
+    {
+      "name": "onExportRequest",
+      "kind": "function",
+      "description": "onExportRequest({ format, chartId? }) -> Promise<{ blobRef, filename }>. Called by the format list on activation; for `png-chart` the shell resolves through the application-charts render shell."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Chart render shell",
+      "kind": "tac",
+      "tacId": "TAC-1901-application-charts-render-shell",
+      "description": "PNG-of-chart export generation delegates to the charts shell; the dashboard export handle carries no PNG generator of its own."
+    }
+  ],
+  "tradeoffs": "The three shipped formats (CSV, PDF, PNG-of-chart) cover the common dashboard export cases; ADR-2003's elicited override handles SVG, XLSX and any operator-specific format. The delegation to the charts shell means a project that ships a bespoke chart engine outside the render shell needs a PNG output path of its own; the export handle names the residual under project-side review.",
+  "notes": "Known mechanism-reach gap: the pack browser has no download-capture seam today, so AC-19106-2 (PNG delegation) is proven at project-side review, not through the shipped pack. The README names it individually.",
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19101.json

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19101",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The dashboard shell renders the five required regions on every shipped surface",
+  "asA": "product owner responsible for the shipped dashboard surface",
+  "iWant": "the shell to render a tile row, a chart region, filter chrome, a timeframe picker and an export handle on every dashboard surface",
+  "soThat": "every REQ, TAC and pack check on this blueprint anchors onto a stable, inspectable shell structure rather than a floating layout convention",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19101-1",
+      "description": "Given a rendered dashboard surface, the DOM carries five labelled `role=\"region\"` elements naming (via `aria-label` or an in-region `<h2>` header) the tile row, the chart region, the filter chrome, the timeframe picker and the export handle. A surface that omits one of the five regions either renders the region as an empty labelled `role=\"region\"` element the pack can inspect or supersedes REQ-001 with a project-authored REQ documenting the omission.",
+      "given": "a rendered dashboard surface",
+      "when": "the accessibility tree is read",
+      "then": "five labelled regions cover the tile row, the chart region, the filter chrome, the timeframe picker and the export handle",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-19101-2",
+      "description": "Given the shell's chart region, the rendered chart mounts through the application-charts render shell (TAC-1901): the chart region contains at least one `section.chartRegion[role=\"region\"]` element carrying the shape the application-charts pack asserts on (an `svg.chartSvg` and a paired `<table>` element in the same landmark). A chart region that renders a chart outside the render shell fails project-side review.",
+      "given": "the rendered chart region",
+      "when": "the mount seam is inspected",
+      "then": "the chart mounts through the application-charts render shell",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19102.json

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19102",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The primary KPI tile sits top-left in DOM order and in CSS Grid position across the ratified breakpoints",
+  "asA": "reader glancing at the shipped dashboard on a laptop, a tablet and a phone",
+  "iWant": "the primary KPI to land at the top-left first-fixation position on every ratified breakpoint",
+  "soThat": "the F-scan reading pattern lands on the primary KPI first, without a per-surface layout negotiation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19102-1",
+      "description": "Given a rendered dashboard surface at each of the three ratified viewports (1440, 1024, 360), the primary KPI tile (`data-tile-role=\"primary-kpi\"`) is the first tile in DOM order within the tile row region; at 1440 and 1024 the tile's computed CSS Grid `grid-column-start` is 1 and `grid-row-start` is 1; at 360 the tile row reflows to one column and the primary KPI's `grid-row-start` is 1 (the top row). The tile carries a `data-kpi-kind` attribute whose value is one of the ADR-2001 enum (revenue, active-users, error-rate, throughput, custom). Probed by the application-dashboard pack check AC-19102-1 (Playwright drives the browser to the dashboard route, resizes the viewport to each of the three widths, reads the DOM order and the computed CSS Grid position, and asserts every breakpoint places the primary KPI top-left).",
+      "given": "a rendered dashboard surface at 1440, 1024 and 360",
+      "when": "the DOM order and the computed CSS Grid position are read",
+      "then": "the primary KPI tile is first in DOM order and top-left in CSS Grid at each of the three widths",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-19102-2",
+      "description": "Given a rendered dashboard surface with no primary KPI tile, the surface either supersedes REQ-002 with a project-authored REQ documenting the omission or fails project-side review. This case is a documentation-and-review contract; the pack asserts the primary KPI tile exists (AC-19102-1) but does not itself enforce the fallback path.",
+      "given": "a rendered dashboard with no primary KPI tile",
+      "when": "the surface is reviewed",
+      "then": "the surface supersedes REQ-002 with a project-authored REQ or fails review",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19103.json

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19103",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every tile honours the four-state contract with distinct visuals, role region, aria-live polite and non-colour distinction",
+  "asA": "screen-reader user and colour-blind reader on the shipped dashboard",
+  "iWant": "every tile state (loading, empty, error, populated) to carry a distinct visual, a labelled region, an aria-live polite announcer and a non-colour distinction",
+  "soThat": "the tile's current state is reachable regardless of assistive tech and legible regardless of colour perception",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19103-1",
+      "description": "Given a rendered tile in each of the four states (loading, empty, error, populated), the tile wraps its content in a `role=\"region\"` element carrying `aria-live=\"polite\"` and a labelled state descriptor (`data-tile-state=\"<state>\"`). The state's visual cue is not colour-only: loading carries a skeleton stripe or spinner element, empty carries a labelled empty-state block, error carries a labelled error block with the recorded reason, populated carries the metric value. Every state exposes its accessible name as `<tile title>, <state>` on the wrapping region. Probed by the application-dashboard pack check AC-19103-1 (Playwright drives to `?tile=<id>&state=<state>` for each of the four states on each of two tiles, reads the accessibility tree and the DOM, and asserts every state carries the role region, the aria-live polite, the data-tile-state attribute, and a non-colour visual cue).",
+      "given": "a tile switched into each of the four states",
+      "when": "the DOM and the accessibility tree are read",
+      "then": "each state carries role region, aria-live polite, data-tile-state, a non-colour visual cue and the announced name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-19103-2",
+      "description": "Given a tile transitioning between states (loading to populated, populated to error) at runtime, the tile's `aria-live=\"polite\"` region announces the new state's accessible name to the assistive tech; the announcement text reads `<tile title>, <new state>` and the visual cue changes in the same paint. This AC is a runtime-observable behaviour on state transition; the pack does not simulate the transition today (the runner has no synthetic-event seam beyond click/type/press), so the AC is proven at project-side review and the README names the transition-observation gap under known mechanism-reach gaps.",
+      "given": "a tile transitioning between states",
+      "when": "the transition renders",
+      "then": "the aria-live polite region announces the new state's accessible name and the visual cue changes",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}