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.

Content Style

I’m pretty loose on content but have some loose guidelines in my head.

Articles

I usually have some kind of featured image when writing articles. Articles may also have subtitles, though I try to avoid over-using them. I’m not completely settled on a heading capitalization but usually try to follow something like APA style where most words are capitalized, but small, minor words after the start are lowercase.

Recipes

My recipe pages are primarily to track how we make different recipes, so many of them are still very close to the original. I don’t intend or need to pull from other website’s SEO, so when posting a recipe I try to use the following conventions:

1. Clearly identify the source in the first paragraph (if not first sentence) of the recipe with a link (or link to the book with page numbers).
2. For recipes I’ve used as inspiration but don’t follow, I still try to list them somewhere in the description.
3. Give some indication of how heavily the recipe was modified so people know if the source might be worth looking at.
4. Write the instructions in my own words so that they match what I do and don’t just duplicate content.
5. Never use another site’s copyrighted photos for recipes. Even if it’s ugly, I’ll still use my own.
6. I will mark recipes as “noindex” upon request if the source (e.g. family) does not want it in google results.
7. I’m still trying to figure out what best way to help but not hurt other site’s rankings. I could noindex but that wouldn’t provide backlinks. Also Google does not always like canonical URL relations, particularly cross domain and if any content has been changed. Canonical URLs also affect how pages get shared.

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

Current page Random Page

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.

Text Wrapping

Use the .no-wrap class to avoid wrapping text. As you can see this line of text keeps going without a page break. However, you should only use this on strings that you don’t want to wrap or you can screw up your page formatting.

If you don’t want to have the text scroll like the above line, a shorter string would only keep the important text together. E.g. something like this which will be kept together but other text will wrap.

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

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>

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}

Lists

Unordered

• Item one
• Item two
  • Subitem A
  • Subitem B
• Item three

Ordered

1. Fist item
2. Second item
   1. Two point one
   2. Two point two
   3. Two point three
      1. Two point three one
3. 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 are useful for calling out the context of an article. They previously used inline styles but now use an element selector.

<aside>
  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>

There is also an aside used for post status information that looks like the following:

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.

Here is a form with <fieldset>:

Personal

Name Date of Birth January February March April May June July August September October November December 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 1998 1999 2000 2001 2002 Favorite Animal House Cat Lion Goldfish Swordfish Dog Llama

Account

Email Must be unique Password Address

Preferences

Color Preference

I prefer yellow I prefer gold I prefer yellow-orange

Automobile Preference Maserati Koenigsegg McLaren Mitsubishi Register Reset No clicky

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.

{% 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
• SD Wave FC
• SD Super Bloom Ultimate
• SD Legion Rugby
• Not Found
• Colophon
• Foster Care
• Links
• Pay Anthony Ciccarello
• Photo Gallery - Page 1 of 5
• Cookbooks
• Referrals
• Resume
• San Diego Sports Teams
• Search
• Stickers

Pagination

For paginated pages, you can show pagination links at the bottom.

{% include "pagination.html" %}

Footer

TODO: Describe the footer below.