Bugcrowd design system: Contributing

We would 💗 your contribution.

Getting started

Last updated: Apr 17, 2018

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.

Writing

Last updated: Jun 27, 2018

Use:

  • Simple sentences, brevity is a plus
  • Active voice > passive voice
  • Present tense (“Returns a value” vs “Will return a value…”)
  • Gender-neutral pronouns
  • Oxford comma (“foo, bar, baz”)
  • Write in Markdown.

Markdown support

Last updated: Apr 18, 2018

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: Apr 18, 2018

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: Apr 18, 2018
  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
    ---