@sproutsocial/racine

Racine

“A single word often betrays a great design.” –Jean Racine

Racine is a component library consisting of documented, reusable components built for consumption in Sprout Social’s web products. The design principals of this library are based off Sprout Social’s Design SystemSEEDS and the components are expressed as React components which encapsulate logic, styling, example usage and documentation.

Racine Setup

To get started running Racine locally, assure you have Node.js and NPM installed and then simply clone or download this GitHub repo and run the following commands:

yarn; yarn start

Contributing to Racine

Contributions to Racine are welcome from any part of the team, whether updating component presets, documentation or adding a new component to the library. If you are interested in getting involved, feel free to submit a Pull Request, create a ticket on the Racine Initiatives Jira Board, or join us at the Component Library Guild meeting. Please read on to the next section for best practices when creating a new component.

A good Racine component should…

...have an easily statable, specific purpose.

✓	⚠
A component should be able to be described in a maximum of 1-3 sentences	Don’t make components so specific or vague that they can’t be reused or are easy to confuse with other components

...attempt to solve a single concern.

⚠
If a component requires constant tweaks or one off changes, it is probably doing too much or needs further refinement or to be split into multiple components

...have well documented props and a verbose description.

⚠
Avoid scenarios like declaring, “this is a theme prop”, explain what exactly is being themed and how that theme was derived

...incorporate its own error and default states.

⚠
The end-to-end experience should be considered as a part of the component’s creation, not as an afterthought

...contain tests and QA attributes when appropriate.

✓	⚠
Contributors should leverage available testing tools like Jest as needed and work with QA to determine if specific attributes are needed for testing	If modifying the component has the potential to ruin your team members’ or our customers day, it probably needs to be tested

…be context agnostic.

✓	⚠
Should be able to work in any of Sprout’s products	Avoiding defining any layout, sizes, color or spacing assumptions that may hinder reusability

…be tested in all relevant supported browsers and platforms.

✓
If there are technology limitations then the component should gracefully degrade or contain a polyfill
Users should be able to use the component for its stated purpose in all supported browsers and platforms unless otherwise noted

…have at least one functional preset defined.

✓
The more context available, the easier it is to convey the component’s purpose
Components should use as many presets as is needed to demonstrate its intended uses

…define its own styles.

⚠
Don’t override or style other components or DOM elements outside of the scope of the component

…be able to be easily categorized.

✓	⚠
“Atomically” as well as in other taxonomies available in the Component library	If a component cannot easily be categorized, it might be too complex or have a purpose that is not well defined

Questions to ask when creating a component

Let's go from idea to delivery. In this example, we will create a new component called KurtRussell.

Does this need to be in Racine?

In order to ensure the longevity of Racine, the components that are added need to be reusable and of high quality. Ask yourself, does KurtRussell need to be in Racine? Will other teams benefit from this pattern? Does it deliver a need no other component delivers? Is there more value in creating a new component, or should an existing component be extended? For example, if Racine already has PatrickSwayze, would we be better served with a HollywoodActor component that covers both?

If you are having trouble answering these questions, then talk about it:

• Component Library Guild meeting is the best place to discuss the benefits of a particular component
• For quicker questions, use the #eng-guild-components or #eng_web channels in Slack

What category does this belong to?

After discussion, it's agreed that, yes, KurtRussell belongs in Racine. Of course, naming things is hard. If KurtRussell doesn't fit in any of our existing categories, discuss with the Design developer and or Front-End engineers on your team, add it to the agenda of the Component Library Guild meeting at or reach out in the #racine #eng_web Slack channels to get advice.

Scaffolding your component

To build a new Racine component quickly, simply use the command line:

yarn new

This command will walk you through naming, categorizing and tagging your new component.

One complete, the scaffolding tool will generate three files for your new component:

• index.js

  The component JavaScript and JSX goes here.

• presets.js

  Presets and example use cases for the component

• data.js

  Component Metadata like categories, tags and accessibility status

• _styles.scss

Component styles. Note: global variables and Sass mixins are automatically imported, so there's no need to @import them in these files.

• index.test.js

Jest tests for the component.

Documenting Your Component

Documentation should be written inline in KurtRussell.js, following the existing boilerplate comments the file after running yarn new. The documentation is extracted with react-docgen.

Prop names should, along with the propType, be self-documenting. Props should be documented if they would not be clear to other developers who are not familiar with the component. Certain basic universal props like onClick and isHidden probably don't need a thorough documentation but you should strive to add as much context as needed.

presets.js should contain, at a minimum, the common use cases for this component. They are included in this file as Javascript objects in presets. Many components, like form elements, need values passed into them, so uncomment componentPresentation. This allows you to override how Racine renders your component.

Soliciting Feedback

As the author of a global component, you are accountable for soliciting feedback from fellow designers and developers on your team as well other teams who might be affected. If you would like to start a discussion about the component, the #eng-guild-components and #eng-web channels on Slack are a great place to start.

Naming Components

Are you making a Patrick Swayze Card? Then here's how you should name the component.

• Does this component utilize an existing Card pattern? Your component should be CardPatrickSwayze.
• Is this component a new kind of card altogether? Your component should be PatrickSwayzeCard.