masi/design-playbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: handoff annotation, enterprise flow and AI-assisted feature rules

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-10-24 01:55:11 -03:00
parent 2e97c3b931
commit 96ed2cffeb
9 changed files with 252 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
View File
@@ -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 |
llms.txt
+5 -2
View File
@@ -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
playbook_test.go
+1 -1
View File
@@ -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
principles/07-design-systems-tokens.md
+19
View File
@@ -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).
principles/11-handoff-annotations.md
+60
View File
@@ -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).
principles/12-enterprise-flows.md
+92
View File
@@ -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).
principles/13-ai-assisted-features.md
+50
View File
@@ -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).
sources/SOURCES.md
+9
View File
@@ -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 |
|---|---|---|---|
sources/UNVERIFIED.md
+15
View File
@@ -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.