feat(mcp): widget UX polish — i18n, colour semantics, CTAs, dead payload data, card alignment (#570)

[guillermoscript]

What

The seven polish items from #570, plus one bug found in the tooling they needed. None of these were broken output — each one worked and read badly.

Closes #570

Why

Per item, and what turned out to be true rather than what the issue assumed:

1. Widgets were English-only next to Spanish content. Every string a widget owned was hardcoded, and every date went through toLocaleDateString(undefined, …), which is the reader's browser locale rather than the school's. New resources/shared/i18n.tsx exposes useLang / useStrings / useFormat, driven by useWidget().locale (the BCP 47 tag the host supplies per SEP-1865) and timeZone. All 13 widgets with user-visible chrome now carry an en/es table, typed Record<Lang, T> so a missing Spanish string is a compile error rather than a runtime fallback. Every toLocale* call site is gone. practice-player had a hand-rolled navigator.language sniff for one string; it now uses the shared hook.

Only widget-owned strings are translated. Course titles, lesson titles, student names and tags come out of the database in the school's own language and are rendered verbatim.

2. Brand purple was a mid value on a red→green scale. completionColor (school-overview) and progressColor (student-progress-roster) were the same function copied twice, both running amber → brand → green. They collapse into resources/shared/severity.tsx on red/amber/green with brand removed — the rule #571 already states ("Accents theme, status colours deliberately do not").

The two copies had already drifted: at exactly 0% one returned zinc and the other red. That forced the real question, so "no data" is now null and distinct from a real zero — a draft course with nothing to complete reads neutral instead of being painted as a failing one.

Also in scope, from the same item: KPI tiles get a stated rule (colour marks a verdict; counts of courses and students are facts and stay neutral), and the 3 published · 2 draft caption gains the missing archived bucket so the parts sum to the 6 shown above them.

Not in the issue, fixed anyway: the at-risk tile's caption was the hardcoded string "active · 0 lessons done" — not derived from anything. The real rule (analytics.ts) is active enrollment + course has published lessons + zero completions, so the caption now says that. Flagging separately because it was wrong output, not polish. Related: that number counts enrollment pairs, not distinct students, while the tile is labelled "At-risk students". I left the label alone — changing what it counts is #568's territory — but the caption now discloses the unit.

3. exam-readiness buried the thing to act on. Topics render weakest-first, the weakest is marked, the practice CTA drops to a quiet link on already-mastered topics so it stops competing, and days-until-exam is rendered from exam.exam_date (counted in calendar days, so a 09:00 exam tomorrow reads "tomorrow", not "in 0 days").

4. my-learning's next lesson is now a button. It is the card's actual job, and it was a grey pill in the footer.

5. course-catalog had no price to render. Not "not displayed" — not present. lms_browse_catalog selected course_id, title, description, thumbnail_url, tags, created_at and never asked for one. It now joins product_courses → products and reports the cheapest active product per course (a course can be sold under several, so this aggregates rather than .single()-ing). Enroll/Access collapse into one verb, Not in plan becomes a real path instead of a grey dead end, and the 96px 📖 placeholder is dropped when there is no thumbnail rather than reserving space for nothing.

6. study-plan's next_lessons was dropped in the common case. Slight correction to the issue: it was rendered — inside the goals.length === 0 branch only. So the moment a student had a plan at all, the payload was fetched and thrown away. Same fix, aimed at the case you actually see.

7. Null fields broke card-row alignment. course-dashboard, course-catalog and gamification-profile give their cards a shared row grid via grid-rows-subgrid, so a null description or an absent tag row collapses without pushing the tags and footers out of line with the neighbouring cards.

Drive-by: brand= never worked

The demo tools' documented brand=ocean|sunset|forest argument themed nothing. src/tools/demo.ts computed the branding, named it in the output text, and never attached it to the result — BRANDING_META_KEY was an unused import. It now goes through widget({ metadata }), the same _meta sideband the real server uses.

I fixed it because I needed that channel: the headless preview harness supplies no host locale, so useWidget().locale falls back to "en" and the Spanish path would have had no evidence at all. The demo tools now take lang=en|es over the same sideband. Nothing in production sets it; the host stays the source of truth. Documented in docs/WIDGET_DEMO_DATA.md.

How to QA

No migration, no seed data, no login — this is all offline against committed fixtures.

cd mcp-server && npm install
MCP_DEMO_WIDGETS=1 npm run dev
# inspector: http://localhost:3000/inspector?autoConnect=http%3A%2F%2Flocalhost%3A3000%2Fmcp

Then, per item — every one has a named fixture:

1. i18n — run lms_demo_school_overview with variant=default, then again with lang=es. The fixtures are Spanish, so lang=es is what a real school looks like and the default is the mismatch the issue is about. Dates and numbers should follow (4 ago 2026, 54 %).
2. Colour — lms_demo_school_overview and lms_demo_student_progress_roster, variant=default. No violet in any bar; 68% is amber, 22% is red, 91% is green. Drafts with 0 lessons are grey with —, not red 0%. The Courses tile should read 3 published · 2 draft · 1 archived and sum to 6.
3. exam-readiness — variant=default. Topics run 12 → 88, the 12% "Compilador de React" is first and flagged, "Server components" (88) has a quiet link, and the header shows a countdown.
4. my-learning — variant=default. The next lesson is a filled primary button.
5. course-catalog — variant=subscriber. Prices on the cards you cannot yet access, one verb on every CTA, Get access where Not in plan used to be a dead end, and no book-emoji blocks. variant=no-plan for the unsubscribed case.
6. study-plan — variant=default (i.e. with goals, where it used to be dropped). An "Up next" block with an Open → per lesson.
7. Alignment — lms_demo_course_dashboard variant=default ("Diseño de APIs REST" has no description) and lms_demo_gamification_profile variant=default ("Buena gente" has no description and no tier). Tag rows and footers should sit on one line across each row.
8. The drive-by — any demo tool with brand=forest. It should render green. On master it renders violet.

Whole set at once, both themes:

./scripts/shoot-demo-widgets.sh dark     # → mcp-server/demo-shots/dark/
./scripts/shoot-demo-widgets.sh light

Screenshots / GIF

Posted as a comment below — before/after for each item, dark and light, plus the Spanish render.

Checklist

• npm run typecheck and npm run test:unit pass — in mcp-server: tsc --noEmit clean, vitest run 39/39
• npm run build passes — mcp-use build, 18 widgets built, type check passed
• Every new tenant-scoped query filters by tenant_id (or the table genuinely has no such column) — the new product_courses query filters tenant_id and is explicit about products.status = 'active' on top of the RLS policy that already enforces it
• Tested with every relevant role (student / teacher / admin) — see below
• Loading and error states handled — pending branches translated too; the price lookup degrades to no price rather than failing the catalog
• New UI strings added to both messages/en.json and messages/es.json — n/a, and worth being explicit: MCP widgets render in a host iframe and never load next-intl, which is exactly why they had no i18n. Their strings live in per-widget tables next to the component.
• Migration — none.

On the role checkbox, honestly

The widgets are covered per role by their fixtures, which is what this issue's "done when" asks for, and the tool-policy split is unchanged. What I did not do is exercise lms_browse_catalog against a live tenant with real products rows — the price join is the one change here that touches a database query, and offline fixtures cannot prove it. The RLS policies allow it ("Anyone can view active products" is TO anon, authenticated USING (status = 'active'), and product_courses is USING (true)), and it fails soft — a query error leaves cards priceless rather than breaking the catalog. But a reviewer with a seeded tenant should confirm a real price appears.

Notes for the reviewer

• submission-grader also has changes in fix(mcp): submission-grader misreports what is graded — ungraded zeros, invisible overrides, decorative confidence (#567) #574 (issue submission-grader: ungraded questions render as 0, overrides are invisible, AI confidence is decoration #567, in flight). I only touched its strings and date formatting, but expect a conflict there for whichever lands second.
• my-learning's progress bars are still brand-coloured, deliberately. That widget never had a red→green ramp — it is brand for in-progress and green for complete, a two-state accent rather than a severity scale, so item 2's rule does not apply to it.
• The lang _meta override is a preview affordance, not a second config surface. Nothing in production sets it, and there is no locale column anywhere in the schema to set it from.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bs69mfRZXog8KPM1n626RA

[guillermoscript]

Visual evidence

Before/after per item, from the committed fixtures — every one is reproducible offline in under a minute with MCP_DEMO_WIDGETS=1 npm run dev and the named variant. Left is master, right is this branch, same fixture, same theme.

2. Colour semantics — school_overview:default

Three separate things in one shot. The bars stop using brand violet as the value between amber and green: 68% and 47% are amber, 22% is red, 91% stays green. 3 published · 2 draft becomes 3 published · 2 draft · 1 archived, which now sums to the 6 above it. The at-risk caption stops claiming active · 0 lessons done — a string that was hardcoded, not computed — and states the rule the number actually comes from.

Two smaller ones visible here too: the KPI accents follow a rule now (54% and 76% are verdicts and get colour; the counts are facts and stay neutral), and "Diseño de APIs REST" — a draft with 0 published lessons — reads — on a grey bar instead of a red 0%, because having nothing to complete is not the same as having completed nothing.

3. exam-readiness — exam_readiness:default

Before, the topics run 88, 79, 44, 35, 62, 12 — payload order, so the weakest topic in the course is the last thing you reach, and all six "Practice this" buttons shout equally. After: 12, 35, 44, 62, 79, 88, with the 12% topic flagged and outlined, and the mastered 88 dropped to a quiet link so it stops competing. The header gains the countdown (in 8 days) instead of making the reader subtract dates.

5. course-catalog — course_catalog:subscriber

The six identical grey 📖 blocks are gone, which is most of the height back. Prices appear on the cards where price is still a decision. Enroll and Access become one verb. Not in plan — grey text on the only cards where the student still had something to decide — becomes Get access; the card with no active product keeps an honest "not in your plan" with no CTA, because there is genuinely nothing to sell.

This one also shows item 7: the tag rows and the footers now sit on one line across each row.

4. my-learning — my_learning:default

6. study-plan — study_plan:default

Note this is the default variant — the one with goals. context.next_lessons was only ever rendered in the no-goals branch, so on the left the server sent it and the widget dropped it.

7. Card alignment — course_dashboard:default and gamification_profile:default

"Diseño de APIs REST" has no description; "Buena gente" has neither a description nor a tier badge. Their neighbours' tag rows, badges and footers no longer move to accommodate them.

---

The Spanish path

The thing the issue is actually about: the fixtures have always been Spanish, and the chrome around them was not. These are the same fixtures with lang=es.

Dates, numbers and currency follow the locale, not just the words — 4 ago 2026, dentro de 8 días, 1.043, 89,00 US$, and 54 % with the space Spanish typography wants. Course titles, lesson titles and tags are untouched: they are already in the school's language.

The drive-by

lms_demo_my_learning brand=forest. On master this renders the platform violet, because the demo tool computed the branding and never attached it. Same command on this branch. It is one line, but it is documented in WIDGET_DEMO_DATA.md and in #571 as a working feature, and it is the channel the lang argument above rides on.

What is not proven here

These are fixtures, so they prove rendering, not the database. The one change in this PR that fixtures cannot cover is the price join in lms_browse_catalog (product_courses → products). The RLS allows it and it fails soft, but a reviewer with a seeded tenant should confirm a real price shows up on a real catalog. Called out in the PR body too.

[guillermoscript]

Merged into master as b1134e7.

All seven items from #570 shipped: widget-owned strings and every date/number now follow the host locale in en/es; the brand colour is out of the red→green status ramp (and the two drifted copies of that ramp are one shared helper); exam-readiness sorts weakest-first with a countdown; my-learning's next lesson is a real button; the catalog shows a price and an upgrade path on one vocabulary; study-plan renders context.next_lessons in the case you actually see; and the three card grids share a row grid so optional blocks collapse without dragging their neighbours out of line.

Two things that were not in the issue and are worth remembering:

• The at-risk KPI caption was the hardcoded string "active · 0 lessons done" — not computed from anything. It now states the rule the number really comes from. The number still counts enrollment pairs while the tile is labelled "students"; that is left for widgets: missing data rendered as real data (raw user ids, ungraded exams as "—", filter-blaming empty state) #568.
• The demo tools' brand=ocean|sunset|forest argument had never worked — the branding was computed and then dropped instead of being attached to _meta. Fixed, because the same sideband now carries the lang= argument the offline harness needs to render the Spanish path at all.

Still unproven by this PR, and stated in the body too: the price join in lms_browse_catalog was verified against fixtures, not a seeded tenant. It fails soft (a query error leaves cards priceless rather than breaking the catalog), but the first person with real products rows should confirm a price actually appears.