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 `