Bugcrowd Design System

Search/

Getting started

Last modified:

Welcome to the Bugcrowd’s Design System.

The Bugcrowd Design System (DS) is our shared commons for designing and building Bugcrowd’s user interfaces.

This website documents these commons.

Whether you’re in design, product, or engineering, we hope you find this resource useful.

Wait, what’s a “Design System”?

A design system is a set of standards to manage design at scale by reducing redundancy while creating a shared language and visual consistency across different pages and channels. — Nielsen Norman Group

In other words: a shared single source of truth used to realize Bugcrowd’s products.

Think style guide + pattern library; …like Lego, but for user interfaces.

Bugcrowd’s DS is currently an in-house project. We’d like to open source it at some stage.

While many of our components are bespoke, our documentation includes best practice UX and accessibility guidance you may find useful in solving similar design problems.

Back to top

Where do I start?

Last modified:

You’re probably looking to install and import the DS — if that’s you see the Developer workflow.

If you’re a designer we’ve got you covered too under the Designer workflow.

That said, there’s many ways to “use” the DS 🙂 — check out these curated jumping-off links to core features:

  • Guiding Principles of our DS
  • The Accessibility section, complete with printable posters and info on compliance & testing
  • The Language section is packed with tips for writing better UI copy
  • Color palettes — includes dark theme demo
  • Layouts — pre-made page designs using the Grid system
  • Our Buttons component — always a good start in any DS 💅

Designer workflow

Last modified:

This document provides design guidance, specifications, and tools to streamline the process of getting from Figma to finished products.

To help you start designing, here you can find a list of Figma links:

Developer workflow

Last modified:

Currently the DS is packaged as a monolith and served as 2 NPM packages:

You’ll want both and you’ll want to keep their versions matching at all times.

Yup — for us maintainers this means a breaking change to one component will cause a major version bump across the entirety of the DS. We have a plan to atomically restructure the DS components, co-locating source files and atomically packaging them. The NPM publish workflow is managed via GitHub Actions.

Pre-flight check

As a Bugcrowder, we assume you’ve completed developer onboarding (eg. you’ve installed Node and configured GitHub access tokens, etc.).

We also assume you’ve setup ~/.npmrc with your developer auth_token, eg:

@bugcrowd:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_TOKEN}

Installing the DS

Install the DS using a NPM package manager.

We recommend using npm:

npm install @bugcrowd/bc-elements @bugcrowd/bc-flair

ℹ️ We recommend pinning the DS to a specific version and only manually updating.

⚠️ Warning: When using the DS explicitly in a project, the DS cannot be installed by a dependency again at a different version. If a dependency also installs the DS that version must be identical in version to your project’s version of the DS. See BC-22471. We’re not recommending yarn as we hit issues using it and NPM workspaces.

What do you get?

You’ll find both source code and compiled files in your node_modules/ folder:

  • node_modules/@bugcrowd/bc-flair/dist/scss/index.scss is the SCSS’s entry point
  • node_modules/@bugcrowd/bc-flair/dist/main.css is (all) the compiled CSS
  • node_modules/@bugcrowd/bc-elements/build/ contains the bc-elements.

Do I use the compiled CSS or SCSS source?

Knowing whether you need the SCSS will determine how you ingest the DS’ CSS styles provided by bc-flair.

If you don’t need the DS’ SCSS internals you can simply use the post-install compiled CSS (main.css).

Inversely, if any of the below apply you’ll need the SCSS:

Using the SCSS

Include bc-flair’s SCSS with @use at-rule, eg. your top-level application.scss:

// DS SCSS:
@use '~@bugcrowd/bc-flair/dist/scss/foundations' as *;
@use '~@bugcrowd/bc-flair/dist/scss/forms' as *;

You can optionally use SCSS namespaces, eg:

// DS SCSS:
@use '~@bugcrowd/bc-flair/dist/scss/foundations' as core;
@use '~@bugcrowd/bc-flair/dist/scss/forms' as form;

SCSS internals, like variables and mixins, are stored in shared partials per-folder grouping — so .bc-btn’s SCSS variables live in forms/variables.

Right, let’s use the DS.

The next sections cover static templating and ReactJS setups.

Static templating setup

Using the DS with static templating engines like Ruby’s Haml is easy:

  1. Include the @bugcrowd/bc-flair (S)CSS stylesheet in your project
  2. Add a <link> to the stylesheet in the <head> of your project’s template(s)
  3. Apply the bc-body CSS class to a high-level container (eg. the <body>)
  4. 🎉
  5. Use the DS’ BEM-convention CSS classes to style and build.

✨ Building forms in Haml? Get in touch because we’ve got a config for simple_form that makes them a breeze.

Using React components

For dynamic sites using React adding the DS takes just a few extra steps.

Import @bugcrowd/bc-elements as React components into your project.

Do this by using ES6 import statements:

import { BcAvatar } from '@bugcrowd/bc-elements'

You’re now ready to use DS components in your JSX. 🎉

You can inspect any BcElement to see its required and optional React props.

These props alter component behavior and styles.

To use a component you must pass any required props, eg. BcLabels must receive a htmlFor:

<BcLabel htmlFor='id-input-username'>Username</BcLabel>

Styling and customization

Customizing a DS component is often as easy as:

  • Adding a BEM modifier class
  • Setting a native HTML state (eg. disabled)
  • Setting an ARIA attribute (eg. aria-expanded)

If you’re in React each BcElement supports passing additional props, like CSS classes.

Use this to add helper classes, or your own custom classes, eg:

<BcAvatar
  src={'https://bugcrowd.com/pingu.jpg'}
  alt={'Portrait of Pingu, the cute TV show penguin'}
  className='bc-helper-noprint my-custom-class'
/>

You’ll find info for each components’ props and features in its documentation entry.

Caution: Adding custom props that the DS component sets will override them (and potentially break things).

DS Maintainer workflow

Last modified:

For local maintenance and development see:

Testing releases

As DS maintainers we need to test releases downstream.

We test releases using yalc.

There are npm scripts wrapping yalc both in the DS and in CC.

To help us test releases for you, we may ask to add a yalc script to your project’s package.json.

We prefer manual testing using yalc instead of releasing alphas or release candidates.

In the DS repository

npm run local:test

This will publish the bc-elements and bc-flair packages to the yalc store which is located by default at ~/.yalc.

The script uses the --push flag which updates all other repositories where these packages have been linked.

So after modifying a file in bc-elements or bc-flair you can simply run npm run local:test and that’ll run the build and local:test for each package, and finally updates the yalc store. Neat!

⚠️ Yalc will not install DS dependencies when using yalc downstream (eg. floating-ui). You will need to install them manually as a devDependency, sadly (temporarily, for the duration of your yalc testing).

In CC repository or anywhere else

npm run ds:local

This adds a .yalc folder and yalc.lock file to the target repository and (sym)links bc-elements and bc-flair to the packages in the yalc store.

npm run ds:remote

This removes .yalc folder and yalc.lock from the target repository and triggers a npm install --force to re-instate the bc-elements and bc-flair version in the package-lock.json file.

To check if there are yalc installations in a repository run npx yalc installations show.

DS site feature branch testing

We use Infrastructure Team’s “Garden” to deploy and test feature branches of the DS.

Follow the setup guide in the bc-garden repository.

You’ll need the .github.env file in the DS’ repository and have configured your infrastructure access.

Once you have started the aws-vault session and VPN per Garden’s setup you’ll want to provision the Garden stack for the DS:

garden deploy

(This might take a little time.)

Once done it’ll return the URL for your deployed feature branch.

Run garden get outputs if you forget the URL. 🙂

For more info refer to Garden’s documentation and for support see the #garden-fun Slack channel.

Code and structure

Last modified:

The DS is structured roughly as follows:

Source code and structure

The source code is mostly comprised of:

  • SCSS
  • React and TypeScript that emit JSX components
  • Markup examples for render testing
  • Code to support building the Markdown documentation you’re reading now 🙂 (Astro)

We make intentional use of CSS’ Cascade and name CSS classes using the BEM naming schema to scope and minimize component inter-dependencies.

We have a plan to atomically restructure the DS components, co-locating source files and atomically packaging them.

Component documentation structure

Each component documentation entry follows the same structure for ease of browsing:

  1. Rendered example and React, HTML, and Haml code blocks (tabbed)
  2. JS/React implementation
  3. HTML and markup semantics
  4. Design details
  5. Accessibility and inclusive design considerations
  6. Rationale — why this exists and any important decisions made
  7. See also — any similar components, external links, etc.

Updates and support

Last modified:

The Bugcrowd DS is a living project.

DS releases are semantically versioned — including both design and code artifacts, and their documentation.

⚠️ Warning: When using the DS explicitly in a project, the DS cannot be installed by a dependency again at a different version. If a dependency also installs the DS that version must be identical in version to your project’s version of the DS. See BC-22471.

If you’re a Bugcrowder, come find us on Slack under #designsystem and #design-support.

Breaking changes

Whether in form or function, releases that constitute breaking changes downstream are coordinated by the DS team.