To keep in mind

These components accelerate our designers and front-end engineers and show how they behave interactively. Shared components let us reuse existing work and build upon what we have.

Component design

Naming things is hard!

Talk to someone in Design Systems Team for help on names that work for designers and engineers, as well as respect industry guidelines like W3C specifications, popular frameworks, and so on. For example:

• Name of a component
• Name of props e.g. "mood"–ideally the possible values would be suggested by the prop name. Avoid "type" or "variant" where possible.
• Name of prop values e.g. "affirmative", "destructive"
• Name of sizing options e.g. small/medium/large

Stand on the shoulders of giants

Where possible, we build on the community of practice around design systems and open-source component libraries. There's no need to reinvent the wheel.

Find 3 examples of someone who's done this before. For example, try Shopify's Polaris Design System, Atlassian's Design System, Salesforce's Lightning Design System, Ant Design's System, or Google's Material Design. You might find inspiration for design guidelines, prop names, and implementation details. Look for a component library or framework that's already built what you're considering.

Implementation considerations

You might need to consider:

• Nested HTML: Will any HTML, such as a link be present? For example, a link in a checkbox label, or a button in a notification paragraph.
• Text wrapping: Will there be any text wrapping, breaking, or truncating for user-generated content, such as URLs/emails?
• RTL: Does there need to be right-to-left (RTL) options for localization and internationalization?
• Security: Are there any possible data confidentiality or security concerns? Consider dummy text.
• Motion: Does there need to be motion?
• Performance: Consider latency, size, perceived performance, compilation/minification, caching, CDNs, and delivery.
• Inheritance: Is there likely to be style inheritance problems with legacy styles, such as Bootstrap?
• Responsive: How responsive is it?
• Accessibility: How accessible is it? Culture Amp employees can check out Web Accessibility (Current Compliance, Going Forward, Statement and Answers for Customers).

API Design

States

There might be more than 1 dimension of state. In addition to default, hover, focus, active, and disabled states, a component might have other dimensions of states such as a checkbox being checked, unchecked or mixed, or an input being readonly.

Props: noMargin

It is common for components to come with default margins surrounding them and yet these margins can cause problems in app, given surrounding content. For all components that come with default spacing, we provide a noMargin boolean prop to turn the default margins off as needed.

Props: sizes

Use "Small", "Medium", "Large": in code, sm, md, lg. For more information, see Sizing guidelines.

Want to learn more about great components?

• Documenting Components by Nathan Curtis.
• Component Design Guidelines by Nathan Curtis.
• Size in Design Systems by Nathan Curtis.