Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
97 changes: 97 additions & 0 deletions packages/storybook/src/docs/capitalization.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import { Meta } from '@storybook/addon-docs/blocks';
Comment thread
aangerhofer marked this conversation as resolved.
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" />

@rajsite rajsite Aug 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The 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 patterns like stratus-storybook. Would be a minor clean-up to move the current stuff in patterns out, seems like we could move them all into internals, thoughts?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or even more generic and have concepts and start moving more docs under there

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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:

  1. remove that guidance and centralize it here. More maintainable but less discoverable.
  2. duplicate guidance both here and in component docs. Less maintainable but more discoverable.
  3. 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!

Comment thread
aangerhofer marked this conversation as resolved.
Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same for button labels.

Here is SystemLink's guidance:

Image

### Banner

The title of a banner should use sentence case along with the rest of the
elements.

<img src={bannerImage} alt="Banner capitalization example" />

@rajsite rajsite Aug 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The 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:

<NimbleAnchorButton target="_parent" href="./?path=/docs/using-storybook--docs" appearance="block">Using Storybook</NimbleAnchorButton>


### Breadcrumb

Breadcrumbs should use title case.

<img src={breadcrumbImage} alt="Breadcrumb capitalization example" />

### Chip

Chips should use Title Case.
Comment thread
aangerhofer marked this conversation as resolved.
Outdated

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aangerhofer @jattasNI
tagging here to see comment thread for tabs and comments about chips in there.

<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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the distinction between app level and dialog/drawer level?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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".

@GaTechYJ GaTechYJ Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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)
Image

Carbon Design System Example (has both title and sentence case in their documentation examples)

Image Image

be sentence case.

<img src={tabsImage} alt="Tabs capitalization example" />

### Tile
Comment thread
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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?
Image

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.

Image

Your call whether these cases are worth clarifying.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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" />