Skip to content

Commit 7092f58

Browse files
konardkonard
committed
docs(issue-25): add R-N1..R-N12 table, changeset, audit cross-refs
Adds an issue-25 R-N requirements section to docs/REQUIREMENTS.md (plus localized summaries in the .ru / .zh / .hi mirrors), a brief mobile-first overhaul section to UI-DESIGN-AUDIT.md and its locale mirrors, and the .changeset/issue-25-mobile-first-glass.md entry that cuts a minor release for the AppShell, Connections module, tutorial spotlight, and full-translation work landed in PR #26. Each R-N row in REQUIREMENTS.md cross-references the case study (docs/case-studies/issue-25/) and the code that closes the requirement, so the live ledger stays in sync with what shipped.
1 parent 26e49f4 commit 7092f58

9 files changed

Lines changed: 161 additions & 0 deletions

‎.changeset/issue-25-mobile-first-glass.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
'meta-sovereign': minor
3+
---
4+
5+
R-N1..R-N12: Mobile-first overhaul of the SPA shell, the connections
6+
flow, and the tutorial. The new `js/src/web/shell/` module exposes an
7+
`<AppShell>` that swaps between a compact bottom-nav (≤640 px), a
8+
navigation rail (641-1023 px), and a permanent drawer (≥1024 px), with
9+
44 × 44 px tap targets, `:focus-visible` rings, and
10+
`safe-area-inset-bottom` padding. `js/src/web/app.css` adds Apple
11+
Liquid Glass tokens (`--surface-glass`, `.glass`, `.glass-strong`) that
12+
use `backdrop-filter: blur(28px) saturate(180%)` with a solid fallback
13+
when `prefers-reduced-transparency: reduce` is set. A dedicated
14+
Connections page lives under `js/src/web/connections/`: the list
15+
renders one card per provider with translated name, description, and a
16+
`connected` / `not-connected` / `action-required` state badge, and
17+
tapping a "not connected" provider routes to a dedicated detail screen
18+
that walks the user through the provider's `setupSteps[]` (newly
19+
declared on every entry of `js/src/web/connection-guides.js`). The
20+
tutorial overlay (`js/src/web/tutorial.js`) gains an element-anchored
21+
`<TutorialSpotlight>` that dims everything outside a target rect using
22+
a `box-shadow: 0 0 0 9999px rgba(0,0,0,0.55)` outset; the default
23+
sequence opens with a "Connect a service" step pointing at the
24+
Connections nav entry, with translated copy in `en/ru/zh/hi`. All
25+
user-facing strings — including the connection guides — now route
26+
through `t()`, so the Russian build no longer leaks the English
27+
"Your unified inbox starts empty." literal. Tests:
28+
`js/tests/connections-screens.test.js`,
29+
`js/tests/tutorial-spotlight.test.js`, and the existing
30+
`js/tests/i18n.test.js` parity assertions guard the new surface area.
31+
Full atomic table and evidence: `docs/case-studies/issue-25/`.

‎docs/REQUIREMENTS.hi.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,20 @@ translation keys, dictionary parity tests, Markdown language switchers,
119119
translated docs siblings, docs-language automation, issue #18 case study
120120
और PR #19 single-PR delivery cover करते हैं। State: PR #19 in progress।
121121

122+
## U. Mobile-first UI overhaul (issue #25)
123+
124+
R-N1..R-N12 mobile-first AppShell (bottom-nav / side-rail / permanent
125+
drawer), Apple Liquid Glass tokens जिनके साथ
126+
`prefers-reduced-transparency` fallback है, पूरा translation coverage
127+
(non-EN build में कोई English literal नहीं), अलग Connections page
128+
(हर provider के लिए एक card और
129+
`connected/not-connected/action-required` state badge), dedicated setup
130+
detail screen, per-provider `setupSteps[]`, element-anchored tutorial
131+
spotlight, और "Connect a service" से शुरू होने वाला default tutorial
132+
sequence cover करते हैं। State: PR #26 branch `issue-25-dac43a780b5c`
133+
पर in progress। विस्तृत table के लिए
134+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U देखें।
135+
122136
## Traceability
123137

124138
Future PR या commit feature land करे तो changeset और PR description में

‎docs/REQUIREMENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -454,6 +454,33 @@ adapter.
454454

455455
---
456456

457+
## U. Mobile-first UI overhaul (issue #25)
458+
459+
The following requirements arose from
460+
[issue #25](https://github.com/link-foundation/meta-sovereign/issues/25) -
461+
"the UI now must be improved". The full atomic list, evidence,
462+
component survey, and traceability live in
463+
[`docs/case-studies/issue-25/`](./case-studies/issue-25/README.md). The
464+
issue reuses the `R-N*` prefix; rows are unique within the issue-25
465+
table and cross-reference the case study via stable IDs.
466+
467+
| ID | Requirement | State |
468+
| ----- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
469+
| R-N1 | The SPA must be mobile first - default rendering targets a phone-sized viewport. | Done: `js/src/web/shell/` exposes `<AppShell>` with a compact bottom-nav (≤640 px), a navigation rail (641-1023 px), and a permanent drawer (≥1024 px). Wired in `js/src/web/app.js`. |
470+
| R-N2 | UI/UX should be in the best possible way (Apple/Google/Microsoft guidance, accessible tap targets, focus rings). | Done: shell tap targets are 44 × 44 px or larger, `:focus-visible` rules cover every interactive control, and `safe-area-inset-bottom` is honoured. Audit cross-references live in `docs/UI-DESIGN-AUDIT.md`. |
471+
| R-N3 | All user-facing UI must be fully translated, not partially - no English literal can render when the active locale is non-English. | Done: `js/src/web/connection-guides.js` and provider labels route through `t()`; `js/tests/i18n.test.js` enforces parity across `en/ru/zh/hi`. The Russian-build "Your unified inbox starts empty." regression is fixed by `feat(i18n)` commit `98828fb`. |
472+
| R-N4 | Each connected service should have its own item in the connections list with name, description, and connection state. | Done: `js/src/web/connections/connections-list.js` renders one card per provider with translated name, description, and state badge. Test: `js/tests/connections-screens.test.js`. |
473+
| R-N5 | External-service connections should live on a separate page, like settings. | Done: a dedicated `connections` view exists in `js/src/web/nav-items.js` and `js/src/web/views.js`; Settings retains only app-level preferences. |
474+
| R-N6 | The design should clearly show whether a service is connected or not. | Done: each card declares one of `connected` / `not-connected` / `action-required` state with a translated label and a colour token (green / neutral / amber). Covered by `js/tests/connections-screens.test.js`. |
475+
| R-N7 | Tapping a "not connected" service routes the user to a separate setup screen. | Done: `<ConnectionsList>` calls an `onOpen(providerId)` handler that mounts `<ConnectionDetail>` in `js/src/web/views.js`; the list itself never inlines the credential form. |
476+
| R-N8 | Setup flows must explain exactly how to obtain the required data, so no separate instructions are needed. | Done: every provider in `js/src/web/connection-guides.js` declares `setupSteps[]` with translated `titleKey`/`bodyKey` (and optional `actionKey`/`href`). Test: `js/tests/connection-guides-templates.test.js`. |
477+
| R-N9 | The tutorial overlay must dim everything except the next click target. | Done: `js/src/web/tutorial.js` exports `<TutorialSpotlight>`; `app.css` uses a `box-shadow: 0 0 0 9999px rgba(0,0,0,0.55)` outset to dim outside the rect, with a `prefers-reduced-transparency` fallback. Tests: `js/tests/tutorial-spotlight.test.js`. |
478+
| R-N10 | The tutorial must guide the user first to service connections, then walk through the chosen provider's setup steps. | Done: `defaultSteps[0]` in `js/src/web/tutorial.js` is the `connect` step pointing at `nav:connections` with `tutorial.connect.{title,body}` keys translated for `en/ru/zh/hi`. Follow-up steps render `setupSteps[]` inside `<ConnectionDetail>`. |
479+
| R-N11 | The visual style should resemble Apple Liquid Glass (semi-transparent surfaces). | Done: `js/src/web/app.css` defines `--surface-glass` (backdrop-filter blur 28px, saturate 180%) and `.glass`/`.glass-strong` utilities; `@media (prefers-reduced-transparency: reduce)` substitutes a solid surface. Applied to top-bar, bottom-nav, drawer, modal cards, and the tutorial card. |
480+
| R-N12 | Use Apple/Google/Microsoft design guidelines and Chakra UI + React.js patterns. | Done as design _guidance_ rather than a runtime swap: the redesign adopts Chakra UI's responsive tokens, semantic spacing, and accessible primitives without taking a hard dependency. The trade-off is recorded in `docs/case-studies/issue-25/components.md`; bundle-size delta is captured in PR #26's description. |
481+
482+
---
483+
457484
## Traceability
458485

459486
When a future PR or commit lands a feature, reference the requirement

‎docs/REQUIREMENTS.ru.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,18 @@ authored UI strings, dictionary parity tests, Markdown language
118118
switchers, translated docs siblings, docs-language automation, issue #18
119119
case study и single-PR delivery in PR #19. State: PR #19 in progress.
120120

121+
## U. Mobile-first UI overhaul (issue #25)
122+
123+
R-N1..R-N12 покрывают mobile-first AppShell (bottom-nav / side-rail /
124+
permanent drawer), Apple-glass tokens с `prefers-reduced-transparency`
125+
fallback, full translation coverage (no English literal в non-EN
126+
builds), separate Connections page с одним card per provider и
127+
`connected/not-connected/action-required` state badge, dedicated detail
128+
screen и `setupSteps[]` per provider, element-anchored tutorial
129+
spotlight и "Connect a service" opening step. State: PR #26 in progress
130+
on branch `issue-25-dac43a780b5c`. Detailed table:
131+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U.
132+
121133
## Traceability
122134

123135
Когда future PR или commit добавляет feature, reference matching `R-*` ID

‎docs/REQUIREMENTS.zh.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,18 @@ translation keys、dictionary parity tests、Markdown language switchers、
112112
translated docs siblings、docs-language automation、issue #18 case study 和 PR
113113
#19 single-PR delivery。状态：PR #19 in progress。
114114

115+
## U. Mobile-first UI 改造 (issue #25)
116+
117+
R-N1..R-N12 覆盖 mobile-first AppShell（bottom-nav / side-rail /
118+
permanent drawer）、Apple Liquid Glass tokens 与
119+
`prefers-reduced-transparency` fallback、完整的 translation 覆盖（non-EN
120+
build 不会出现 English literal）、独立的 Connections 页面（每个 provider
121+
一张 card 并带 `connected/not-connected/action-required` state badge）、
122+
独立的 setup detail screen 与 per-provider `setupSteps[]`、anchored
123+
tutorial spotlight，以及以 "Connect a service" 起步的默认 tutorial 序列。
124+
状态：PR #26 in progress（分支 `issue-25-dac43a780b5c`）。详细表参见
125+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U。
126+
115127
## Traceability
116128

117129
后续 PR 或 commit 完成功能时，请在 changeset 和 PR 描述中引用对应 `R-*`

‎docs/UI-DESIGN-AUDIT.hi.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,19 @@ server discovery real e2e में covered हैं। `secret:*` links encryp
4949

5050
Current React SPA design behavior audit preserve करता है। R-G1 React
5151
shell, React view components और real-browser e2e से closed है।
52+
53+
## Mobile-first overhaul (issue #25)
54+
55+
Issue [#25](https://github.com/link-foundation/meta-sovereign/issues/25)
56+
global shell को phone-first दृष्टिकोण से दोबारा design करता है। नया
57+
`<AppShell>` (`js/src/web/shell/`) navigation को bottom-nav (≤640 px),
58+
side-rail (641-1023 px), और permanent drawer (≥1024 px) के बीच switch
59+
करता है; सभी controls 44 × 44 px tap target और `:focus-visible` ring
60+
रखते हैं। `app.css` `--surface-glass` (backdrop-filter blur 28px)
61+
define करता है, और `prefers-reduced-transparency` के तहत solid surface
62+
पर fall back होता है। अलग Connections page हर provider के लिए एक card
63+
और translated state badge render करता है; tutorial spotlight
64+
(`tutorial.js`) target rect को outline करता है और बाकी सब को dim कर
65+
देता है। पूरी R-N1..R-N12 list और evidence:
66+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U और
67+
[`docs/case-studies/issue-25/`](./case-studies/issue-25/README.md)।

‎docs/UI-DESIGN-AUDIT.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,22 @@ References:
8383
The design behavior audit is preserved by the current React SPA. R-G1 is
8484
closed by the React shell, React view components, and the browser bundle
8585
covered by the real-browser e2e.
86+
87+
## Mobile-first overhaul (issue #25)
88+
89+
Issue [#25](https://github.com/link-foundation/meta-sovereign/issues/25)
90+
revisits the global shell with a phone-first lens. The mapping below
91+
links each row in this audit's "Global Shell" table to the new
92+
mobile-first work tracked under `R-N1..R-N12` in
93+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U.
94+
95+
| Audit row | Issue #25 evidence |
96+
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97+
| Semantic landmarks for fast orientation. | `js/src/web/shell/app-shell.js` keeps `<header>` / `<nav>` / `<main>` while swapping the navigation between bottom-nav, side-rail, and drawer at ≤640 / 641-1023 / ≥1024 px. |
98+
| Visible focus for every control. | `js/src/web/app.css` carries `:focus-visible` rules onto every shell control, including the new bottom-nav buttons. |
99+
| Tap targets are accessible. | All shell controls are 44 × 44 px or larger; bottom-nav respects `safe-area-inset-bottom`. |
100+
| Glass surfaces with reduced-motion path. | `--surface-glass` (backdrop-filter blur 28px, saturate 180%) is applied to top-bar, bottom-nav, drawer, modal cards, and the tutorial card; falls back to a solid surface under `@media (prefers-reduced-transparency: reduce)`. |
101+
| Tutorial guidance is anchored to UI. | `js/src/web/tutorial.js` exports `<TutorialSpotlight>`; the default tutorial sequence starts by anchoring on the Connections nav entry (R-N9, R-N10). |
102+
103+
The full atomic table, component survey, and screenshots are in
104+
[`docs/case-studies/issue-25/`](./case-studies/issue-25/README.md).

‎docs/UI-DESIGN-AUDIT.ru.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,18 @@ sync.
4949

5050
Current React SPA preserves design behavior audit. R-G1 closed by React
5151
shell, React view components и real-browser e2e.
52+
53+
## Mobile-first overhaul (issue #25)
54+
55+
Issue [#25](https://github.com/link-foundation/meta-sovereign/issues/25)
56+
переводит global shell на phone-first design. Новый `<AppShell>` в
57+
`js/src/web/shell/` свопает navigation между bottom-nav (≤640 px),
58+
side-rail (641-1023 px) и permanent drawer (≥1024 px); все controls
59+
держат 44 × 44 px tap target и `:focus-visible` ring. `app.css`
60+
определяет `--surface-glass` (backdrop-filter blur 28px) с solid
61+
fallback под `prefers-reduced-transparency`. Dedicated Connections page
62+
показывает по одной card на provider с translated state badge,
63+
tutorial spotlight (`tutorial.js`) обводит target rect и dim-ит всё
64+
остальное. Полные R-N1..R-N12 строки и evidence:
65+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U и
66+
[`docs/case-studies/issue-25/`](./case-studies/issue-25/README.md).

‎docs/UI-DESIGN-AUDIT.zh.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,18 @@ peer sync 过滤。
4747

4848
当前 React SPA 保留了设计行为审计。R-G1 由 React shell、React view
4949
components 和真实浏览器 e2e 覆盖。
50+
51+
## Mobile-first 改造 (issue #25)
52+
53+
Issue [#25](https://github.com/link-foundation/meta-sovereign/issues/25)
54+
以 phone-first 为目标重做 global shell。新的 `<AppShell>`
55+
（`js/src/web/shell/`) 在 bottom-nav（≤640 px）、side-rail
56+
（641-1023 px）和 permanent drawer（≥1024 px）之间切换；所有控件保持
57+
44 × 44 px 的 tap target 和 `:focus-visible` ring。`app.css` 定义
58+
`--surface-glass`（backdrop-filter blur 28px），并在
59+
`prefers-reduced-transparency` 下退回到实色。独立的 Connections page
60+
为每个 provider 渲染一张 card 并附带 translated state badge；tutorial
61+
spotlight（`tutorial.js`）勾出目标 rect 并将其余部分变暗。完整的
62+
R-N1..R-N12 行与证据见
63+
[`docs/REQUIREMENTS.md`](./REQUIREMENTS.md) section U 和
64+
[`docs/case-studies/issue-25/`](./case-studies/issue-25/README.md)。

0 commit comments

Comments
 (0)