From 96ed2cffeb9a808d5a1260b4f3e4802b36d82e7e Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 24 Oct 2026 01:55:11 -0300 Subject: [PATCH] feat: handoff annotation, enterprise flow and AI-assisted feature rules ANN-01..10, ENT-01..15, AIX-01..08 and SYS-13..15, with sources S35-S37, F01-F02. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- llms.txt | 7 +- playbook_test.go | 2 +- principles/07-design-systems-tokens.md | 19 ++++++ principles/11-handoff-annotations.md | 60 +++++++++++++++++ principles/12-enterprise-flows.md | 92 ++++++++++++++++++++++++++ principles/13-ai-assisted-features.md | 50 ++++++++++++++ sources/SOURCES.md | 9 +++ sources/UNVERIFIED.md | 15 +++++ 9 files changed, 252 insertions(+), 4 deletions(-) create mode 100644 principles/11-handoff-annotations.md create mode 100644 principles/12-enterprise-flows.md create mode 100644 principles/13-ai-assisted-features.md diff --git a/README.md b/README.md index cf831b6..a019862 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ improving a UI library, on the web (HTML, CSS, React) or native (Rust, egui). | Path | Contents | |---|---| -| `principles/` | 10 documents, about 150 rules with stable ids: interaction intent (INT), perception (PSY), visual (VIS), motion (MOT), accessibility (A11Y), feedback and forms (FBK), design systems and tokens (SYS), anti-patterns (BAD), CSS craft (CSS), component patterns (PAT) | +| `principles/` | 13 documents, about 185 rules with stable ids: interaction intent (INT), perception (PSY), visual (VIS), motion (MOT), accessibility (A11Y), feedback and forms (FBK), design systems and tokens (SYS), anti-patterns (BAD), CSS craft (CSS), component patterns (PAT), handoff annotations (ANN), enterprise flows (ENT), AI-assisted features (AIX) | | `platforms/` | How the rules map to web and to native egui | | `checklists/` | Design review, WCAG 2.2 AA audit, pre-ship gate | | `templates/` | Screen brief, component spec, DTCG-shaped token files (light, dark, base) with enforced contrast pairs | diff --git a/llms.txt b/llms.txt index f91fb99..07b2b84 100644 --- a/llms.txt +++ b/llms.txt @@ -1,8 +1,8 @@ # design-playbook -> Design reference for building accessible, non-generic user interfaces. About 150 rules with stable ids (INT, PSY, VIS, MOT, A11Y, FBK, SYS, BAD), each traced to a source; WCAG 2.2 AA oriented. Web and native egui. Search with the `playbook` CLI (`playbook search QUERY`) or follow the links below. Rules without a cited source are general knowledge defaults. +> Design reference for building accessible, non-generic user interfaces. About 185 rules with stable ids (INT, PSY, VIS, MOT, A11Y, FBK, SYS, BAD), each traced to a source; WCAG 2.2 AA oriented. Web and native egui. Search with the `playbook` CLI (`playbook search QUERY`) or follow the links below. Rules without a cited source are general knowledge defaults. -Rule id prefixes: INT interaction intent, PSY perception and timing, VIS visual design, MOT motion, A11Y accessibility, FBK feedback states forms, SYS design systems tokens, BAD anti-patterns, CSS CSS craft, PAT component patterns. +Rule id prefixes: INT interaction intent, PSY perception and timing, VIS visual design, MOT motion, A11Y accessibility, FBK feedback states forms, SYS design systems tokens, BAD anti-patterns, CSS CSS craft, PAT component patterns, ANN handoff annotations, ENT enterprise flows, AIX AI-assisted features. ## Principles - [Interaction and intent](principles/01-interaction-intent.md): wait, infer, act-and-undo, ask; undo over confirm; release-to-commit; menu aim @@ -15,6 +15,9 @@ Rule id prefixes: INT interaction intent, PSY perception and timing, VIS visual - [Anti-patterns](principles/08-anti-patterns.md): hard failures, soft failures, generic AI design tells - [CSS craft](principles/09-css-craft.md): layered shadows, transitions, CSS vs JS animation, springs, reset, defensive CSS, anchor positioning - [Component patterns](principles/10-component-patterns.md): tooltips, toggletips, notifications, toggle buttons, optimistic UI numbers, touch target sizes +- [Handoff annotations](principles/11-handoff-annotations.md): label, body, placement, spacing, overview zoom, unknowns as questions +- [Enterprise flows](principles/12-enterprise-flows.md): SSO sign-in and failure states, waiting and approval, timed assessments +- [AI-assisted features](principles/13-ai-assisted-features.md): human in the loop, confidence, accept/edit/dismiss, disclosure, data settings ## Platforms - [Web](platforms/web.md): baseline CSS, native elements, dialog and focus, forms, motion recipes diff --git a/playbook_test.go b/playbook_test.go index c410a24..3065315 100644 --- a/playbook_test.go +++ b/playbook_test.go @@ -27,7 +27,7 @@ func TestCrossReferencesResolve(t *testing.T) { if len(known) < 80 { t.Fatalf("only %d rules found", len(known)) } - ref := regexp.MustCompile(`\b(INT|PSY|VIS|MOT|A11Y|FBK|SYS|BAD|CSS|PAT)-(\d+)\b`) + ref := regexp.MustCompile(`\b(INT|PSY|VIS|MOT|A11Y|FBK|SYS|BAD|CSS|PAT|ANN|ENT|AIX)-(\d+)\b`) fs.WalkDir(Corpus, ".", func(p string, e fs.DirEntry, err error) error { if err != nil || e.IsDir() || !strings.HasSuffix(p, ".md") && !strings.HasSuffix(p, ".json") && !strings.HasSuffix(p, ".txt") { return nil diff --git a/principles/07-design-systems-tokens.md b/principles/07-design-systems-tokens.md index 896dffe..eceb43a 100644 --- a/principles/07-design-systems-tokens.md +++ b/principles/07-design-systems-tokens.md @@ -81,3 +81,22 @@ children. ### SYS-12 Platform parity without identical pixels Same tokens and behaviors across web and native (egui); idiomatic layout per platform. See platforms/web.md and platforms/native-egui.md. + +### SYS-13 Screens use instances of the library, never pasted copies +Every button, input, chip, row or sheet on a screen is an instance of a library +component (main on the design-system page; any page may instance it). A pasted +or hand-drawn look-alike drifts the moment the component changes. Lint for it +("not an instance"): a frame whose name, size and fill match a library component +but has no component link is a finding. If the component is missing, add it to +the library first, then instance it (F02). + +### SYS-14 Colour, spacing and type come from variables +On screens use variables and tokens, not literal hex or px that happen to equal +a token (SYS-01). Check by search: zero hard-coded colours in a finished page +(F02). + +### SYS-15 Swap and sync keep the instance's place in its parent +Swapping an instance to another variant or re-syncing it to a changed main must +keep what the parent decided: order, alignment, fill/hug/fixed sizing, margins +and overrides (text, icon). After any bulk swap, compare screenshots of three +screens before and after (F02, GK). diff --git a/principles/11-handoff-annotations.md b/principles/11-handoff-annotations.md new file mode 100644 index 0000000..9da0de9 --- /dev/null +++ b/principles/11-handoff-annotations.md @@ -0,0 +1,60 @@ +# Handoff annotations on design files + +Rules for notes that travel with a design to developers and reviewers. Source: +user feedback on annotated Interview flows, 2026-10-23 (F01), applied in +F02; items marked GK are defaults to test. Overview and placement numbers are +from F01 unless noted. + +### ANN-01 The label is the complete rule +Label is at most 60 characters and states the rule itself ("Submit locked until +every required field is valid"), not a topic ("Submit button"). A reader who +only sees labels must still get the rule. + +### ANN-02 Body is condition then outcome, values as "Field: value" +One line for "when X, then Y". Then concrete values, one per line, as +`Field: value` (`Debounce: 300 ms`, `Max length: 120`, `Retry: every 5 s`). +No prose paragraphs, no adjectives in place of numbers. + +### ANN-03 Few notes, high value; skip what the UI shows +Annotate what a developer cannot read off the screen: rules, behaviour, data +source, limits, roles, accessibility. Do not annotate colour, spacing, labels +or anything the component already states. About 3 to 6 notes per screen is a +healthy range (GK); more means the design is under-specified or the notes +are decoration. + +### ANN-04 Attach to the exact element, not the frame +Anchor each note to the node it describes (the button, the field, the timer), +so it follows the element when the layout moves and the leader line points at +the thing. A note on the screen frame is a note on nothing. + +### ANN-05 Unknowns are written as a question for the team +If the rule is not decided, write `? (team) Is there a grace period after +00:00?` and list it in the handoff. Never invent a number or behaviour to fill +the gap; an invented rule gets built (F01, F02). + +### ANN-06 Categories drive styling +Fixed set: rule, behaviour, content, data, a11y, dev, role. Each category has +one badge colour and icon, defined once as tokens (SYS-01); never colour alone +(A11Y-03). Pick the category by the reader: dev notes for engineers, role for +who can see or do it. + +### ANN-07 Placement: beside the target, on its own screen +Put the card on the nearest free side of its own screen, never over a +component, never over another note. Leader lines are short and orthogonal +(horizontal, vertical, at most one bend) and never cross another screen. + +### ANN-08 Overview zoom shows badges, not cards +Zoomed out (below 60%, the scale at which a card drawn at its minimum readable size outgrows the space kept for it; PaperCraft uses 60%) show numbered category badges only; cards +appear when zoomed in or when the badge is selected. Cards at overview size +are unreadable noise and hide the layout. + +### ANN-09 Leave room: gaps between screens fit the notes +Gap between neighbouring screens is about card width plus margins on both +sides: 640 px for 280 to 320 px cards (F01). Notes then sit beside their +screen without crossing the next one. Plan gaps before placing screens; +moving screens afterwards breaks leader lines. + +### ANN-10 Check placement by screenshot +Render the overlay and look: no card over a component, no crossing lines, no +card cut by the page edge. Unchecked placement is reported as unchecked (F02 +could not see the overlay in screenshots). diff --git a/principles/12-enterprise-flows.md b/principles/12-enterprise-flows.md new file mode 100644 index 0000000..9b7f9d2 --- /dev/null +++ b/principles/12-enterprise-flows.md @@ -0,0 +1,92 @@ +# Enterprise sign-in, waiting, and timed assessments + +Rules from the Interview redesign (F02, reports under papercraft +specs/interview-redesign) and SSO guidance (S37). Numbers marked GK are +defaults to test. Related: FBK-03, FBK-05, FBK-11, A11Y-16, INT-07. + +## Sign-in + +### ENT-01 Company SSO is the single primary action +Workforce tools show one primary button ("Continue with company SSO") above +the fold. Email and password, if allowed at all, sit behind a disclosure as a +fallback (PSY-04, S37). Do not bury SSO under password fields (S37). + +### ENT-02 No consumer social buttons in workforce tools +No Google, Microsoft, Apple or GitHub buttons: they offer accounts the +company does not control and split identity. Audit with a text search for the +provider names (F02). + +### ENT-03 Split external and internal users by entry path +Staff enter through SSO (email-domain lookup may route them, S37). External +users (candidates, vendors) enter through their own link or code, not through +the staff screen. Show the user type as a tag in every header once signed in +(F02). + +### ENT-04 After SSO, identity is read-only +Show name and email from the provider as plain text, not editable fields. +Offer "Use a different account" as the only change. Never ask again for what +the IdP already provided. + +### ENT-05 Five SSO failure states, each with a recovery action +| State | Say | Action | +|---|---|---| +| Redirecting | "Taking you to your company sign-in" | Cancel; link if stuck after 5 s (GK) | +| Cancelled | Sign-in was cancelled, nothing changed | Try again | +| Not allowed | This account has no access, name the admin to ask | Use a different account; Request access | +| Expired | Your session ended, work is saved | Sign in again, returns to the same page | +| IdP unavailable | The company sign-in is not responding, not your fault | Retry; fallback if enabled; contact admin | +Credential errors stay generic to avoid account enumeration (FBK-05, F02). + +## Waiting and approval + +### ENT-06 Honest status with expected time +A pending screen states what is happening, who acts next and the expected +time ("Usually within 1 working day"). If unknown, say so; never a placeholder +promise. Ask the team for the figure (ANN-05). + +### ENT-07 The waiting page updates itself +Poll or push, and update the status and page without reload (poll every 5 to +15 s, GK). Announce the change with `role="status"` (A11Y-27). Keep a manual +Refresh for failures and show "Last checked hh:mm". + +### ENT-08 Disabled action with an inline reason +A locked action stays visible with the reason next to it ("Available when the +session opens at 09:00"). No tooltip-only reasons (FBK-02, PAT-01). + +### ENT-09 Reversible admin actions act, then undo +Approve, reject, move, close: do it at once, show a toast with Undo for 8 to +10 s (GK), no "Are you sure". Irreversible ones (delete, end session for +everyone) get a confirm that names the effect and count (INT-06, INT-07, S09). + +## Timed assessments + +### ENT-10 Autosave status is always visible +In the header of every tab: Saving, Saved hh:mm, Offline (kept on device), Not +saved with Retry. Icon plus text (A11Y-03). Never swallow a failed save. + +### ENT-11 Timer visible, warning under 5 minutes +Timer in the persistent header. At 5 minutes left: colour change plus a +banner stating the consequence ("At 00:00 your work is submitted +automatically") and a Submit now action. No sound-only or colour-only +signal (A11Y-16, A11Y-03). + +### ENT-12 Auto-submit at 00:00, with offline retry +At zero: save the draft, submit, show a screen with the steps. Offline: keep +the draft locally, retry every 5 s, offer Copy my work, and say so. Define the +grace period as a team question until decided (ANN-05). + +### ENT-13 Confirm the final submit with a summary +Irreversible submit opens a summary: what is saved, last test result, optional +parts left, unanswered items by name, time left. Buttons repeat the verb +("Submit solution" and "Keep working"), safe action is the default +focus (INT-07, BAD-25). Validate on submit rather than disabling it (FBK-09). + +### ENT-14 Run is secondary, Submit is the only primary +Harmless repeatable actions (Run tests) are secondary and keep their label +while running; the final irreversible action is the single primary (VIS-07, +FBK-03). + +### ENT-15 Offline never drops input +Banner says edits are kept, which actions pause (Run, Submit) and that the +timer keeps running; a confirmation shows on reconnect with the number of +changes synced (FBK-11, INT-11). diff --git a/principles/13-ai-assisted-features.md b/principles/13-ai-assisted-features.md new file mode 100644 index 0000000..c5f2f08 --- /dev/null +++ b/principles/13-ai-assisted-features.md @@ -0,0 +1,50 @@ +# AI-assisted features (human in the loop) + +Sources: Microsoft HAX Guidelines for Human-AI Interaction (S36, G-numbers +below are its guideline numbers), Google PAIR People + AI Guidebook (S35, +read only through a search summary), plus project practice (F02). Apple HIG +Machine learning and NN/g AI articles could not be fetched (UNVERIFIED.md). + +### AIX-01 AI suggests, the human decides +Output is a proposal until a person accepts it. No AI result writes to shared +or user data, sends, deletes or pays without an explicit action. Scope +the service down when unsure rather than guessing (G10, G16). + +### AIX-02 Per-item accept, edit, dismiss +For lists of suggestions, each item has Accept, Edit and Dismiss, plus a bulk +"Accept all" only when every item is shown. Dismissal is one click, undoable +(G7, G8, G9, INT-06). Accepted items look like human-made items, plus a quiet +origin mark (AIX-05). + +### AIX-03 Show confidence and evidence +Show how sure the system is only where it changes the decision, as a plain +label (High, Medium, Low) rather than a false-precision percentage (S35: if, +when and how to show confidence is a design decision; G2). Link to the +evidence: source text, row, or the rule that fired (G11). If the reasoning +cannot be shown, say what the system looked at. + +### AIX-04 Calibrate trust, do not maximise it +Say what the feature can and cannot do on first use (G1, G2). Low-confidence +items sit lower or are marked, never styled like confirmed results. Do not +word output as fact ("Detected" over "Is") (S35). + +### AIX-05 Disclose AI use to affected people +Anyone whose data, score or outcome the AI touches is told that AI was used, +what for, and who reviews it, in the place they see the result (GK; +regulation may require it, check locally). Staff see an "AI" origin mark on +each suggestion. + +### AIX-06 Settings control what data is sent +Settings list what leaves the device or tenant, per feature, with an off +switch and the default off for sensitive content (G17, G18). Show a preview of the +payload before the first send. Notify users when the model or behaviour changes (G18). + +### AIX-07 Feedback and correction are cheap and granular +A thumbs or "Wrong because..." on each item, not only on the whole answer +(G15). Corrections persist for the session at least, and the system says +whether it will learn from them (G12 to G14). + +### AIX-08 Failure is a state, not a dead end +Define loading (state what it is doing, PSY-02), no result, low confidence, +error, and "AI off" states. The manual path always works without AI (FBK-02, +FBK-05). diff --git a/sources/SOURCES.md b/sources/SOURCES.md index 0b4bf40..0e35ff8 100644 --- a/sources/SOURCES.md +++ b/sources/SOURCES.md @@ -61,6 +61,15 @@ this list as a verbatim citation. See `reading-list.md` for the wider map of blogs, magazines and design-system sites, with read status. +## Added 2026-10-23 (annotations, enterprise flows, AI features) +| id | Source | Level | Read | +|---|---|---|---| +| S35 | Google PAIR, People + AI Guidebook, Explainability + Trust https://pair.withgoogle.com/chapter/People%20+%20AI%20Guidebook%20-%20Explainability%20+%20Trust.pdf | P | search summary only; the PDF text could not be extracted | +| S36 | Microsoft, Guidelines for Human-AI Interaction (18 guidelines, G1 to G18) https://www.microsoft.com/en-us/research/articles/guidelines-for-human-ai-interaction-eighteen-best-practices-for-human-centered-ai-design/ | P | full list of guideline titles; no examples | +| S37 | WorkOS, SSO sign-in UX https://workos.com/docs/sso/ux/sign-in (plus search results for WorkOS and Scalekit SSO guides) | E | sign-in page full; error handling not covered by it | +| F01 | User feedback on annotated designs, 2026-10-23 (project owner, first-party) | E | stated by the owner, not a published source | +| F02 | PaperCraft Interview redesign reports, `specs/interview-redesign/*-report.md` (project practice, 2026-10-23) | E | read in full; design decisions, not tested with users | + ## Videos (see videos.md for notes per video) | id | Video | Level | Read | |---|---|---|---| diff --git a/sources/UNVERIFIED.md b/sources/UNVERIFIED.md index 6dee7d1..748ac25 100644 --- a/sources/UNVERIFIED.md +++ b/sources/UNVERIFIED.md @@ -44,3 +44,18 @@ Do not harden these into rules; check them and move them out. - web.dev Learn Accessibility: only the module index was read. - Smashing optimistic-UI article (2016): the 1 to 3% failure rate and 2 s window are the author's estimates. + +## Added 2026-10-23 +- Apple HIG Machine learning page returned no body text; NN/g AI UX article URL + returned 404 and a search found no NN/g article on accept/edit/dismiss. The + AIX rules do not cite either. +- PAIR Explainability + Trust (S35) was read through a search summary, not the + chapter text. Check wording before quoting. +- Numbers in ANN and ENT marked GK (3 to 6 notes per screen, 50% badge zoom, + 5 to 15 s polling, 8 to 10 s undo toast, 5 s stuck-redirect link) are + defaults to test, not sourced. 640 px gap is the owner's value for 280 to + 320 px cards (F01). +- WorkOS error-state guidance was not on the page fetched; the five SSO + failure states (ENT-05) come from the Interview redesign (F02), not WorkOS. +- AIX-05 (disclose AI use) is general knowledge; legal disclosure duties vary + by jurisdiction and were not researched.