-
Notifications
You must be signed in to change notification settings - Fork 14
Capitalization Guidelines for Nimble in storybook #3032
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||
|---|---|---|---|---|
| @@ -0,0 +1,97 @@ | ||||
| import { Meta } from '@storybook/addon-docs/blocks'; | ||||
| import bannerImage from './capitalization-assets/banner.png'; | ||||
| import breadcrumbImage from './capitalization-assets/breadcrumb.png'; | ||||
| import chipImage from './capitalization-assets/chip.png'; | ||||
| import containerImage from './capitalization-assets/container.png'; | ||||
| import dialogImage from './capitalization-assets/dialog.png'; | ||||
| import drawerImage from './capitalization-assets/drawer.png'; | ||||
| import menuImage from './capitalization-assets/menu.png'; | ||||
| import stepperImage from './capitalization-assets/stepper.png'; | ||||
| import tileImage from './capitalization-assets/tile.png'; | ||||
| import tabsImage from './capitalization-assets/tabs.png'; | ||||
| import treeViewImage from './capitalization-assets/tree-view.png'; | ||||
|
|
||||
| <Meta title="Style/Capitalization" /> | ||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @jattasNI not sure about the subsection "Style". Think it's pretty overloaded here / narrowly scoped. Kinda want to align on
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Or even more generic and have
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We had a similar conversation in a meeting this morning. There is indeed a vision to add more content like more styling pages (control spacing / typography / color / etc) and like higher level patterns (similar to Stratus patterns or other design system patterns) and like general application guidance (accessibility). Looking at other design systems, some potential names for this section are "Guidelines", "Patterns", or "Design Language". If we're going to start with a single section name for all of these concepts I like the idea of something very general like "Guidelines" or "Concepts". Happy to let @aangerhofer pick. Another takeaway was that we should move this section to be the first one below the getting started content and above the components in the Storybook navigation tree. |
||||
|
|
||||
| # Capitalization | ||||
|
|
||||
| ## Overview | ||||
|
|
||||
| In general, use the following capitalization conventions to ensure consistency | ||||
| across the interface: | ||||
|
|
||||
| - ALL CAPS for table headers. | ||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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 | ||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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:
I would vote for 2 if you're willing to do the work!
aangerhofer marked this conversation as resolved.
Outdated
|
||||
|
|
||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be good to add a section about control labels to this list. I think we currently use sentence case in SystemLink.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||||
| ### Banner | ||||
|
|
||||
| The title of a banner should use sentence case along with the rest of the | ||||
| elements. | ||||
|
|
||||
| <img src={bannerImage} alt="Banner capitalization example" /> | ||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We can reference components directly in docs via nimble-react. Lets use the actual components in the docs instead of images (which can get out of date and are not theme-aware). Example of leveraging the components in the docs:
|
||||
|
|
||||
| ### Breadcrumb | ||||
|
|
||||
| Breadcrumbs should use title case. | ||||
|
|
||||
| <img src={breadcrumbImage} alt="Breadcrumb capitalization example" /> | ||||
|
|
||||
| ### Chip | ||||
|
|
||||
| Chips should use Title Case. | ||||
|
aangerhofer marked this conversation as resolved.
Outdated
|
||||
|
|
||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @aangerhofer @jattasNI |
||||
| <img src={chipImage} alt="Chip capitalization example" /> | ||||
|
|
||||
| ### Container | ||||
|
|
||||
| Containers should use sentence case for all elements. | ||||
|
|
||||
| <img src={containerImage} alt="Container capitalization example" /> | ||||
|
|
||||
| ### Dialog | ||||
|
|
||||
| Dialog titles should use title case. Content inside the dialog should use | ||||
| sentence case. | ||||
|
|
||||
| <img src={dialogImage} alt="Dialog capitalization example" /> | ||||
|
|
||||
| ### Drawer | ||||
|
|
||||
| Drawer titles should be title case. Other elements should be sentence case. | ||||
|
|
||||
| <img src={drawerImage} alt="Drawer capitalization example" /> | ||||
|
|
||||
| ### Menu | ||||
|
|
||||
| Menus group headers should be all caps. The rest of the elements should be | ||||
| sentence case. | ||||
|
|
||||
| <img src={menuImage} alt="Menu capitalization example" /> | ||||
|
|
||||
| ### Stepper | ||||
|
|
||||
| Stepper titles should be title case, subtitles should be sentence case. | ||||
|
|
||||
| <img src={stepperImage} alt="Stepper capitalization example" /> | ||||
|
|
||||
| ### Tabs | ||||
|
|
||||
| Tabs in applications should be title case. Tabs in dialogs and drawers should | ||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why the distinction between app level and dialog/drawer level?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I was thinking one is the title of a page vs the other is more like a subsection.. But I don't feel too strongly & am open to title for both. @mollykreis do you know what is normal for SL?
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It looks like we're inconsistent within SystemLink, but most of our tabs are single words. Therefore, the difference between title casing and sentence casing isn't much. The only two places I see multi-word tabs within an application are "Work Items" and "Data tables". Similarly, I couldn't find many places multi-word tabs appear in dialogs/drawers. In fact, the only one I found used sentence casing: "API keys". There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I can go either way on this. Part of me wants consistency and have them the same ... whichever one we choose. It's visually more consistent and just easier for us to remember. If I have to pick, I'd vote title case. I can find examples of both and even other design systems contradicting themselves. GitHub Example (sentence case) Carbon Design System Example (has both title and sentence case in their documentation examples)
|
||||
| be sentence case. | ||||
|
|
||||
| <img src={tabsImage} alt="Tabs capitalization example" /> | ||||
|
|
||||
| ### Tile | ||||
|
aangerhofer marked this conversation as resolved.
Outdated
|
||||
|
|
||||
| Tiles should use all caps. | ||||
|
|
||||
| <img src={tileImage} alt="Tile capitalization example" /> | ||||
|
|
||||
| ### Tree View | ||||
|
|
||||
| Tree view should use sentence case for all elements and sub elements. | ||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @NIbokeefe thoughts on trees being title case when used as main Nav? I think we should - and are in SL. It differs from what I've seen in your figma files though
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Chips - yes when something is already represented as title case, we should leave that. I should add an "edge case" section to this pr There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @jattasNI makes a good point and user defined chip values. If capitalization matter for case sensitivity, it would be bad to override the representation of it when showing it to the user There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @aangerhofer thoughts on how it'll behave for having sentence case in the tree (all elements) in a left navigation pane, and then in main document pane, the main identifier of the chapter/sub-topic you just clicked on would be ... sentence or title? This text would be at the top of the page in a title-ish position. Again, thinking of consistency between the strings. If I had to pick, I'd vote title case for all tree items ... especially if it's being used in a master-detail navigation layout. |
||||
|
|
||||
| <img src={treeViewImage} alt="Tree view capitalization example" /> | ||||






Uh oh!
There was an error while loading. Please reload this page.