Style guide

In this style guide, I will walk you through the thought process that went into designing each of the components that you can see on this website.

Body text

The first component is the body text. As this website will consist primarily of articles on a variety of topics, the readability of the text content is of the highest priority. One of the first choices I needed to make was: the choice of a typeface or font. I chose Crimson Pro, which feels easy on the eyes and scales easily to different font sizes.

For the default font size, I opted for 18px, as that gives good readability on smaller screen sizes.

The line height is set to 1.3 times the font size to provide enough spacing between the different paragraph lines and reduce the feeling of clutter.

To set the line length, I used the CSS “ch” unit, which allows you to size the text based on the width of the “0” character. This will allow the line length to grow and shrink proportionally depending on the font size. To fit an optimum amount of around 60 characters per line, I put the line length to 50ch, which seems to be the perfect value to achieve this goal with the current font choice. In addition, I constrained the maximum width to 100% of the screen size to avoid a scrollbar appearing on smaller screens.

Ideally, the text below should fit on a single line without wrapping:

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefgh

Some lines with long words start will overflow the maximum width of a paragraph, so we need to set up word wrapping and hyphenation to break paragraphs in the middle of a word to preserve the flow of the article.

Finally, I made some minor tweaks to make the text more readable by setting the “text-rendering” CSS property to “optimizeLegibility” and changing the color to a dark gray that is a bit easier on the eyes than the default black. This was done by setting the “color” property to the value “#333”.

Headings

Once happy with the look and feel of the body text, I moved on to style the different headers. Three levels of headers will be commonly used on the website: h1, h2, and h3. In some cases, h4, h5, and h6 might be needed, so they have also been given a style, but I don't expect these to be used very often.

Equals and LIKE operators treat trailing spaces differently in MySQL

Some example text

Each header has a larger margin before than after to clarify which text content belongs together with which header. The font size of the headers is not huge, as we might have long article titles. For this reason, the font sizes range from 0.7rem to 1.5rem.

The Ubuntu sans-serif font is used to make the headers stand out from the standard body text, and font-weight makes smaller headers more prominent by reducing their thickness.

Letter spacing and line height are applied at different levels to maintain readability.

There is a CSS utility class, “body-text-margin” that can be used to reduce the lead margin between subsequent headers. It is applied in the h2, h3, h4, and h6 elements shown above.

Links

In the body text, links commonly refer to other resources you can find online. This sentence contains a link to the Activity feed. As you can see, the link has been given a distinctive color and font-weight from the rest of the text to make it stand out.

When links are longer, for example, Using HTTP/2 in your Spring Boot application, or even an actual link https://brytecode.be/articles/using-http-2-in-your-spring-boot-application/, these links should wrap appropriately to the following line without messing up the flow of the text.

To ensure links wrap correctly in most browsers, I have a tool to generate <wbr> tags to indicate Word Break Opportunities to the browser. See the CSS Tricks article on this subject for more information.

External links, such as the CSS Tricks link, should open in a separate tab.

Inline code

Smaller fragments of code can be mentioned directly within a paragraph’s text. For example, when I talked about the “optimizeLegibility” property earlier, I could have said to add the following line to your CSS for paragraph tags: text-rendering: optimizeLegibility;.

To display code in a paragraph prominently, I use the JetBrains Mono font and reduce the size to 0.8em to match the body text font more. Note that I use relative units here, as code tags can occur in several different contexts, and their size needs to be adjusted accordingly.

Earlier, we enabled automatic hyphenation to add hyphens to paragraphs that need to wrap to multiple lines. This does not work in code blocks, as the additional hyphens will lead to confusion, so we disable this behavior for code tags.

We should also be able to deal with LONG_CONSTANT_NAMES_INSIDE_A_PARAGRAPH_THAT_MIGHT_BREAK_FORMATTING. So, we need to ensure that word wrapping still works for code elements.

A light blue background is given to the code element to group all the code, and the font-weight is reduced to make the code fragments easier on the eyes.

Code blocks

For larger sections of code, we want to provide syntax highlighting, and we want to separate them clearly from other content.

# This TOML file starts with a comment

value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"
value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"
value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"
value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"
value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"
value       = "string"
date        = 2023-01-01
longText    = "This is a longer fragment of text that should cause a scrollbar to appear on smaller screen sizes"

All code blocks have a dark blue background. We limit their height to 60% of the viewport to maintain ease of scrolling for the reader. Scrollbars are enabled to allow for both horizontal and vertical scrolling. As with inline code, we prevent hyphenation, as this makes the code difficult to read. For syntax highlighting, we use the Prism library with a custom theme.

Blocks that are not highlighted look like the ones shown below.

This is code without highlighting.

Block quotes

Block quotes are slightly indented on the left-hand side to make them more distinct from standard body text. A blue line in front helps indicate that this is a quote. The source that is being cited is preceded by an em-dash, and its “font-style” is set to “italic” to make it stand out within the quote.

This is a quote from an article.

Source

Lists

Both numbered, and unordered lists are used on this website.

Cars
Bicycles
Airplanes
…

I've opted to use an open circle rather than a closed disc in the unordered lists.

The first item on the list
The second item on the list
The third item on the list

Numbered lists use the “Ubuntu” font for the numbers, which are slightly smaller than the other text.

Tables

Tables are indented slightly, similar to block quotes and code blocks. They use zebra striping to make the rows easier to scan. A little padding is added to the cells to make everything feel less cluttered. The tables are made horizontally scrollable, making them easier to navigate on smaller devices.

Captions of tables are in italics and slightly smaller than the table contents.

For the headings, I've chosen to make them bold but reduce their size a bit to counter the effect of the boldness. Letter spacing is used to keep things readable.

Drivers with their license registration date
Name	Age	Profession	Registration date
John Doe	31	Truck driver	1995-01-05
Jane Doe	52	Manager	1996-04-04

Link buttons

A link button is the first non-standard HTML component that might be used on a page. These are links that are not supposed to be used inside the body text. They can be used for call-to-actions and should be a block-level element. Link buttons can be combined with an image.

This is a paragraph before.

Go to the home page

This is a paragraph after.

Go to the home page