Skip to content

Latest commit

 

History

History

stylesheets

README.md

PML Style Sheets

PML Version  Sass Version  Status

Experimenting with PML CSS files via Sass.

NEWS — The stylesheets sub-project now uses the new new CSS related options introduced in PMLC 3.x, which allow overriding the default stylesheets with custom .css files, which has improved its Rake automation.

WARNING — This sub-project hasn't been updated since PML 3.1.0, the PML sources contain deprecated syntax constructs and won't convert using the latest PMLC, and the :css Rake task is broken due to breaking changes in PMLC command-line options.

At the moment there are no plans to revive this project until PMLC adopts better HTML templates and improves its HTML formatting conventions.

Table of Contents

Directory Contents

WARNING! — The generated CSS files and HTML documents are not tracked by Git, so in order to view the test documents you'll have to build them locally via Rake.

Building

The tests in this folder are controlled via the css Rake task (included in default task).

To build just the samples:

rake css

or, to force-rebuild them:

rake css -B

How Tests Work

The tests system in this directory is designed to allow contributors to add new stylesheets or test documents without having to tweak the main Rakefile.

The Rakefile is driven by rules based on pattern-matching naming conventions, so as long as you abide to the following descriptions you can add new assets to this directory and they will be immediately automated.

Stylesheet Folders

Every folder with a name starting in css__ contains a different set of stylesheets (one or more) to be tested. All *.css files found within a stylesheet folder will be used when building the test HTML documents — i.e. having separate CSS files it's just a matter of convenience.

You are not meant to create any *.css files directly: instead work on the Sass sources (*.scss), and let Rake create each CSS stylesheet automatically from it.

WARNING! — All *.css files within this directory will be automatically deleted (and lost) when the project is clobbered (i.e. rake clobber).

Sass sources can be arbitrarily named, and their filename will determine the name of the final CSS stylesheet since the two will only differ in their file extension:

  • <filename>.scss → <filename>.css

You can add to each stylesheet directory as many Sass modules (_*.scss) as you like, and even organize them into subfolders. Rake will track changes to any Sass modules, along with Sass sources, and whenever a module has changed it will rebuild the entire stylesheet directory.

The /css__default/ folder is a special case, since its Sass sources simply import the default PML stylesheets found in the root folder of the stylesheets project:

Currently, it's just intended for study and comparison with other custom CSS files.

Test Documents

Any *.pml document inside the /src-docs/ folder will be converted to HTML into each and every css__*/ stylesheet folder using the CSS files found within the latter, so that each stylesheet can be tested using the same documents.

NOTE — The PMLC output HTML documents are post-processed by our Rakefile to eliminate the css/ prefix in CSS paths in order to use the original CSS files generated by Sass, instead of their copies which PMLC creates within the css/ subfolder (see Issue #93).

This hackish workaround allows us to keep to CSS stylesheets together with the Sass-generated .css.map files and benefit from full CSS-to-Sass debugging when inspecting the test documents in the browser Dev Tools (tested with Chrome browser) — a feature which we definitely can't do without in this type of project.

Rake will track any changes to the test documents sources, along with their assets (in /_shared/) and update any file tasks as required.

Test documents should be created as a single .pml source file, and any required dependencies should be added to the /_shared/ directory instead, so that Rake can track their changes — assets include reusable PML file snippets, images, JavaScript, etc. Any files within the /_shared/ directory tree (i.e. sub-folders included) will be considered by Rake as requirements (dependencies) of the PML test documents, with the exception of Markdown files (.md) which will be ignored.

Dependencies

To build the assets in this folder you'll also need Dart Sass.

Reference Links

PML

CSS Schools

The various CSS design schools of thought (methodologies).

CSS References

Free CSS Books

Useful eBooks, articles and cheat-sheets that can be downloaded and consulted offline.

CSS Processors

The variousCSS preprocessors (and post-processors).

HTML/CSS boilerplates

  • H5BP — HTML5 Boilerplate.
  • Modernizr — browser-features detection library.
  • Normalize.css — a modern, HTML5-ready alternative to CSS resets.

CSS Topics

Specificity

points category example
highest !important rule !important
1,0,0,0 Inline styles <h1 style="color: pink;">
0,1,0,0 IDs #navbar
0,0,1,0 Classes .test
0,0,1,0 Pseudo-classes :hover
0,0,1,0 Attribute selectors [href]
0,0,0,1 Elements h1
0,0,0,1 Pseudo-elements :before
0,0,0,0 universal selector *

For an explanation of the preceding table, see Chris Coyier's Calculating CSS Specificity Value.

For more articles and tutorials:

Good Design Practices

Vertical Rhythm

Articles:

Online Tools:

Web Page Layout

Flexbox