Skip to content

Commit

Permalink
docs: Improve documentation for new contributors, trussels (#402)
Browse files Browse the repository at this point in the history 
* add and update docs

* Add notes about merging external contributions

* Add documentation issue template, comment out descriptions

* cleanup and code review
  • Loading branch information
@haworku
haworku authored Aug 19, 2020
1 parent 2a33597 commit 0849a30
Show file tree
Hide file tree
Showing 13 changed files with 219 additions and 174 deletions.
26 changes: 10 additions & 16 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
name: Bug report
about: Create a report to help us improve
title: "[bug]"
title: "[fix]"
labels: "type: bug"
assignees: ''

---

**Describe the bug**
A clear and concise description of what the bug is.
<!-- A clear and concise description of what the bug is. -->

**To Reproduce**
Steps to reproduce the behavior:
Expand All @@ -18,21 +18,15 @@ Steps to reproduce the behavior:
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.
<!-- A clear and concise description of what you expected to happen. -->

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Desktop (please complete the following information):**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]

**Smartphone (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
<!-- If applicable, add screenshots to help explain your problem. -->

**Additional context**
Add any other context about the problem here.
<!-- Add any other context about the problem here. -->

**Device and Browser Information (please complete the following information if describing a UI bug):**
<!-- - OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22] -->
20 changes: 20 additions & 0 deletions .github/ISSUE_TEMPLATE/docs_request.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
name: Documentation request
about: Suggest documentation (or Storybook) improvements
title: "[docs]"
labels: "type: documentation"
assignees: ''

---

**Does this documentation relate to a specific USWDS feature?**
<!-- If documentation relates to a USWDS feature or specific Storybook story, please link it here and provide some context. -->

**Is your documentation related to a problem or inconsistency? Please describe.**
<!-- A clear and concise description of what the problem is. Ex. I'm can't find information on [...] -->

**Describe the documentation you'd like**
<!-- A clear and concise description of what you want to happen. -->

**Additional context**
<!-- Add any other context or screenshots about the documentation here. -->
12 changes: 6 additions & 6 deletions .github/ISSUE_TEMPLATE/feature_request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ assignees: ''
---

**Does your feature request relate to a specific USWDS feature?**
This project prioritizes work needed to gain full parity with the USWDS components and styles. If your feature request relates to a USWDS feature, please link it here and provide some context. If it doesn't, that's okay, but the request may be reprioritized accordingly.
<!-- If your feature request relates to a USWDS feature, please name and link it here. Provide some context. -->

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->

**Describe the solution you'd like**
A clear and concise description of what you want to happen.
<!-- A clear and concise description of what you want to happen. -->

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
<!-- A clear and concise description of any alternative solutions or features you've considered. -->

**Additional context**
Add any other context or screenshots about the feature request here.
**Additional context**
<!-- Add any other context or screenshots about the feature request here. -->
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
71 changes: 20 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,34 @@
[![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/)

## Table of Contents
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).

1. [Background](#background)
1. [Install](#install)
1. [Usage](#usage)
1. [Maintainers](#maintainers)
1. [Contributing](#contributing)
1. [License](#license)
1. [Roadmap](#roadmap)
**Table of Contents**

## Background
- [@trussworks/react-uswds](#trussworksreact-uswds)
- [Background](#background)
- [Non-Goals](#non-goals)
- [Install](#install)
- [Usage](#usage)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#license)

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:
## Background

- 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 Down Expand Up @@ -64,37 +61,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 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 0849a30

Please sign in to comment.