Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

General spec cleanup #107

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

General spec cleanup #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,16 @@ The methodology and ideas behind Knyle Style Sheets are contained in [SPEC.md](h
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.
.star-given - A highlight indicating you've already given a star.
.star-given:hover - Subtle hover highlight on top of star-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.star-given{
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.star-given is what is used in part of the SPEC and everywhere in the test/ directory. Going to assume .stars-given is a typo.

...
}
a.button.star.disabled{
Expand Down
34 changes: 17 additions & 17 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,50 @@ Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology f

## Purpose

KSS is a set of guidelines to help you produce an HTML styleguide tied to CSS documentation that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine. It is designed with CSS preprocessors (such as SCSS or LESS) in mind, and flexible enough to accommodate a multitude of CSS frameworks (such as YUI, Blueprint or 960).
KSS is a set of guidelines to help you produce an HTML styleguide tied to CSS documentation that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine. It is designed with CSS preprocessors (such as Sass or LESS) in mind, and flexible enough to accommodate a multitude of CSS frameworks (such as Bootstrap or Foundation).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The preprocessor is called "Sass", not "SCSS".

Young-uns don't even know what YUI is. Using popular 2015-era CSS frameworks. We'll have to revisit this in another 5 years, I'm sure. :-)


KSS focuses on *how people work with CSS* — it does not define code structures, naming conventions, or methods for abstraction. It is important to understand that the styleguide format and documentation format are intrinsically tied to one another.

## Style Documentation

Unlike TomDoc, not every CSS rule should be documented. You should document a rule declaration when the rule can accurately describe a visual UI element in the styleguide. Each element should have one documentation block describing that particular UI element's various states.

KSS documentation is hierarchical in nature — any documentation blocks at any point within the styleguide hierarchy apply to the documentation blocks beneath that level. This means that documentation for 2.1 applies to documentation for 2.1.3.
KSS documentation is hierarchical in nature — any documentation block at any point within the styleguide hierarchy applies to the documentation blocks beneath that level. This means that documentation for 2.1 applies to documentation for 2.1.3.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"that level" is singular, but the "that" refers to "blocks" which is plural. Made singular throughout. One of my mom's earlier professions was a grammar teacher. :-p


### Format

The basic format for KSS documentation can be best explained in an example:
The basic format for KSS documentation can be explained best in an example:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto the earlier thing about my mom. Still… it's now me correcting grammar, so I guess I'm going to have to own it.


```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.
.star-given - A highlight indicating you've already given a star.
.star-given:hover - Subtle hover highlight on top of star-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.star-given{
...
}
a.button.star.disabled{
...
}
```

When using a preprocessor that supports the functionality, use `//` to prefix your comment sections (SCSS example):
When using a preprocessor that supports the functionality, use `//` to prefix your comment sections (Sass example):

```scss
// 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.
// .star-given - A highlight indicating you've already given a star.
// .star-given:hover - Subtle hover highlight on top of star-given styling.
// .disabled - Dims the button to indicate it cannot be used.
//
// Styleguide 2.1.3.
Expand All @@ -66,13 +66,13 @@ Each KSS documentation block consists of three parts: a description of what the

### The description section

The description should be plain sentences of what the CSS rule or hierarchy does and looks like. A good description gives guidance toward the application of elements the CSS rules style.
The description should be plain sentences of what the CSS rule or hierarchy does or looks like. A good description gives guidance toward the application of elements the CSS rules style.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Earlier in the spec it says "Each KSS documentation block consists of three parts: a description of what the element does or looks like" (emphasis mine). This later wording should be the same.


CSS rules that depend on specific HTML structures should describe those structures using `<element#id.class:pseudo>` notation. For example:

```scss
// A feed of activity items. Within each <section.feed>, there should be many
// <article>s which are the feed items.
// <article>s which are the feed items.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accidental double space.

```

To describe the status of a set of rules, you should prefix the description with **Experimental** or **Deprecated**.
Expand All @@ -96,8 +96,8 @@ If the UI element you are documenting has multiple states or styles depending on

```scss
// :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.
// .star-given - A highlight indicating you've already given a star.
// .star-given:hover - Subtle hover highlight on top of star-given styling.
// .disabled - Dims the button to indicate it cannot be used.
```

Expand All @@ -111,7 +111,7 @@ If the UI element you are documenting has an example in the styleguide, you shou

References can be integer sections separated by periods. Each period denotes a hierarchy of the styleguide. Styleguide references can point to entire sections, a portion of the section, or a specific example.

References may also be period seperated word keys. Leading words denote hierarchy.
References may also be period seperated word keys. Leading words denote hierarchy.

```scss
// Styleguide Forms.Checkboxes.
Expand All @@ -131,7 +131,7 @@ If there is no example, then you must note that there is no reference.

## Preprocessor Helper Documentation

If you use a CSS preprocessor like SCSS or LESS, you should document all helper functions (sometimes called mixins).
If you use a CSS preprocessor like Sass or LESS, you should document all helper functions (sometimes called mixins).

```scss
// Creates a linear gradient background, from top to bottom.
Expand All @@ -145,7 +145,7 @@ If you use a CSS preprocessor like SCSS or LESS, you should document all helper
}
```

Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.
Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.

### The parameters section

Expand Down Expand Up @@ -192,7 +192,7 @@ The styleguide should be organized by numbered sections. These sections can go a
4.1 Number tables
4.2 Diagram tables

The goal here is to create an organizational structure that is flexible, but rigid enough to be machine processed and referenced inside of documentation.
The goal here is to create an organizational structure that is flexible, but rigid enough to be machine processed and referenced inside of documentation.

### Example

Expand Down