Skip to content

Commit

Permalink
add and update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@haworku
haworku committed Aug 17, 2020
1 parent 8e98f0f commit 7b32cf1
Show file tree
Hide file tree
Showing 10 changed files with 178 additions and 155 deletions.
9 changes: 0 additions & 9 deletions .github/pull_request_template.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,5 @@
<!--
CHECKLIST
- [ ] PR title conforms to conventional commits, e.g. feat: Button
- [ ] PR includes `yarn audit` output if dependencies changed
- [ ] Any new components are exported from `index.ts`
-->

# Summary

<!-- Describe the changes and the scope. List any new components. -->

## Related Issues or PRs

<!-- Link existing Github issue(s), e.g. closes #123 -->
Expand Down
76 changes: 20 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,35 @@
[![CircleCI](https://img.shields.io/circleci/build/github/trussworks/react-uswds/develop)](https://circleci.com/gh/trussworks/react-uswds)
[![npm downloads](https://img.shields.io/npm/dm/@trussworks/react-uswds)](https://www.npmjs.com/package/@trussworks/react-uswds)

React USWDS 2.0 component library
**ReactUSWDS Component Library**

This is a front end component library whose aim is to develop [React](https://reactjs.org/) implementations of the design patterns defined by the [United States Web Design System (USWDS) 2.0](https://designsystem.digital.gov/). The primary goal of this library is to document and provide common UI components that can be included in other projects that adhere to or are based off of the USWDS, removing a significant amount of overhead UI development from such projects.
This is a frontend component library, built in [React](https://reactjs.org/) with [Typescript](https://www.typescriptlang.org/), based on design patterns defined by the [United States Web Design System (USWDS) 2.0](https://designsystem.digital.gov/). Our primary goal is to document and provide common UI components following the USWDS specification. This library removes a significant amount of overhead UI development for projects based on this standard.

A deployed instance of the ReactUSWDS Storybook is located at: https://trussworks.github.io/react-uswds/
A deployed instance of the ReactUSWDS Storybook is located at: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/)

An example application, built with React-USWDS, can be found in the `/example` folder and run with the appropriate [`yarn:example` commands](./docs/contributing.md#available-commands).

## Table of Contents

1. [Background](#background)
1. [Install](#install)
1. [Usage](#usage)
1. [Maintainers](#maintainers)
1. [Contributing](#contributing)
1. [License](#license)
1. [Roadmap](#roadmap)
- [@trussworks/react-uswds](#trussworksreact-uswds)
- [Table of Contents](#table-of-contents)
- [Background](#background)
- [Non-Goals](#non-goals)
- [Install](#install)
- [Usage](#usage)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#license)

## Background

The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be actually useful, they should follow best practices and baseline standards for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization in implementation (such as via React `props`). Therefore we should adhere to these development guidelines as much as possible:

- Encourage a strict separation of concerns, focusing on UI (rendered HTML and CSS) rather than any application logic.
- Expose the necessary props for composability and extensibility, such as event handlers, custom CSS classes, etc.
- Maintain a high standard of unit test coverage and cross-browser/device support, so that projects including this depedency can focus on integration and implementation.
- Provide thorough documentation (using a web interface such as Storybook) so that users can view the components as they render in the UI, the source code required to use them, and specifications such as how props are used, a11y support, and test coverage.
- Consistent and transparent versioning so that multiple projects can rely on this package, and it can be maintained as React and USWDS release new versions while also providing backwards compatibility.
The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be useful, they should follow best practices for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization. We adhere to a set of [development guidelines](./docs/contributing.md#guidelines) as much as possible and use automation to enforce tests, linting, and other standards.

#### Non-Goals
### Non-Goals

This is not meant to be a one-size-fits-all front end solution to every Truss web project. We are starting off with the very opinionated decision to cater towards a project that wants to use (or at least branch off of) USWDS 2.0, and is using React as a front end framework.
This is not meant to be a one-size-fits-all front end solution, We are starting off with the opinionated decision to cater towards projects that use the U.S. Design System 2.0, and encapsulate these specific styles and markup in React components.

In addition to working towards the above outcomes, we are hoping to gain learnings around how to best abstract out UI code from implementation; help demonstrate and standardize front end code practices for other Truss projects; and develop and distribute a shared JS library to other teams.
In the process, we expect to gain learnings around how to best abstract out UI code from implementation; how to better standardize and document front end code practices; and how to develop, maintain, and distribute a shared JS library in alignment with our [company values at Truss](https://truss.works/values).

## Install

Expand All @@ -44,12 +42,6 @@ Install this package with npm or yarn:
yarn add @trussworks/react-uswds
```

or

```
npm i @trussworks/react-uswds
```

## Usage

You can import modules using ES6 syntax:
Expand All @@ -64,37 +56,9 @@ Also make sure to include the following in order to import the compiled CSS from
@import '~@trussworks/react-uswds/lib/index.css';
```

**[More info about using USWDS CSS & SCSS](./docs/scss.md)**

### Icons

[USWDS recommends using Font Awesome](https://designsystem.digital.gov/components/icons/), and that project [provides a package for use with React](https://github.com/FortAwesome/react-fontawesome).

To add this to your project, install react-font-awesome and at least one style of icon:

```
yarn add @fortawesome/fontawesome-svg-core \
@fortawesome/free-solid-svg-icons \
@fortawesome/react-fontawesome
```

You can then add Font Awesome icons to your projects using the `FontAwesome` component:


```jsx
import ReactDOM from 'react-dom'
import { Button } from '@trussworks/react-uswds'
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faSave } from '@fortawesome/free-solid-svg-icons'

const button = <Button type="button">
<FontAwesomeIcon icon={faSave} /> Save Changes
</Button>;

ReactDOM.render(button, document.body);
```
Note: If you aren't already using USWDS as a dependency, you will also need to import uswds styles. **[Read more info about using USWDS styles and assets here](./docs/styles_and_assets.md)**

For more information on working with and configuring react-fontawesome, please see [that project's documentation](https://github.com/FortAwesome/react-fontawesome#installation). To find specific icons for your project, [search on the Font Awesome site](https://fontawesome.com/icons).
Having issues? See [FAQs](./docs/faqs.md).

## Maintainers

Expand Down
15 changes: 8 additions & 7 deletions docs/adding_new_components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@

Every new `react-uswds` component needs the following:

- [ ] **A Github issue with the requirements clearly listed.** Requirements include a rough sketch of the expected props and any state the component will handle.
- [ ] **A Github issue with the requirements clearly listed.** Requirements include a rough sketch of the expected props and state the component will handle.
- [ ] **A component file (`.tsx`) inside a matching folder** - e.g. `component/GovBanner/GovBanner.tsx`.
- [ ] **An export from the package entry point** - e.g. `index.ts` must have the line `export { GovBanner } from './components/GovBanner/GovBanner'`
- [ ] **Unit tests** (`test.tsx` file) for logic relating to props and events handlers.
- [ ] **Storybook stories** (`stories.tsx` file) illustrating the use of the component. The goal is parity with the USWDS design system examples. Use the [component story format](https://storybook.js.org/docs/formats/component-story-format/).

## Navigating documentation

We can extrapolate the requirements for `react-uswds` components by referencing several sources. Relevant documentation includes:
We extrapolate the requirements for `react-uswds` components by referencing several sources. Relevant documentation includes:

- HTML markup and written descriptions of components in the [design system docs](https://designsystem.digital.gov/components/footer/)
- Live code demos in the [uswds storybook](https://components.designsystem.digital.gov/)
Expand All @@ -29,8 +29,9 @@ Pay special attention to:

### Props

- Require props that are fundamental to the element (such as `id` and `name` for a form input), even if they aren't necessarily "required" HTML attributes. Make all other props optional.
- Extend the standard HTML attributes as props for the primary element in the component. For example, a form can have its own props and also extend the `HTMLFormElement`
- Require props that are fundamental to the element (such as `id` and `name` for a form input), even if they aren't necessarily "required" HTML attributes. - Make all other props optional.
- Avoid [conflicting boolean props](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/). When props are mutually exclusive you likely need to use an enum prop instead. See `<Button />`.
- Extend the standard HTML attributes as props for the primary element in the component. For example, see how a form has its own props and also extends the `HTMLFormElement`

```javascript
interface FormProps {
Expand All @@ -43,13 +44,13 @@ Pay special attention to:
): React.ReactElement =>
```

- Avoid [conflicting boolean props](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/). When props are mutually exclusive you likely need to use an enum prop instead. See `<Button />`.

There is a significant difference between thinking about the component props in `react-uswds` versus in application code, where all the likely prop values are known and where the domain is well understood. We don't know all the potential ways our components will be used. We want to allow a consumer to use a variety of HTML attributes, including `aria-` values, additional CSS classes, , and custom event handlers. This is why the library uses [spread attributes](https://reactjs.org/docs/jsx-in-depth.html#spread-attributes) for the basic HTML element props in each component. This allows us to be more expansive with the allowable props while still maintaining type safety with Typescript.
### State
- Group state declarations and hooks at the top of the component function. Make it easy to see how state is being used in the component.
- When using [`useState`](https://reactjs.org/docs/hooks-state.html), prefer [functional updates](https://reactjs.org/docs/hooks-reference.html#functional-updates). Object spread syntax is useful here.
- Keep components as flexible as possible. This means leaving business logic/implementation details out of the component (use props instead of internal state). Anytime you find yourself using component `state` heavily, ask yourself if its something that should actually be tracked by the consumer instead.
- Leave business logic/implementation details out of the component state. Use props for this purpose instead. Anytime you find yourself using component `state` heavily, ask yourself if its something that should actually be tracked by the consumer (and passed in as props instead).
### Children
Expand Down
Loading

0 comments on commit 7b32cf1

Please sign in to comment.