[Docs] Update Switch writing guidelines#5558
[Docs] Update Switch writing guidelines#5558florent-leborgne wants to merge 9 commits intoelastic:mainfrom
Conversation
|
Preview documentation changes for this PR: https://eui.elastic.co/pr_5558/ |
|
Preview documentation changes for this PR: https://eui.elastic.co/pr_5558/ |
There was a problem hiding this comment.
Thanks, @florent-leborgne for opening this PR.
One of the things we considered in our slack conversation was to break down the checkbox/radio/switch components to its own page. So I pushed some changes (8bd0d90) to included a new section called "Selection controls".
I found it having the GuideRules on the examples page a little bit confusing and it was introducing a new pattern in our docs. Normally the GuideRules only live on guidelines tabs.
We could have these writing guidelines without the GuideRules component. Maybe just pure text. So this wouldn't introduce a new pattern.
But I decided to create a new tab "Guidelines" and move the GuideRules there.
We talked in slack that it would be weird to have an entire page dedicated to just switch guidelines but I changed my opinion:
- I think our users already know where to find specific component guidelines.
- It will be weird to only see guidelines for one component. But I see this as a first step. And we should soon, include more guidelines for the rest of "Selection controls".
- We could think of a new pattern like a flyout... But it will take time to think about the best design and routing. So for now, I think this is the best compromise.
@florent-leborgne and @gchaps what do you think of these changes?
| <EuiLink href="https://github.com/elastic/eui/pull/5119#discussion_r699717319"> | ||
| table header | ||
| </EuiLink> |
There was a problem hiding this comment.
This link doesn't seem correct.
|
Preview documentation changes for this PR: https://eui.elastic.co/pr_5558/ |
|
@miukimiu Thanks a lot for the suggestion. I really like having a tab that is dedicated to guidelines. And yes with time we will find more guidelines for more components. I would still like to make it more visible from the example section that guidelines exist for a specific component. In this case, once you've scrolled down to the "Switch" section, it's easy to miss that there are guidelines for it. Do you think a link can do the trick (until we think of a new pattern as you mentioned)? |
|
@florent-leborgne yes, I think for now a link can do the trick. Here are a few examples where we're linking to a guideline page (for inspiration):
|
|
Thanks for your input @miukimiu. |
|
Preview documentation changes for this PR: https://eui.elastic.co/pr_5558/ |
|
Thanks, @florent-leborgne! I cherry-picked your commits to #5607. I decided to have better docs and examples for all the selection controls. So I'm closing this PR in favor of #5607. If you don't mind, I'll then add you as a reviewer in #5607. 🙂 I'll make sure to keep your contributions intact! 🎉 |
|
@miukimiu Thanks that makes sense! FYI the UX writing group also intends to add guidelines for more components soon. For example, I'm working with @gchaps on checkboxes this week. Do you want us to wait until you're done with your new PR, or add things on top of it? |
|
To not overcomplicate, I think is better if we wait until #5607 is merged. 😄 |
|
Sure thing 😁 |
Summary
This PR updates docs only. As discussed in Slack, the UX writing group suggests some updates to writing guidelines and examples about the EuiSwitch component.
With the hope of making these guidelines easier to find and use, I moved them directly in the component section.
Please let me know if there are any additional steps I should take to complete this PR, or advise a different approach.
If this approach is fine, this is something we could repeat in the future for other components.
Before:
After:
Checklist
- [ ] Check against all themes for compatibility in both light and dark modes- [ ] Checked in mobile- [ ] Checked in Chrome, Safari, Edge, and Firefox- [ ] Props have proper autodocs and playground toggles- [ ] Added documentation- [ ] Checked Code Sandbox works for any docs examples- [ ] Added or updated jest and cypress tests- [ ] Checked for breaking changes and labeled appropriately- [ ] Checked for accessibility including keyboard-only and screenreader modes- [ ] A changelog entry exists and is marked appropriately