Skip to content

Latest commit

 

History

History
101 lines (68 loc) · 3.43 KB

conventions.md

File metadata and controls

101 lines (68 loc) · 3.43 KB

Conventions

This document describes conventions within the Yarrharr codebase.

Browser Support

The primary target browser is Firefox (current release, not ESR). Testing in Chrome and Edge is useful as tends to reveal bugs. Internet Explorer is not supported. I do not test in Safari or iOS as I lack the appropriate hardware.

JavaScript Features

The project only targets browsers which natively support ES2015 syntax and <script type="module">. Specifically:

  • Firefox ≥ 54
  • Chrome ≥ 60
  • Edge ≥ 15

CSS Features

The following are okay to use:

  • Flexbox (display: flex, flex-* properties)
  • Grid layout (display: grid, grid-* properties, fr unit, display: content)
  • Variables a.k.a. custom properties (--foo: 1rem, font-size: var(--foo))
  • CSS containment and container queries

Units

New CSS should use the rem unit for all things. Old CSS is converted at a ratio of 16px to 1rem.

Page Layout

The page is a stack of full-width boxes:

+-----------------------------------+
|                                   |
+-----------------------------------+
|                                   |
+-----------------------------------+
|                                   |
|                                   |
|                                   |
|                                   |
+-----------------------------------+

There are two layouts: wide and narrow. The wide layout flexes according to the width of the window. The narrow layout assigns a max-width to each box, and flexes down when the window is narrower than that.

Each box in the stack has a max-width assigned individually, allowing each box to apply padding as necessary or appropriate. The CSS variable --layout-max-width indicates the max-width to apply when a non-flexible is appropriate (e.g. forms and such).

For example:

.box {
    margin: 0 auto;
    max-width: var(--layout-max-width);
    box-sizing: border-box;
    /* You might put padding here, or sub-components may provide it. */
}

The narrow width may become user-configurable some day.

Links

A regular link like this will display with an underline:

<a href="#">...</a>

To disable the underline use the no-underline class. The underline class can be used to re-add the underline in a specific location:

<a class="no-underline">
    <svg class="icon" width="1em" height="1em" />
    <span class="underline">...</a>
</a>

A link may be styled as a button using the text-button class:

<a class="text-button text-button-primary">...</a>

Icons

Icons have the form:

<svg class="icon" width="1em" height="1em" />

Within the SVG, the currentColor keyword is used so that the icon color can be assigned from CSS like .icon { color: blue }. Parts of the icon may be assigned classes to allow individual targeting.

Icons are defined in an inline sprite, found at yarrharr/templates/icons.html.

All icons are drawn on a 20×20 grid. This is generally defined asviewBox="0 0 20 20" or viewBox="-10 -10 20 20". The latter form is useful for symmetrical icons, as 0,0 is the center of the icon.

The live JSX editor on reactjs.org can be useful when authoring icons.