Bugcrowd design system: Contributing

We would 💗 your contribution.

Getting started

Guidance last updated: Jun 6, 2023

We think of pull requests as a conversation starter.

Please feel free to contact us:

  • Slack:
    • #design-support channel
    • @designers team
  • Github team: bugcrowd/design

We push through changes as pull requests on GitHub and track the project internally.

Writing Sass? Check out Our Sass guidelines for helpful advice and our shared principles.

Markdown support

Guidance last updated: Jun 6, 2023

These docs are written in Markdown, a simple markup language with a plain text formatting syntax.

It’s easy to write and read, plus it converts readily into HTML (and other formats too).

We use kramdown which has some nifty features, not limited to:

  • Smart typography:
    • em dash: ‘---’ becomes (—)
    • apostrophe/single quotes: ‘'oh la-la!'’ becomes (‘oh la-la!’)
    • apostrophe/single quotes: ‘"oh la-la!"’ becomes (“oh la-la!”)
    • ellipsis: ‘...’ becomes (‘…’)
  • Definition lists (<dl>, <dt>, & <dd>).

Check out the kramdown syntax documentation for a full overview.

Syntax highlighting

Guidance last updated: Jun 6, 2023

Use color to make code syntax more easy to read.

You can add syntax highlighting to fenced code blocks:

``` ruby
def what?


def what?

We use rouge for this functionality.

Haml support

Guidance last updated: Jun 6, 2023

There’s a custom Liquid filter available for Haml.

It lives in _plugins/haml_filter.rb.

Folder structure

Guidance last updated: Jun 6, 2023
  1. Place Sass partials into their rightful place:
  2. Place a corresponding Haml markup file in the templates/ folder. It must have the same name/slug as your partial, eg:
    ├── main.scss
    ├── design-system
    │   ├── components
    │   │   ├── _my-feature.scss
    │   │   └── templates
    │   │       ├── my-feature--variant.haml
    │   │       └── my-feature.haml
    │   └── foundations

    If the feature has a variant add a markup file for using the BEM -- variant notation.

  3. Create a new Markdown file within the collection corresponding to the taxonomy, eg ‘my-feature’ is a component, so its home is:
    ├── index.md
    └── my-feature.md
  4. Define any variants in the metadata (YAML frontmatter) of this Markdown file, eg:
    title: Notification
    summary: >
      Use my feature to do X, Y, Z for contexts A and B, but never for C.
      - warning
      - error
      - success