title: Tufte CSS
url: http://www.daveliepmann.com/tufte-css/
hash_url: a2b3449824cfc20ff89550bd696e1669

<article>
<section>
  <p>Tufte CSS provides tools to style web articles using the ideas demonstrated by Edward Tufte’s books and handouts. Tufte’s style is known for its simplicity, extensive use of sidenotes, tight integration of graphics with text, and carefully chosen typography.</p>
  <p>The idea is essentially cribbed wholesale from <a href="https://tufte-latex.github.io/tufte-latex/">Tufte-<span class="latex">L<sup>a</sup>T<sub>e</sub>X</span></a> and <a href="http://rmarkdown.rstudio.com/tufte_handout_format.html">R Markdown’s Tufte Handout format</a><label for="sn-tufte-handout" class="margin-toggle sidenote-number"/><input type="checkbox" id="sn-tufte-handout" class="margin-toggle"/>.
    <span class="sidenote">
      This page was in fact originally an adaptation of the <a href="http://rmarkdown.rstudio.com/examples/tufte-handout.pdf">Tufte Handout Example</a> PDF.
    </span>
    I give hearty thanks to all the people who have contributed to those projects.</p>
  <p>If you see anything that Tufte CSS could improve, we welcome your contribution in the form of an issue or pull request on the GitHub project: <a href="https://github.com/daveliepmann/tufte-css">tufte-css</a>. Please note the <a href="https://github.com/daveliepmann/tufte-css#contributing">contribution guidelines</a>.</p>
  <p>Finally, a reminder about the goal of this project. The web is not print. Webpages are not books. Therefore, the goal of Tufte CSS is not to say “websites should look like this interpretation of Tufte’s books” but rather “here are some techniques Tufte developed that we’ve found useful in print; maybe you can find a way to make them useful on the web”. Tufte CSS is merely a sketch of one way to implement this particular set of ideas. It should be a starting point, not a design goal, because any project should present their information as best suits their particular circumstances.</p>
</section>

<section>
  <h2>Getting Started</h2>
  <p>To use Tufte CSS, copy <span class="code">tufte.css</span>, <span class="code">ETBembo-RomanLF.ttf</span>, and <span class="code">ETBembo-DisplayItalic.ttf</span> to your project directory and add the following to your HTML document’s <span class="code">head</span> block:</p>

  <pre class="code">&lt;link rel="stylesheet"
  href="tufte.css"/&gt;</pre>

  <p>Now you just have to use the provided CSS rules, and the Tufte CSS conventions described in this document. For best results, View Source and Inspect Element frequently.</p>
</section>

<section>
  <h2>Fundamentals</h2>
  <h3>Sections and Headings</h3>
  <p>Organize your document with an <span class="code">article</span> element inside your <span class="code">body</span> tag. Inside that, use <span class="code">section</span> tags around each logical grouping of text and headings.</p>
  <p>Tufte CSS uses <span class="code">h1</span> for the document title, <span class="code">p</span> with class <span class="code">subtitle</span> for the document subtitle, <span class="code">h2</span> for section headings, and <span class="code">h3</span> for low-level headings. More specific headings are not supported. If you feel the urge to reach for a heading of level 4 or greater, consider redesigning your document:</p>
  <blockquote cite="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0000hB">
    <p>[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 <em>sentences</em> which then cumulate sequentially into <em>paragraphs</em>, rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn’t require an elaborate hierarchy to organize.</p>
    <footer><a href="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0000hB">Edward Tufte, forum post, ‘Book design: advice and examples’ thread</a></footer>
  </blockquote>
  <p>As a bonus, this excerpt regarding the use of headings provides an example of block quotes. They are just lightly styled, semantically correct HTML using <span class="code">blockquote</span> and <span class="code">footer</span> elements.</p>
  <p><span class="newthought">In his later books<label for="sn-in-his-later-books" class="margin-toggle sidenote-number"/></span><input type="checkbox" id="sn-in-his-later-books" class="margin-toggle"/><span class="sidenote">E.g. <a href="http://www.edwardtufte.com/tufte/books_be">Beautiful Evidence</a></span>, Tufte starts each section with a bit of vertical space, a non-indented paragraph, and the first few words of the sentence set in small caps. For this we use a span with the class <span class="code">newthought</span>, as demonstrated at the beginning of this paragraph. The vertical space is accomplished separately, through the <span class="code">&lt;section&gt;</span> class. I feel the vertical space is unnecessary when using this technique to replace <span class="code">h2</span> elements, as in this paragaph. Be consistent: though I do so in this paragraph for the purpose of demonstration, do not alternate use of header elements and the <span class="code">newthought</span> technique. Pick one approach and stick to it.</p>

  <h3>Text</h3>
  <p>Although paper handouts obviously have a pure white background, the web is better served by the use of slightly off-white and off-black colors. I picked <span class="code">#fffff8</span> and <span class="code">#111111</span> because they are nearly indistinguishable from their ‘pure’ cousins, but dial down the harsh contrast. Sidenote numbers are bright red to distinguish them from inline text.</p>
  <p>In print, Tufte uses the proprietary Monotype Bembo<label for="sn-proprietary-monotype-bembo" class="margin-toggle sidenote-number"/><input type="checkbox" id="sn-proprietary-monotype-bembo" class="margin-toggle"/><span class="sidenote">See Tufte’s comment in the <a href="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0000Vt">Tufte book fonts</a> thread.</span> font. A similar effect is achieved in digital formats with ETBembo, which Tufte CSS supplies with a <span class="code">@font-face</span> reference to a .ttf file. <a href="https://github.com/daveliepmann/tufte-css/commit/0a810a7d5f4707941c6f9fe99a53ec41f50a5c00">Thanks to Linjie Ding</a>, italicized text uses the ETBembo Italic font instead of mechanically skewing the characters. In case ETBembo somehow doesn’t work, Tufte CSS degrades gracefully to other serif fonts like Palatino and Georgia.</p>
  <p class="sans">If you prefer sans-serifs, use the <span class="code">sans</span> class. It relies on Gill Sans, Tufte’s sans-serif font of choice. Notice how weird and jarring this paragraph is, since it switches from serif to sans-serif? Don’t follow this paragraph’s bad example! Pick either serif or sans-serif for paragraphs throughout your document.</p>
  <p>Links in Tufte CSS match the body text in color and do not change on mouseover or when clicked. They are underlined, since this is the most widely recognized indicator of clickable text. <label for="mn-blue-links" class="margin-toggle">⊕</label><input type="checkbox" id="mn-blue-links" class="margin-toggle"/><span class="marginnote">Blue text, while also a widely recognizable clickable-text indicator, is crass and distracting. Luckily, it is also rendered unnecessary by the use of underlining.</span> However, because most browsers’ default underlining is so thick and distracting, the underline effect is achieved using a padded border instead of standard <span class="code">text-decoration</span>. As always, these design choices are merely one approach that Tufte CSS provides by default. Other approaches, such as changing color on click or mouseover, or using highlighting or color instead of underlining to denote links, could also be made to work. The goal is to make sentences readable without interference from links, as well as to make links immediately identifiable even by casual web users.</p>

  <h3>Lists</h3>
  <p>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:</p>
  <ul>
    <li>Does this list actually have to be represented using an HTML <span class="code">ul</span> or <span class="code">ol</span> element?</li>
    <li>Would my idea be better expressed as sentences in paragraphs?</li>
    <li>Is my message causally complex enough to warrant a flow diagram instead?</li>
  </ul>
  <p>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 <em>Beautiful Evidence</em>, excerpted at some length by Tufte himself <a href="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0002QF">on his website</a>. 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.</p>
  <p>For these reasons, Tufte CSS encourages caution before reaching for a list element, and by default removes the bullet points from unordered lists.</p>
</section>

<section>
  <h2>Sidenotes</h2>
  <p>One of the most distinctive features of Tufte’s style is his extensive use of sidenotes.<label for="sn-extensive-use-of-sidenotes" class="margin-toggle sidenote-number"/><input type="checkbox" id="sn-extensive-use-of-sidenotes" class="margin-toggle"/><span class="sidenote">This is a sidenote.</span> Sidenotes are like footnotes, except they don’t force the reader to jump their eye to the bottom of the page, but instead display off to the side in the margin. Perhaps you have noticed their use in this document already. You are very astute.</p>
  <p>Sidenotes are a great example of the web not being like print. On sufficiently large viewports, Tufte CSS uses the margin for sidenotes, margin notes, and small figures. On smaller viewports, elements that would go in the margin are hidden until the user toggles them into view. The goal is to present related but not necessary information such as asides or citations <em>as close as possible</em> to the text that references them. At the same time, this secondary information should stay out of the way of the eye, not interfering with the progression of ideas in the main text.</p>
    <p>Sidenotes consist of two elements: a superscript reference number that goes inline with the text, and a sidenote with content. To add the former, just put a label and dummy checkbox into the text where you want the reference to go, like so:</p>
    <p>
      </p><pre class="code">
&lt;label for="sn-demo" class="margin-toggle sidenote-number"&gt;&lt;/label&gt;
&lt;input type="checkbox" id="sn-demo" class="margin-toggle"/&gt;</pre>

  <p>You must manually assign a reference <span class="code">id</span> to each side or margin note, replacing “sn-demo” in the <span class="code">for</span> and the <span class="code">id</span> attribute values with an appropriate descriptor. I find it useful to use prefixes like <span class="code">sn-</span> for sidenotes and <span class="code">mn-</span> for margin notes.</p>
  <p>Immediately adjacent to that sidenote reference in the main text goes the sidenote content itself, in a <span class="code">span</span> with class <span class="code">sidenote</span>. This tag is also inserted directly in the middle of the body text, but is either pushed into the margin or hidden by default. Make sure to position your sidenotes correctly by keeping the sidenote-number label close to the sidenote itself.</p>
  <p>If you want a sidenote without footnote-style numberings, then you want a margin note.
    <label for="mn-demo" class="margin-toggle">⊕</label>
    <input type="checkbox" id="mn-demo" class="margin-toggle"/>
    <span class="marginnote">
      This is a margin note. Notice there isn’t a number preceding the note.
    </span> On large screens, a margin note is just a sidenote that omits the reference number. This lessens the distracting effect taking away from the flow of the main text, but can increase the cognitive load of matching a margin note to its referent text. However, on small screens, a margin note is like a sidenote except its viewability-toggle is a symbol rather than a reference number. This document currently uses the symbol ⊕ (<span class="code">&amp;#8853;</span>), but it’s up to you.</p>
  <p>Margin notes are created just like sidenotes, but with the <span class="code">marginnote</span> class for the content and the <span class="code">margin-toggle</span> class for the label and dummy checkbox. For instance, here is the code for the margin note used in the previous paragraph:</p>
  <p>
    </p><pre class="code">
&lt;label for="mn-demo" class="margin-toggle"&gt;&amp;#8853;&lt;/label&gt;
&lt;input type="checkbox" id="mn-demo" class="margin-toggle"/&gt;
&lt;span class="marginnote"&gt;
This is a margin note. Notice there isn’t a number preceding the note.
&lt;/span&gt;</pre>

  <p>Figures in the margin are created as margin notes, as demonstrated in the next section.</p>
</section>

<section>
  <h2>Figures</h2>
  <p>Tufte emphasizes tight integration of graphics with text. Data, graphs, and figures are kept with the text that discusses them. In print, this means they are not relegated to a separate page. On the web, that means readability of graphics and their accompanying text without extra clicks, tab-switching, or scrolling.</p>
  <p>Figures should try to use the <span class="code">figure</span> element, which by default are constrained to the main column. Don’t wrap figures in a paragraph tag. Any label or margin note goes in a <span class="code">figcaption</span> tag inside the figure. For example, most of the time I should introduce a figure directly into the main flow of discussion, like so:</p>
  <figure>
    <img src="http://www.daveliepmann.com/tufte-css/main-column-figure.png"/>
    <figcaption>Figure 1: A figure the width of the main column</figcaption>
  </figure>
  <p>Tight integration of graphics is central to Tufte’s work. <label for="mn-figure-1" class="margin-toggle">⊕</label><input type="checkbox" id="mn-figure-1" class="margin-toggle"/><span class="marginnote"><img src="http://www.daveliepmann.com/tufte-css/margin-figure.png"/>Figure 2: Sepal length vs. petal length, colored by species</span> To place figures in the margin, just wrap an image (or whatever) in a margin note inside a <span class="code">p</span> tag, as seen in Figure 2 to the right of this paragraph.</p>
  <p>If you need a full-width figure, give it the <span class="code">fullwidth</span> class. Make sure that’s inside an <span class="code">article</span>, and it will take up (almost) the full width of the screen. To give it a caption, use a <span class="code">figcaption</span> tag inside the <span class="code">figure</span> tag. This approach is demonstrated in Figure 3, which I suppose plots the data in the following code:</p>
  <p class="code">qplot(wt, mpg, data = mtcars, colour = factor(cyl))</p>
  <figure class="fullwidth">
    <img src="http://www.daveliepmann.com/tufte-css/fullwidth-figure.png"/>
    <figcaption>Figure 3: Full width figure</figcaption>
  </figure>
</section>

<section>
  <h2>Tables</h2>
  <p>Tabular data are presented by default with right-aligned numbers, left-aligned text, and minimal grid lines. Table labels are margin notes with an additional <span class="code">table-label</span> class, placed inside a <span class="code">div</span> tag of class <span class="code">table-wrapper</span> that wraps the <span class="code">table</span>.</p>
    <div class="table-wrapper">
      <span class="table-caption">
        Table 1: first row of metcars.
        </span>
      <table>
        <thead><th/><th>mpg</th><th>cyl</th><th>disp</th><th>hp</th><th>drat</th><th>wt</th></thead>
        <tbody>
          <tr><td class="text">Mazda RX4</td><td>21.0</td><td>6</td><td>160</td><td>110</td><td>3.90</td><td>2.62</td></tr>
          <tr><td class="text">Mazda RX4 Wag</td><td>21.0</td><td>6</td><td>160</td><td>110</td><td>3.90</td><td>2.88</td></tr>
          <tr><td class="text">Datsun 710</td><td>22.8</td><td>4</td><td>108</td><td>93</td><td>3.85</td><td>2.32</td></tr>
          <tr><td class="text">Hornet 4 Drive</td><td>21.4</td><td>6</td><td>258</td><td>110</td><td>3.08</td><td>3.21</td></tr>
          <tr><td class="text">Hornet Sportabout</td><td>18.7</td><td>8</td><td>360</td><td>175</td><td>3.15</td><td>3.44</td></tr>
          <tr><td class="text">Valiant</td><td>18.1</td><td>6</td><td>225</td><td>105</td><td>2.76</td><td>3.46</td></tr>
        </tbody>
      </table>
    </div>

    <p>Please understand: this is not the One True Table. Such a style does not exist. One must craft each data table with custom care to the narrative one is telling with that specific data. So take this not as “the table style to use”, but rather as “a table style to start from”. From here, use principles to guide you: avoid chartjunk, optimize the data-ink ratio (“within reason”, as Tufte says), and “mobilize every graphical element, perhaps several times over, to show the data.”<label for="sn-show-the-data" class="margin-toggle sidenote-number"/><input type="checkbox" id="sn-show-the-data" class="margin-toggle"/>.
      <span class="sidenote">
        Page 139, The Visual Display of Quantitative Information, Edward Tufte 2001.
      </span> Know when to reach for more complex data presentation tools, like a custom graphic or a JavaScript charting library.</p>

    <p>For instance, academic publications written in <span class="latex">L<sup>a</sup>T<sub>e</sub>X</span> often rely on the <span class="code">booktabs</span> package to produce clean, clear tables. Similar results can be achieved in Tufte CSS with the <span class="code">booktabs</span> class, as demonstrated in Table 2:</p>
    <div class="table-wrapper">
      <span class="table-caption">
        Table 2: An example of a <span class="code">booktabs</span>-styled table.
      </span>
      <table class="booktabs">
        <thead>
          <tr><th colspan="2" class="cmid">Items</th><th class="nocmid"/></tr>
          <tr><th>Animal</th><th>Description</th><th>Price ($)</th></tr>
        </thead>
        <tbody>
          <tr><td>Gnat</td>     <td>per gram</td><td class="r">13.65</td></tr>
          <tr><td/>         <td>each</td>    <td class="r">0.01</td></tr>
          <tr><td>Gnu</td>      <td>stuffed</td> <td class="r">92.50</td></tr>
          <tr><td>Emu</td>      <td>stuffed</td> <td class="r">33.33</td></tr>
          <tr><td>Armadillo</td><td>frozen</td>  <td class="r">8.99</td></tr>
        </tbody>
      </table>
    </div>
    <p>Notice how this table is centered, compact, and surrounded by heavy rules on the top and bottom. A lighter-weight rule is used to separate the table head from its body. If you need a column heading to span two or more other column headings, an even lighter-weight rule may be used. Vertical rules are unnecessary. Additionally, the spacing around the rules has been increased to avoid a cramped appearance.</p>
</section>

<section>
  <h2>Code</h2>
  <p>Technical jargon, programming language terms, and code samples are denoted with the <span class="code">code</span> class, as I’ve been using in this document to denote HTML. Code needs to be monospace for formatting purposes and to aid in code analysis, but it must maintain its readability. To those ends, Tufte CSS apes GitHub’s font selection, which degrades gracefully along the monospace spectrum from the elegant but rare Consolas all the way to good old reliable Courier.</p>
  <p>Extended code examples should use a <span class="code">pre</span> tag with class <span class="code">code</span>. This adds control over indentation and overflow as well:</p>
  <pre class="code">
;; Some code examples in Clojure. This is a comment.

;; applying a function to every item in the collection
(map tufte-css blog-posts)
;;;; if unfamiliar, see http://www.lispcast.com/annotated-map

;; side-effecty loop (unformatted, causing text overflow) - from https://clojuredocs.org/clojure.core/doseq
(doseq [[[a b] [c d]] (map list (sorted-map :1 1 :2 2) (sorted-map :3 3 :4 4))] (prn (* b d)))

;; that same side-effecty loop, formatted
(doseq [[[a b] [c d]] (map list
                       (sorted-map :1 1 :2 2)
                       (sorted-map :3 3 :4 4))]
(prn (* b d)))

;; If this proselytizing has worked, check out:
;; http://howistart.org/posts/clojure/1
  </pre>
</section>

<section>
  <h2>Other Tools</h2>
  <p>Tufte CSS attempts only to cover some basic “Tuftean” ideas, providing one possible set of defaults, using cascading stylesheets. Therefore many of the more interesting techniques he points to are far outside the scope of this project. Graphing data, interactive data visualizations, and non-traditional text formats are fantastic tools that aren’t covered by Tufte CSS. Here is a short and incomplete overview of tools that can help accomplish a few Tufte-like techniques.</p>
  <p>Sparklines are awesome, and can be created in a variety of ways. People are making them with <a href="https://github.com/adactio/Canvas-Sparkline">plain javascript</a>, <a href="http://omnipotent.net/jquery.sparkline/#s-about">jQuery</a>, <a href="http://www.tnoda.com/blog/2013-12-19">d3.js</a>, and <a href="http://www.highcharts.com/demo/sparkline">HighCharts</a>. Evaluate those solutions to see which is most appropriate for your needs.</p>
  <p>If you need to display mathematical symbols and equations, I hear <a href="http://www.mathjax.org/">MathJax</a> is good.</p>
  <p>Although I don’t follow all of its prescriptions, I like <a href="http://practicaltypography.com/">Butterick’s Practical Typography</a> for its thoughts on designing text for the web.</p>
  <p> Bret Victor’s has published some vintage computer science talks and papers, like <a href="http://worrydream.com/EnlightenedImaginationForCitizens/">this one by Alan Kay</a>, that have a Tufte-CSS feel that I quite like.</p>
</section>
</article>
