From ef76815eb2f93f24cdd4e0cb4e543d1ee994f698 Mon Sep 17 00:00:00 2001 From: Till JS Date: Wed, 22 Apr 2026 18:07:44 +0200 Subject: [PATCH] docs(optimizable): add README index + refresh frontend-consistency tracker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The frontend-consistency-improvements.md was stale โ€” it still listed the 13 Tailwind-based ListViews as "to migrate" even though all 21 flagged modules shipped today (a2a43b1d5, 86c205ffc, 7d6a340b1, 52af8c0ce, 3e09ff66d). Rewrite to reflect the SHIPPED state and list the next layer of open consistency work (i18n, Phosphor icons, cross-surface theme parity). New docs/optimizable/README.md is the master index. Consolidates: - ๐Ÿ”ด Release blocker: tier-patch revert (links memory entry) - ๐ŸŸ  Tracked trackers: per-topic links with status - ๐ŸŸก Small open items without a dedicated file: module-structure audit, plan-inventory hygiene, memory-hygiene post-release, cross-surface theme parity - How-to: list of `pnpm run audit:*` commands for live metrics Doesn't introduce new work items beyond what's already been discussed this session โ€” just gives them a home so future sessions can pick up any one without re-discovery. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/optimizable/README.md | 97 +++++++++++++++++ .../frontend-consistency-improvements.md | 103 +++++++++++------- 2 files changed, 163 insertions(+), 37 deletions(-) create mode 100644 docs/optimizable/README.md diff --git a/docs/optimizable/README.md b/docs/optimizable/README.md new file mode 100644 index 000000000..356926090 --- /dev/null +++ b/docs/optimizable/README.md @@ -0,0 +1,97 @@ +# docs/optimizable โ€” Known Improvements Register + +Per-topic tracking docs for known-but-unshipped improvements. Run +`pnpm run audit:*` for live metrics on any item marked "OPEN" below. + +## ๐Ÿ”ด Release blockers + +### Tier-patch revert + +MANA_APPS were patched to `guest` tier locally on 2026-04-10 for pre-release +testing. **Must revert before production release.** Production tiers +are in commit `7df515434` but the working copy may still override. + +Context: memory entry `project_tier_patch_resolved.md` +(`/Users/till/.claude/projects/.../memory/`). Check +`packages/shared-branding/src/mana-apps.ts` and revert any +`requiredTier: 'guest'` patches before cutting a release. + +## ๐ŸŸ  Tracked open debt + +Each topic has its own tracker. Status as of 2026-04-22. + +| Topic | Tracker | Status | +|---|---|---| +| Frontend theming | [frontend-consistency-improvements.md](frontend-consistency-improvements.md) | Theming migration SHIPPED (ListViews, transition-all, a11y). i18n + icon bloat + cross-surface parity still OPEN. | +| i18n coverage | [i18n-migration-inventory.md](i18n-migration-inventory.md) | 65 / 78 modules hardcode German. Per-module work. | +| Test health | [test-health.md](test-health.md) | 34 / 653 tests failing (spaces-foundation WIP). 66 / 78 modules without any tests. | +| Bundle size | [bundle-analysis.md](bundle-analysis.md) | /invoices split SHIPPED (-516 KB). Icons + layout OPEN. | +| Foundation services | [foundation-layer-improvements.md](foundation-layer-improvements.md) | Contacts/Todo/Calendar architecture notes. | +| AI Workbench audit | [ai-workbench-audit-2026-04-16.md](ai-workbench-audit-2026-04-16.md) | Point-in-time audit snapshot. | + +## ๐ŸŸก Small open items (no dedicated tracker yet) + +### Module-structure consistency audit + +Not every module has a DetailView. Some have master-detail (todo, +notes, calendar), some are single-surface (calc, moodlit), some have +standalone routes (presi/deck/[id]). An audit of which modules +implement the full module-config pattern (ListView + DetailView + +components/ + queries.ts + stores/) vs which are partial would give a +sense of how strict the module SSoT actually is. + +**Suggested artefact:** `docs/optimizable/module-structure.md` + +`scripts/audit-module-structure.mjs` listing which collections are +defined vs missing per module. + +### Plan-inventory hygiene + +`docs/plans/` holds ~40 `.md` files. Some shipped (spaces-foundation, +news-research, library M1), some are in-flight (library M2โ€“M8, AI +Workbench follow-ups, space-scoped data model Modell ฮฒ), some are +stale. No single "which plans are alive / dead / shipped" index. + +**Suggested artefact:** one-liner status table in `docs/plans/README.md` +(SHIPPED / IN-FLIGHT / DRAFT / STALE with date). + +### Memory-hygiene post-release + +After the release (tier-patch revert + go-live), several memory +entries become historical: + +- `project_tier_patch_resolved.md` โ€” switch from "ACTIVE AGAIN for + testing" to "resolved". Or delete once the risk is gone. +- `project_spaces_foundation.md` โ€” mark "SHIPPED 2026-04-20" as + post-release state. +- `project_news_research_module.md` / `project_library_module.md` / + `project_ai_workbench_rollout.md` โ€” prune if follow-ups are no + longer relevant. + +No automation needed; a single post-release memory pass clears it. + +### Cross-surface theme parity + +See [frontend-consistency-improvements.md ยง6](frontend-consistency-improvements.md#6-cross-surface-theme-parity--open) +for the landing / mobile / games audit. + +## How to find live numbers + +```bash +pnpm run audit:all # port-drift + i18n + test-coverage (summary) +pnpm run audit:bundle # bundle size + content hints +pnpm run audit:icon-usage # Phosphor icon inventory +pnpm run audit:i18n-coverage # per-module hardcoded-string scan +pnpm run audit:port-drift # CLAUDE.md โ†” code port drift +pnpm run audit:test-coverage # file-level test presence +``` + +`validate:all` (pre-push gate) is the complementary set โ€” things that +would fail a push, not just report. See `package.json` scripts. + +## Historical context + +Frontend-consistency tracker (this directory's original content) has +been substantially completed: the 21 Tailwind ListViews, `transition-all`, +a11y, neutral-palette, and theme-token migrations all shipped on +2026-04-22. What remains is the next layer โ€” i18n, icons, bundle, +cross-surface โ€” documented above. diff --git a/docs/optimizable/frontend-consistency-improvements.md b/docs/optimizable/frontend-consistency-improvements.md index 2f819ce2b..555d06781 100644 --- a/docs/optimizable/frontend-consistency-improvements.md +++ b/docs/optimizable/frontend-consistency-improvements.md @@ -1,51 +1,80 @@ # Frontend Consistency Improvements -Tracked improvements for UI/styling consistency across the Mana unified app. +Tracked improvements for UI / styling consistency across the Mana +unified app. -## 1. Standardize ListView Styling Approach +## 1. ListView theme-token migration โ€” โœ… **SHIPPED 2026-04-22** -**Status:** Open -**Priority:** Low (no functional impact, maintenance concern) -**Effort:** Medium (13 modules to migrate) +All 76 module ListViews and the broader `lib/modules/**` + `routes/(app)/**` +surface now use theme tokens (`text-foreground`, `bg-muted`, +`border-border`, `--color-*` scoped CSS) instead of raw Tailwind +`white/N` or neutral-palette classes. -### Problem +Enforced by three validators wired into `validate:all` + lint-staged: -Module ListViews use two different styling approaches: +- `validate:theme-variables` โ€” CSS variable naming (`--muted` forbidden, + `--color-muted` required) +- `validate:theme-utilities` โ€” Tailwind class rules: no `(bg|text|border)-white/N`, + no `(bg|text|border)-(gray|slate|zinc|neutral|stone)-N` +- `validate:theme-parity` โ€” 25 tokens ร— 9 theme variants parity check -- **Scoped CSS + `hsl(var(--color-*))` theme tokens** โ€” 27 modules (65%) - - todo, notes, drink, contacts, journal, dreams, habits, firsts, calendar, chat, places, inventory, finance, news, body, calc, events, photos, automations, period, uload, picture, recipes -- **Tailwind utility classes** โ€” 13 modules (35%) - - food, plants, moodlit, cards, presi, storage, skilltree, context, guides, memoro, who, music, playground, citycorners, questions, times +See `packages/shared-tailwind/brand-literals.md` for the register of +intentional hex literals (period pink, calc retro skins, skilltree +branch accents, who deck colours, etc.). -### Why it matters +## 2. `transition-all` sweep โ€” โœ… **SHIPPED 2026-04-22** -- Tailwind modules sometimes hardcode colors (`bg-white/5`, `text-white/80`) instead of using theme tokens, breaking theme consistency. -- `transition-all` in Tailwind classes can cause rendering bugs with CSS custom properties (recipe module had invisible text until hover โ€” fixed by switching to specific transition properties). -- Mixed approaches make it harder to audit theme compliance and onboard new contributors. +All 98 `transition-all` occurrences replaced with specific transitions +(`transition-colors`, `transition-opacity`, `transition-[width]`, +`transition-[border-color,box-shadow]`, `transition-[transform,colors,box-shadow]`). +Prevents the P5 CSS-custom-property rendering bug where colours don't +resolve on first paint. -### Recommendation +Codemod: `scripts/migrate-transition-all.mjs`. -Migrate the 13 Tailwind-based ListViews to scoped CSS with `hsl(var(--color-*))` tokens, matching the majority pattern. Key rules: +## 3. a11y warnings โ€” โœ… **SHIPPED 2026-04-22** -1. Use `hsl(var(--color-foreground))`, `hsl(var(--color-muted))`, etc. โ€” not hardcoded colors. -2. Use specific `transition: transform 0.15s, box-shadow 0.15s` โ€” never `transition-all` (causes CSS variable animation bugs). -3. Keep scoped `