Bugcrowd design system: Contributing

We would 💗 your contribution.

Getting started

Last updated: Dec 6, 2021

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

Last updated: Dec 6, 2021

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

Last updated: Dec 6, 2021

Use color to make code syntax more easy to read.

You can add syntax highlighting to fenced code blocks:

``` ruby
def what?
  42
end
```

yields:

def what?
  42
end

We use rouge for this functionality.

Folder structure

Last updated: Dec 6, 2021
  1. Place Sass partials into their rightful place:
    _assets/stylesheets/design-system/
    
  2. Place a corresponding Haml markup file in the templates/ folder. It must have the same name/slug as your partial, eg:
    _assets/stylesheets
    ├── 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:
    _components
    ├── 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.
    bem_variants:
      - warning
      - error
      - success
    ---