Docs: Say how long a notice can be, in the copy guide - #81195
Conversation
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
|
||
| A snackbar dismisses itself about six seconds after it appears, whether or not anyone has finished reading. That’s the budget for the whole message, and it doesn’t stretch to fit a longer one. | ||
|
|
||
| So keep a snackbar short enough to take in at a glance—one line is a good target. Counting characters isn’t much help here, because translations often run longer than the English original: a message that sits on one line for you can wrap to three somewhere else. |
There was a problem hiding this comment.
@annezazu does this cover what you were after?
|
Good idea expanding on this section, but I also really like @jasmussen's version of error message guidance in #81143, so I wonder if there's scope to use or integrate that version in this doc file? I see you commented similarly in #81143 (comment) 😄 |
|
I love it! Thanks for doing this. You both comment, here and on #81143, about whether there should be overlap between the skill and the Storybook doc. I think there should be, but I defer to you all on which parts should overlap and how we keep things from drifting: I love the idea of the skill, it certainly seems more portable than MCP which I think Storybook could/would/should have at some point, but I also don't keep up with the latest best practices in this field, so I'll simply defer to you. On that note, I'm a little under the weather today, so I won't be able to immediately respond to the feedback you shared in #81143, but simply note that I agree with all of this. I will hopefully be able to come back to this work tomorrow, but in the mean time if in your own work on combining or sharing details between these two PRs, you wish to commandeer 81143, make all your edits, deduplicate or combine, here's my blanket permission to do so 🙏 |
|
|
||
| #### FIVE: Remember that a message can disappear before it’s been read. | ||
|
|
||
| A snackbar dismisses itself about six seconds after it appears, whether or not anyone has finished reading. That’s the budget for the whole message, and it doesn’t stretch to fit a longer one. |
There was a problem hiding this comment.
Hmm, did we mean to qualify the auto dismissal as the default behavior? Snackbar stays open when explicitDismiss is set, and the skill itself recommends that option, so saying it always disappears, and is always the wrong place for something that must be read, may feel a little inconsistent.
|
Happy to go with either. If #81143 lands, we could probably just close this PR. The only question I'd ask is whether Storybook can act as the canonical documentation source for WordPress. One option is to split the error docs up into two bits:
with cross refs to each. Mainly so the same rules aren't in two places |
The Error Messaging section covers tone, cause and resolution, but not length, and a snackbar dismisses itself about six seconds after it appears whether or not the message has been read. Add a fifth tip: aim for one line, don't reach for a character count because translations run longer than the English, and move anything that has to be read and acted on out of a snackbar entirely. The defensive data design skill keeps the two API facts, the timeout and explicitDismiss, and defers the question of how long the text can be to here, so the guidance has a single home. Nothing is added about tone or humour. The guide already settles that in two places: Error Messaging rejects "Oopsie, we can't let you do that!" as too cute, and UI Descriptions asks for subtle personality rather than forced attempts at whimsy.
A snackbar can be told to stay until it is dismissed, and the defensive data design skill recommends exactly that for anything the reader has to finish. Saying it always clears itself, and is always the wrong home for a message that matters, contradicted that advice. Say "by default", and offer both ways out: keep the snackbar up, or use a notice that persists by design.
cac1837 to
8b4382d
Compare
4 participants
What
Follow-up to #81131 to update docs with the maxims from https://make.wordpress.org/core/2026/08/04/defensive-data-design/
This is stacked on
add/defensive-data-design-agents(#81131) because it edits the skill file that PR introduces.Adds a fifth tip to the copy guide's Error Messaging section, on how long a notice can be, and trims the equivalent guidance out of the defensive data design skill so it has one home.
I wanted to also add a note about "fun" from "Plain language, make it obvious, natural. (And also fun.)", but the guide already alludes to it and warns us against over doing it: