Capitalization Guidelines for Nimble in storybook - #3032
Conversation
| @@ -0,0 +1,97 @@ | |||
| import { Meta } from '@storybook/addon-docs/blocks'; | |||
There was a problem hiding this comment.
I added @mollykreis as a reviewer because she has a long history of helping keep SystemLink UI casing consistent and probably knows our current rules better than anyone.
| - Sentence case for all other UI text. | ||
|
|
||
| ## Element Cases | ||
|
|
There was a problem hiding this comment.
It would be good to add a section about control labels to this list. I think we currently use sentence case in SystemLink.
|
|
||
| ### Chip | ||
|
|
||
| Chips should use Title Case. |
There was a problem hiding this comment.
nit: consistency about "Title Case" vs "title case" across this document. Personally I'd vote to demonstrate what it looks like in the section at the top and then use normal sentence capitalization elsewhere, but I'm fine if you prefer to demonstrate what it looks like everywhere.
|
|
||
| <img src={tabsImage} alt="Tabs capitalization example" /> | ||
|
|
||
| ### Tile |
There was a problem hiding this comment.
Nimble doesn't have tiles right now. Is this the same as a Card? Or is it a concept that hasn't made it to code yet?
|
|
||
| ### Tree View | ||
|
|
||
| Tree view should use sentence case for all elements and sub elements. |
There was a problem hiding this comment.
I generally agree with sentence case for trees, though in SystemLink the main navigation tree uses Title Case. I guess you could argue that app titles are proper nouns so that overrides the sentence case guidance?
Kinda related, I'm fine with Title Case for chips but often in SystemLink they are names of resources that have their own capitalization rules or are provided by users. That would override this guidance too.
Your call whether these cases are worth clarifying.
|
|
||
| ### Tabs | ||
|
|
||
| Tabs in applications should be title case. Tabs in dialogs and drawers should |
There was a problem hiding this comment.
Why the distinction between app level and dialog/drawer level?
| In general, use the following capitalization conventions to ensure consistency | ||
| across the interface: | ||
|
|
||
| - ALL CAPS for table headers. |
There was a problem hiding this comment.
The table column content section currently says "Titles should use "Headline Casing" and Nimble will automatically capitalize them for display in the header." That approach is necessary so that the content isn't all caps when it's rendered in other places like tooltips or screen readers. Your call whether to get into that level of detail here.
| - Title Case for dialog titles. | ||
| - Sentence case for all other UI text. | ||
|
|
||
| ## Element Cases |
There was a problem hiding this comment.
We should decide on a strategy for including this content inline on individual component doc pages. e.g. The table column content section already has some guidance. We could do similar for other content and label slots if we want.
Options I see are:
- remove that guidance and centralize it here. More maintainable but less discoverable.
- duplicate guidance both here and in component docs. Less maintainable but more discoverable.
- only document component guidance in component docs and simplify this page to just use summary info. Also more maintainable but less discoverable.
I would vote for 2 if you're willing to do the work!
| - Title Case for dialog titles. | ||
| - Sentence case for all other UI text. | ||
|
|
||
| ## Element Cases |
There was a problem hiding this comment.
We tend to use this terminology in Nimble
| ## Element Cases | |
| ## Component Cases |
3 participants
Pull Request
🤨 Rationale
It's really starting to bother me that our only capitalization guidance sits in the unmaintained fuse document. I also want to make an agent skill to catch capitalization issues and step one was getting some markdown around capitalization & team agreement.
👩💻 Implementation
Did my best to see what we're doing, made some judgement calls
🧪 Testing
Putting the PR up for review so we can debate the rules
✅ Checklist