Skip to content

ui(console): group the console's cards so each page draws one surface set - #1201

Open
HugoXK wants to merge 3 commits into
mainfrom
dev3/659-card-ceilings
Open

HugoXK wants to merge 3 commits into
mainfrom
dev3/659-card-ceilings

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Author: Fledge Platform Dev-3
Commit identity: commit.author and commit.committer are both Fledge Platform Dev-3 <dev3@fledge.invalid>, read back from GET /repos/HugoXK/fledge/commits/7bf06478b596b1cc7ffdc96beeabcf87e5526d5b after the push.

Fixes #659

What a user sees differently

Before. /dashboard stacked one ruled section per area, so a reader with one pending decision met five cards before reaching the delivery numbers: setup, "Needs your decision", delivery, repositories and jobs. /settings drew four cards, and /admin drew nine — including a full-width card that held nothing but the page's own title.

After. The same routes, controls, data and copy in fewer surfaces. /dashboard draws four cards, and the pending-decision queue is a rule-separated band in the flow instead of a card of its own. /settings draws three, with the notification preferences as a sub-block of Account & access. /admin draws five: the console header is a header, pending approvals sit at the top of the user card, and release, backups and retention share one maintenance card — that card carries a new "Maintenance / 维护" chip in the section nav, and the existing release, backups and retention chips still jump inside it.

The counting rule and the measured numbers

A card is an occurrence of the exact attribute class="card" — not the class="card…" prefix and not a card class token. class="quota-card card", class="card notices" and class="card provider-card" are real, differently styled surfaces, so under either looser rule a fix could drop a class name and keep the box.

page fixture exact before exact after ceiling
/dashboard empty 4 4 control, exactly 4
/dashboard one notification + one pending action 5 4 ≤ 4
/settings empty 4 3 ≤ 3
/admin empty 9 5 ≤ 5

What the fifth card actually is. On the busy dashboard the exact count is five because four plain cards are joined by the pending-action queue; the notification banner renders class="card notices", a compound class the exact-attribute counter never matches. That is why the seat's three columns read 5 / 8 / 9 (exact / prefix / tokens) on that fixture: the banner moves only the two looser columns. The previous docs/ui.md sentence said the banner made the fifth card and this PR corrects that attribution in the doc.

Two assertions close the holes the count alone leaves open. First, the busy fixture must still contain id="actions-needed": if actions stopped being honoured the busy page would fall to four and both the ceiling and the control would pass on a false green. Second, reclassifying has to remove the chrome, not the name: plain .card is a transparent box with a 1px top rule, so the test now asserts that .band paints no background, no shadow and no border except its own border-left, and that .sub paints no background, no shadow and no border at all — the separator lives on .sub + .sub.

The control sentence also runs the other way round from the original card: a conditional-only fix does pass the ceiling, because the empty page stays at 4. What the empty page at exactly 4 pins is the four real surfaces (setup, delivery, repositories, jobs): removing one of those fails, while removing the conditional card does not.

Red first, at f1c48ed3

In a clean worktree at f1c48ed3513a8180b870fae19fb95d32222da44b — this branch's parent — with only the committed test/layout.test.ts copied in, npx tsx --test test/layout.test.ts gives 16 tests, 14 pass, 2 fail, and the two failures name the work:

card ceilings: dashboard 5/4, settings 4/3, admin 9/5
.band keeps only its own left rule
  actual: []
  expected: ['border-left']

The control assertion in the same file — the empty dashboard at exactly 4 — passes at the base by design, which is what makes it a control rather than a third red row. The copy that ran there is byte-identical to the committed file (test/layout.test.ts sha256 6c7111e694956ca19833e3cb03c71e7c1926789e04356b8f8c95b206146f846b), so nothing was edited after the red run.

At the tip 7bf06478b596b1cc7ffdc96beeabcf87e5526d5b that file is 16/16, and with test/sectionNav.test.ts together 27/27.

What changed

File Change
src/views/pages.ts Dashboard: #actions-needed is <section class="band"> instead of a card. Settings: the #notifications block moves inside #account-access as a <section class="sub">. Admin: the console header card becomes <header class="page-head">, #pending becomes a sub-block at the top of the #users card, and release/backups/retention become sub-blocks of one #maintenance card; its nav chip is added between Audit and Release.
public/app.css .page-head (no top rule, section gap only), .band (a 1px left rule instead of a section rule), .sub + .sub generalised from the settings shell so grouped panels separate the same way, and one scroll-margin rule so an anchor nested inside a card still clears the section nav.
test/layout.test.ts The new count test on the exact attribute, with the banner + pending-action fixture built from a real NotificationRow and ActionRow; the queue-presence assertion; the empty dashboard as the control; and the chrome assertion for .band and .sub.
test/sectionNav.test.ts Every card with an id still needs exactly one chip, in card order, and a chip that names no card and no sub-block still fails. The test comment now states why a sub-block chip is deliberately not held to document order: notifications is placed as a topic after Models although it sits inside the account card, and pending leads the admin page although it sits inside the users card.
docs/ui.md One paragraph under the token table records the three ceilings, attributes the busy fixture's fifth card to the queue rather than the banner, and states that a block leaves the card system by dropping the box chrome.
changelog.d/659.changed.md The user-visible entry.
mock/*.html, mock/assets/app.css Regenerated with npm run mock:snapshot; no hand edits.

Alternatives considered

  • Count the class="card…" prefix or the card token. Rejected: the compound classes (quota-card card, card notices, card provider-card) are differently styled surfaces, so a fix could pass the ceiling by renaming a card rather than removing one.
  • Set /dashboard to ≤ 3 on the empty fixture. Rejected: the seat's CHANGES at e893d038aaf3 asked for one of two things, and naming the fixture that renders the fifth card keeps the ceiling measured against the base it is compared to.
  • Give the grouped admin card no id. Rejected: a card the section nav cannot name is the defect feat: list and revoke a user's other sessions in settings (#356) #423 fixed; the group card carries #maintenance and a chip instead.
  • Merge the audit table into the jobs card. Rejected: it would group two unrelated tables to reach the number instead of grouping the maintenance surfaces that already belong together.
  • Order sub-block chips by document position. Rejected: they are topics, not page sections — notifications belongs after Models in a reader's order even though it renders inside the account card, and pending leads the admin page even though it renders inside the users card. The card chips are the ordered list; the test says so and the comment says why.

Uncertainty and residual risk

  • The design pass the card explicitly leaves to the owner — which surface leads and which single accent wins — is not in this slice; only the count and the grouping are.
  • The maintenance card's first visible heading is still "Release & deployment", while its nav chip reads "Maintenance". The three existing chips jump straight to the inner blocks, so nothing is unreachable, but the group heading is the nav chip rather than a new <h2>; adding one would have changed copy the card asked to keep.
  • The mock snapshot set covers /dashboard and /settings only; /admin's 9→5 is verified by the count test and the screenshots, not by a regenerated mock snapshot — its markup is asserted directly through adminPage.

Ran:

  • npx tsx --test test/layout.test.ts in a clean worktree at f1c48ed3 with only the committed test file copied in — 16 tests, 14 pass, 2 fail: card ceilings: dashboard 5/4, settings 4/3, admin 9/5 and .band keeps only its own left rule (actual [], expected ['border-left']); the control passes.
  • npx tsx --test test/layout.test.ts at the tip — 16/16; npx tsx --test test/layout.test.ts test/sectionNav.test.ts — 27/27.
  • npm run check at the tip — exit 0: lint 11 warning(s) in 8 entries match the baseline, tsc --noEmit clean, 3266 tests / 3266 pass / 0 fail, build clean.
  • npm run mock:check — mock-snapshot: ok (14 files).
  • node scripts/risk-gate.mjs --base f1c48ed3513a8180b870fae19fb95d32222da44b at the tip — output below.
  • Chromium, full page, signed in as the same seeded development user (one unread notification and one pending action on the dashboard), English and Chinese, 1280 and 360:
before  dashboard 5  settings 4  admin 9   overflow 0 at both widths
after   dashboard 4  settings 3  admin 5   overflow 0 at both widths

Not run:

  • No npm run visual:matrix from this box (its CI job runs it): the local browser cache here carries the headless shell only, and the matrix's own gate pass is the job's evidence, not a local one.
  • No Docker image build, no deployment, no screen-reader pass.
  • No docs/deploy.md change (a docs card is in flight) and nothing on #1016.
Fledge risk tier
base: f1c48ed3513a8180b870fae19fb95d32222da44b
head: HEAD
changed files: 17

T2: src/views/pages.ts
T1: public/app.css, test/layout.test.ts, test/sectionNav.test.ts
T0: changelog.d/659.changed.md, docs/architecture.md, docs/ui.md
limits: 20 files / 400 lines (advisory)

risk-tier: T2; basis: mock/add-repository.html

The basis is a regenerated mock snapshot, which the rule set places at T2 by default rather than by name; the page renderer itself (src/views/pages.ts) is listed T2 above. It needs a PASS at this tip.

Branch state

Three commits on dev3/659-card-ceilings, parent f1c48ed3513a8180b870fae19fb95d32222da44b (live main, the #1184 release fix). The first carries the grouping, its test, docs/ui.md, the changelog fragment and the regenerated mocks; the second and third are docs-only and correct docs/architecture.md — the nav paragraph, then the /settings paragraph, which still called #notifications a fourth card when it is a sub-block inside #account-access. The first commit was built on 25d0c459 and rebased onto f1c48ed3 before the branch was ever pushed, so there is no merge commit and nothing was force-pushed. #1184 touched docs/deploy.md, scripts/release-open.mjs and test/releaseOpen.test.ts; none of the three overlaps this diff, and git diff 25d0c459 f1c48ed3 -- src/views public mock is empty.

Risk and rollback

Rollback: revert this commit. Nothing is stored, migrated or routed differently; every page returns to its previous markup and the mock snapshots to their previous bytes. The only reader-visible loss is the grouping itself.

Docs and changelog

Docs updated: docs/ui.md records the three ceilings next to the spacing scale, and docs/architecture.md now describes the nav the grouped pages actually draw — card chips in card order plus topic-ordered chips for grouped sub-blocks, /admin opening with a header rather than a card, and /settings drawing three cards with #notifications as a sub-block inside #account-access. Changelog: changelog.d/659.changed.md.

Before / after frames

Chromium, full page, deviceScaleFactor: 1, light, the same seeded development user on both sides (dashboard: one unread notification and one pending action — the fixture the ceiling is measured on). Before is main 25d0c459d0b4a69a55e5884769cf0eb90f79f46d, the commit before #1184; the rendered inputs are byte-identical at f1c48ed3 (git diff empty for src/views, public and mock), so these frames are what the branch's own base renders. After is this tip 7bf06478b596b1cc7ffdc96beeabcf87e5526d5b. document.scrollWidth - innerWidth is 0 in every frame. Images live on the evidence/659 branch (images only, no PR, not for merge); the file names under that branch match the URLs below.

English:

page 1280 before 1280 after 360 before 360 after
/dashboard dashboard en 1280 before dashboard en 1280 after dashboard en 360 before dashboard en 360 after
/settings settings en 1280 before settings en 1280 after settings en 360 before settings en 360 after
/admin admin en 1280 before admin en 1280 after admin en 360 before admin en 360 after

Chinese:

page 1280 before 1280 after 360 before 360 after
/dashboard dashboard zh 1280 before dashboard zh 1280 after dashboard zh 360 before dashboard zh 360 after
/settings settings zh 1280 before settings zh 1280 after settings zh 360 before settings zh 360 after
/admin admin zh 1280 before admin zh 1280 after admin zh 360 before admin zh 360 after

… set

The dashboard's pending-decision queue is a rule-separated band instead of a
card, settings keeps three cards with the notification preferences inside
Account & access, and admin keeps five: the console header is a header, pending
approvals sit at the top of the user card, and release, backups and retention
share one maintenance card.

test/layout.test.ts counts the exact class="card" attribute and caps the three
pages at 4, 3 and 5, each strictly below the base it was measured on (5, 4, 9);
the empty dashboard at exactly 4 stays the control. docs/ui.md records the three
ceilings, and mock/ is regenerated with npm run mock:snapshot.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at 539c8a5

  • docs/architecture.md:177-180 still says /settings draws "four group cards … #notifications" and that its nav is "four links, one per .card[id] in draw order". At this tip /settings renders three exact class="card" surfaces (account-access, model-providers, feedback) with #notifications a .sub inside #account-access (src/views/pages.ts:2807), so the four chips are three card chips plus one sub-block chip. That contradicts the paragraph this commit fixes at docs/architecture.md:157-170 and docs/ui.md:86-88 ("/settings at 3 (base 4)").
  • Fix (docs only): say three group cards on :177, add #notifications to the #account-access sub-block list on :178, and on :179 describe the nav as card chips in draw order plus the grouped sub-block chips.
  • Non-blocking: docs/architecture.md:158-159 "a chip for each grouped sub-block that keeps an id" reads as every id-bearing sub-block, but #account, #sessions and #tokens keep ids and have no chip — "each former card now grouped into a sub-block" would be exact.
    Ran: npx tsx --test test/layout.test.ts test/sectionNav.test.ts (27/27 pass at this tree); tsx render probe: exact class="card" counts empty dashboard 4, busy dashboard 4, settings 3, admin 5, and id="actions-needed" still renders on the busy dashboard.
    Not run: full npm run check locally (CI ci-ok success 136724764120 at this tip); mock:check locally (CI mock-check success 136723986392); no pixel inspection of the 24 evidence/659 PNGs — all 24 URLs resolve but I read no images.
    Written-by: HugoXK-bot

Fledge Platform Dev-3 added 2 commits November 21, 2026 04:24
The grouped pages give admin a header instead of a card and add chips for
sub-blocks inside a card, so the paragraph that said one chip per card is no
longer true. Name the sub-block targets, the topic ordering, and the first chip.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ui: cut the console's card density and give it a deliberate visual hierarchy

2 participants