... | ... | @@ -54,6 +54,7 @@ Most of the components in the Components Library use a number of small- er, high |
|
|
[PubSweet UI](https://gitlab.coko.foundation/pubsweet/pubsweet/tree/master/packages/ui) (@pubsweet/ui) is an important PubSweet package intended to house these small components. It makes an ever-expanding list of these components available for developers, and plays a central role in the development of a front-end component. UI elements are categorized based on a loose adherence to the principles of atomic design (http://bradfrost.com/blog/post/atomic-web-design/).
|
|
|
|
|
|
PubSweet also provides a [complementary library](https://gitlab.coko.foundation/pubsweet/pubsweet/tree/master/packages/ui-toolkit), `@pubsweet/ui‐toolkit` that provides some helper functions, as well as bits of reusable CSS (eg. rotation keyframes, animations, fade-ins, etc.).
|
|
|
|
|
|
## Conventional Commits
|
|
|
All changes to components are documented using [Conventional Commits](h ttps://conventionalcommits.org/). A good example of how this might look like in practice is our [commit log](https://gitlab.coko.foundation/pubsweet/pubsweet/commits/master). All contributions to these libraries are required to follow this particular commit structure.
|
|
|
|
... | ... | @@ -84,7 +85,8 @@ Things to keep in mind when creating a new component: |
|
|
* Follow [Conventional Commits](https://www.conventionalcommits.o rg/en/v1.0.0-beta.2/) or keep a healthy changelog;
|
|
|
* Write documentation;
|
|
|
* Write tests.
|
|
|
* Design
|
|
|
|
|
|
## Design
|
|
|
### Layout and what makes a UI component
|
|
|
Relying on Brad Frost's principles of Atomic Design, PubSweet UI (`@pubsweet/ui`) is a single component offering an ensemble of smaller reusable elements classified as either atoms or molecules. We use the word "component" to refer both to a component released as an independent package and to any of the elements inside PubSweet UI.
|
|
|
|
... | ... | @@ -106,52 +108,65 @@ Let’s take the example of a series of radio buttons. In a group of two ("yes" |
|
|
### Theming-ready components
|
|
|
As PubSweet provides a set of tools to easily change the look and feel of any UI element, your atom or molecule should be developed using the set of variables as the minimum-required CSS.
|
|
|
For example, the primary button atom is set to use the primary color for its background color:
|
|
|
```const Button = styled.button`background: ${props => props.theme.colorPrimary};````
|
|
|
`const Button = styled.button`background: ${props => props.theme.colorPrimary};``
|
|
|
|
|
|
For a complete list of variables, you can check the `pubsweet/design` [repo regarding variables](https://gitlab.coko.foundation/pubsweet/design/blob/master/OnTheming.md#variables).
|
|
|
|
|
|
### Accessibility
|
|
|
Accessibility must be an important consideration in the choices of design and UI/UX made for PubSweet. As a minimum, all PubSweet components must comply with the Web Content Accessibility Guidelines (WCAG) version 2.0 at level AA. There is no simple checklist or automated test for this but here are some things to keep in mind:
|
|
|
* Ensure that all forms and controls can be operated using the keyboard only. This includes having a recognisable style on the currently-focused element.
|
|
|
* Test components and pages in a screen reader such as ChromeVox, VoiceOver (Mac) or Narrator (Windows) and check that the order in which things are announced makes sense.
|
|
|
* Use the Accessible Rich Internet Applications (ARIA) specification to your advantage. It provides a number of attributes that allow custom UI components to be imparted with the same accessibility features as native components such as <button> or <select>.
|
|
|
* Colors should be chosen with contrast in mind and ratio should pass at least the AA grade for the WCAG 2.0 test.
|
|
|
|
|
|
#### Further reading
|
|
|
* [W3C Accessibility homepage](https://www.w3.org/standards/webdesign/accessibility)
|
|
|
* [WCAG Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)
|
|
|
* [Authoring Tool Accessibility Guidelines (ATAG)](https://www.w3.org/WAI/standards-guidelines/atag/)
|
|
|
* [The A11Y project](https://a11yproject.com)
|
|
|
* [Inclusive Components](https://inclusive-components.design)
|
|
|
|
|
|
## Setting the vertical rhythm
|
|
|
A vertical rhythm is a way to bring consistency in spacing, so each UI com- ponent fits into place and none seems awkward (unless you design it that way). Therefore each component should use the same vertical grid for its in- ternal layout. Setting the line-height of your body text as a gridUnit variable is a good way to keep a coherent relationship between your text and your non-textual elements.
|
|
|
In HTML, the height of an element is always the result of this formula: border‐top + padding‐top + content + padding‐bottom + border‐bottom. Be sure that the result of the calculation is always a multiple of your gridUnit.
|
|
|
A vertical rhythm is a way to bring consistency in spacing, so each UI component fits into place and none seems awkward (unless you design it that way). Therefore each component should use the same vertical grid for its internal layout. Setting the line-height of your body text as a `gridUnit` variable is a good way to keep a coherent relationship between your text and your non-textual elements.
|
|
|
|
|
|
In HTML, the height of an element is always the result of this formula: `border‐top + padding‐top + content + padding‐bottom + border‐bottom`. Be sure that the result of the calculation is always a multiple of your `gridUnit`.
|
|
|
|
|
|
# Using components
|
|
|
Using a component is as simple as installing it, configuring it, and then including the functionality it exports in your own app's code.
|
|
|
Installing
|
|
|
|
|
|
## Installing
|
|
|
Components can be installed using the PubSweet CLI:
|
|
|
pubsweet add login
|
|
|
```pubsweet add login```
|
|
|
This installs the pubsweet‐component‐login package, and adds the component to the app config so PubSweet knows to load it.
|
|
|
Note that the CLI adds the pubsweet‐component‐ prefix automatically if it's not already present.
|
|
|
|
|
|
Note that the CLI adds the `pubsweet‐component‐` prefix automatically if it's not already present.
|
|
|
|
|
|
You can also manually install components using npm or yarn:
|
|
|
npm install --save pubsweet-component-login yarn add pubsweet-component-login
|
|
|
```npm install --save pubsweet-component-login```
|
|
|
```yarn add pubsweet-component-login```
|
|
|
|
|
|
If you do that, you'll need to also add the component manually to the list in config/components.json.
|
|
|
Configuring
|
|
|
|
|
|
## Configuring
|
|
|
There are two aspects to configuring components:
|
|
|
The app can be configured to know which components to load. The component itself can be con�gured.
|
|
|
Specify which components to load
|
|
|
1. The app can be configured to know which components to load. The component itself can be configured.
|
|
|
2. Specify which components to load
|
|
|
|
|
|
PubSweet will load any components in the pubsweet.components array of the configuration object.
|
|
|
You can add components to this array manually, or if you install the com- ponent using the CLI they will be added for you.
|
|
|
In a pubsweet CLI-generated app, the list of loaded components is in its own JSON file at ./config/components.json.
|
|
|
[
|
|
|
]
|
|
|
You need to use the full npm package name in the config array, i.e. pubsweet‐component‐login , not just login.
|
|
|
Configuring a component
|
|
|
You can add components to this array manually, or if you install the component using the CLI they will be added for you.
|
|
|
|
|
|
In a pubsweet CLI-generated app, the list of loaded components is in its own JSON file at `./config/components.json`.
|
|
|
|
|
|
You need to use the full npm package name in the config array, i.e. `pubsweet‐component‐login`, not just `login`.
|
|
|
|
|
|
## Configuring a component
|
|
|
Any component can define its own configurable options, and can access general configuration from the client or server.
|
|
|
|
|
|
Each component's README.md should specify which configuration options can be used, and what they do.
|
|
|
Example snippets from AppBar component.
|
|
|
The app bar appears at the top of every page of the application. Functionality customisation:
|
|
|
//It displays the name of the application (as a link to the home page), the //username of the current user, and a link to sign out.
|
|
|
"pubsweet-component-login", "pubsweet-component-signup", "pubsweet-component-wizard"
|
|
|
|
|
|
### Example snippets from AppBar component.
|
|
|
The app bar appears at the top of every page of the application. It displays the name of the application (as a link to the home page), the //username of the current user, and a link to sign out.
|
|
|
Functionality customization:
|
|
|
```
|
|
|
<AppBar brand="xpub" user={{ username: 'user', admin: true }} />
|
|
|
//When the user is not signed in, only the login link is displayed. <AppBar brand="xpub" />
|
... | ... | @@ -193,9 +208,9 @@ LogoLink: css` |
|
|
visibility: hidden; }
|
|
|
`, }
|
|
|
} }
|
|
|
```
|
|
|
export const cokoTheme
|
|
|
|
|
|
export const cokoTheme
|
|
|
```
|
|
|
# Next steps
|
|
|
* Learn how to use components in your app.
|
|
|
* Take a look at the component library to see what existing components can do
|
... | ... | |