Capitalization Guidelines for Nimble in storybook by aangerhofer · Pull Request #3032 · ni/nimble

aangerhofer · 2026-08-14T21:16:06Z

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

I have updated the project documentation to reflect my changes or determined no changes are needed.

jattasNI · 2026-08-17T16:50:05Z

+- Sentence case for all other UI text.
+
+## Element Cases
+


It would be good to add a section about control labels to this list. I think we currently use sentence case in SystemLink.

Same for button labels.

Here is SystemLink's guidance:

jattasNI · 2026-08-17T16:57:57Z

+
+### Tree View
+
+Tree view should use sentence case for all elements and sub elements.


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.

@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

Chips - yes when something is already represented as title case, we should leave that. I should add an "edge case" section to this pr

@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

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

jattasNI · 2026-08-17T16:59:13Z

+
+### Tabs
+
+Tabs in applications should be title case. Tabs in dialogs and drawers should


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

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?

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

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)

jattasNI · 2026-08-17T16:59:29Z

+In general, use the following capitalization conventions to ensure consistency
+across the interface:
+
+- ALL CAPS for table headers.


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.

jattasNI · 2026-08-17T17:02:25Z

+- Title Case for dialog titles.
+- Sentence case for all other UI text.
+
+## Element Cases


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!

rajsite · 2026-08-21T15:29:11Z

+The title of a banner should use sentence case along with the rest of the
+elements.
+
+<img src={bannerImage} alt="Banner capitalization example" />


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:

nimble/packages/storybook/src/docs/getting-started.mdx

Line 32 in b76b8c9

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

rajsite · 2026-08-21T15:40:08Z

+import tabsImage from './capitalization-assets/tabs.png';
+import treeViewImage from './capitalization-assets/tree-view.png';
+
+<Meta title="Style/Capitalization" />


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

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

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.

GaTechYJ · 2026-08-26T17:28:06Z

+
+### Tree View
+
+Tree view should use sentence case for all elements and sub elements.


@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

GaTechYJ · 2026-08-26T19:52:31Z

+
+### Tabs
+
+Tabs in applications should be title case. Tabs in dialogs and drawers should


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)

GaTechYJ · 2026-08-26T20:04:22Z

+
+### Tree View
+
+Tree view should use sentence case for all elements and sub elements.


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

GaTechYJ · 2026-08-26T20:06:59Z

+### Chip
+
+Chips should use title case.
+


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

First pass of capitalization guidelines in Nimble

bccd660

aangerhofer requested review from jattasNI and rajsite as code owners August 14, 2026 21:16

aangerhofer requested review from NIbokeefe, fredvisser and hellovolcano August 14, 2026 21:17

jattasNI requested a review from mollykreis August 17, 2026 16:38

mollykreis approved these changes Aug 17, 2026

View reviewed changes

jattasNI approved these changes Aug 17, 2026

View reviewed changes

rajsite reviewed Aug 21, 2026

View reviewed changes

small pr feedback

2747605

GaTechYJ reviewed Aug 26, 2026

View reviewed changes


		### Tree View

		Tree view should use sentence case for all elements and sub elements.


		### Tabs

		Tabs in applications should be title case. Tabs in dialogs and drawers should

Uh oh!

Conversation

aangerhofer commented Aug 14, 2026

Pull Request

🤨 Rationale

👩‍💻 Implementation

🧪 Testing

✅ Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaTechYJ Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rajsite Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rajsite Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaTechYJ Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

GaTechYJ Aug 26, 2026 •

edited

Loading

rajsite Aug 21, 2026 •

edited

Loading

rajsite Aug 21, 2026 •

edited

Loading

GaTechYJ Aug 26, 2026 •

edited

Loading