Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kneath/kss
A methodology for documenting CSS and generating styleguides.
https://github.com/kneath/kss
Last synced: 30 days ago
JSON representation
A methodology for documenting CSS and generating styleguides.
- Host: GitHub
- URL: https://github.com/kneath/kss
- Owner: kneath
- License: mit
- Created: 2011-11-25T18:03:29.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2017-12-06T06:40:17.000Z (almost 7 years ago)
- Last Synced: 2024-05-17T21:46:02.592Z (6 months ago)
- Language: Ruby
- Homepage: warpspire.com/kss
- Size: 741 KB
- Stars: 4,036
- Watchers: 99
- Forks: 277
- Open Issues: 36
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Knyle Style Sheets
Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and styleguide format. It is **not** a preprocessor, CSS framework, naming convention, or specificity guideline.
* **[The Spec (What KSS is)](https://github.com/kneath/kss/blob/master/SPEC.md)**
* **[Example living styleguide](https://github.com/kneath/kss/tree/master/example)**
## KSS in a nutshell
The methodology and ideas behind Knyle Style Sheets are contained in [SPEC.md](https://github.com/kneath/kss/blob/master/SPEC.md). At its core, KSS is a documenting syntax for CSS.
```css
/*
A button suitable for giving stars to someone.
:hover - Subtle hover highlight.
.stars-given - A highlight indicating you've already given a star.
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
.disabled - Dims the button to indicate it cannot be used.
Styleguide 2.1.3.
*/
a.button.star{
...
}
a.button.star.stars-given{
...
}
a.button.star.disabled{
...
}
```
KSS can also support words as Styleguide section names
```scss
// Styleguide Forms.Checkboxes.
// - or -
// Styleguide Forms - Special Checkboxes.
```
## Ruby Library [](https://travis-ci.org/kneath/kss) [](https://codeclimate.com/github/kneath/kss)
This repository includes a ruby library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines. To use the library, include it in your project as a gem from . Then, create a parser and explore your KSS.
```ruby
styleguide = Kss::Parser.new("#{RACK_ROOT}public/stylesheets")
styleguide.section('2.1.1')
# =>
styleguide.section('2.1.1').description
# => "A button suitable for giving stars to someone."
styleguide.section('2.1.1').modifiers.first
# =>
styleguide.section('2.1.1').modifiers.first.name
# => ':hover'
styleguide.section('2.1.1').modifiers.first.class_name
# => 'pseudo-class-hover'
styleguide.section('2.1.1').modifiers.first.description
# => 'Subtle hover highlight'
```
You can also initialize the `Kss::Parser` with a string CSS by using `Kss::Parser.new(string)`
```ruby
buttons =<<-'EOS'
/*
Your standard form button.
:hover - Highlights when hovering.
:disabled - Dims the button when disabled.
Styleguide 1.1
*/
button {
padding: 5px 15px;
line-height: normal;
/* ... */
}
button:disabled {
opacity: 0.5;
}
EOS
styleguide = Kss::Parser.new(buttons)
styleguide.section('1.1')
# =>
styleguide.section('1.1').description
# => "Your standard form button."
# ...
```
The library is also fully TomDoc'd, completing the circle of life.
## Generating styleguides
The documenting syntax and ruby library are intended to generate styleguides automatically. To do this, you'll need to leverage a small javascript library that generates class styles for pseudo-class styles (`:hover`, `:disabled`, etc).
* [kss.coffee](https://github.com/kneath/kss/blob/master/lib/kss.coffee)
* [kss.js](https://github.com/kneath/kss/blob/master/example/public/javascripts/kss.js) (compiled js)
For an example of how to generate a styleguide, check out the [`example`](https://github.com/kneath/kss/tree/master/example) sinatra application.
## Development
To hack on KSS, you'll need to install dependencies with `bundle install`. Run tests with `rake`.
To make your life easier, I suggest `bundle install --binstubs` and adding `bin/` to your `$PATH`. If you don't understand this, just blindly add `bundle exec` in front of everything you'd normally do, like `bundle exec rake`.
I apologize on behalf of the Ruby community for this, it's embarrassing and disappointing that dependency management is still so clumsy.
## Implementations
The KSS specification has also been implemented in [Python](https://github.com/seanbrant/pykss), [Node.js](https://github.com/kss-node/kss-node), [PHP](https://github.com/kss-php/kss-php) and [Java] (https://github.com/revbingo/kss-java)