Website style guide
In the beginning, there was complexity
Years ago, when I set out to create my own website, I did not, as I was overwhelmed with possibilities. I thought about complex, intriguing designs, with the highest technical fidelity, amazing easter-eggs, and a mind-blowing user experience. Creating a mountain in front of myself, unable to climb, ever-growing.
Back then, creating websites professionally, of course I wanted to have the best of the best of the best. I did 26 design iterations, from pure Sketch designs to full-fledged, complete with pattern libraries and code. Every new prototype more complex than the one before.
I also went through a lot of technologies I could use — from the well-known to the never-heard-of, including the (in)famous "I will build my own X". Creating holistic testing strategies, code guidelines, documentation, … you name it. "Everything a professional does", so I convinced myself.
I deleted it all. What if; just HTML and CSS, no fancy technologies, no pop-ups, no content jumps. Not saying there is a relation between "fancy technologies to "negatives", just stating what I wanted to reduce. I was creative my whole youth, learned to be a designer and even worked as one for a while. But I am no designer, not anymore, and I did not love the time I was; or at least what I was doing back then.
I started working on something I thought will be a WIP (work in progress), a simple website, no extras, nothing fancy. Getting something I started to like, I removed everything not necessary. I had a cookie banner, because everyone does — but why? Do I have cookies, do I need them? I mean, realistically cookies are amazing, the ones to eat, but I had none on my website, so gone with the cookie banner.
This is not true anymore today. While my site grew, I switched to 11ty, a static site generator that did not lock me into a specific framework. I was able to gradually streamline some parts of maintaining my website, but that was all. Just a bit of help managing the blog, creating a feed and the sitemap. Everything else still holds true; simplicity.
The style guide
The following content is a living document of defined styles and components, how to use them, and how they are created. With "components" I refer to the combination of HTML and CSS to create a logical unit for my website.
Not having any build system, I still wanted to have some kind of variables for my CSS — custom properties to the rescue. With very good browser support I hesitated not, using custom properties for fonts, sizes, and colors.
Because I did not want to include custom fonts I use a standard set
of sans-serif font families. The variables, defined inside the
:root, look as follows.
For consistency of e.g. paddings and margins I define a set of reusable sizes.
And at last, a set of colors.
Here how they look like:
There are five headlines defined, where
h1 is reserved
for the website title. There is a base set of styles all headings
The font size and margin for headings are defined per heading.
.h1 Website title
Only used once per page as website title.
.h2 Page title
This heading size is used for page titles or to separate larger content areas.
.h3 Section title
Used in an article or page.
.h4 Sub-section title
Further divide content in articles or pages.
.h5 Paragraph heading
Small additional heading for paragraphs.
Text styles are kept minimal. What you see all the time here, and right now, is a paragraph.
Seven lines of style declarations are all for paragraphs.
This is a simple paragraph.
Blockquote components will inherit all paragraph styles, besides defining own unique styles. There is also some extras for paragraphs inside blockquote elements. All blockquote elements will be inside a figure element.
The callout is used to bring focus to important information, most often used in a tutorial or similar knowledge focused articles.
The CSS for the
strong element is just
making it bold.
This is very strong text.
Emphasising text comes in two "flavours"; one is the semantic version, the other is a visual representation only.
This is emphasised.
This is also emphasised, but only visually.
Links are represented by color and a simple hover effect. There is
also a separate style when a definition element
Here is a link.
Including a definition element.
Don't forget, every link needs a title.
Address elements get some original italic style.
La Taverna del Brigante
Via Aldo Manuzio, 82
04010 Bassiano LT
So far there is only one type of list, an unordered list.
- This is
- an unordered list
To show additional information aside I was under the impression I
complex structure. Happily this was not the case, all it needed was
a container wrapping what will be referenced and the
aside absolute placed in relation to it.
Show the aside and how to make that happen. This will only show on the right side of the content on larger screens. Otherwise, it will be part of the content flow.
Media on this site are images and video, but can also be other
rich‑content like code blocks. It is placed inside a
figure element with caption. Every image will have a
webp version, every video a webm.
The basic media content style is for the
Images will always have a webp version and a caption.
They are placed inside the
picture element, and will
show up larger on mobile devices by using the full device width.
loading="lazy" is only used for images below the
Similar to webp for images, video will always have a webm version and a caption. A "poster" will be used to show a preview image of the video.
Code can be used inside paragraphs and as standalone code blocks with syntax highlighting.
Inside text the
code element is used.
Code blocks are placed inside
figure elements and can
have optionally a
highlighting is supported through
Besides some custom styling, styles are taken from a highlight.js
theme represented by CSS classes prefixed with
A different set of supported languages, or even more, can be set up on the highlight.js configuration page.
This concludes the set of noteworthy components styled through the style.css file. Over time this will expand and cover whatever new components I will add. For now, that was it.