mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:01:09 +02:00
docs(optimizable): add README index + refresh frontend-consistency tracker
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) <noreply@anthropic.com>
This commit is contained in:
Till JS
parent
81a426af28
commit
ef76815eb2
2 changed files with 163 additions and 37 deletions
97
docs/optimizable/README.md
Normal file
97
docs/optimizable/README.md
Normal file
|
|
@ -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.
|
||||||
|
|
@ -1,51 +1,80 @@
|
||||||
# Frontend Consistency Improvements
|
# 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
|
All 76 module ListViews and the broader `lib/modules/**` + `routes/(app)/**`
|
||||||
**Priority:** Low (no functional impact, maintenance concern)
|
surface now use theme tokens (`text-foreground`, `bg-muted`,
|
||||||
**Effort:** Medium (13 modules to migrate)
|
`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%)
|
See `packages/shared-tailwind/brand-literals.md` for the register of
|
||||||
- todo, notes, drink, contacts, journal, dreams, habits, firsts, calendar, chat, places, inventory, finance, news, body, calc, events, photos, automations, period, uload, picture, recipes
|
intentional hex literals (period pink, calc retro skins, skilltree
|
||||||
- **Tailwind utility classes** — 13 modules (35%)
|
branch accents, who deck colours, etc.).
|
||||||
- food, plants, moodlit, cards, presi, storage, skilltree, context, guides, memoro, who, music, playground, citycorners, questions, times
|
|
||||||
|
|
||||||
### 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.
|
All 98 `transition-all` occurrences replaced with specific transitions
|
||||||
- `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).
|
(`transition-colors`, `transition-opacity`, `transition-[width]`,
|
||||||
- Mixed approaches make it harder to audit theme compliance and onboard new contributors.
|
`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.
|
30 svelte-check warnings resolved; `pnpm check` now runs with
|
||||||
2. Use specific `transition: transform 0.15s, box-shadow 0.15s` — never `transition-all` (causes CSS variable animation bugs).
|
`--fail-on-warnings` so any regression blocks pre-push. Covers
|
||||||
3. Keep scoped `<style>` blocks — no Tailwind utility classes in ListView templates.
|
a11y (missing keyboard handlers, missing labels), dead CSS selectors,
|
||||||
|
and Svelte 5 `$state` local-reference bugs.
|
||||||
|
|
||||||
### Modules to migrate
|
## 4. i18n coverage — OPEN
|
||||||
|
|
||||||
- [ ] food
|
65 / 78 modules still hardcode German in `.svelte` templates. The
|
||||||
- [ ] plants
|
translation infrastructure (`@mana/shared-i18n`, per-module locale
|
||||||
- [ ] moodlit
|
files for de / en / it / fr / es with ~3500 German strings) is fully
|
||||||
- [ ] cards
|
wired; what's missing is usage. See
|
||||||
- [ ] presi
|
[`i18n-migration-inventory.md`](i18n-migration-inventory.md) for the
|
||||||
- [ ] storage
|
priority list and per-module workflow. Run
|
||||||
- [ ] skilltree
|
`pnpm run audit:i18n-coverage` for live numbers.
|
||||||
- [ ] context
|
|
||||||
- [ ] guides
|
Top offenders today: broadcast (26 hits), articles (24), events (23),
|
||||||
- [ ] memoro
|
invoices (22), quiz + stretch (20 each), library (19), profile (17),
|
||||||
- [ ] who
|
skilltree PARTIAL (15), calendar PARTIAL (14).
|
||||||
- [ ] music
|
|
||||||
- [ ] playground
|
## 5. Phosphor icon bloat — OPEN
|
||||||
- [ ] citycorners
|
|
||||||
- [ ] questions
|
`@mana/shared-icons` contributes 466 KB of icon paths to the shared
|
||||||
- [ ] times
|
bundle. See [`bundle-analysis.md`](bundle-analysis.md) §2. Biggest
|
||||||
|
offender: `app-registry/apps.ts` imports 69 icons statically for the
|
||||||
|
module-name → icon-component map — ~290 KB alone. Recommended fix:
|
||||||
|
lazy `getIconComponent(name)` helper backed by per-icon dynamic
|
||||||
|
imports.
|
||||||
|
|
||||||
|
Run `pnpm run audit:icon-usage` for the current inventory.
|
||||||
|
|
||||||
|
## 6. Cross-surface theme parity — OPEN
|
||||||
|
|
||||||
|
Not yet audited:
|
||||||
|
|
||||||
|
- **`apps/mana/apps/landing/`** (Astro) — does the landing page use
|
||||||
|
the same theme tokens as the SvelteKit app, or a parallel system?
|
||||||
|
Theme drift would mean Lume / Nature / Stone variants don't match
|
||||||
|
between marketing and app.
|
||||||
|
- **`apps/memoro/apps/mobile/`** (Expo, RN) — the only remaining
|
||||||
|
mobile surface. `@mana/shared-theme` targets React Native; is the
|
||||||
|
token set aligned with the web `--color-*` palette?
|
||||||
|
- **`games/`** (arcade, voxelava, whopixels, worldream) — separate
|
||||||
|
Vite/Svelte apps; unlikely to be aligned with the main theme but
|
||||||
|
worth confirming.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue