Envisioned CSS

Envisioned CSS provides styles to give online documentation the hierarchy and clarity of minimalist academic textbooks. The goal of Envisioned CSS is to present text, tables, graphics and callouts in harmony.

Envisioned CSS is grateful for Dave Liepmann's Tufte CSS available on GitHub at tufte-css. Tufte is a master of clean documentation and his approach has been adapted by Envisioned CSS to improve typography choices and table formatting for online consumption. This page is in fact an adaptation of the Tufte Handout Example PDF.

If you want to help improve Envisioned CSS, feel free to create an issue or pull request on the GitHub project: envisioned-css.

This approach isn't to make websites more like books, rather to use existing best practices for documentation and adapt them to the web. This is a starting point not a rigid set of rules.

Getting Started

To use Envisioned CSS, copy envisioned.css, tablesaw-bare.css, Roboto-Regular.ttf, RobotoCondensed-Regular.ttf and RobotoMono-Regular.ttf to your project directory and add the following to your HTML document's head block:

      	<link rel="stylesheet" href="css/envisioned.css"/>
        <link rel="stylesheet" href="css/tablesaw-bare.css"/>
        <link rel="stylesheet" href="css/nudge.css"/>
      

You will also need to copy jquery.js,tablesaw-stackonly.js and nudge.min.js (or the folder structure) add the following block prior to the closing </body> tag:

      	<script src="js/jquery.js"></script>
        <script src="js/tablesaw-bare.js"></script>
        <script src="js/nudge.min.js"></script>
      

Use the following CSS rules, and the Envisioned CSS structure described for optimal results. Use your preferred browser development tools for additional clarity.

Fundamentals

Navigation

Online navigation is a basic necessity. Minimal navigation has been added to this project to support navigation between sections and/or separate pages of related documentation. Organize your navigation within a nav element inside your body tag. Inside the nav tags use the following:

      	<nav class="pushy pushy-left"/>
            <ul>
            	<li><a href="#">Item 1</a></li>
                <li><a href="#">Item 2</a></li>
            </ul>
        </nav>
      

The above snippet needs to live within the body tag, but it must reside above the rest of the page content. So the navigation can nudge the content over, put the entirety your article within a div tag:

      	<div id="container"/>
            <article>
            	<section>
                	<p>Section 1 Content</p>
                </section>
                <section>
                	<p>Section 2 Content</p>
                </section>
            </article>
        </div>
      

Sections

Organize your document with an article element inside your body tag. Inside that, use section tags around each logical grouping of text and headings.

Headings

Envisioned CSS uses h1 for the page title, h2 for section headings, and h3 for subsection headings. More specific headings are not supported. Clean documentation should not use more than 3 levels of hierarchy. If this feels restrictive, consider restructuring your content:

[It is] notable that the Feynman lectures (3 volumes) write about all of physics in 1800 pages, using only 2 levels of hierarchical headings: chapters and A-level heads in the text. It also uses the methodology of sentences which then cumulate sequentially into paragraphs, rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn't require an elaborate hierarchy to organize.

In his later booksE.g. Beautiful Evidence, Tufte starts each section with a bit of vertical space, a non-indented paragraph, and sets the first few words of the sentence in small caps. For this we use a span with the class newthought, as demonstrated at the beginning of this paragraph. The vertical space is accomplished separately, through the <section> class. The vertical space seems unnecessary when using this technique to replace h2 elements, as in this paragaph. Whichever approach you choose, be consistent. Do not alternate use of header elements and the newthought technique. Pick one approach and stick to it.

Color

Although print handouts typically have a pure white background, the web is better served by the use of slightly off-white and off-black colors. This approach reduces eye strain and improves readability. The selected hues are #fefefe (background) and #222 (text).

Other types of content, such as links and code, have slightly different visual treatments. Sidenote numbers are bright red to distinguish them from regular text.

Font

In print, Tufte uses the proprietary Monotype BemboSee Tufte's comment in the Tufte book fonts thread. font. However, reading online is a much different experience. The fonts selected are all within the RobotoSee the Roboto styles and variations. Family which improve readability. Roboto is the signature font family and the default font on Android and ChromeOS.

Envisioned CSS includes several Roboto fonts using @font-face. This means you'll have to make the .ttf files available to your readers. By default I've set Roboto Condensed for the body font, however, if you desire more word spacing you can easily which it to Roboto regular.

Code snippets (using the code class) are RobotoMono-RegularSee the Roboto Mono styles and variations. font.

Lists

Tufte points out that while lists have valid uses, they tend to promote ineffective writing habits due to their "lack of syntactic and intellectual discipline". He is particularly critical of hierarchical and bullet-pointed lists. So before reaching for an HTML list element, ask yourself:

• Does this list actually have to be represented using an HTML ul or ol element?
• Would my idea be better expressed as sentences in paragraphs?
• Is my message causally complex enough to warrant a flow diagram instead?

This is but a small subset of a proper overview of the topic of lists in communication. A better way to understand Tufte's thoughts on lists would be to read "The Cognitive Style of PowerPoint: Pitching Out Corrupts Within," a chapter in Tufte's book Beautiful Evidence, excerpted at some length by Tufte himself on his website. The whole piece is information-dense and therefore difficult to summarize. He speaks to web design specifically, but in terms of examples and principles rather than as a set of simple do-this, don't-do-that prescriptions. It is well worth reading in full for that reason alone.

For these reasons, Envisioned CSS encourages caution before reaching for a list element, and by default removes the bullet points from unordered lists.

Sidenotes

One of the most distinctive features of Tufte's style is his extensive use of sidenotes.This is a sidenote. Perhaps you have noticed their use in this document already.

On large viewports, Envisioned CSS uses the margin for sidenotes, margin notes, and small figures. Sidenotes consist of 1) a superscript reference number that goes inline with the text, and 2) a sidenote containing content that repeats the superscripted number to reinforce its connection to the text. To add the former, just put <span class="sidenote-number"></span> where you want the reference to go. Immediately after that goes the span with class sidenote, inserted directly into the middle of the p tag containing the reference text. This will give the sidenote the correct height.

If you don't want footnote-style numberings on your sidenotes, what you want is a margin note. ⊕ This is a margin note. Notice there isn't a number preceding the note. They are almost identical to sidenotes but are kept semantically distinct because they operate differently on small screens. Figures in the margin are created as margin notes, as demonstrated in the next section.

Figures

Tufte emphasizes tight integration of graphics with text. Data, graphs, and figures are kept in context with the text that discusses them. In print, this means they are not relegated to a separate page. On online, that means graphics and their accompanying text are displayed in context to minimize extra clicks and unnecessary scrolling. On small devices this context has been adapted with minimal clicking.

Images and graphics play an integral role in Tufte’s work⊕Figure 1: Visual Comparison of species. To place figures in the margin, just wrap an image (or whatever) in a margin note inside a p tag, as seen in Figure 1 to the right of this paragraph.

If you need a full-width figure, give it the fullwidth class. Make sure that's inside an article, and it will take up (almost) the full width of the screen. Don't wrap the figure in a paragraph tag. To give it a caption, use a figcaption tag inside the figure tag. This approach is demonstrated in Figure 2.

Data plot description

Besides margin and full width figures, you can of course also include figures constrained to the main column. You're going to have to police yourself with the size of any images. Wrap the figure tag in a paragraph tag. Any label or margin note goes in a figcaption tag inside the figure.

Tables

Tables are presented by default with minimal grid lines. Table labels are margin notes with an additional table-label class, placed inside a div tag of class table-wrapper that wraps the table. Note that on smaller viewports (e.g. tablets and phones) tables will collapse into unordered lists. This adaptive functionality, provided by TableSawTablesaw was created by filament group., makes tabular data easier to consume on small devices.

Code

Code samples are monospace using the code class, as I've been using in this document to denote HTML tags like the word 'code' earlier in this sentence. Code blocks use that class in conjunction with the pre tag, which gives us indentation too:

// imperative programming:
for (i = 0; i++; i <= num) {
   all_the_things[i].useEnvisioned();
}