path: root/resources/css.org

# -*- mode: org; -*-

#+TITLE: Global CSS file
#+SUBTITLE: Site-wide styling informations.
#+AUTHOR: Marius Peter
#+DATE: <2022-01-30 Sun>
#+OPTIONS: toc:nil
#+PROPERTY: header-args :tangle mlnp.css

#+DESCRIPTION: Styling information for the entire following websites: mlnp.fr, wiki.mlnp.fr, and blog.mlnp.fr.
#+KEYWORDS: org-mode emacs blendux mlnp literate programming
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="mlnp.css" />
#+TOC: headlines 2


#+begin_abstract
This page describes the /entire/ website's styling
*information*. After experimenting with =flexbox= and =grid= layouts,
I decided to go with a plain linear document flow. This maximizes
design legibility and the accessibility of affordances. The beginning
of this document contains a placeholder section to test
#+end_abstract


* First level heading
SCHEDULED: <2022-02-18 Fri> DEADLINE: <2022-02-18 Fri>

** Second level heading
<2022-02-18 Fri>

*** Third level heading
<2022-02-18 Fri 12:48>

**** Fourth level heading. This is styled like a list item by default.

- Itemized list.
- This is the second item.
- This third item makes this list respect the [[https://en.wikipedia.org/wiki/Rule_of_three_(writing)][rule of three]].

| Category | Value           |
|----------+-----------------|
|        1 | A first value.  |
|        2 | A second value. |
|        3 | A third value!  |


* Global definitions
<2022-02-11 Fri>

These styles apply across the entire website, to every element.

#+BEGIN_SRC css
  body {
      background: linear-gradient(0deg, skyblue 10%, aliceblue 30%);
      background-attachment: fixed;
      margin: 0;
  }
#+END_SRC


** Colors

Declaring individual one-liner color rules enables efficient searching
for the relevant properties.


*** Variables

These colors variables can be accessed anywhere in the rest of the stylesheet.

#+NAME: colors
#+BEGIN_SRC css
  :root {
      --topnav: dodgerblue;
      --topnav-menu: royalblue;
  }
#+END_SRC


*** Background

We assign colors to the page element backgrounds.

#+BEGIN_SRC css
  .todo { background: tomato; }
  .done { background: forestgreen; }
  .timestamp { background: var(--topnav); }
  .title { background: var(--topnav); }
  #topnav { background: var(--topnav); }
  .button { background: var(--topnav-menu); }
  #topnav #hamburger { background: var(--topnav-menu); }
  #topnav #hamburger:hover { background: white; }
  #topnav #hamburger:hover .line { background: var(--topnav); }
  #topnav .button:hover { background: white; }
  #shadow { background: black; }
  thead { background: var(--topnav); }
  #topnav ul a:hover { background: white; }
  #org-div-home-and-up { background: var(--topnav); }
  #postamble { background: var(--topnav); }
  #outline-container-main-content
  .outline-3 { background: var(--topnav); }
#+END_SRC


*** Foreground

#+NAME: foreground
#+BEGIN_SRC css
  .todo, .done { color: white; }
  .timestamp { color: white; }
  .title { color: white; }
  .subtitle { color: lightgray; }
  .button { color: white; }
  #topnav #hamburger { color: white; }
  #topnav #hamburger:hover { color: var(--topnav-menu); }
  #topnav .button:hover { color: var(--topnav-menu); }
  #topnav ul a { color: white; }
  #topnav ul a:hover { color: var(--topnav-menu); }
  #org-div-home-and-up { color: white; }
  #postamble { color: white; }
  thead { color: white; }
#+END_SRC


** Typefaces

In the following section, we specify the fonts used across the
website. We use the following fonts for the [[https://en.wikipedia.org/wiki/Latin_script][Latin script]]:

- Public Sans :: A modern, smart sans serif font created by the
  [[https://public-sans.digital.gov/][USWDS]]. I use it for body text.
- Jost :: A modern geometric sans serif font by [[https://indestructibletype.com/Jost.html][indestructible
  type*]]. I use it for page title and subtitle.
- Hack :: A monospace typeface designed for source code. I love its
  legible characters and wide coverage, I use it frequently as a
  terminal font. Available at [[https://sourcefoundry.org/hack/][sourcefoundry]].
- Monoisome :: An alternative monospace typeface with great support
  for ligatures and icons. Get it from [[https://larsenwork.com/monoid/][larsenwork]].


We use the following fonts for other scripts:

- Cairo :: A simple, sans-serif typeface for Arabic script.
- Jost :: This font has good support for Cyrillic script.


*** Sans

#+NAME: faces-sans
#+BEGIN_SRC css
  @font-face {
      font-family: "Public Sans";
      src: url("fonts/PublicSans-Regular.otf");
  }
  @font-face {
      font-family: "Jost";
      src: url("fonts/Jost-Regular.ttf");
  }
  @font-face {
      font-family: "Cairo";
      src: url("fonts/Cairo-Regular.ttf");
  }
  @font-face {
      font-family: "Amiri";
      src: url("fonts/Amiri-Regular.ttf");
  }
#+END_SRC


*** Serif

#+NAME: faces-serif
#+BEGIN_SRC css
  /* None for now! */
#+END_SRC


*** Monospace

#+NAME: faces-monospace
#+BEGIN_SRC css
  @font-face {
      font-family: "Hack";
      src: url("fonts/Hack-Regular.ttf");
  }
  @font-face {
      font-family: "Monoisome";
      src: url("fonts/Monoisome-Regular.ttf");
  }
#+END_SRC


*** Assigning fonts to elements

We apply the previously defined font faces to the page elements.

#+NAME: fonts
#+BEGIN_SRC css
  #content { font-family: "Public Sans", sans-serif; }
  .title,
  h1, h2,
  h3, h4,
  #org-div-home-and-up,
  #topnav { font-family: "Jost", sans-serif; }
  pre,
  code, .src,
  .timestamp,
  #postamble { font-family: "Hack", monospace; }
  pre { font-size: 0.8em; line-height: 1em; }
#+END_SRC


** TODO Tab-select styling

Tab-selected content must appear with a wide, contrasted border. This
is an accessiblity concern.

#+BEGIN_SRC css
  a:focus {
      border: 0.2em solid aquamarine;
  }
#+END_SRC


* Homepage

Certains homepage sections are styled uniquely, for visual impact.

#+begin_src css
  #main-content, #text-main-content {
      display: none;
  }
  #outline-container-main-content {
      display: flex;
      flex-direction: row;
      flex-wrap: wrap;
      margin-top: 1em;
      gap: 1em;
  }
  #outline-container-main-content .outline-3 {
      max-width: 12em;
      padding: 0 1em;
      border-radius: 8px;
  }
#+end_src


* Main content

The following rule concerns all the content displayed on the page.

It concerns all children (not all descendants!) of the main ~#content~
section, except for the title and topnav sections.

#+BEGIN_SRC css
  #content > :not(.title, #topnav) {
      line-height: 1.5em;
      width: 60%;
      margin: auto;
  }
  p { text-align: justify; }
#+END_SRC


** TODO `Home' and `Up' links

#+BEGIN_SRC css
  #org-div-home-and-up {}
#+END_SRC


** Title and subtitle

#+BEGIN_SRC css
  .title {
      margin-top: 0;
      margin-bottom: 0;
      padding-top: 0.5em;
      padding-bottom: 0.5em;
  }
#+END_SRC


** Table of contents

The table of contents exported to HTML from Org mode takes the form of
an unordered list. We suppress bullet points that would otherwise
appear before each entry.

#+BEGIN_SRC css
  #table-of-contents ul {
      list-style-type: none;
  }
#+END_SRC


** Tables

Tables are susceptible to becoming very wide and tall. I choose to
make big tables fit in a predetermined footprint so as not to disrupt
document flow. This ensures we can scroll to the following section
without having to scroll the entire table.

Using the ~block~ display property has the additional benefit of
displaying a black border around the table; this provides an
additional visual cue that we have reached the table's horizontal or
vertical extremity.

#+BEGIN_SRC css
  .big-table {
      display: block;
      max-height: 20em;
      max-width: 100%;
      overflow: auto;
      scrollbar-width: thin;
  }
  table caption {
      margin: 0.5em;
      /* background: steelblue; */
  }
#+END_SRC

I also want table headers to stick to the top of the table. This
serves as a useful reminder of the

#+BEGIN_SRC css
  thead {
      position: sticky;
      top: 0;
  }
#+END_SRC


** Images

#+BEGIN_SRC css
.figure img { max-width: 100%; min-width: 30%; }
#+END_SRC


*** TODO Hero images

#+BEGIN_SRC css
  /* .figure { style max-width: 100%; min-width: 30%; } */
#+END_SRC


** Workflow states

Here, we define styling for TODO, DONE and other workflow state
keywords.

#+BEGIN_SRC css
  .todo, .done {
      /* line-height: 1em; */
      font-weight: bold;
      padding: 0 0.2em;
      border-radius: 4px;
      display: inline-block;
  }
#+END_SRC


** Timestamps

<2022-02-14 Mon>--<2022-02-21 Mon>

#+BEGIN_SRC css
  .timestamp {
      display: inline-block;
      padding: 0 0.2em;
      border-radius: 8px;
      white-space: nowrap;
  }
#+END_SRC


** Anchor links

Because of the sticky header, we require all content that can be
jumped to on the page to appear at an offset below this header.

#+BEGIN_SRC css
  h1, h2,
  h3, h4,
  h5, h6,
  #table-of-contents,
  table { scroll-margin-top: 4rem; }
#+END_SRC


** Postamble

#+BEGIN_SRC css
  #postamble {
      width: 18em;
      margin: 1em auto;
      padding: 1em;
      border-radius: 8px;
  }
#+END_SRC


* Responsive top navigation bar

On wide screens, the top navigation bar contains links to the other
top-level website pages. On narrow screens, it contains buttons that
act as shortcuts to the website's home, the page's table of contents,
and links to the other top-level website pages which are accessible
via a hamburger menu.

#+NAME: navbar
#+BEGIN_SRC css
  #topnav {
      z-index: 100;
      position: sticky;
      top: 0;
  }
#+END_SRC


** Components

In this section, we define the appearance of the components contained
inside the top navigation bar.


*** Hamburger menu

As of 2022, hamburger menus are still a contentious topic among UX
designers. It was previously celebrated by mobile designers for its
compact appearance and now universally recognizable function, however,
studies by Google show increased user engagement with interfaces
displaying the possible links or actions as tabs at the bottom of the
interface. I like hamburgers and wanted to challenge my CSS design
skills, so I went with this menu implementation.

In the website's mobile version, the hamburger menu will capture the
top-level navigation links to declutter the top navigation bar.


**** Suppressing the menu checkbox

The checkbox used to toggle the menu is never displayed. We use the
~#hamburger~ and ~#shadow~ labels to toggle the menu instead.

#+BEGIN_SRC css
  #menu-toggle { display: none; }
#+END_SRC


**** Design

The hamburger menu is comprised of three ~div~ elements with class
~.line~ stacked on top of each other, with IDs ~#one~, ~#two~, and
~#three~ respectively.

#+BEGIN_SRC css
  #topnav #hamburger {
      position: absolute;
      right: 0;
      margin: 0.5em;
      padding: 0.5em;
      height: 1.5em;
      width: 1.5em;
      border-radius: 8px;
  }
  #topnav #hamburger .line {
      position: relative;
      height: 0.2em;
      width: 100%;
      margin: 0.2em auto;
      background: white;
      border-radius: 2px;
  }
#+END_SRC


**** Animation

Our juicy hamburger should transform into a cross when activated, and
regain its meaty appearance when deactivated. Modern CSS engines are
powerful enough to animate individual icon components, enabling richer
visuals effects and enhanced affordance cues.


***** Hamburger

#+BEGIN_SRC css
  #menu-toggle:not(:checked) ~ #hamburger #one {
      transform: translateY(0) rotate(0);
      transition: transform 0.2s;
  }
  #menu-toggle:not(:checked) ~ #hamburger #two {
      transition: opacity 0.2s;
      opacity: 1;
  }
  #menu-toggle:not(:checked) ~ #hamburger #three {
      transform: translateY(0) rotate(0);
      transition: transform 0.2s;
  }

#+END_SRC


***** Cross

#+BEGIN_SRC css
  #menu-toggle:checked ~ #hamburger #one {
      transform: translateY(0.4em) rotate(-45deg);
      transition: transform 0.2s;
  }
  #menu-toggle:checked ~ #hamburger #two {
      transition: opacity 0.2s;
      opacity: 0;
  }
  #menu-toggle:checked ~ #hamburger #three {
      transform: translateY(-0.4em) rotate(45deg);
      transition: transform 0.2s;
  }
#+END_SRC




*** Navigation buttons

These buttons appear in the website's narrow version. They present
useful shorcuts to the user, namely links to the homepage and to the
current page's table of contents.

#+BEGIN_SRC css
  #buttons {
      position: absolute;
      margin: 0.5em;
      padding: 0.5em 0;
  }
  .button {
      text-decoration: none;
      border-radius: 0 8px 8px 0;
      padding: 0.5em;
  }
#+END_SRC


** Wide screens


*** Top navigation links---wide

On wide screens, top-level links appears as a banner right under the
page title.

#+BEGIN_SRC css
  #topnav ul {
      display: flex;
      flex-direction: row;
      justify-content: center;
      position: relative;
      list-style-type: none;
      padding: 0.5em;
      margin: 0;
  }
  #topnav ul a {
      padding: 0.5em;
      text-decoration: none;
  }
#+END_SRC


*** Hide navigation buttons

When the top navigation bar is wide, the navigation buttons are hidden
from the viewport.

#+NAME: wide-hidden-buttons
#+BEGIN_SRC css
  #buttons {
      transform: translateX(-200%);
  }
#+END_SRC


*** Hide hamburger menu

The hamburger menu is tucked out of sight, to the right of the
viewport.

#+BEGIN_SRC css
  #hamburger {
      transform: translateX(200%);
  }
#+END_SRC


** Narrow screens

These styles apply to screens narrower than 500px.

#+BEGIN_SRC css :noweb no-export
  @media all and (max-width: 500px) {
      <<narrow-topnav>>
      <<narrow-buttons>>
      <<narrow-hamburger>>
      <<narrow-topnav-links>>
      <<narrow-topnav-menu-toggle>>
      <<narrow-topnav-shadow>>
      <<narrow-content>>
  }
#+END_SRC


*** Top navigation bar

#+NAME: narrow-topnav
#+BEGIN_SRC css :tangle no
  #topnav { height: 3.5em; }
#+END_SRC


*** Navigation buttons

On narrow screens, the navigation buttons become visible.

#+NAME: narrow-buttons
#+BEGIN_SRC css :tangle no
  #topnav #buttons {
      transform: translateX(0);
      transition: transform 1s;
  }
#+END_SRC


*** Hamburger icon

On narrow screens, the hamburger menu also becomes visible.

#+NAME: narrow-hamburger
#+BEGIN_SRC css :tangle no
  #topnav #hamburger {
      transform: translateX(0);
      transition: transform 1s;
  }
#+END_SRC


*** Clickable menu labels

Both the hamburger menu and the shadow cast when the menu is unfolded
should appear clickable to the user.

#+BEGIN_SRC css
  #hamburger, #shadow {
      cursor: pointer;
  }
#+END_SRC


*** TODO Top navigation links---narrow

The navigation links contained in the top banner are stacked into a
column, their visibility can be toggled thanks to the ~#hamburger~
label.

#+NAME: narrow-topnav-links
#+BEGIN_SRC css :tangle no
  #topnav ul {
      position: absolute;
      flex-direction: column;
      background: var(--topnav);
      height: calc(100vh - 3.5em);
      top: 3.5em;
      padding: 0 0.5em;
      justify-content: normal;
      overflow: auto;
  }
  #topnav ul a { display: block; }

#+END_SRC

Toggle appearance of the navigation menu.

#+NAME: narrow-topnav-menu-toggle
#+BEGIN_SRC css :tangle no
  #menu-toggle:not(:checked) ~ ul {
      transition: transform 0.5s;
      transform: translateX(-100%);
  }
  #menu-toggle:checked ~ ul {
      transition: transform 0.5s;
      transform: translateX(0);
  }
#+END_SRC


When the navigation menu is open, the area of the interface not
covered by the navigation links should be obscured. This affords a
larger ``quit'' area, this is more ergonomic for mobile users. This

#+NAME: narrow-topnav-shadow
#+BEGIN_SRC css :tangle no
  #shadow {
      display: block;
      position: absolute;
      height: calc(100vh - 3.5em);
      top: 3.5em;
      right: 0;
      width: 100%;
  }
  #topnav #menu-toggle:not(:checked) ~ #shadow {
      transition: opacity 0.5s;
      visibility: hidden;
      opacity: 0;
  }
  #topnav #menu-toggle:checked ~ #shadow {
      transition: opacity 0.5s;
      visibility: visible;
      opacity: 0.5;
  }
#+END_SRC


*** Narrow content

I'm gonna test the footnotes.[fn:1]

#+NAME: narrow-content
#+BEGIN_SRC css :tangle no
  #content > :not(.title, #topnav) { width: 90%; }
  #outline-container-main-content {
      flex-direction: column;
  }
#+END_SRC


* Footnotes

[fn:1] This footnote is just to test footnote appearance.