🧱 Bricks

A bunch of accessible (#a11y) React presentational components to help build your UI (brick by brick).

✋ Bricks is still in development and therefore isn't quite ready for consumption.

Installing a Component

Bricks is a monorepo meaning every component is an interdependent npm package located in the /packages folder. It makes sense to use npm's scoped packages so that we can group all of Brick's components under one scope: @bricks.

├── packages
│   ├── hide-visually #@bricks/hide-visually
│   ├── spacing       #@bricks/spacing
│   └── …

Placeholders

The following instructions use two placeholders to avoid repeating the same information in every package's README.md file.

`<package-name>`

This placeholder represents a component's package name which you can get from the name field of the package's package.json file. For example:

"name": "@bricks/hide-visually"

—source

`<ComponentName>`

This placeholder represents the component/file name, for example:

Component name	JavaScript file name	CSS file name
`HideVisually`	`Hidevisually.js`	`HideVisually.css`
`Spacing`	`Spacing.js`	`Spacing.css`

Case Formats

Package names use kebab-case.
Component/file names use PascalCase.

npm

Run the following command using npm:

npm install @bricks/<package-name> --save-dev

If you prefer Yarn, use this command instead:

yarn add @bricks/<package-name> --dev

✋ Make sure to install the package's peerDependencies.

Download/CDN

jsDelivr https://www.jsdelivr.com/package/npm/@bricks/<package-name>
unpkg https://unpkg.com/@bricks/<package-name>

How to Add a Component

With a Bundler (webpack, Parcel, etc.)

ES Modules

import { <ComponentName> } from '@bricks/<package-name>';

CommonJS Modules

const <ComponentName> = require('@bricks/<package-name>');

Styles

import '@bricks/<package-name>/lib/<ComponentName>.css';

💡 For general information on how Brick's is styled, see the Styling section.

Example

import { HideVisually } from '@bricks/HideVisually';
import '@bricks/hide-visually/lib/HideVisually.css';

Without a bundler

JavaScript

Add a <script> element to your document:

<script src="https://unpkg.com/@bricks/<package-name>.js"></script>

You can find the library on:

window.Bricks<ComponentName>

For example:

window.BricksHideVisually

Styles

Add a <link> element to your document making sure it's placed before any of your project's styles:

<link
  rel="stylesheet"
  href="https://unpkg.com/@bricks/<package-name>/lib/<ComponentName>.css"
/>
<link rel="stylesheet" href="<your-projects-styles>" />

Example

<!DOCTYPE html>
<html>
  <head>
    …
    <link
      rel="stylesheet"
      href="https://unpkg.com/@bricks/hide-visually/lib/HideVisually.css"
    />
    <link rel="stylesheet" href="/styles/styles.css" />
  </head>
  <body>
    …
    <!-- peerDependencies (for <version-number> see package.json) -->
    <script src="https://unpkg.com/react/<version-number>"></script>
    <script src="https://unpkg.com/react-dom/<version-number>"></script>
    <!-- Bricks component -->
    <script src="https://unpkg.com/@bricks/hide-visually.js"></script>
  </body>
</html>

Tokens

Will be explained soon…

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.—https://www.lightningdesignsystem.com/design-tokens/

Styling

How Components are Styled Internally

Bricks uses vanilla CSS to style its components and only includes functional styles. That is, styles that are necassary for the component to work rather than not how it works and looks. How a component looks is left up to you 🙂.

Class selectors are always used and are structured like this:

[scope-][component-name][element]

[element] will be removed if there's only one element.

So, for the HideVisually component, which is only one element, the class name will be:

bricks-hide-visually

Global Styles

Bricks doesn't use any global styles, all styles are scoped to a component by the parent element's class selector.

If you're looking for a lightweight and somewhat opinionated CSS foundation that is best suited to applications then we recommend backpack.css 🎒🔌.

How Components are Styled Externally

It's up to you how you want to extend a component's styles. For example, you can use the className prop or if CSS-in-JS is your thing you can extend that way. For example:

`className` prop

Vanilla

<Heading className="heading" />

CSS Modules

<Heading className={styles.heading} />

`styled-components`

const HeadingStyled = styled(Heading)`
  // Your project styles
`;

✋ However, when you extend a component's styles you should be referencing Bricks' functional styles so you know what's already been provided and therefore what not to override.

Additionally, never use Brick's CSS classes in your stylesheet, always provide your own.

Closed for Extension

Certain components cannot be extended as they are purely functional, for example, the HideVisually and Spacing components. These components will be labelled as such and will not allow className and/or style props to be applied.

Placement

You need to always make sure that Brick's component styles are imported before your own project styles to ensure the rules of the cascade and specificity apply.

So, when looking at your compiled stylesheet you should always see Bricks CSS classes coming first, for example:

/* Your stylesheet */

.bricks-heading {
  /* Bricks library styles */
}

.heading {
  /* Your project styles */
}

.bricks-fieldset-root {
  /* Bricks library styles */
}

.fieldset {
  /* Your project styles */
}

Or:

/* Your stylesheet */

.bricks-heading {
  /* Bricks library styles */
}

.bricks-fieldset-root {
  /* Bricks library styles */
}

.heading {
  /* Your project styles */
}

.fieldset {
  /* Your project styles */
}

It really depends on where you import Brick's library styles and your own project styles within your project. As long as the library styles are imported first then everything will be fine.

Child Elements

Will be explained soon…

Sandbox

Bricks uses Storybook for its sandbox, view here.

✋ The sandbox is not Brick's official documentation, that is handled via the README.md's.

The sandbox is used for two purposes:

As a development environment.
A place where people can go to see Brick's components being used in certain scenerios and demoing their API's (props).

Development

Bricks uses Lerna to manage its monorepo.

Installation

Clone the repository and cd into the project:

git clone git@github.com:chris-pearce/bricks.git && cd bricks

Install the dependencies:
```
yarn install
```
Bootstrap the project using Lerna:
```
yarn bootstrap
```
Build the project:
```
yarn build
```

Scripts

In the order they are listed in the master package.json file.

`yarn dev`

Launches the Sandbox.

💡 The script detects all files within the packages folder ending in .stories.js.

`yarn deploy:sandbox`

Deploys the sandbox to the GitHub Pages site using storybook-deployer.

`yarn bootstrap`

Bootstraps Lerna so all dependencies get linked for cross-component development.

✋ Will be removed as Bricks is using Yarn Workspaces.

`yarn postbootstrap`

Runs yarn build (see next script) directly after yarn bootstrap.

`yarn build`

Builds all packages saving them to their lib folder.

The following tasks are performed in this order:

Clean the package's lib folder.
Bundle the packages using Rollup.
Copy statics files to the package's lib folder.

`yarn precommit`

Perform a series of tasks using lint-staged which are automatically triggered when performing a git commit.

The following tasks are performed in this order:

Runs Prettier over all processed files rewriting any issues.
Lints all JavaScript files using ESLint rewriting any issues (see yarn lint).

`yarn lint`

Lints all JavaScript files in the project using ESLint. See .eslintignore for the files ESLint ignores.

✋ Runs automatically as part of the precommit hook.

`yarn clean:lib`

Cleans all of the lib folders within each package.

Yarn Workspaces

Will be explained soon…

Some further reading in the meantime:

Visual Studio Code

Will be explained soon…

Roadmap

This roadmap is specifically concerned with upcoming Bricks components.

Coming Soon…

Heading
Container
Fieldset
LongFormCopy
Icon
Media

Later

Dialog
MenuButton
Toolip

Browser support

Here's the Browserslist query Bricks uses:

last 4 versions and > 0.5%,
Firefox ESR,
not ie < 11,
not op_mini all,
not dead

Which you can see here.

Contributing

Coming soon…

License

The code is available under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.vscode		.vscode
packages		packages
sandbox		sandbox
scripts		scripts
.browserslistrc		.browserslistrc
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
lerna.json		lerna.json
package.json		package.json
rollup.config.js		rollup.config.js
yarn.lock		yarn.lock

License

chris-pearce/bricks

Folders and files

Latest commit

History

Repository files navigation

🧱 Bricks

Table of Contents

Installing a Component

Placeholders

<package-name>

<ComponentName>

Case Formats

npm

Download/CDN

How to Add a Component

With a Bundler (webpack, Parcel, etc.)

ES Modules

CommonJS Modules

Styles

Example

Without a bundler

JavaScript

Styles

Example

Tokens

Styling

How Components are Styled Internally

Global Styles

How Components are Styled Externally

className prop

Vanilla

CSS Modules

styled-components

Closed for Extension

Placement

Child Elements

Sandbox

Development

Installation

Scripts

yarn dev

yarn deploy:sandbox

yarn bootstrap

yarn postbootstrap

yarn build

yarn precommit

yarn lint

yarn clean:lib

Yarn Workspaces

Visual Studio Code

Roadmap

Coming Soon…

Later

Browser support

Contributing

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Languages

`<package-name>`

`<ComponentName>`

`className` prop

`styled-components`

`yarn dev`

`yarn deploy:sandbox`

`yarn bootstrap`

`yarn postbootstrap`

`yarn build`

`yarn precommit`

`yarn lint`

`yarn clean:lib`