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
- How to Add a Component
- Tokens
- Styling
- Sandbox
- Development
- Roadmap
- Browser support
- Contributing
- License
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
│ └── …The following instructions use two placeholders to avoid repeating the same information in every package's README.md file.
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
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 |
- Package names use kebab-case.
- Component/file names use PascalCase.
Run the following command using npm:
npm install @bricks/<package-name> --save-devIf you prefer Yarn, use this command instead:
yarn add @bricks/<package-name> --dev✋ Make sure to install the package's peerDependencies.
- jsDelivr
https://www.jsdelivr.com/package/npm/@bricks/<package-name> - unpkg
https://unpkg.com/@bricks/<package-name>
import { <ComponentName> } from '@bricks/<package-name>';const <ComponentName> = require('@bricks/<package-name>');import '@bricks/<package-name>/lib/<ComponentName>.css';💡 For general information on how Brick's is styled, see the Styling section.
import { HideVisually } from '@bricks/HideVisually';
import '@bricks/hide-visually/lib/HideVisually.css';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
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>" /><!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>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/
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
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 🎒🔌.
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:
<Heading className="heading" /><Heading className={styles.heading} />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.
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.
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.
Will be explained soon…
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).
Bricks uses Lerna to manage its monorepo.
-
Clone the repository and
cdinto the project:git clone [email protected]:chris-pearce/bricks.git && cd bricks
-
Install the dependencies:
yarn install
-
Bootstrap the project using Lerna:
yarn bootstrap
-
Build the project:
yarn build
In the order they are listed in the master package.json file.
Launches the Sandbox.
💡 The script detects all files within the packages folder ending in .stories.js.
Deploys the sandbox to the GitHub Pages site using storybook-deployer.
Bootstraps Lerna so all dependencies get linked for cross-component development.
✋ Will be removed as Bricks is using Yarn Workspaces.
Runs yarn build (see next script) directly after yarn bootstrap.
Builds all packages saving them to their lib folder.
The following tasks are performed in this order:
- Clean the package's
libfolder. - Bundle the packages using Rollup.
- Copy statics files to the package's
libfolder.
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).
Lints all JavaScript files in the project using ESLint. See .eslintignore for the files ESLint ignores.
✋ Runs automatically as part of the precommit hook.
Cleans all of the lib folders within each package.
Will be explained soon…
Some further reading in the meantime:
Will be explained soon…
This roadmap is specifically concerned with upcoming Bricks components.
HeadingContainerFieldsetLongFormCopyIconMedia
DialogMenuButtonToolip
Here's the Browserslist query Bricks uses:
last 4 versions and > 0.5%,
Firefox ESR,
not ie < 11,
not op_mini all,
not deadWhich you can see here.
Coming soon…
The code is available under the MIT license.