kss-php/kss-php

A PHP implementation of KSS: a methodology for documenting CSS and generating styleguides

Knyle Style Sheets

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., _(*1)

• 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., _(*2)

/*
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., _(*3)

<?php

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

$section = $styleguide->getSection('Buttons - Star Button');
// Returns a \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 \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)., _(*4)

• kss.coffee
• kss.js (compiled js)

For an example of how to generate a styleguide, check out the example php pages., _(*5)

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:, _(*6)

$ 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:, _(*7)

$ 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] (https://github.com/kss-php/KssBundle) as well. The KSS Bundle uses Twig templates to make the styleguide block easier to customize and include in your views., _(*8)