Imperfect

Agave theme details

Inspired by Sylvia's My Bearblog theme CSS, lightly annotated.

This page describes details for the Agave theme for Bear Blog. To view or copy the CSS for your own use, check out the theme page.

If you notice any missing details or references, or have details to suggest yourself, feel free to contact me.

Name

I think it's a fitting name for the accent colors I chose.

Inspirations

In alphabetical order, non-exhaustive:

Environment

Most of my CSS was built within mgx's handy bearblog css playground.

Font limitations

For fonts, the playground doesn't support @import URLs, but it does support @font-face src URLs. If you want to import custom fonts from Google Fonts or Bunny Fonts, I would recommend picking one of these options:

  1. Use default or common fonts
  2. Import fonts with @import after applying your CSS to your blog
  3. Using @font-face src URLs in the playground, then doing the above

I chose the last option. Here is a boilerplate example of one @font-face declaration:

@font-face {
  font-family: 'Font Name';
  font-style: normal;
  font-weight: 400;
  src: url(https://fonts.bunny.net/font-name/files/font-name-latin-400-normal.woff2) format('woff2'), url(https://fonts.bunny.net/font-name/files/font-name-text-latin-400-normal.woff) format('woff');
}

If you need multiple fonts or variants, you will need to duplicate the above with appropriate changes to the font name and source URLs. As to why you would want to use @import, you can import as many fonts and variants as you need in one line like in this boilerplate example:

@import url(https://fonts.bunny.net/css?family=font-one:400,400i,700,700i|font-two:400,400i);

Owl selector limitations

The playground's layout doesn't play well with CSS that applies the owl selector (* + *) universally or to the body element. Make sure you constrain it like so:

:is(header, main, footer) * + * { margin-top: 1.5rem; }

You can learn more about the owl selector under "Owl selectors" below.

Variables

Colors

Agave uses an adaptive, human-readable tricolor palette containing a background, foreground, and accent color (shades of teal, hence the theme name). The chosen colors meet WCAG and APCA compliant contrast per Myndex of APCA's Bridge PCA Contrast Calculator. Feel free to edit the background and foreground colors if you prefer less color contrast. I recommend using this HSL Color Picker to modify hsl values if needed.

Fonts

Fonts are served from Bunny Fonts as a more private alternative to Google Fonts.

Size units

rem and em units define sizes throughout the theme. The only exception is width, where I use px as an alternative to using rem with clamp. I would recommend Josh's The Surprising Truth About Pixels and Accessibility: should I use pixels or rems? for further reading on this subject.

Font sizes

Font scale sizes use rem values mapped to px integer values. I based this decision on this Reddit thread, What typographic scale is preferred for responsive design?:

Sometimes type scales look awkward in smaller form factors. Thus, you can use smaller font sizes on mobile, large on desktop. If you're using a scale, you can use different intervals (or even different ratios/scales altogether) for different form factors.

Using type scale site scales often ends with weird decimal pixels/rems, which aren't good bc they get rounded to whole number which is bad, or aren't rounded which looks bad on older monitors. Either round to whole numbers or use fallbacks.

Code and syntax highlight styles

Sylvia's Pygments stylesheet markup from Prettifying code with syntax highlighting was adapted to use a slightly edited version of the bw theme showcased in Pygments' Styles page.

Sylvia's word wrap styling for code blocks applies heregenerally.

Styles

Linear gradient background animations

Hovering over links triggers a linear-gradient background to sweep right while the link text color changes. Moving the cursor away reverses the animation.

Buttons reuse the same animation.

Tab-through outlines

A :focus-visible outline improves aesthetics and accessibility for tabbing through the page, without unintended outlines from clicking through via :focus. outline-offset prevents the outline from overlapping background animations.

External links display an external link icon thanks to this Stack Overflow page: url - CSS: Style external links - Stack Overflow.

Reduced Motion

The prefers-reduced-motion declaration minimizes the animation duration when Reduced Motion is turned on for Apple devices. This CSS Tricks page explains it in detail: Prefers-reduced-motion

Upvote button

Hovering over the upvote button switches the emoji. Clicking on the upvote button:

Navigation bar links are aligned with the blog title.

Blog list styles

Blog post lists have their Flexbox row directions reversed so post titles precede the date. Vertically centered leader lines get inserted before the date.

The closest analogue I found on Bear Blog is Sylvia's Blog list with dates on right + leading dots, which doesn't center the leader lines.

Page styles

Centered body element

Inspired by the CSS Vlad uses, all page content is centered horizontally and vertically.

Owl selectors

Setting vertical margins per element can be tedious and messy. Relying on vertical rhythms is too inconsistent and brittle for universal use.

Agave uses an owl selector (* + *) to apply the same vertical margin to all elements following a first sibling:

:is(header, main, footer) * + * { margin-top: 1.5rem; }

Then exceptions are created to ignore margin for certain elements that don't need it (in thie case: nav, the page title, and lists), like so;

nav,
main h1:first-of-type,
:is(ul, ol) * + * {
  margin-top: 0;
}

For more information and visuals, check out Saleh's explanation at The Owl Selector in CSS.

Media styles

A pseudo-directive accompanies the footer content using the ::after pseudo-class (which doesn't support hyperlinks). Footer elements stack on mobile viewports to prevent odd wrapping or collision with each other.

I reused print styles from Robert's Bearming theme.

Other styles

Pseudo-classes like ::selection and ::target-text, and other elements like accent-color for inputs, adhere to the theme's color palette.

Table styles

Sticky headers

Tables have sticky headers, but once the header becomes stuck to the top of the page, the header cell borders are preserved.

Here is an example:

Table Header 1 Table Header 2
Table Cell A1 Table Cell B2
Table Cell A2 Table Cell B2

You can test this yourself by changing the background-color for table thead th.

Thanks to Sylvia's Does this work?, Bradley's Please Make Your Table Headings Sticky, and this Stack Overflow page: html - Border style do not work with sticky position element. Note: using border-separate works perfectly fine in my experience.

Want to reach out? Connect with me however you prefer: