Component Introductions
Pithy Names and Descriptions That Go a Long Way
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.
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.
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.
If demystifying synonyms is your game, sprinkle in a little “also known as” subtlety to sensitize rather than confuse.
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.
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:
Buttons can be used to show the user’s choice of options for actions and assign these to a clear hierarchy. (Audi)
Grid systems are used for creating page layouts through a series of rows and columns that house your content. (IBM Carbon)
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.
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:
The Predix UI Buttons module is a simple, robust, extensible baseline for building entire suites of buttons on. (GE Predix)
Buttons make common actions immediately visible and easy to perform with one click or tap. They can be used for any type of action, including navigation.(Shopify)
Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another. (Github Primer)
Buttons are used to invoke an event. (Salesforce Lightning)
For Cards:
Provide entry into detailed content via an image, text, and related information. (Discovery Comet)
A card is a sheet of material that serves as an entry point to more detailed information. (Material UI)
Cards contain elements and functions on a single topic and can be used as teasers for further content. (Audi)
For (Layout) Grids:
This 12-column, responsive grid provides structure for website content. (USDS)
The grid provides the foundation for harmoniously positioning elements, while maintaining a consistent and coherent look to the screen. (Atlassian)
Box component provides an easy way to apply standardized size & space to your layout. (Mineral)
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
