@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 System SEEDS 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 install
$ 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.

Contents

• New Components
  • A good Racine component should…
  • Questions to ask when creating a component
  • Scaffolding Your Component
  • Documenting Your Component
  • Soliciting Feedback
• Working with Code
  • Committing Changes
  • Submitting PRs
  • Releasing

New Components

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.

What should I name the component?

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.

Scaffolding Your Component

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

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
• index.test.js: Jest tests for the component
• 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.

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 their Flow types, 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 an exported array.

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.

Working with Code

Committing Changes

We use standard-version to automatically update the changelog and decide new version numbers. As such, we need commit messages to follow a consistent format.

Example commit messages (simply match this pattern and your commit message will be accepted):

• feat: add alert component
• fix(alert): display the correct icon when type is "danger"
• feat(alert): remove "danger" alert type[\n]BREAKING CHANGE: removes one option for "type" prop
• feat(icons): add reporting range icon
• feat(dependencies): upgrade classnames to 2.2.5
• chore(dependencies): upgrade babel dependencies to latest version (chore because they are devDependencies)
• feat(build): add dist/iconList.js to package output

Commit message format:

type(scope): message

body

footer

type is one of the following:

• fix: Solves a bug
• feat: Adds a new feature
• build: Affects the build system or external dependencies
• docs: Adds or alters documentation or the racine app
• perf: Improves performance
• test: Adds or modifies tests
• chore: Other changes that don't modify src or test files

scope is optional but, with few exceptions, should be used for all feat and fix commits. Common scopes include:

• [component name]: Changes to a racine component
• icons: Changes to the SVG icon files
• dependencies: Changes to dependencies should be feat, and devDependencies should be chore
• build: Changes to the build that make significant changes to the published package, should be a feat or fix

message requirements:

• starts with lower case
• uses the imperative, present tense: "change" not "changed" nor "changes"
• includes motivation for the change and contrasts with previous behavior

Submitting PRs

1. Create a new branch

$ git checkout -b my-branch-name

1. Make your changes

2. Test your changes

$ yarn test

1. Commit your changes, following the commit message guidelines above. For additional help, you can use the yarn commit command instead of git commit

$ git add -A
$ git commit -m "MESSAGE"

1. Push your change

$ git push origin my-branch-name

1. Open a PR (you should see the option to open a PR at the top of the racine github page)

Congrats, thanks for contributing!

Releasing

Only those with admin privileges to the Racine repo can publish new versions of the package. Contact one of the following about releasing a new version:

• Ben Lister
• Ben Rothman
• Doug Garofalo
• Kevin Bertram
• Shane Brunson
• Westin Wrzesinski

To publish, run the following from the master branch

$ yarn release

See the standard-version docs for details about specifying the new version, pre-releases, etc.