Style Guide
This page lays out the site-wide styles and how to use them. It’s a form of visual documentation and a reference for how to display visual elements. It also allows easier testing of styles and cross-browser compatibility checks. This page was partially inspired by pages like gRegor Morrill’s style guide and some CSS framework documentation sites.
See the source of common.css for the complete styles. Custom shortcodes and other build customizations are defined in .eleventy.js and the imported files. Includes are defined in the /_includes directory.
Testing Steps
The following steps should be completed to check site-wide style changes.
- Visual check of light/dark mode
- Accessibility check of light/dark mode
- Check multiple browsers (Chrome, Safari, Firefox, Mobile)
- Check multiple screen readers
- Zooming on page
- Changing default font size
CSS Units
Use REM units where reasonable with a base-2 sizing structure based on a 16px default that can be modified by users for accessibility. Units that should adjust with the font size can use em units. Some things like borders or images still are defined in pixels.
Use css custom properties for colors (for theming) and base styles. The most significant styles would be widths and margins that my need to be referenced elsewhere.
Colors
Three theme colors are defined. The muted and distinct colors are set to flip between light and dark color schemes.
Base
The base color is used for the header and outlined buttons.
Accent
The accent color is used for buttons
Alternate
The alternate color is used for links
Typeography
The site uses native OS system fonts. Headings each have their own size. To allow for flexibility while retaining semantic accuracy, there should be a class to override heading styles.
Headers
Headers break up the page content. They are semantically significant, so if a different heading is visually needed than semantically, specific classes can be used to fake a heading style. Typically I write headers with “Title Casing” but adjust based on the context.
Heading Level 1
H1s are used for the title of a page. H1 styling can be forced with the .h1
class.
Heading Level 2
H2s help define the major sections of an article. H2 styling can be forced with the .h2
class.
Heading Level 3
H3s are used under h2s. H3 styling can be forced with the .h3
class.
Heading Level 4
H4s are used under h3s but should be rarely used. H4 styling can be forced with the .h4
class.
Heading Level 5
H5s are used under h4s but should be rarely used. H5 styling can be forced with the .h5
class.
Body Text Example: Adventures of Huckleberry Finn
You don’t know about me without you have read a book by the name of The Adventures of Tom Sawyer; but that ain’t no matter. That book was made by Mr. Mark Twain, and he told the truth, mainly. There was things which he stretched, but mainly he told the truth. That is nothing. I never seen anybody but lied one time or another, without it was Aunt Polly, or the widow, or maybe Mary. Aunt Polly–Tom’s Aunt Polly, she is–and Mary, and the Widow Douglas is all told about in that book, which is mostly a true book, with some stretchers, as I said before.
Now the way that the book winds up is this: Tom and me found the money that the robbers hid in the cave, and it made us rich. We got six thousand dollars apiece–all gold. It was an awful sight of money when it was piled up. Well, Judge Thatcher he took it and put it out at interest, and it fetched us a dollar a day apiece all the year round–more than a body could tell what to do with. The Widow Douglas she took me for her son, and allowed she would sivilize me; but it was rough living in the house all the time, considering how dismal regular and decent the widow was in all her ways; and so when I couldn’t stand it no longer I lit out. I got into my old rags and my sugar-hogshead again, and was free and satisfied. But Tom Sawyer he hunted me up and said he was going to start a band of robbers, and I might join if I would go back to the widow and be respectable. So I went back.
Special Text
Text can be strengthened, emphasized, or even made smaller. In markdown quotes in “quoted text” are stylized to highlight the begining vs the end.
Links
Links in paragraph are styled to increase readability and make it clear they are links. This includes different colored text and underlining, though bold text has been considered. Links should ideally contain multiple word for increased readability.
In navigation sections, links aren’t blue, but their linkyness should probably be emphasized with underlining, at least on hover.
Buttons
Buttons can be styled with classes. Disabled buttons should not be clickable.
Input buttons are also styled like buttons.
Links can also be styled to look similar to buttons but are underlined on hover or focus.
Images
![image displayed as wide as the text](/assets/img/2019-italy-trevi-fountain-night.jpg)
![image displayed to the left of text](/assets/img/2022-rose-yellow.jpg)
There are several ways to display images. Above is shown the wide orientation which goes as wide as the text is allowed.
Floated content is also possible and it will wrap around the floated image. However this can lead to situations where later headings also begin to wrap.
To prevent further text from wraping around the image use a clearfix. Also note that images need an empty line above and below in markdown to be rendered correctly.
<div style="clear:both;"></div>
![image displayed to the right of text](/assets/img/2020-birding-ca-peregrine.jpg)
float: right
Captions support markdown syntax but be careful with quotes in alt text. You can use the “stylized” quotes to fixt that. Below is a default width image with a caption. It uses the .post-img--wide
class name.
![image displayed to the right of text](
/assets/img/2020-birding-ca-peregrine.jpg
"This image is `float: right`"
){.post-img--float .post-img--float-right}
![image displayed not full-width on desktop](/assets/img/2018-yellowstone-grand-prismatic.jpg)
Lists
Unordered
- Item one
- Item two
- Subitem A
- Subitem B
- Item three
Ordered
- Fist item
- Second item
- Two point one
- Two point two
- Two point three
- Two point three one
- Third item
Quotes
Text in a <blockquote>
“Say, who is you? Whar is you? Dog my cats ef I didn’ hear sumf’n. Well, I know what I’s gwyne to do: I’s gwyne to set down here and listen tell I hears it agin.”
—Mark Twain, “Adventures of Huckleberry Finn”
Code Blocks
Currently using highlight.css or highlight-dark.css to style code depending on the user’s preferred color scheme.
Markdown’s inline code references <div>example</div>
are not syntax highlighted.
const trimTime = (dateInput) => {
const date = new Date(dateInput); // Parse date in case it is a string
return new Date(date.getFullYear(), date.getMonth(), date.getDate());
};
Sometimes HTML shows up unexpectedly as code blocks due to indenting, sometimes hidden by liquid pre-processing. This can be escaped using a custom removeindents
shortcode.
{% removeindents %}
<div>
<p>Accidentally indented</p>
</div>
{% endremoveindents %}
Note that setting a language is required to get syntax highlighting.
A default code block is shown more simply.
The prism theme needed to be modified to not require the language-*
class name.
This text has no highlighting
Horizontal Ruler
The following is an <hr>
tag which can also be defined in markdown with three dashes (---
) on their own line.
It’s an empty tag and yes I am stalling to write a larger block of text so this looks more like a normal context.
Please accept my apology for wasting your time.
It’s often used to break up two paragraphs with a hard pivot but without a heading change. It gives some visual space between the two groups of text. You can see an example on the Migrating Angular Types Blog Post.
Embed links
These are inspired by Medium’s approach to linking to external content. It shows a preview of the title, text, and featured image which acts as a link.
{% include "embed-link.html"
title: "Blue-throated Motmot"
url: "https://ebird.org/species/bltmot1/"
description: "Scarce inhabitant of highland forests in Chiapas and south to Honduras. Found in humid pine and evergreen forest, perching at all levels. Like other motmots, rather inactive a…"
img: "/assets/img/embed-thumbnail-blue-throated-motmot.jpg"
alt: "green bird with bright blue throat and a long skinny tail"
%}
Aside
These need to be formalized but they are usefull for calling out the context of an article. So far I’ve added inline styles since I want them to appear in RSS readers.
<aside
style="padding: 1rem 0;font-size: 1.1em;border-top: medium double #333;border-bottom: medium double #333;margin: 2rem;font-style: italic;"
>
This post is part of a series describing our trip to Italy. To read an
overview of our trip and why we went, check out this
<a href="/blog/2019/11/27/we-traveled-to-italy/">introductory post</a>.
</aside>
Forms
Forms are designed for one column. Buttons within a form will be full width.
Many form elements that aren’t necessary have not been implemented but are listed below.
Links can be styled more like buttons with the .btn-link
class.
Recipes
To add microformats to recipes, use the recipe-ingredients
and recipe-directions
shortcodes.
{% recipe-ingredients %}
- 1/2 cup Ingredient one
- 1 tablespoon Ingredient one
{% endrecipe-ingredients %}
{% recipe-directions %}
1. Step one details
1. Step two details
{% endrecipe-directions %}
I’ve also experimented with Cooklang via markdown-it-cooklang. Use the recipe-cooklang
shortcode to enable parsing that syntax.
{% recipe-cooklang %}
1. Add the @chicken{1.5%lb}, @shallot{2}, 2 cloves of @garlic{3%cloves minced}, @oregano{1%tbsp dried}, @paprika{1%tsp}, and a pinch of @red pepper{1%pinch}, @salt{1%pinch}, and @black pepper{1%pinch} to a bowl.
1. Mix until it starts to combine. Coat your hands with a bit of oil, roll the meat into tablespoon-size balls (will make about 20-25 meatballs).
{% endrecipe-cooklang %}
Updates
Pages can have updates listed below. See /updates-test/ for an example.
Post previews
Posts can be summarized and shown in feed pages or as suggestions below other posts.
View more articles
{% include "post-card.html" post: nextPost %}
Different post types appear differently
Pages with custom styles
Review the following pages for issues as they have their own unique styles.
- What we learned in puppy kinder
- Not Found
- Colophon
- Foster Care
- Links
- Pay Anthony Ciccarello
- Photo Gallery - Page 1 of 4
- Referrals
- Resume
- Search
Pagination
For paginated pages, you can show pagination links at the bottom.
{% include "pagination.html" %}
Footer
TODO: Describe the footer below.