Essay Style Guide

Layout, Figures, Dials, Knobs and Marginalia

Article Intro. A few short <p> that offer an overview of the content that follows. Be inspirational, controversial, ask questions, engage and entice the reader. Most of the deeper content will follow in the article text, so it's okay to be light in tone, catchy, and concise in wordcount in the Article Header.

<h1> are used once per article to identify the title. They can be immediately followed with an <h2> subtitle or an introductory <p>.

We believe in a computing future where programming is within the grasp of everyone and hope this article can inspire and challenge our industry.

We welcome your feedback: @inkandswitch or [email protected].

Header

An article begins with a Title, Subtitle, and Byline, followed by the Article Intro which offers an overview of the content that follows.

Title and Subtitle

Example image of Article Title

<h1> are used once per document to identify the Title. The Title can be immediately followed with an <h2> Subtitle or Article Intro text.

Byline

Example image of Article Byline

The Byline should always contain the Ink & Switch Lockup and date. While an Author Name is optional, it is important to to give proper attribution to sources and collaborators throughout the article.

Article Intro

Example image of Article Intro

The Article Intro sets the tone for the content to follow. Here it's okay to be light in tone, inspirational, controversial, ask questions, and engage the reader. Most of the deeper content will follow in the article text.

The Muse Article effectively incorporates a short video to give a brief tour of the Muse application, however, if a few short paragraphs can convey the appropriate message, that works too!

Outro

Example image of Outro Paragraph

The Outro sentence of Article Intro or Article Conclusion always welcomes feedback on the topic.

CSS Class

Use Case

.outro

Apply to the last paragraph of the Article Intro or Conclusion for for a small splat of brand.

Article Text

Ink & Switch articles include several main topics, or <h2> Sections, which are supported by their <h3> Subtopics, text and other content.

Section Headers

Example image of Section Header

A Section of article content, from <h2> to the next <h2> can optionally be wrapped in <section>, which provides additional structure and reinforces the hierarchy for some browsers and readers.

Subtopic Headers

Example image of Subtopic Header

<h3> are used to clarify Subtopics, or act as the supportive subtitle of an <h2>.

Asides

Asides are a great way to call attention to, or support article content, and are architecturally similar to Figure Captions.

Asides should appear in the DOM immediately after the block element that they relate to, or, if they have an <h4> to set the appropriate context, they can precede their related content1.

Example image of an Article Aside

Screenshot of the above Aside on wide viewport.

<aside class="move-up-3">
  <h4>Aside Example</h4>
  <p>For example, <aside class="move-up-3"> will move an aside up 3 lines of article text.</p>
</aside>

Asides automatically float into a position nearby the previous block, however, asides do occasionally need to be repositioned.

CSS Class

Use Case

.move-up-num

Apply this class to an <aside> to position it visually. Typically used to align an aside to it's related text. Occasionally used to avoid overlapping asides. num represents the number of lines to move, and can be any value from 1-25.

.callout

Will position the aside as it appears in the DOM, either above or below the related text. Useful as footnotes, callout, or when several aside elements are required, yet there is limited space in margin. Use this class sparingly.

Blockquotes

“HyperCard was a tool for making tools – Mac users could use Hypercard to build their own mini-programs to balance their taxes, manage sports statistics, make music – all kinds of individualized software that would be useful (or fun) for individual users. These little programs were called stacks, and were built as a system of cards that could be hyperlinked together.”

Lists

  1. No spinners: your work at your fingertips
  2. Your work is not trapped on one device
  3. The network is optional
  4. Seamless collaboration with your colleagues
  5. The Long Now
  6. Security and privacy by default
  7. You retain ultimate control

Since HTML renders whitespace, it is best to remove whitespace including line breaks within an <li>.

<ul>
  <li>List Item 1</li>
  <li>List Item 2</li>
</ul>

Figures

Figures can include flow or embedded content such as <img>, <video>, <pre>, <table> or other visual content, and will generally span the width of the article text. Follow the content with an aside, using <figcaption>. The same rules apply to <figcaption> as <aside> for article text.

Images

Figcaptions

Figcaptions will always align to the top right of their parent Figure. Try to keep Figcaptions shorter than the height of the figure.

Videos

When embedding video, be sure to include the controls attribute to display the default browser video controls. This allows the user to scrub or replay the video. If you'd like to loop video, you can also ammend the loop attribute.

<video preload="metadata" controls loop>

Tiled Figures

Occasionally, there is a need to display multiple images or videos next to each other, or on a tiled grid. Wrapping the images in a <div> with the appropriate utility class will allow us to tile 2,3 or 4 images next to each other, and in multiple rows.

<figure>
  <div class="grid grid-columns-2">
    <img src="image1.png" />
    <img src="image2.png" />
  </div>
  <figcaption>
    <p>An example figure with 2 tiled images.</p>
  </figcaption>
</figure>
This code shows an example figure using the <grid> utility class to tile 2 images next to each other.

CSS Class

Use Case

.grid

Apply this class to a <div> that is the parent of the content you'd like to display in a grid.

.grid-columns-2

Will display the children in rows of 2 columns.

.grid-columns-3

Will display the children in rows of 3 columns.

.grid-columns-4

Will display the children in rows of 4 columns.

For example, by appending the utility class <grid-columns-3 to a <div> containing 6 images, we can display the images in a tiled grid.

Code

<figure>
  <video preload="metadata" controls>
    <source src="media/muse-studio-for-ideas/muse-tour.mp4#t=0.1">
  </video>
  <figcaption>
    <h3>A brief tour</h3>
    <p>Some capabilities of the Muse studio for ideas iPad application.</p>
  </figcaption>
</figure>

Any figure can be displayed with a caption, but they are always optional. Be sure the figcaption comes after the figure, just like Asides.

Tables

Utility Classes

When presenting data or any structured content in a table, you might prefer to adjust the style of content or width of the column display data in a more elegant way. To do so, use the utility classes described in this table.

CSS Class

Use Case

.row-highlight-off

Use this to optionally turn off row highlighting. Great for complex tables that make use of colspan or rowspan.

.column-number

Apply this class to all <td> with numerical data. This preserves character width of data so digits align properly.

.column-width-auto

Will set the width of the column to the default width determined by the browser. Useful for <th> or <td> that can be flexible width, or for smaller <table> that does not need to be the full width of the article.

.column-width-text

Will set the width of the column to the width of the text. Useful for headers for numerical data.

.column-width-half

Will make columns 1/2 width. Apply this class to an entire <table>, or to an individual <th> or <td>. This table uses this class.

.column-width-third

Will make the column 1/3rd of the total width. Useful if you want one column to be a fixed width, or longer than the others. Apply this class to an entire <table>, or to an individual <th> or <td>.

.column-width-quarter

Will make the column 1/4th of the total width. Useful if you want one column to be a fixed width, or longer than the others. Apply this class to an entire <table>, or to an individual <th> or <td>.

.column-width-eigth

Will make the column 1/8th of the total width. Useful if you want one column to be a fixed width, or longer than the others. Apply this class to an entire <table>, or to an individual <th> or <td>.

Table with Charts

This table makes use of many of the utility classes described above.

Device Program Latency (ms)
iPad Pro Notes 20
GoodNotes 30
Flutter 35
Surface Pro OneNote 25
SketchPad 30
Canvas 60
Pixelbook Squid 40
Canvas 60
Samsung S3 Squid 60
Flutter 65
Canvas 75
LiveBoard 80

<svg> is a scalable method of implementing Bar graphs within a table.

Wide Content

Occasionally, content might be more suited to a full-width layout. For these instances, apply the utility class .wide to block level article content. This feature is especially suited to a figure with video, images, or possibly tables with more data than can fit comfortably in the width of article text.

This is an example of a single full-width image and caption.

This is an example of a full-width grid of images and caption.

Files and Email Attachments

1. Fast 2. Multi-device 3. Offline 4. Collaboration 5. Longevity 6. Privacy 7. User control
✔ ➖ ✔ ✘ ✔ ➖ ✔

Conclusion

Summarize your findings in a few paragraphs, and invite our readers to contribute by ending with a closing paragraph similar to the following:

At Ink & Switch we continue to believe that the end-user programming utopia is reachable. Are you working on this problem, or have thoughts on what we've written here? Get in touch: @inkandswitch or [email protected].

Appendix

An appendix can have a few closing <h3> subtopics, or can be less structured set of links, or <p>.

One last thought to consider

Using Lorem Ipsum is not the best way to convey example text, but it's a decent placeholder. A future iteration of this guide will have more information about voice and tone, and sharing to social media with the <meta property="og:..."> tags.