README

This is a PHP implementation of Knyle Style Sheets (KSS). 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)
Example living styleguide

KSS in a nutshell

The methodology and ideas behind Knyle Style Sheets are contained in SPEC.md of the origin ruby version of KSS. At its core, KSS is a documenting syntax for CSS.

/*
A button suitable for giving stars to someone.

Markup: <a class="button star $modifierClass">Button</a>

: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.
.stars--disabled    - Dims the button to indicate it cannot be used.

Styleguide Buttons - Star Button
*/
a.button.star {
  ...
}
a.button.star:hover {
  ...
}
a.button.stars--given {
  ...
}
a.button.stars--given:hover {
  ...
}
a.button.stars--disabled {
  ...
}

PHP Library

This repository includes a php library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines. To use the library, include it in your project as a composer dependency (see below). Then, create a parser and explore your KSS.

<?php

require_once('../vendors/autoload.php');
$styleguide = new \Scan\Kss\Parser('public/stylesheets')

$section = $styleguide->getSection('Buttons - Star Button');
// Returns a \Scan\Kss\Section object

echo $section->getTitle();
// Echoes "Star Button"

echo $section->getDescription();
// echoes "A button suitable for giving stars to someone."

echo $section->getMarkup();
// echoes "<a class="button star $modifierClass">Button</a>"

$modifier = current($section->getModifiers());
// Returns a \Scan\Kss\Modifier object

echo $modifier->getName();
// echoes ':hover'

echo $modifier->getClassName();
// echoes 'psuedo-class-hover'

echo $modifier->getDescription();
// echoes 'Subtle hover highlight'

echo $modifier->getExampleHtml();
// echoes <a class="button stars stars-given">Button</a> for the .stars-given modifier

Generating styleguides

The documenting syntax and php 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
kss.js (compiled js)

For an example of how to generate a styleguide, check out the example php pages.

Dependencies

The PHP version of KSS has dependencies managed by Composer. If you did not install kss-php using composer, you must install these dependencies manually before using the library by running the following commands:

$ composer install

If you do not yet have Composer, download it following the instructions on http://getcomposer.org or run the following commands to install it globally on your system:

$ curl -s https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

Symfony2 Bundle

If your project uses symfony2, consider using the KSS Bundle as well. The KSS Bundle uses Twig templates to make the styleguide block easier to customize and include in your views.

scan / kss-php

Maintainers

Details