Button: Revise documentation #66617
Draft
Button: Revise documentation #66617
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mirka
added
[Type] Developer Documentation
|
Size Change: 0 B Total Size: 1.82 MB ℹ️ View Unchanged
|
|
Flaky tests detected in ec69ef6. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/11839917233
|
mirka
commented
Oct 31, 2024
There was a problem hiding this comment.
How about we write the supplementary docs in a file like this? I'm having second thoughts about putting all the documentation into the main Docs page, because it can already be quite long with the props table and the stories.
mirka
commented
Oct 31, 2024
There was a problem hiding this comment.
This is now auto-generated using the npm run docs:components command.
mirka
commented
Oct 31, 2024
Comment on lines
+117
to
+120
| * 1. `'primary'` (the primary button styles) | ||
| * 2. `'secondary'` (the default button styles) | ||
| * 3. `'tertiary'` (the text-based button styles) | ||
| * 4. `'link'` (the link button styles) |
There was a problem hiding this comment.
These descriptions need to be improved (see size prop description for example). It also fails to capture that there is a default (variant={ undefined }) variant.
5 tasks
- added content - added embeds
Removed sample Figma embed link
- Fixed Figma links
mirka
commented
Nov 15, 2024
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-1069&node-type=frame&t=HfUDxJShbqa3dM4N-11" title="destructive" height="400" /> | ||
|
|
||
| ### Sizes | ||
| The default size is 40px. Use smaller sizes for compact views or when placing buttons in small components, such as dropdowns or dialogs. |
There was a problem hiding this comment.
This seems vague, compared to the more specific guidelines already given in the props docs for size. I think people will need the more specific guidance to design consistently.
There was a problem hiding this comment.
I'll let @jameskoster chime in here. My interpretation was that these size assignments were for the older version of this component, but I could be totally wrong.
There was a problem hiding this comment.
Agree it's vague, but I'm not sure we can do much better until there are designs for more admin pages/patterns. At the moment smaller button sizes really are just for use in UIs that require greater density. I suppose we could add a note saying that if you're unsure then use the default size, but I don't know if it's worth it?
There was a problem hiding this comment.
I'm just suggesting that the guideline specificity be consistent between this doc and the prop description:
- `'default'`: For normal text-label buttons, unless it is a toggle button.
- `'compact'`: For toggle buttons, icon buttons, and buttons when used in context of either.
- `'small'`: For icon buttons associated with more advanced or auxiliary features.For example, I could just duplicate this ☝️ to the Sizes section of the doc. I'd think this is very relevant because it includes some crucial information like how the default size is not for icon buttons.
Comment on lines
29
to
35
| ### Tertiary | ||
| Tertiary buttons have minimal emphasis. Use them sparingly to subtly highlight an action. | ||
|
|
||
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-874&node-type=frame&t=HfUDxJShbqa3dM4N-11" title="tertiary" height="400" /> | ||
|
|
||
| ### Default | ||
| Use default buttons for actions of equal priority. |
There was a problem hiding this comment.
I still do not understand when we should use tertiary vs. default 😅 @WordPress/gutenberg-design Is there any more specific guidance we can give, or maybe an example of when they should be used?
There was a problem hiding this comment.
I don't understand this either. My take is we address this when we take a look at button philosophy. (Unless someone knows a fundamental difference between the two) 😅
There was a problem hiding this comment.
Wonderful discussion. For me it's about the names themselves, primary, secondary, tertiary suggest a hierarchy where none exists. There isn't a specific rule of "Tertiary buttons must be next to secondary buttons", etc. I'd much more have appreciated simple button names: solid, outline, text, for which we could then provide very simple instructions for each:
- Use a solid button when you want to convey prominence of an action, that the action is important or primary for the context.
- Use an outline button for lower prominence, or when the context benefits from the outline aligning with other bordered elements.
- Use a text button for lowest prominence: these are for less important actions.
There was a problem hiding this comment.
Is there an existing issue for button design system work where we can add these thoughts as feedback? cc @jasmussen @jameskoster
There was a problem hiding this comment.
There's #63856 which is probably the main one.
| # Button | ||
| Buttons allow users to take actions and make selections with a single click or tap. | ||
|
|
||
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-280&node-type=frame&t=JLKM1grrtWleRkFR-11" title="kitchen-sink-button" height="400" /> |
There was a problem hiding this comment.
@auareyou I'm wondering if we can set up a better frame size for the Figma embeds, so the content isn't needlessly scaled down when rendered in the iframe. The max content width for the Storybook doc page is 1000px, while the Figma frames (for example this) are 1280px wide. Does the initial zoom factor become closer to 100% when the Figma frame widths are reduced? (I would love to just set a fixed 100% zoom factor from the code side, but I don't think there's a way to do that.)
There was a problem hiding this comment.
Yes, @mirka, we can definitely change the height. Are you suggesting changing the width to 1000px in the images and then whatever height is proportional?
There was a problem hiding this comment.
Are you suggesting changing the width to 1000px in the images and then whatever height is proportional?
Right. But I don't know whether the height proportionality affects the initial zoom factor, and I don't have edit access for Figma, so could you experiment a bit to see if there is a better size setup? It's ok if nothing works, but just wanted to check if there's an easy way to make it closer to 100%.
There was a problem hiding this comment.
I've resized them to 1000px by 300px. Let me know if it doesn't work.
There was a problem hiding this comment.
Did you experiment with a couple values? It's a lot closer to 100%, but still slightly off (the buttons are 36px high instead of 40px), no? Seems like something we can get right once, and reuse those metrics for everything.
auareyou
approved these changes
Nov 21, 2024
| # Button | ||
| Buttons allow users to take actions and make selections with a single click or tap. | ||
|
|
||
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-280&node-type=frame&t=JLKM1grrtWleRkFR-11" title="kitchen-sink-button" height="400" /> |
There was a problem hiding this comment.
I've resized them to 1000px by 300px. Let me know if it doesn't work.
Comment on lines
29
to
35
| ### Tertiary | ||
| Tertiary buttons have minimal emphasis. Use them sparingly to subtly highlight an action. | ||
|
|
||
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-874&node-type=frame&t=HfUDxJShbqa3dM4N-11" title="tertiary" height="400" /> | ||
|
|
||
| ### Default | ||
| Use default buttons for actions of equal priority. |
There was a problem hiding this comment.
Is there an existing issue for button design system work where we can add these thoughts as feedback? cc @jasmussen @jameskoster
mirka
commented
Nov 21, 2024
| # Button | ||
| Buttons allow users to take actions and make selections with a single click or tap. | ||
|
|
||
| <FigmaEmbed url="https://www.figma.com/design/V7NfxdP0ybEMXf01WyWGKB/Storybook-documentation-Figma-assets?node-id=5-280&node-type=frame&t=JLKM1grrtWleRkFR-11" title="Overview of button variants" height="400" /> |
There was a problem hiding this comment.
@auareyou I went in and fixed them all in this one, but FYI the title attribute is an accessible name, not an id. So it needs to be meaningful text.
Comment on lines
+68
to
+72
| /** | ||
| * Primary buttons stand out with bold color fills, making them distinct | ||
| * from the background. Since they naturally draw attention, each layout should contain | ||
| * only one primary button to guide users toward the most important action. | ||
| */ |
There was a problem hiding this comment.
I am reevaluating this PR from a user perspective, and I realized that we're probably not adding much value by showing a separate page with variants, including a full specimen of hover/active/disabled states. Also, some of the states are already wrong (i.e. not the same as in shipping code). For example, look at all the Link variants — they're all wrong. @auareyou Can you troubleshoot this? Are we using the Figma library components incorrectly in some way?
What I see in the Figma embed
Actual Link variant (default)
We already show an interactive list of all the variants in the normal story docs, so I suggest we just move the copy there. That's where all this kind of basic, important information should live. What do you think?
The Best Practices page is probably a good home for more supplementary information, like patterns/examples that don't quite fit in the normal story docs.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
Moves the supplementary Button docs to the Storybook, and expands on the content.
Why?
As we evolve the design system, we need better documentation.
How?
best-practices— not sure this is the best name, could be better.)FigmaEmbedcomponent for easy embedding of Figma links.Testing Instructions
Run
npm run storybook:dev. You should see a new Best Practices page under the folder for Button. Review the content.Screenshots or screencast