Skip to content

Commit 7ef50a4

Browse files
docs(qa): add cross-cutting UX convention items to the platform checklist (#22140)
## Summary On the maintainer's instruction — 「写进测试清单:把这些原则加到 docs/qa/platform-checklist/,例如"每个写操作都有反馈""每个禁用控件都说明原因""不对用户显示机器名"。这样以后每轮测试都会检查。」 — this adds one area, `docs/qa/platform-checklist/areas/ux-conventions.json`, with three items so every checklist run samples these conventions across the console and Studio: - `ux-conventions.write-feedback` — every user-initiated write answers visibly: success names what changed, a refusal says why, a no-op claims nothing, and Undo restores where a surface offers it. - `ux-conventions.disabled-control-reason` — every disabled control shows its reason on hover and on keyboard focus, and exposes it as an accessible description. - `ux-conventions.labels-over-machine-names` — where a label exists users see it; machine names, raw ids and spec paths appear only as secondary text. Each item lists the rows known to fail on stock in `knownGaps`, citing the objectui cards filed from the 2026-10-07 browser QA pass, so a run scores them fail and cites the card instead of re-filing. `FOLLOW-UPS.md` section 11 registers those rows (F1–F8) and three open decisions for the maintainer: P1 vs P0 (whether these join every release sweep), which writes should offer Undo, and whether direct manipulation needs a toast. `scripts/checklist-symbol-anchor-baseline.json` gains a floor for the new area file at the count `--anchor-census` measured (8) — a new floor, no floor lowered. Scope: a scoped authoring by one reader, grounded in a source reading on `main` and the browser pass — not a five-angle sweep, so it makes no claim about what else is missing. ## Verification - `pnpm check:platform-checklist` — exit 0: selector self-test 31 cases, validator self-test 221 assertions, ledger OK (16 areas, 279 items, 18 file floors held). - `node scripts/checklist-select.mjs area:ux-conventions` — resolves the three items as runnable. - `node scripts/check-doc-authoring.mjs` — exit 0 (this required gate reads `docs/qa/`). ## Changeset A QA ledger and its anchor baseline only — nothing publishes from a released package, so this PR carries `skip-changeset`. --- _Generated by [Claude Code](https://claude.ai/code/session_01D76mrPJrSSdaKRxR2rvrMG)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 8f2e808 commit 7ef50a4

3 files changed

Lines changed: 339 additions & 1 deletion

File tree

‎docs/qa/platform-checklist/FOLLOW-UPS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -659,3 +659,53 @@ is the first FOLLOW-UPS section to carry symbol anchors, so
659659
`scripts/checklist-symbol-anchor-baseline.json` gains a `FOLLOW-UPS.md` floor at the
660660
count `--anchor-census` measured. Adding a floor for a newly-anchored file is not
661661
lowering one — that stays maintainer-only.)
662+
663+
## 11. Scoped authoring 2026-10-08 — cross-cutting UX conventions (maintainer-directed)
664+
665+
**Not a sweep.** The maintainer directed three conventions onto the ledger so that every
666+
run checks them, verbatim: 「写进测试清单:把这些原则加到 docs/qa/platform-checklist/,例如"每个写操作都有反馈""每个禁用控件都说明原因""不对用户显示机器名"。这样以后每轮测试都会检查。」
667+
They live in one new area, `areas/ux-conventions.json`:
668+
669+
- `ux-conventions.write-feedback` — every user-initiated write answers visibly; success
670+
names what changed, a refusal says why, a no-op claims nothing; Undo restores where offered.
671+
- `ux-conventions.disabled-control-reason` — every disabled control shows its reason on
672+
hover and on keyboard focus, and exposes it as an accessible description.
673+
- `ux-conventions.labels-over-machine-names` — where a label exists users see it; machine
674+
names, raw ids and spec paths appear only as secondary text.
675+
676+
Ledger **276 → 279 items**; `coverage.json` untouched (a convention belongs to no
677+
metadata kind). ⚠️ **Executed by one reader, sequentially**, grounded in a source reading
678+
on `main` and the 2026-10-07 browser QA pass on the showcase boot (objectstack
679+
`879bd38c`, objectui `179f6fe9`). No hunter angle was run, so this section supports
680+
**no** claim about what else is missing.
681+
682+
### 11a. Expected-fail rows on stock — already carded: score FAIL, cite the card, never re-file
683+
684+
| # | item · variant | observed 2026-10-07 | card |
685+
|---|---|---|---|
686+
| F1 | write-feedback · Invite User | the action declares successMessage 'Invitation sent'; nothing was shown while the sys_invitation and sys_email rows were written | objectstack-ai/objectui#11817 |
687+
| F2 | write-feedback · Studio publish | no success confirmation; only the header flips to "No drafts pending publish" | objectstack-ai/objectui#11807 |
688+
| F3 | write-feedback · inline edit no-op | "1 row modified · Save All (1)" after a click with no value change | objectstack-ai/objectui#11816 |
689+
| F4 | disabled-control-reason · Archive | disabled in both placements with no title, tooltip or aria-describedby | objectstack-ai/objectui#11811 |
690+
| F5 | labels · Explain access, permission-set list, nav editor, Changes panel | raw user id as the principal; machine names where labels exist | objectstack-ai/objectui#11862 |
691+
| F6 | labels · Profile | the auth library's raw user.role ("user") for the platform admin | objectstack-ai/objectui#11866 |
692+
| F7 | labels · flow Node Type select | raw snake_case node types | objectstack-ai/objectui#11778 |
693+
| F8 | labels · banners | raw Zod paths, class names and tracker ids in author-facing refusals | objectstack-ai/objectui#11785 |
694+
695+
### 11b. Decisions for the maintainer
696+
697+
- **Priority.** The three items are authored **P1**. A release sweep selects
698+
`since == vN` ∪ every `P0` ∪ the items whose `source` cites a release PR ("How a release
699+
sweep works" in README.md), so a P1 item runs when a run selects `area:ux-conventions`
700+
or `priority:P1` — not automatically in every release sweep. Raising them to **P0**
701+
makes them release-gating smoke, which is the literal reading of 「以后每轮测试都会检查」;
702+
that is the maintainer's call, not an author's.
703+
- **Undo.** Scored only where a surface already offers it (record edit). Which other
704+
writes should offer Undo is a product decision with no card yet.
705+
- **Direct manipulation.** A kanban card landing in its new column is accepted as its own
706+
success feedback; no toast is required. Say so if a toast is wanted there too.
707+
708+
### 11c. Note on `since`
709+
710+
`since: "v17.7"` records the release in which the ledger began checking these
711+
conventions; the surfaces they sample predate it.

0 commit comments

Comments
 (0)