@components

Component Introductions

Pithy Names and Descriptions That Go a Long Way

Masthead

#2 of 6 of the series Documenting Components:
Overview | Intros | Examples | Design | Code | Authoring


Component Names: “My name is…”

Naming a thing well is essential, and sometimes hard.

A component’s name (Buttons) appears as the page’s title, a label in site’s navigation (Buttons), and a code identifier of a CSS class (-button) or HTML element name (<Button>). Button is easy. It’s a name we refer to easily and consistently, together, everywhere in our work.

Illustration of a component name appearing in different artifacts
Persist the same component name throughout design, code and conversation

Drawer or Accordion or Collapsible is hard. Even harder? Grid or Layout or Layout Grid or Rows & Columns or Box or Proportional Grid or whatever you call invisible scaffolding visually ordering a page. Even Card isn’t universally defined: is it a generic container or the defined composite of all it contains? Making a library forces the choice.

Bar chart indicating the popularity of the simple term grid
Name of component used to “Establish visual order on a page using rows and columns,” across 21 libraries.

For most doc sites, navigation relies on label alone. With a little effort, nav could be enhanced with a thumbnail, maybe only via a tooltip on hover. That same snapshot—or fully rendered components—could also be arranged in a gallery introducing the Components section. We can do more.

Diagram of thumbnails appearing in navigation

If demystifying synonyms is your game, sprinkle in a little “also known as” subtlety to sensitize rather than confuse.

Diagram of a preferred term and alternate terms displayed adjacently

Takeaway: A optimally clear title can be a challenge, so sweat the decision only just enough. Always pair it with a sensitizing example, and sprinkle hints elsewhere in the UI.


Button or Buttons? Deciding Singular vs Plural Form

Names in code uniformly refer to a singular instance (-button, -input, -card). For components used many times on a page, whether primitive (Buttons, Inputs) or composed (Cards), an industry sample suggests most libraries prefer the plural form for page titles and site navigation labels.

Illustration of whether to include component names as plural

However, the singular form is common for components used once on a page. Global Navigation, Footer, and Grid are thought to frame the page (although Grids do repeat within a page). Similarly, a Masthead, Hero, or Billboard can set the page’s tone, but aren’t repeated further down. When we verbalize these, the singular form sounds more natural.

Now, navigation is tricky. As a component label, it’s the most vague, so consider avoiding it altogether. Yet for the remaining examples, plural variants — Footers, Grids, and Mastheads — work just fine.

Takeaway: Most teams favor plurals, and it’s up to your team to form a convention. Perfect consistency may not be worth the stirring the passions, but if you mix both, have a rationale.


Component Intros: “…and what I do is…”

Names offer an imperfect, incomplete component explanation. Therefore, many libraries elaborate with a description to capture a component’s essence.

Tantalizing with a Deck

The description can be short:

Each elaborates with details that sensitize: a Button’s action and hierarchy, a Grid’s rows, columns, and purpose to create page layout.

As a typographic tradition, the description—known as a Deck—should be paired visually with the component’s title and separate from remaining content. The deck’s font size should notably larger than paragraphs that follow. Tantalize the reader onward.


Keep the Deck to a Tweet

How long’s too long? I encourage teammates to embrace “Tweet length” (and by tweet, I mean original the length of 144 characters). Is two sentences OK? Perhaps, although my peer reviewing history is littered with suggestions trimming from two sentences to one.

Illustation of what to do: keep an intro short
Illustration of what not to do: go long with an intro
DO Keep the deck short. DON’T explain everything before Examples do a better job explaining everything.

When writing an introduction, capture the essence, not the whole story. That means clarifying component structure and purpose instead of implementation details. For a Grid, “rows and columns” for “responsive layout” are favored over “12 columns” or “breakpoints at 768 and 1024.” For Buttons, keep it very short. Like 10 words or less short! Everyone knows what a button is.

Takeaway: Set essential context and tone, avoid packing in every feature, and above all else: keep it short.


Industry Examples to Inspire

For Buttons :

For Cards :

For (Layout) Grids:


A Too-Detailed Introduction? “Get to the Goods!”

Sometimes components require introductions that elaborate on concepts, complexity, or library-specific points of view that aren’t self evident.

This is very evident in Layout Grid documentation. Rows, columns, breakpoints, alignment, shifting, stacking, offsetting. Oh my, there’s so much to understand. I’m exhausted just thinking about it.

So the instinct is to introduce in detail. An introductory paragraph becomes a section. Code examples to explain each concept only crop up later, mirror the introduction’s subheads. The repetition is unnecessary, bogging a reader down in details before they even get started.

Component recognition relies as much or more on what a reader sees (the picture) rather than read (the name), even if recall and conversation depend on the name. Therefore, position the name as the page’s title close to the item’s picture. Usability testing of component doc affirms:

“I don’t want to read all this.”
“Show me stuff I can immediately use.”
“Get me to the goods.”
“Where are the tools?”

In a introduction, avoid deep context setting and lengthy overviews. Save the feature details and expansive design and code guidelines for the examples.

Takeaway: Spare the gory details; instead, get to examples adopters can immediately apply! If you have long story to tell, save it for later.


Component introductions must be powerful yet short. The objective is to tantalize enough to ensure the reader is in the right place. As a result, minimize the distance from component title to a first glimpse of the “goods” that follow. Get to the examples you can to use.

#1. Overview ← Previous | Next → #3. Examples

Need help with your system?

EightShapes can energize your efforts to coach, workshop, assess or partner with you to design, code, document and manage a system.