From d1253e8a7b4d2dc4d6a8f0b91dea3a654e72222e Mon Sep 17 00:00:00 2001 From: Sulthan Zaki Date: Mon, 27 Jul 2026 00:34:01 +0700 Subject: [PATCH] docs: track product context and UI critique snapshots MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PRODUCT.md records the durable constraints the UI work keeps having to rediscover: dark-first is binding (night reading), mobile is the target rather than the starting breakpoint, and updated_at ordering is a correctness rule the design must not decorate over. The two critique snapshots are the scored before/after (21/40, then 26/40) the card fixes were driven from — worth keeping as the record of which problems were already known, and which ones the fixes introduced. Co-Authored-By: Claude Opus 5 --- PRODUCT.md | 56 +++++++++++++++++++ ...6T15-50-42Z__backend-templates-app-html.md | 52 +++++++++++++++++ ...6T17-08-41Z__backend-templates-app-html.md | 51 +++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 PRODUCT.md create mode 100644 backend/.impeccable/critique/2026-07-26T15-50-42Z__backend-templates-app-html.md create mode 100644 backend/.impeccable/critique/2026-07-26T17-08-41Z__backend-templates-app-html.md diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..3540e61 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,56 @@ +# Product + + + +## Platform + +web + +## Users + +Single user (self-hosted, no accounts, no multi-user planned). Reads manga on **asurascans.com** and **demonicscans.org** primarily via Bromite on mobile, also checks/updates from a desktop browser. The web UI is the cross-device view into progress captured by the userscript while reading. + +## Product Purpose + +Tracks read-progress ("last chapter read") per manga series across two otherwise-unrelated manga sites that each have their own separate `localStorage`. A Go backend unifies bookmarks into one store; the web UI is a password-gated browser view of that store for reviewing, favouriting, correcting, or removing bookmarks, and jumping back into a series to continue reading. A background poller also refreshes each series' latest-published-chapter so the list can flag "NEW" without the user visiting the site. + +## Positioning + +Not a public reading tracker or social app — a private, self-hosted sync layer purpose-built for two specific scraped sites, with no server-side account system (single bearer token + one password-gated session). + +## Operating Context + +- Primary reading device: Bromite (mobile Chromium), where a userscript captures progress automatically. +- Web UI is a secondary surface: checking list state, correcting a wrong chapter number, removing dead bookmarks, jumping to "continue reading." +- Manga cover art and titles come from the source sites' `og:image`/`og:title` — real content, not placeholders. +- List order is driven by `updated_at`, which moves only on real reading progress (not favouriting, not a newly detected chapter) — a UI constraint the redesign must not break. + +## Capabilities and Constraints + +- Two tabs: All / Favourites. Search-filter by title (client-side, `filter.js`). +- Card actions: continue (opens source site), toggle favourite, manual chapter override, delete (with confirm). +- "Continue reading" horizontal strip for recently-progressed series. +- htmx-driven partial updates (card re-render on favourite/chapter/delete), no client-side framework/build step — templates are Go `html/template`, `go:embed`-ed. +- Mobile-first is a hard functional constraint (primary device is a phone), not just a starting breakpoint. + +## Brand Commitments + +- Name: **mangaBookmark**. +- **Dark-first is binding**: current dark-by-default / light-follows-system-preference behavior must be preserved as a design constraint, not just a starting default, because reading happens at night. + +## Evidence on Hand + +- Live templates/CSS at `backend/templates/*.html`, `backend/static/style.css` — current implemented UI, functional but not yet treated as an intentional design system. +- No logo, screenshots, or marketing copy exist; none should be fabricated. + +## Product Principles + +- Dark-first, night-reading-optimized — never regress to a light-default or high-glare surface. +- Mobile is the primary target; desktop is an enhancement, not the design center. +- Progress data integrity over visual flourish: `updated_at`/list-ordering behavior is a correctness constraint the UI must respect, not decorate over. +- No accounts, no multi-tenant chrome — the whole product is for one reader. +- Prefer native platform affordances (system dark/light, native touch targets) over custom widgetry — this is a lean self-hosted tool, not a product to demo. + +## Accessibility & Inclusion + +Explicit personal requirement: optimized for **low-light/night reading** — minimize glare and eye strain (true dark surfaces, restrained brightness/contrast on accents, no jarring pure-white flashes), beyond generic touch-target/contrast compliance. diff --git a/backend/.impeccable/critique/2026-07-26T15-50-42Z__backend-templates-app-html.md b/backend/.impeccable/critique/2026-07-26T15-50-42Z__backend-templates-app-html.md new file mode 100644 index 0000000..303ca7e --- /dev/null +++ b/backend/.impeccable/critique/2026-07-26T15-50-42Z__backend-templates-app-html.md @@ -0,0 +1,52 @@ +--- +target: backend/templates (web UI) +total_score: 21 +max_score: 40 +na_heuristics: +p0_count: 0 +p1_count: 2 +timestamp: 2026-07-26T15-50-42Z +slug: backend-templates-app-html +--- +Method: dual-agent (A: ab4734f79f4becbf2 · B: af2c412345f87a2d1) + +## Design Health Score + +| # | Heuristic | Score | Key Issue | +|---|---|---|---| +| 1 | Visibility of System Status | 2 | No hx-indicator on any htmx mutation — favourite/save/delete swap silently | +| 2 | Match System/Real World | 3 | Icon-only actions rely on title= tooltips, which never fire on touch | +| 3 | User Control and Freedom | 2 | Favourite-toggle and chapter-save are instant, no undo | +| 4 | Consistency and Standards | 3 | Native unstyled confirm() for delete breaks from themed htmx-swap pattern | +| 5 | Error Prevention | 2 | Chapter input has no max, no reference to LatestChapter while editing | +| 6 | Recognition Rather Than Recall | 3 | Good persistent state; edit form doesn't show current latest chapter | +| 7 | Flexibility and Efficiency | 1 | No bulk actions, no shortcuts, no filter for "has new chapter" | +| 8 | Aesthetic/Minimalist Design | 3 | Lean; .meta/.actions rows lack visual grouping | +| 9 | Error Recovery | 1 | No failed-request UI state anywhere | +| 10 | Help and Documentation | 1 | Zero affordance explains the favourite/NEW-don't-reorder rule | + +Total: 21/40 — Acceptable band + +## Design Specificity Verdict +Generic-competent. Nothing signals manga/night-reading/two-site-unification beyond the header text. site-{{.Site}} badge (the actual product differentiator) styled as a neutral pill, same weight as everything else. + +Deterministic scan: CLI static-HTML detector 0 findings (exit 0). Browser/live detector found: tight-leading (line-height 1.25, real), overused-font/single-font (100% Roboto), flat-type-hierarchy advisory (~1.5:1 ratio). One text-occlusion hit was a false positive (detector's own leftover overlay text). + +## Priority Issues +P1 — Silent failure on every htmx mutation (no hx-indicator, no error UI). Fix: hx-indicator + htmx:responseError inline error text. +P1 — NEW-chapter signal has no visual priority/filter despite poller existing for exactly this. Fix: elevate .new styling, add "Updated" quick-filter. +P2 — Native confirm() on delete breaks dark theme, violates "no pure-white flash" a11y requirement. Fix: inline htmx confirm row. +P2 — Chapter input has no upper bound/reference to LatestChapter. Fix: show "Latest: Ch N" inline, soft max warning. +P3 — Single font, flat type scale, line-height under 1.3 floor. Fix: real typographic hierarchy. + +## Persona Red Flags +Casey (mobile, primary): 4 stacked chrome regions before content; touch-only tooltips never fire; silent failures invite repeat-tapping. +Riley (stress): webkit-only line-clamp with no fallback; no-cover cards render blank with no placeholder; filter.js untested at scale. + +## Minor Observations +Continue-strip not tab-scoped. Fixed accent colors unverified for contrast against light theme. title= tooltips dead weight on touch. + +## Questions to Consider +1. Why does the NEW-chapter signal carry less visual weight than the static site badge? +2. Why is confirm() (guaranteed to break theme) still unreplaced given the explicit no-white-flash requirement? +3. Does the ordering rule need an explanation, or does needing one mean the mental model fights the user? diff --git a/backend/.impeccable/critique/2026-07-26T17-08-41Z__backend-templates-app-html.md b/backend/.impeccable/critique/2026-07-26T17-08-41Z__backend-templates-app-html.md new file mode 100644 index 0000000..a1d3e44 --- /dev/null +++ b/backend/.impeccable/critique/2026-07-26T17-08-41Z__backend-templates-app-html.md @@ -0,0 +1,51 @@ +--- +target: backend/templates (web UI) +total_score: 26 +max_score: 40 +na_heuristics: +p0_count: 1 +p1_count: 0 +timestamp: 2026-07-26T17-08-41Z +slug: backend-templates-app-html +--- +Method: dual-agent (A: a67675dd3039e8156 · B: aa64e48aafb9db799), regression independently re-verified live + +## Design Health Score + +| # | Heuristic | Score | Key Issue | +|---|---|---|---| +| 1 | Visibility of System Status | 3 | htmx dimming/error-inline verified live and working | +| 2 | Match System/Real World | 4 | "Continue reading," "Updated," site names all read naturally | +| 3 | User Control and Freedom | 3 | Cancel works; no undo after delete (acceptable, single-user tool) | +| 4 | Consistency and Standards | 2 | Disclosure-toggle pattern consistent; bare-emoji icons vs. tuned typography mismatch | +| 5 | Error Prevention | 2 | Chapter input still has no max, hint is prose-only | +| 6 | Recognition Rather Than Recall | 2 | The hint meant to aid recall is what causes the overflow bug | +| 7 | Flexibility and Efficiency | 3 | Search, tabs, direct Continue link present | +| 8 | Aesthetic/Minimalist Design | 2 | Clean tokens undercut by a live horizontal-scroll bug and flat no-cover placeholder | +| 9 | Error Recovery | 3 | "No connection - try again" verified firing on network abort | +| 10 | Help and Documentation | 2 | No help affordance beyond hover tooltips | + +Total: 26/40 - Acceptable band. Trend: 21 -> 26. + +## Design Specificity Verdict +Real measured progress: site-tinted badges and --new ribbon hue verified via computed contrast (5.3-9.0:1), genuine product-specific signal. Working against it: bare OS-emoji icons (star/pencil/trash/play) clash with tuned typography; no-cover placeholder still a flat contentless box. + +Deterministic scan: CLI 0 findings (clean). Live detector: overused-font/single-font expected (deliberate single-typeface Operate surface). flat-type-hierarchy already accepted. monotonous-spacing and text-occlusion confirmed FALSE POSITIVES (detector's own accumulated debug overlays). edge-flush-cards on Continue-reading strip likely false positive (deliberate scrollable carousel with edge-bleed). ai-color-palette flagging new site-tint hues - plausible false positive (contrast-verified, restrained) but unconfirmed. + +## Priority Issues +P0 - Chapter-edit form causes 97-127px horizontal page overflow on mobile, Save button pushed off-screen. .chapter-form has display:flex with no wrap, now holds 3 children (hint/input/button) in one unwrapped row. Confirmed live at 390px and 360px. Regression from the harden command - hint text was verified to render but never checked for container overflow at mobile width. Fix: flex-wrap:wrap + .hint{flex:1 0 100%}, same pattern already used in .actions/.confirm-row. +P3 - Icon-glyph inconsistency: bare emoji vs tuned type/color system. +P3 - No-cover placeholder reads as stuck loading skeleton, not designed empty state. +P3 - .confirm-row text wraps awkwardly ("Remove/this?") - cosmetic only, no overflow. + +## Persona Red Flags +Casey (mobile, primary): chapter-form overflow directly hits her core task (one-handed chapter correction), unexpected sideways scroll needed. +Sam (accessibility): well-served overall, but no custom :focus-visible on icon/action buttons. + +## Minor Observations +Continue-reading strip still not tab-scoped. updated_at ordering verified live via actual favourite-toggle round-trip. ai-color-palette on site tints worth a second glance, unconfirmed either way. + +## Questions to Consider +1. Did the harden command's verification ever check mobile viewport width with the hint text present, or only that it rendered? +2. Is the emoji-icon look deliberate "undesigned" for a single-user tool, or just expedient? +3. Is a missing og:image common enough in practice to deserve real empty-state design?