Skip to content
This repository has been archived by the owner on Apr 6, 2020. It is now read-only.

Commit

Permalink
General update to documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@bartkozal
bartkozal committed Sep 18, 2015
1 parent 1daeb61 commit fc9a0d2
Show file tree
Hide file tree
Showing 13 changed files with 176 additions and 247 deletions.
4 changes: 3 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Features included:
* Normalize
* Colors
* Vertical rhythm
* Global box-sizing set to border-box
* Box-sizing for all elements (excluding `<img>`) is set to `border-box`
* Grid system based on fractals with flexbox under the hood
* Responsive support with customizable breakpoints (and approach, you can
choose between mobile-first and desktop-first)
Expand All @@ -41,6 +41,8 @@ these projects:
* [sassy-gridlover](https://github.com/hiulit/Sassy-Gridlover)
* [colors](https://github.com/mrmrs/colors)

* * *

### Development

To edit and compile documentation locally you have to install two Ruby
Expand Down
7 changes: 4 additions & 3 deletions docs/_includes/navigation.ext
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
<li><a href="/">Quick Start</a></li>
<li><a href="/global">Global</a></li>
<li><a href="/layout">Layout</a></li>
<li><a href="/">Home</a></li>
<li><a href="/quick-start">Quick Start</a></li>
<li><a href="/defaults">Defaults</a></li>
<li><a href="/layout">Grid & Layout</a></li>
<li><a href="/responsive">Responsive</a></li>
<li><a href="/type">Type</a></li>
<li><a href="/images">Images</a></li>
Expand Down
34 changes: 10 additions & 24 deletions docs/global.md → docs/defaults.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,8 @@
layout: default
---

[Normalize](https://github.com/necolas/normalize.css) is included.

Box-sizing is changed for all elements (excluding `<img>`) and set to `border-box`.

Vertical scrollbar is always visible.

### Defaults

To see the all available defaults please check the `sass/_defaults.sass`
file. Variables listed below are recommended to set on your part.
I prefer to adjust settings listed below per each project. List of all
variables is available under `sass/_defaults.sass`.

```sass
$color-ui: $color-silver
Expand Down Expand Up @@ -77,32 +69,26 @@ $sticky-footer-height: triple($spacing-unit)
<div class="grid-item 1/6"><div class="color-block color-block-black">$color-black</div></div>
</div>

### Functions
### Size functions

Sizing functions return a quotient/product of the provided value.
Size functions return a quotient/product of the provided value.

```sass
div
padding: quarter(12px)
// padding: 3px
padding: quarter(12px) // padding: 3px
div
padding: third(12px)
// padding: 4px
padding: third(12px) // padding: 4px
div
padding: halve(12px)
// padding: 6px
padding: halve(12px) // padding: 6px
div
padding: double(12px)
// padding: 24px
padding: double(12px) // padding: 24px
div
padding: triple(12px)
// padding: 36px
padding: triple(12px) // padding: 36px
div
padding: quadruple(12px)
// padding: 48px
padding: quadruple(12px) // padding: 48px
```
2 changes: 1 addition & 1 deletion docs/extras.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: default
---

Enabled if `$global-extras` is set to true.
Available if `$global-extras` is set to true.

### Type

Expand Down
37 changes: 19 additions & 18 deletions docs/images.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,27 @@
layout: default
---

By default all images are verically aligned to the middle and their
Images are verically aligned to the middle and their
`box-sizing` is set to `content-box`.

The `+img-replace` mixin allows to replace any element contains text with
image.

```sass
div
@mixin img-replace('path/to/img.svg', 100px, 40px)
// div
// background-repeat: no-repeat
// background-image: url('path/to/img.svg')
// width: 100px
// height: 40px
// text-indent: -9999px
// white-space: nowrap
```

### Image helpers

<div class="example">
<img src="http://placehold.it/1200x200" alt="example" class="img-responsive">
</div>
Expand All @@ -28,20 +46,3 @@ By default all images are verically aligned to the middle and their
```html
<img src="img.png" alt="placeholder" class="img-circle">
```

The `+img-replace` mixin allows to replace any element contains text with
image.

```sass
div
@mixin img-replace('path/to/img.svg', 100px, 40px)
// div
// background-repeat: no-repeat
// background-image: url('path/to/img.svg')
// width: 100px
// height: 40px
// text-indent: -9999px
// white-space: nowrap
```

177 changes: 28 additions & 149 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,161 +2,40 @@
layout: default
---

Hocus-Pocus is a simple and design-free [SASS](http://sass-lang.com)
micro framework, ideal as a CSS starter kit.
Hocus-Pocus is a simple and design-free CSS micro-framework built with
[SASS](http://sass-lang.com).

The main idea behind the Hocus-Pocus was to make a universal and
lightweight CSS starter kit that only includes the most common stuff.
Every default can be modified in a clean way by changing a variable, so
there is no need to overwrite provided classes.

Features included:

* Normalize
* Colors
* Vertical rhythm
* Global box-sizing set to border-box
* Box-sizing for all elements (excluding `<img>`) is set to `border-box`
* Responsive support with customizable breakpoints (and approach, you can
choose between mobile-first and desktop-first)
* Helpers: layout, spacing, size, visibility
* Components: type, list, rule, image, table, form, box, flash, navbar,
sticky footer
* Extras

The main idea behind the Hocus-Pocus is to make the most universal and
lightweight framework as possible. It includes only the common stuff
without the specific design. You don't have to overwrite provided CSS
classes and every default can be modified in a clean way just by adjusting
the appropriate variable.
Sites built with Hocus-Pocus:

* [Shelly Cloud Status](https://status.shellycloud.com)

It could not exist without work of awesome people responsible for these
projects:
* * *

Hocus-Pocus could not exist without work of awesome people responsible for
these projects:

* [inuitcss](https://github.com/inuitcss)
* [primer](https://github.com/primer/primer)
* [normalize.css](https://github.com/necolas/normalize.css)
* [flexboxgrid](https://github.com/kristoferjoseph/flexboxgrid)
* [sassy-gridlover](https://github.com/hiulit/Sassy-Gridlover)
* [colors](https://github.com/mrmrs/colors)

Sites built with Hocus-Pocus:

* [Shelly Cloud Status](https://status.shellycloud.com)

### Quick Start

To install Hocus-Pocus use Bower:

```sh
$ bower install hocus-pocus
```

Or [Rails Assets](https://rails-assets.org) if you have a Ruby app:

```ruby
# Gemfile

source 'https://rails-assets.org' do
gem 'rails-assets-hocus-pocus'
end
```

Then include the main Hocus-Pocus file after your variables, but before
the rest of your stylesheets:

```sass
// Your variables
$font-family-base: "Open Sans", sans-serif
$grid-container: 70rem
// Hocus-Pocus include
@import "bower_components/hocus-pocus/hocus-pocus"
// Your stylesheets
@import "objects/meter"
@import "objects/price-box"
@import "inbox/landing-headings-fix"
```

### Principles

Follow the rules from [Mark Otto's Code Guide](http://codeguide.co/#css)

Use [autoprefixer](https://github.com/postcss/autoprefixer) or [autoprefixer-rails](https://github.com/ai/autoprefixer-rails)

Use the following naming convention:

```html
<!-- Objects -->
<div class="media"></div>
<a class="btn"></a>

<!-- Object with a related sub-object -->
<div class="media">
<img class="media-img"></img>
<div class="media-body"></div>
</div>

<!-- Object with modifier -->
<div class="media media-milli"></div>
<a class="btn btn-primary"></a>

<!-- Object with state -->
<a class="btn is-btn-active"></a>
<a class="btn is-btn-disabled"></a>

<!-- Object which requires wrapper -->
<!-- i.e. "position: relative" and "position: absolute" pair -->
<div class="box has-close-link">
<a class="close-link"></a>
</div>

<!-- JavaScript handler -->
<div class="alert js-alert"></div>
```

Avoid styling generic HTML elements:

```css
/* bad */
p {
...
}

/* good */
.blog-post-body > p {
...
}
```

Avoid nested classes:

```css
/* bad */
.blog-post .meta .author {
...
}

/* better */
.blog-post-meta-author {
...
}

/* good */
.post-author {
...
}
```

Never use the HTML id attribute in stylesheets:

```css
/* bad */
#headline {
...
}

/* good */
.headline {
...
}
```

Basic HTML template:

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>...</title>
</head>

<body>
...
</body>
</html>
```

0 comments on commit fc9a0d2

Please sign in to comment.