Component Categorization

[emplums]

Right now in Primer Components, we've got many "building block" type components, and also many "pattern" type components.

• Does it make sense to categorize these separately on the documentation site?
• How should we define "building block" vs "pattern"?
• Should we move pattern components into their own packages?

Right now we call them "pattern" & "helper":

Pattern: Pattern components help us repeat commonly used UI patterns and interactions in order to maintain our brand and provide a great user experience. Some examples of pattern components are Button, Avatar, or Label.

Helper: Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are Flex, Text, Grid, and the Position components.

[emplums]

Examples in other design systems

Shopify Polaris

Polaris has many categories which seem to be organized by function:

• Actions
• Structure
• Forms
• Images and Icons
• Feedback indicators
• Titles & Text
• Behavior (Collapsible, Scrollable)
• Lists and Tables
• Navigation
• Overlays

Notes: They've got a repo with example applications built out using their React components which is pretty neat: https://github.com/Shopify/polaris-react/tree/master/examples

Twilio Paste

• Components (Alert, Form, Button, Heading, etc)
• Layout (Absolute, Aspect Ratio, Flex, Grid, Media Object)
• Primitives (Box, Text, Modal dialog)

IBM Carbon

• Components: Components are one of the key building blocks of the design system. Each component has been designed and coded to solve a specific UI problem, such as presenting a list of options, enabling submission of a form, providing feedback to the user, and so on. All of the components in Carbon have been designed to work harmoniously together, as parts of a greater whole.

• Patterns: Patterns are best practice solutions for how a user achieves a goal. They show reusable combinations of components and templates that address common user objectives with sequences and flows.

Notes: Carbon seems to not have many "helper" components like position, text, etc

[Theme UI]()

• Doesn't seem to categorize components in any way, but has the concept of variant groups which looks like are style variations that can be used on more than one component. For example Button , Close, IconButton and MenuButton have access to the buttons variant group.

Note: ThemeUI is more of a framework for other design systems to use than a design system itself which might be why it has less "pattern" components and more smaller "helper" style components

Chakra UI

• Doesn't seem to organize components in any way, but has the concept of Components, Recipes (examples) and Utilities (custom hooks)

AtlasKit

• Core
• CSS Packs
• Editor
• Elements
• Engagement-Platform
• Growth
• Help
• Helpers
• Home
• Media
• Navigation
• People and Teams
• Search
• Server
• BitBucket
• Jira

Notes: AtlasKit components seem to be divided up by product category. Core seems to be most similar to our component library, does not contain helper components. It looks like each component in Core is it's own package.

HP Grommet

• Layout (Box, Footer, Grid, Header, Layer, Main, Stack)
• Type (Heading, Markdown, Paragraph, Text)
• Controls (Accordion, Anchor, Button, etc)
• Input (Checkbox, MaskedInput, RadioButton, etc)
• Visualizations (Avatar, Calendar, WorldMap, etc)
• Media (Carousel, Image, Video)
• Utilities (AnnounceContext, Collapsible, SkipLinks, Infinite Scroll, Keyboard)

Notes: I like how they organize and visualize their components: https://v2.grommet.io/components

Lexicon Design System

• Patterns: Interaction Patterns define a series of standard behaviours we have in our design system. Here we express different consensus as how every drag and drop must behave or how to differentiate visually among similar actions with different outcome.

• Components: Components that are essential to build interfaces. Each component defines its rules and behaviors. Each component's look and feel is based on the combination our foundations. Therefore, changes to the foundation principles propagate to the entire system.

• Templates: Templates offer prebuilt solutions to tackle repetitive interface challenges. They speed up the design process, as they only require minor modifications to fit your use case and display your content.

• Satellites: These components are for the needs of specific products or applications. They are built using Lexicon's foundations, patterns and components. They belong to the product or application that created them, rather than the design system itself. Therefore, they are not supported in Clay and shouldn't be supported in any base implementation.

Mozilla Protocol

• Fundamentals
• Atoms
• Molecules
• Organisms
• Templates

Workday Canvas

• Buttons
• Containers
• Indicators
• Inputs
• Navigation
• Popups

[emplums]

Started doing some rough diagramming in Figma: https://www.figma.com/file/6hksZw19FFbqgkDRleYZtF/React-Components?node-id=0%3A1

[dmarcey]

As another example, here is the categorization for the Azure Dev Ops Design system: https://developer.microsoft.com/en-us/azure-devops/components

The high-level categories were:

• Structure and layout
• Input controls
• Overlays and notifications
• Data display
• Supporting visuals

Then we had another separate section for "Utilities" which were basically components, but not UI components - things like FocusZone or Observer that were used to build complex UIs, but didn't actually produce any DOM themselves.

IIRC, @yaili helped out with this initial categorization, so she would probably be a good person to talk to about these categories!

[emplums]

Oooh I really like these categories @dmarcey! I've been struggling with figuring out where things like Avatar would fit and I like the wording of "Supporting Visuals: for these kinds of things!

[yaili]

I feel that generally components, patterns, and utilities is the simplest way to have some divisions without too many sections.

We divided the Components section of Azure DevOps in categories to be easier to scan, although under the hood they're all components (and in the nav they're all in alphabetical order). 😊

[yaili]

More random thoughts:

• Would this change have an effect on the other documentation sites (css, view components)? I think that the CSS docs are organised to mirror the code structure. Is that a rule for other sites? 🤔
• Helper and utility works equally well for things that do one thing
• My thinking when I see "patterns" is that these are groups of components put together that occur frequently in the product (and that are somehow unrelated to a specific visual direction — ie a card would generally have a heading, content area, button area, regardless of how they look)

[github-actions[bot]]

Hi! This issue has been marked as stale because it has been open with no activity for 180 days. You can comment on the issue or remove the stale label to keep it open. If you do nothing, this issue will be closed in 7 days.