Skip to content

Commit

Permalink
DevDocs: add doc for creating new components (#24172)
Browse files Browse the repository at this point in the history
This creates a checklist for people who want to create a new UI component.
  • Loading branch information
davewhitley committed Apr 18, 2018
1 parent b3c182b commit 71d4278
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 0 deletions.
3 changes: 3 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,9 @@ Whether somebody is reviewing your code or you are reviewing somebody else’s c

If you feel yourself waiting for someone to review a PR, don’t hesitate to personally ask for someone to review it or to mention them on GitHub. _The PR author is responsible for pushing the change through._

### Adding A New Component

If you'd like to add a new component to Calypso, please review our [new component checklist](../docs/new-component-checklist.md).

### We’re Here To Help

Expand Down
4 changes: 4 additions & 0 deletions docs/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,7 @@ Imagine you want to change the border color of a `SiteIcon` component when it i
If we were doing inline styles it would mean we need to pass down a style prop from `sidebar` (the component that wants to make the modification) all the way down to `site-icon` to modify that specific border style value. Which is messy, obscure, and requires passing down a meaningless attribute through components that don't care about it, coupling them with a design intent you want to express in the "Sidebar". Now, with CSS and our naming guidelines it becomes just an old `.sidebar .site-icon {}` on the sidebar's `style.scss` file.

That remains expressive, simple to read, and given our convention it immediately signals `site-icon` is a child component of `sidebar` at some level to whoever reads the styles or inspects them, reflecting the composition tree naturally in the stylesheet, and the intention of only modifying that individual component in this specific context. Since specificity also increases, it means it doesn't matter where in the build process the sidebar stylesheet order comes.

## Adding A New Component

If you'd like to add a new component to Calypso, please review our [new component checklist](new-component-checklist.md).
40 changes: 40 additions & 0 deletions docs/new-component-checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# New Component Checklist

This checklist is used whenever someone wants to merge a new component to the system. The steps below are edited from Nathan Curtis’ [Component QA article](https://medium.com/eightshapes-llc/component-qa-in-design-systems-b18cb4decb9c).

Before you complete the steps below, please consider the reusability of the component by using this [flowchart](https://coggle.it/diagram/WtUSrld3uAYZHsn-/t/-/992b38cbe685d897b4aec6d0dd93cc4b47c06e0d4484eeb0d7d9a47fb2c48d94):

![New Component Flowchart](https://cldup.com/a-vP702FC1.png)
Credit: [original flowchart](https://coggle.it/diagram/V0hkiP976OIbGpy8/t/vanilla-pattern#e4f393) from the [Vanilla Framework](https://vanillaframework.io/).

## Visual Quality

Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it meet our visual guidelines?

## Accessibility

Has the design and implementation accounted for accessibility? Please use our [accessibility checklist](accessibility-checklist.md).

## Responsiveness

Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected?

## Sufficient States & Variations

Does it cover all the necessary variations (primary, secondary, compact) and states (default, hover, active, disabled, loading), given intended scope?

## Content Resilience

Is each dynamic word or image element resilient to too much, too little, and no content at all, respectively? How long can labels be, and what happens when you run out of space?

## Composability

Does it fit well when placed next to or layered with other components to form a larger composition?

## Functionality

Do all behaviors function as expected? For responsive tabs, are menus (for overflow tabs) behaving correctly in varied device settings?

## Browser Support

Has the component visual quality and accuracy been assessed across Safari, Chrome, Firefox, IE, and other browsers across relevant devices? Please adhere to our [browser support requirements](../README.md#browser-support).

0 comments on commit 71d4278

Please sign in to comment.