diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 66ffaf49..19cddff6 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,7 +12,9 @@ // Install Domna's curated skill set (pinned to 0.0.5) into this workspace, // then install npm deps. `gh repo clone` handles private-repo auth using // the mounted host ~/.config/gh. - "postCreateCommand": "gh repo clone Hestia-Homes/agentic-toolkit /tmp/agentic-toolkit -- --branch 0.0.8 --depth 1 && bash /tmp/agentic-toolkit/setup.sh && npm install", + // impeccable (design-guidance skill, github.com/pbakaus/impeccable) is on + // trial for the home-page redesign; drop its `skills add` step to remove it. + "postCreateCommand": "gh repo clone Hestia-Homes/agentic-toolkit /tmp/agentic-toolkit -- --branch 0.0.8 --depth 1 && bash /tmp/agentic-toolkit/setup.sh && npx --yes skills@latest add pbakaus/impeccable --agent claude-code --copy --global --yes && npm install", "forwardPorts": ["frontend:3000", "pgadmin:80"], diff --git a/.impeccable/critique/2026-07-07T13-05-05Z__portfolios-mock-html.md b/.impeccable/critique/2026-07-07T13-05-05Z__portfolios-mock-html.md new file mode 100644 index 00000000..9d2e630f --- /dev/null +++ b/.impeccable/critique/2026-07-07T13-05-05Z__portfolios-mock-html.md @@ -0,0 +1,67 @@ +--- +target: portfolios home redesign mockup (calm) +total_score: 27 +p0_count: 0 +p1_count: 3 +timestamp: 2026-07-07T13-05-05Z +slug: portfolios-mock-html +--- +# Critique: Portfolios home redesign mockup (Calm direction) + +Method: dual-agent (A: design review · B: detector/mechanical evidence). Target: scratchpad/portfolios-mock.html (artifact 76ff144a). Browser visualization skipped: no browser automation in session. + +## Design Health Score: 27/40 — Acceptable, near Good + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | 3 | Collapsed folders hide all state; a folded folder with 2 at-risk portfolios looks identical to a healthy one | +| 2 | Match System / Real World | 3 | Mixed metaphor: star icon + "Pin" labels + "favourite" in notes — pick one word | +| 3 | User Control and Freedom | 2 | No folder create/reorder/rename/delete anywhere; users can't control the page's primary organising structure | +| 4 | Consistency and Standards | 3 | Card hover-lift implies whole-card clickability but only the name is a link; Pinned isn't collapsible while folders are | +| 5 | Error Prevention | 3 | Low-stakes page; kebab actions undesigned so unassessable | +| 6 | Recognition Rather Than Recall | 3 | Folders only discoverable via hidden kebab menu | +| 7 | Flexibility and Efficiency | 2 | No "/" search shortcut, no bulk select/move, no collapse-all, no status sort | +| 8 | Aesthetic and Minimalist Design | 3 | Pinned-card duplication; status pill outranks the name in reading order | +| 9 | Error Recovery | 3 | No-results state names query + one-click clear (good); real page needs fetch-failure states | +| 10 | Help and Documentation | 2 | One teaching empty state (pinning); nothing teaches folders | + +## Anti-Patterns Verdict + +Passes the product slop test (design review): no banned patterns, schema-honest fields, restrained navy palette, earned familiarity. Deterministic detector: exit 0, zero findings — but its clean bill covers only its own rule set; mechanical checks beyond it found the non-text contrast failures below. + +## Priority Issues + +- **[P1] Sectioned-folders IA collapses at ~15 folders × 60 portfolios.** All folders open by default, no rollup, no jump nav → endless undifferentiated scroll; collapsing destroys at-a-glance state. Fix: collapsed-by-default with persisted open state; folder-header rollups (count, Σ properties, worst-status chips like "2 at risk"); sticky folder index above ~6 folders; or move folders to a left filter rail entirely. +- **[P1] Folder lifecycle undesigned.** No create, reorder (user's own question — order is hardcoded array), rename, delete. Fix: "New folder" affordance; folder-header kebab with Rename/Reorder/Remove; default alphabetical with per-user manual override (position column). +- **[P1] Pin interaction breaks keyboard/SR users.** innerHTML re-render destroys the focused star (focus drops to body); no aria-live announcements for pin/search-count changes. Fix in real build: targeted DOM updates or focus restoration by data-id + polite live region. +- **[P2] Non-text contrast failures (computed).** Idle star/kebab #9aa2b1 on white = 2.57:1; pinned gold star #f1bb06 on white = 1.77:1 (state nearly invisible to low-vision users); card border 1.24:1. Text pairs all pass 4.5:1 (lowest 5.59:1). +- **[P2] Search is name-only, no keyboard path.** Doesn't match status/goal/folder; no "/" focus; header count stays global while filtering (should read "Showing X of Y"). + +## Persona Red Flags + +**Alex (power user):** no keyboard route to search; only name text clickable despite whole-card hover-lift; organising 60 portfolios = 60 kebab round-trips (no bulk move); no collapse-all; no status sort; pinned duplication doubles scan work. + +**Sam (accessibility):** focus wiped on pin toggle; pinned state fails 3:1 non-text contrast; no announcements for dynamic changes; h2-in-summary risks odd NVDA announcements. Keeping: native details/summary, focus ring token, aria-pressed, reduced-motion handling. + +## Minor Observations + +- Empty folder renders a blank dashed box (empty string default) — needs teaching copy. +- Overspend (cost > budget) clamps the bar silently and stays blue — a red state would serve "trustworthy numbers". +- Status pill above the name makes colour the first read; name should lead on a dispatch page. +- Dead CSS (.updated-inline); list view <900px drops all data columns. +- "Hit the star" too casual for institutional register; unify Pinned/Starred/Favourites naming. +- Nothing signals folders are per-user, not shared with teammates. +- Mock file is a fragment (no doctype/lang/viewport) — supplied by the Artifact wrapper at publish, but the real page needs them natively; summary contains flow content (non-conforming, works in practice). +- Real page needs skeleton sections, not spinners. + +## Strengths + +- Schema-honest cards ("No budget set" shown, £-of-£ bar only when both fields exist) — Design Principle 1 executed. +- Trustworthy-numbers craft: tabular-nums, consistent £M/£k, honest >100% percentages. +- 10-value status enum compressed to 8 clean pills, text + colour, never colour alone. + +## Questions to Consider + +- What if folders were a left filter rail instead of page sections? Solves order, scale, and jump-nav in one move. +- What is a collapsed folder for, if collapsing hides all status? The header rollup is the reconciliation, not a nice-to-have. +- Is pin-as-duplicate right, or should pinning float items within their folder? diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 00000000..c69b31cc --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,41 @@ +# Product + +## Register + +product + +## Users + +Three operator groups, all professionals in a task, none casual visitors: + +- **Domna internal team** — analysts/consultants running assessments and modelling on behalf of landlords. Power users; live in the tool daily. +- **Housing-association staff** — landlord-side asset and sustainability managers tracking their portfolios' retrofit progress. Domain-expert but not tool-expert; visit weekly. +- **Contractors/approvers** — external parties with scoped capabilities on specific portfolios; arrive with a narrow job (approve, quote, deliver). + +Shared context: desk work, large screens, often alongside spreadsheets and procurement documents. The home page's job is orientation and dispatch — find the right portfolio fast and understand its state at a glance. + +## Product Purpose + +Domna assesses UK housing portfolios for energy retrofit: ingesting property data (bulk uploads, postcode search), modelling retrofit interventions, and reporting outcomes (EPC uplift, CO2/energy savings, valuation impact) against budgets. Success looks like a landlord trusting Domna's numbers enough to commit retrofit budgets against them. + +## Brand Personality + +**Hypothesis (user undecided — validate against mockup variants):** calm, expert, institutional — quiet confidence appropriate to housing-sector procurement, with measured warmth from the brand tan/brown accents. Brand navy (`#14163d`) carries identity in small, deliberate doses; the surface stays neutral and legible. Not playful, not loud, never salesy inside the product. + +## Anti-references + +- **Generic SaaS admin templates** — Bootstrap/AdminLTE dashboards, hero-metric cards, widget walls. +- **The current home page** — a bare centered grid of identical icon cards with no data, hierarchy, or organisation. +- **Over-designed AI mockup output** — 2rem-rounded cards, giant soft shadows, decorative gradients, invented data the schema can't supply. + +## Design Principles + +1. **Show real state, not decoration.** Every element on a card earns its place by reflecting actual schema data (status, goal, properties, budget). No invented metrics. +2. **Orientation before information.** The home page dispatches users to the right portfolio; scanability (favourites, folders, search, sort) beats per-card completeness. +3. **Earned familiarity.** Standard affordances done precisely — the tool should disappear into the task for someone fluent in Linear/Stripe-class products. +4. **Trustworthy numbers.** Figures are the product; typography and alignment treat numeric data with more care than any decorative element. +5. **Consistency over surprise.** One component vocabulary across the app; delight lives in moments (empty states, transitions), not pages. + +## Accessibility & Inclusion + +WCAG 2.1 AA: ≥4.5:1 body-text contrast (≥3:1 large text), full keyboard operability, visible focus states, `prefers-reduced-motion` alternatives for all animation. B2B housing-sector procurement may require conformance evidence. diff --git a/docs/design/home-redesign/sample1.html b/docs/design/home-redesign/sample1.html new file mode 100644 index 00000000..1a231709 --- /dev/null +++ b/docs/design/home-redesign/sample1.html @@ -0,0 +1,792 @@ + + + + + + + Domna | Property Portfolios + + + + + + + + + + + + + + +
+
+
+ Domna + +
+
+
+ search + +
+ + +
+ User profile +
+
+
+
+
+ +
+
+

+ Property Portfolios +

+

+ Strategic oversight of energy retrofit assets. Curate, monitor, and + scale sustainability across your entire estate architecture. +

+
+
+
+ + +
+ +
+
+ +
+
+ Status: + All Active + expand_more +
+
+ Tag: + Residential + expand_more +
+
+ Sort by: + Budget (High) + expand_more +
+
+ +
+ +
+ +
+
+
+ + In Progress +
+
+ + +
+
+

+ London Social Housing +

+

+ location_on + Greater London Authority +

+
+
+ Budget Utilization + £4.2M / £6.5M +
+
+
+
+
+
+
+ Target EPC + Rating A +
+
+ Properties + 142 Units +
+
+
+ High Priority + Residential +
+
+ +
+
+
+ + Planning +
+
+ + +
+
+

+ Commercial Retrofit 2026 +

+

+ location_on + Manchester City Council +

+
+
+ Budget Utilization + £0.8M / £12.0M +
+
+
+
+
+
+
+ Target EPC + Rating B+ +
+
+ Properties + 28 Assets +
+
+
+ Commercial + Carbon Neutral +
+
+ +
+
+
+ + In Progress +
+
+ + +
+
+

+ Oxfordshire Eco Village +

+

+ location_on + Regional Development +

+
+
+ Budget Utilization + £2.9M / £3.1M +
+
+
+
+
+
+
+ Target EPC + Net Zero +
+
+ Properties + 18 Units +
+
+
+ Sustainability +
+
+ +
+
+
+ + In Progress +
+
+ + +
+
+

+ Northern Estate Phase II +

+

+ location_on + Leeds District +

+
+
+ Budget Utilization + £5.1M / £15.0M +
+
+
+
+
+
+
+ Target EPC + Rating B +
+
+ Properties + 310 Units +
+
+
+ Residential + Scale +
+
+ +
+
+
+ + Planning +
+
+ + +
+
+

+ Birmingham Tech Hub +

+

+ location_on + Innovation District +

+
+
+ Budget Utilization + £0.1M / £4.5M +
+
+
+
+
+
+
+ Target EPC + Rating A +
+
+ Properties + 4 Assets +
+
+
+ Commercial +
+
+ + +
+ +
+
+ + + + + ... + + +
+

+ Showing 6 of 142 portfolios +

+
+
+ + + + diff --git a/docs/design/home-redesign/sample2.html b/docs/design/home-redesign/sample2.html new file mode 100644 index 00000000..6cd777c0 --- /dev/null +++ b/docs/design/home-redesign/sample2.html @@ -0,0 +1,972 @@ + + + + ```html + + + + Domna | Property Portfolios + + + + + + + + + + +
+
+
+ Domna + +
+
+
+ search + +
+ + +
+ User profile +
+
+
+
+
+
+ +
+
+

+ Property Portfolios +

+

+ Strategic oversight of energy retrofit assets. Curate, monitor, + and scale sustainability across your entire estate architecture. +

+
+
+
+ Show + +
+
+ + +
+
+
+
+
+
+ Status: + All Active + expand_more +
+
+ Tag: + Residential + expand_more +
+
+ Sort by: + Budget (High) + expand_more +
+
+ +
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ London Social Housing +

+

+ location_on + Greater London Authority +

+
+
+ Budget Utilization + £4.2M / £6.5M +
+
+
+
+
+
+
+ Target EPC + Rating A +
+
+ Properties + 142 Units +
+
+
+ High Priority + Residential +
+
+
+
+
+ + Planning +
+
+ + +
+
+

+ Commercial Retrofit 2026 +

+

+ location_on + Manchester City Council +

+
+
+ Budget Utilization + £0.8M / £12.0M +
+
+
+
+
+
+
+ Target EPC + Rating B+ +
+
+ Properties + 28 Assets +
+
+
+ Commercial + Carbon Neutral +
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ Oxfordshire Eco Village +

+

+ location_on + Regional Development +

+
+
+ Budget Utilization + £2.9M / £3.1M +
+
+
+
+
+
+
+ Target EPC + Net Zero +
+
+ Properties + 18 Units +
+
+
+ Sustainability +
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ Northern Estate Phase II +

+

+ location_on + Leeds District +

+
+
+ Budget Utilization + £5.1M / £15.0M +
+
+
+
+
+
+
+ Target EPC + Rating B +
+
+ Properties + 310 Units +
+
+
+ Residential + Scale +
+
+
+
+
+ + Planning +
+
+ + +
+
+

+ Birmingham Tech Hub +

+

+ location_on + Innovation District +

+
+
+ Budget Utilization + £0.1M / £4.5M +
+
+
+
+
+
+
+ Target EPC + Rating A +
+
+ Properties + 4 Assets +
+
+
+ Commercial +
+
+ +
+ +
+
+ + + + + ... + + +
+

+ Showing 6 of 142 portfolios +

+
+
+ + + ``` + + diff --git a/docs/design/home-redesign/sample3.html b/docs/design/home-redesign/sample3.html new file mode 100644 index 00000000..643356e3 --- /dev/null +++ b/docs/design/home-redesign/sample3.html @@ -0,0 +1,540 @@ + + + + + + Domna | Property Portfolios + + + + + + + + + +
+
+
+ Domna + +
+
+
+ search + +
+ + +
+ User profile +
+
+
+
+
+
+ +
+
+
+

+ Property Portfolios +

+

+ Strategic oversight of energy retrofit assets. Curate, monitor, and + scale sustainability across your entire estate architecture. +

+
+
+
+ + +
+
+
+
+
+ Status: + All Active + expand_more +
+
+ Tag: + Residential + expand_more +
+
+ Sort by: + Budget (High) + expand_more +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Portfolio NameStatusBudget ProgressTarget EPCProperties
+
+
+ London Social Housing +
+
+ location_on + Greater London Authority +
+
+ 		+
+ + In Progress +
+ 		+
+
+ 64% + £4.2M / £6.5M +
+
+
+
+
+ 		+ Rating A + + 142 Units + + +
+
+
+ Commercial Retrofit 2026 +
+
+ location_on + Manchester City Council +
+
+ 		+
+ + Planning +
+ 		+
+
+ 7% + £0.8M / £12.0M +
+
+
+
+
+ 		+ Rating B+ + + 28 Assets + + +
+
+
+ Oxfordshire Eco Village +
+
+ location_on + Regional Development +
+
+ 		+
+ + In Progress +
+ 		+
+
+ 93% + £2.9M / £3.1M +
+
+
+
+
+ 		+ Net Zero + + 18 Units + + +
+
+
+
+ Items per page: +
+ + expand_more +
+
+
+
+ + + + + ... + + +
+

+ Showing 1-25 of 142 portfolios +

+
+ +
+
+ + + diff --git a/docs/design/home-redesign/sample4.html b/docs/design/home-redesign/sample4.html new file mode 100644 index 00000000..ed6dde8e --- /dev/null +++ b/docs/design/home-redesign/sample4.html @@ -0,0 +1,1136 @@ + + + + + + Domna | Property Portfolios + + + + + + + + + + + +
+
+
+ Domna + +
+
+
+ search + +
+ + +
+ User profile +
+
+
+
+
+
+
+ + +
+

+ Property Portfolios +

+
+
+
+ + +
+
+
+
+
+ Status: + All Active + expand_more +
+
+ Tag: + Residential + expand_more +
+
+ Sort by: + Budget (High) + expand_more +
+ +
+
+
+ Show: + + unfold_more +
+
+
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ London Social Housing +

+

+ location_onGreater London Authority +

+
+
+ Budget Utilization + £4.2M / £6.5M +
+
+
+
+
+
+
+ Target EPCRating A +
+
+ Properties142 Units +
+
+
+ High Priority + Residential +
+
+
+
+
+ + Planning +
+
+ + +
+
+

+ Commercial Retrofit 2026 +

+

+ location_onManchester City Council +

+
+
+ Budget Utilization + £0.8M / £12.0M +
+
+
+
+
+
+
+ Target EPCRating B+ +
+
+ Properties28 Assets +
+
+
+ Commercial + Carbon Neutral +
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ Oxfordshire Eco Village +

+

+ location_onRegional Development +

+
+
+ Budget Utilization + £2.9M / £3.1M +
+
+
+
+
+
+
+ Target EPCNet Zero +
+
+ Properties18 Units +
+
+
+ Sustainability +
+
+
+
+
+ + In Progress +
+
+ + +
+
+

+ Northern Estate Phase II +

+

+ location_onLeeds District +

+
+
+ Budget Utilization + £5.1M / £15.0M +
+
+
+
+
+
+
+ Target EPCRating B +
+
+ Properties310 Units +
+
+
+ Residential +
+
+
+
+
+ + Planning +
+
+ + +
+
+

+ Birmingham Tech Hub +

+

+ location_onInnovation District +

+
+
+ Budget Utilization + £0.1M / £4.5M +
+
+
+
+
+
+
+ Target EPCRating A +
+
+ Properties4 Assets +
+
+
+ Commercial +
+
+ +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Portfolio Name + + Status + + Location + + EPC Target + + Budget Progress + + Assets +
+
+ star + London Social Housing +
+ 		+ In Progress + + Greater London Authority + + A + +
+
+
+
+ 64% +
+ 		142 + +
+
+ star + Commercial Retrofit 2026 +
+ 		+ Planning + + Manchester City Council + + B+ + +
+
+
+
+ 7% +
+ 		28 + +
+
+ star + Oxfordshire Eco Village +
+ 		+ In Progress + + Regional Development + + Net Zero + +
+
+
+
+ 93% +
+ 		18 + +
+
+ star + Northern Estate Phase II +
+ 		+ In Progress + + Leeds District + + B + +
+
+
+
+ 34% +
+ 		310 + +
+
+ star + Birmingham Tech Hub +
+ 		+ Planning + + Innovation District + + A + +
+
+
+
+ 2% +
+ 		4 + +
+
+
+
+
+ + + + + ... + + +
+

+ Showing 6 of + 142 portfolios +

+
+
+ + +