Skip to content

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

License

Notifications You must be signed in to change notification settings

chris-pearce/bricks

Repository files navigation

GitHub license Code of conduct PRs Welcome

🧱 Bricks

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

View Sandbox.

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

Table of Contents

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:

  1. As a development environment.
  2. 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

  1. Clone the repository and cd into the project:

    git clone [email protected]:chris-pearce/bricks.git && cd bricks
  2. Install the dependencies:

    yarn install
  3. Bootstrap the project using Lerna:

    yarn bootstrap
  4. 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:

  1. Clean the package's lib folder.
  2. Bundle the packages using Rollup.
  3. 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:

  1. Runs Prettier over all processed files rewriting any issues.
  2. 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…

  1. Heading
  2. Container
  3. Fieldset
  4. LongFormCopy
  5. Icon
  6. 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.

About

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

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published