mirror of
https://github.com/danog/sass-site.git
synced 2024-12-11 17:09:52 +01:00
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
|
---
|
||
|
|
title: Code Style Guide
|
||
|
|
introduction: >
|
||
|
|
If you would like to contribute to this website's code, please adhere to the
|
||
|
|
following code style guidelines.
|
||
|
|
---
|
||
|
|
|
||
|
|
- Please try to keep lines at a maximum of 80 characters.
|
||
|
|
- Favor clarity over brevity in naming anything.
|
||
|
|
- Pages end with `.html.haml`, `.html.erb`, `.html.md`, etc.
|
||
|
|
- Partials and layouts end with `.haml`, `.md`, `.erb`, etc.
|
||
|
|
|
||
|
|
## Markup
|
||
|
|
|
||
|
|
For the most part, we use [Haml][] and [Markdown][] for writing markup. If you
|
||
|
|
need to use regular HTML anywhere, write HTML5, but favor a strict XHTML style:
|
||
|
|
|
||
|
|
- Use well-formed markup; elements are nested properly and do not overlap.
|
||
|
|
- Write elements and attributes in lowercase.
|
||
|
|
- Quote all attributes.
|
||
|
|
- Self-close empty elements with a space before the trailing slash:
|
||
|
|
(`<hr />`)
|
||
|
|
|
||
|
|
## Style
|
||
|
|
|
||
|
|
This website uses Sass in the SCSS syntax. Make sure you're using the classes
|
||
|
|
that we have to offer before rewriting something, unless you can justify
|
||
|
|
otherwise.
|
||
|
|
|
||
|
|
- Use the style [Brad Frost writes about][bf] for clarity:
|
||
|
|
- Note that older classes do not use this style yet, but we will refactor over
|
||
|
|
time.
|
||
|
|
- Use a `sl-` global namespace.
|
||
|
|
- Use the class prefixes [Harry Roberts][hr] advocates, though we are using a
|
||
|
|
much simpler set:
|
||
|
|
- `c-` is for **components**. Example: `sl-c-card`.
|
||
|
|
- `l-` is for **layouts**. Example: `sl-l-grid`.
|
||
|
|
- `is-` and `has-` for states. Example: `sl-is-active`.
|
||
|
|
- `js-` is for classes specifically created for JavaScript targeting.
|
||
|
|
Exampe: `sl-js-toggle-navigation`
|
||
|
|
- Use the [BEM][] syntax.
|
||
|
|
- **Block** -- the overall component object. Example: `sl-c-card`.
|
||
|
|
- **Element** -- any child of the block. Example: `sl-c-card__header`.
|
||
|
|
- **Modifier** -- any variation. This can be put on a block. Example:
|
||
|
|
`sl-c-card--primary`. It can also be put on an element Example:
|
||
|
|
`sl-c-card__header--large`.
|
||
|
|
- Keep classes as flat as possible, and avoid nesting too deep.
|
||
|
|
- Avoid using element selectors __unless__ you're using a wrapper utility to
|
||
|
|
target everything inside (such as a class around a block of markdown or other
|
||
|
|
longform text to style all its elements properly). This is specifically for
|
||
|
|
when it doesn't make sense to use classes. Be mindful when do this. We can
|
||
|
|
give you feedback in a code review for instances like this.
|
||
|
|
- For naming of variables, mixins, placeholder selectors, or classes, use the
|
||
|
|
general-to-specific approach. See [this article][gts] for more details.
|
||
|
|
- Write comma-delimited selectors on separate lines.
|
||
|
|
|
||
|
|
[haml]: http://haml.info/
|
||
|
|
[markdown]: http://daringfireball.net/projects/markdown/
|
||
|
|
[bf]: http://bradfrost.com/blog/post/css-architecture-for-design-systems/
|
||
|
|
[hr]: https://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/
|
||
|
|
[bem]: http://getbem.com/introduction/
|
||
|
|
[gts]: http://webdesign.tutsplus.com/tutorials/htmlcss-tutorials/quick-tip-name-your-sass-variables-modularly/
|