Skip to content

fix/light-theme-surface-contrast #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ebouchut merged 2 commits into from
Jul 28, 2026
+40 −29
Merged

fix/light-theme-surface-contrast #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d393e98
fix(frontend): Darken Catppuccin light accents for surface text
ebouchut Jul 28, 2026
4895e8d
fix(frontend): Darken Soft Paper light primary and link for surface text
ebouchut Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 24 additions & 17 deletions docs/design/theme-exploration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,12 @@ Upstream palette: the official [Catppuccin palette](https://github.com/catppucci
AnuPpuccin, an Obsidian skin of Catppuccin (GPL-3.0); no AnuPpuccin code or
values are used, only the official Catppuccin palette, so the theme is named
after its real upstream. Pastel accents are designed for dark backgrounds,
so three light-mode values are darkened to pass 4.5:1.
so five light-mode values are darkened to pass 4.5:1. Accent tokens render
as text not only on `--color-bg` but also on the slightly darker
`--color-surface` (site header, flash alerts, cards); the surface is the
binding constraint, so "adjusted" values are tuned to clear 4.5:1 there
(the ratio noted in parentheses is what the replaced value scored on its
binding background).

| Token | Light (Latte) | Ratio on bg | Dark (Mocha) | Ratio on bg |
|---|---|---|---|---|
Expand All @@ -42,12 +47,12 @@ so three light-mode values are darkened to pass 4.5:1.
| `--color-border` | `#ccd0da` (surface0) | | `#313244` (surface0) | |
| `--color-text` | `#4c4f69` (text) | 7.06:1 | `#cdd6f4` (text) | 11.34:1 |
| `--color-text-muted` | `#5c5f77` (subtext1) | 5.53:1 | `#bac2de` (subtext1) | 9.26:1 |
| `--color-primary` | `#8839ef` (mauve) | 4.79:1 | `#cba6f7` (mauve) | 8.07:1 |
| `--color-primary` | `#8230e8` **(adjusted** from mauve `#8839ef`, 4.45:1 on surface**)** | 5.25:1 | `#cba6f7` (mauve) | 8.07:1 |
| `--color-link` | `#1a5cd7` **(adjusted** from blue `#1e66f5`, 4.34:1**)** | 5.22:1 | `#89b4fa` (blue) | 7.79:1 |
| `--color-success` | `#2f7a1f` **(adjusted** from green `#40a02b`, 2.96:1**)** | 4.73:1 | `#a6e3a1` (green) | 11.03:1 |
| `--color-success` | `#2c721d` **(adjusted** from green `#40a02b`, 2.96:1**)** | 5.26:1 | `#a6e3a1` (green) | 11.03:1 |
| `--color-warning` | `#8f5b08` **(adjusted** from yellow `#df8e1d`, 2.31:1**)** | 5.06:1 | `#f9e2af` (yellow) | 12.91:1 |
| `--color-error` | `#d20f39` (red) | 4.80:1 | `#f38ba8` (red) | 7.08:1 |
| `--color-on-primary` (button text) | `#ffffff` | 5.41:1 on primary | `#11111b` (crust) | 9.23:1 on primary |
| `--color-error` | `#c80e37` **(adjusted** from red `#d20f39`, 4.46:1 on surface**)** | 5.20:1 | `#f38ba8` (red) | 7.08:1 |
| `--color-on-primary` (button text) | `#ffffff` | 5.94:1 on primary | `#11111b` (crust) | 9.23:1 on primary |
| `--color-focus` | `#1e66f5` (blue, 3:1 UI requirement) | | `#89b4fa` (blue) | |

Character: fresh, slightly playful pastels; the mauve primary gives the
Expand All @@ -58,8 +63,10 @@ learning platform a distinctive identity without feeling corporate.
Upstream: [nickmilo/soft-paper](https://github.com/nickmilo/soft-paper)
(Obsidian theme). Interesting finding: Soft Paper is itself built on
Catppuccin variables; its light palette is a custom warm paper set and its
dark palette is essentially **Catppuccin Frappe**. Three light-mode
semantic colors are darkened to pass 4.5:1.
dark palette is essentially **Catppuccin Frappe**. Five light-mode
semantic colors are darkened to pass 4.5:1, with the same surface
constraint as Candidate A (the primary doubles as the link color here,
so one adjustment covers both tokens).

| Token | Light (paper) | Ratio on bg | Dark (Frappe) | Ratio on bg |
|---|---|---|---|---|
Expand All @@ -68,8 +75,8 @@ semantic colors are darkened to pass 4.5:1.
| `--color-border` | `#dcd3cb` | | `#414459` | |
| `--color-text` | `#575279` | 5.89:1 | `#c6ceef` | 7.90:1 |
| `--color-text-muted` | `#525252` | 6.32:1 | `#b5bddc` | 6.61:1 |
| `--color-primary` | `#286983` | 4.94:1 | `#8caaee` | 5.34:1 |
| `--color-link` | `#286983` | 4.94:1 | `#8caaee` | 5.34:1 |
| `--color-primary` | `#256278` **(adjusted** from `#286983`, 4.48:1 on surface**)** | 5.49:1 | `#8caaee` | 5.34:1 |
| `--color-link` | `#256278` **(adjusted** from `#286983`, 4.48:1 on surface**)** | 5.49:1 | `#8caaee` | 5.34:1 |
| `--color-success` | `#2f6a4a` **(adjusted** from `#3f7d5b`, 3.96:1**)** | 5.18:1 | `#67c48f` | 5.79:1 |
| `--color-warning` | `#7d570c` **(adjusted** from `#96690f`, 3.93:1**)** | 5.25:1 | `#c9be3e` | 6.40:1 |
| `--color-error` | `#94425a` **(adjusted** from `#a34e63`, 4.44:1**)** | 5.34:1 | `#e78284` | 4.65:1 |
Expand Down Expand Up @@ -97,21 +104,21 @@ verdict, lives in [palettes.html](palettes.html) (same generator,
```mermaid
flowchart LR
t0["bg<br/>#eff1f5"] ~~~ t1["surface<br/>#e6e9ef"] ~~~ t2["surface-deep<br/>#dce0e8"] ~~~ t3["border<br/>#ccd0da"] ~~~ t4["text<br/>#4c4f69"]
t5["text-muted<br/>#5c5f77"] ~~~ t6["primary<br/>#8839ef"] ~~~ t7["on-primary<br/>#ffffff"] ~~~ t8["link<br/>#1a5cd7"] ~~~ t9["success<br/>#2f7a1f"]
t10["warning<br/>#8f5b08"] ~~~ t11["error<br/>#d20f39"] ~~~ t12["focus<br/>#1e66f5"] ~~~ t13["primary-soft<br/>#eadcfd"] ~~~ t14["code-bg<br/>#1e1e2e"]
t5["text-muted<br/>#5c5f77"] ~~~ t6["primary<br/>#8230e8"] ~~~ t7["on-primary<br/>#ffffff"] ~~~ t8["link<br/>#1a5cd7"] ~~~ t9["success<br/>#2c721d"]
t10["warning<br/>#8f5b08"] ~~~ t11["error<br/>#c80e37"] ~~~ t12["focus<br/>#1e66f5"] ~~~ t13["primary-soft<br/>#eadcfd"] ~~~ t14["code-bg<br/>#1e1e2e"]
t15["code-text<br/>#cdd6f4"] ~~~ t16["code-keyword<br/>#cba6f7"] ~~~ t17["code-string<br/>#a6e3a1"] ~~~ t18["code-function<br/>#89b4fa"] ~~~ t19["code-comment<br/>#9399b2"]
style t0 fill:#eff1f5,stroke:#7f7f7f,color:#11111b
style t1 fill:#e6e9ef,stroke:#7f7f7f,color:#11111b
style t2 fill:#dce0e8,stroke:#7f7f7f,color:#11111b
style t3 fill:#ccd0da,stroke:#7f7f7f,color:#11111b
style t4 fill:#4c4f69,stroke:#7f7f7f,color:#f8f8f8
style t5 fill:#5c5f77,stroke:#7f7f7f,color:#f8f8f8
style t6 fill:#8839ef,stroke:#7f7f7f,color:#f8f8f8
style t6 fill:#8230e8,stroke:#7f7f7f,color:#f8f8f8
style t7 fill:#ffffff,stroke:#7f7f7f,color:#11111b
style t8 fill:#1a5cd7,stroke:#7f7f7f,color:#f8f8f8
style t9 fill:#2f7a1f,stroke:#7f7f7f,color:#f8f8f8
style t9 fill:#2c721d,stroke:#7f7f7f,color:#f8f8f8
style t10 fill:#8f5b08,stroke:#7f7f7f,color:#f8f8f8
style t11 fill:#d20f39,stroke:#7f7f7f,color:#f8f8f8
style t11 fill:#c80e37,stroke:#7f7f7f,color:#f8f8f8
style t12 fill:#1e66f5,stroke:#7f7f7f,color:#f8f8f8
style t13 fill:#eadcfd,stroke:#7f7f7f,color:#11111b
style t14 fill:#1e1e2e,stroke:#7f7f7f,color:#f8f8f8
Expand Down Expand Up @@ -157,7 +164,7 @@ flowchart LR
```mermaid
flowchart LR
t0["bg<br/>#eee6dd"] ~~~ t1["surface<br/>#e6dbd1"] ~~~ t2["surface-deep<br/>#ddd0c6"] ~~~ t3["border<br/>#dcd3cb"] ~~~ t4["text<br/>#575279"]
t5["text-muted<br/>#525252"] ~~~ t6["primary<br/>#286983"] ~~~ t7["on-primary<br/>#ffffff"] ~~~ t8["link<br/>#286983"] ~~~ t9["success<br/>#2f6a4a"]
t5["text-muted<br/>#525252"] ~~~ t6["primary<br/>#256278"] ~~~ t7["on-primary<br/>#ffffff"] ~~~ t8["link<br/>#256278"] ~~~ t9["success<br/>#2f6a4a"]
t10["warning<br/>#7d570c"] ~~~ t11["error<br/>#94425a"] ~~~ t12["focus<br/>#286983"] ~~~ t13["primary-soft<br/>#dfe9ec"] ~~~ t14["code-bg<br/>#303446"]
t15["code-text<br/>#c6ceef"] ~~~ t16["code-keyword<br/>#bb93d6"] ~~~ t17["code-string<br/>#67c48f"] ~~~ t18["code-function<br/>#8caaee"] ~~~ t19["code-comment<br/>#838ba7"]
style t0 fill:#eee6dd,stroke:#7f7f7f,color:#11111b
Expand All @@ -166,9 +173,9 @@ flowchart LR
style t3 fill:#dcd3cb,stroke:#7f7f7f,color:#11111b
style t4 fill:#575279,stroke:#7f7f7f,color:#f8f8f8
style t5 fill:#525252,stroke:#7f7f7f,color:#f8f8f8
style t6 fill:#286983,stroke:#7f7f7f,color:#f8f8f8
style t6 fill:#256278,stroke:#7f7f7f,color:#f8f8f8
style t7 fill:#ffffff,stroke:#7f7f7f,color:#11111b
style t8 fill:#286983,stroke:#7f7f7f,color:#f8f8f8
style t8 fill:#256278,stroke:#7f7f7f,color:#f8f8f8
style t9 fill:#2f6a4a,stroke:#7f7f7f,color:#f8f8f8
style t10 fill:#7d570c,stroke:#7f7f7f,color:#f8f8f8
style t11 fill:#94425a,stroke:#7f7f7f,color:#f8f8f8
Expand Down
18 changes: 10 additions & 8 deletions src/main/resources/static/css/theme-catppuccin.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@
Palette: Catppuccin Latte (light) / Mocha (dark), official values from
https://github.com/catppuccin/palette
Values marked "adjusted" are darkened from upstream to reach the WCAG 2.1
AA contrast ratio of 4.5:1 on --color-bg; every pair is documented with
its computed ratio in docs/design/theme-exploration.md
AA contrast ratio of 4.5:1 on every background they sit on as text:
--color-bg AND the slightly darker --color-surface (header, flash alerts,
cards). Every pair is documented with its computed ratio in
docs/design/theme-exploration.md
Both themes define the SAME token names: switching theme = swapping the
<link> to theme-soft-paper.css (no runtime switcher in v1).
*/
Expand All @@ -19,12 +21,12 @@
--color-border: #ccd0da; /* surface0 */
--color-text: #4c4f69; /* text, 7.06:1 */
--color-text-muted: #5c5f77; /* subtext1, 5.53:1 */
--color-primary: #8839ef; /* mauve, 4.79:1 */
--color-on-primary: #ffffff; /* 5.41:1 on primary */
--color-link: #1a5cd7; /* adjusted from blue #1e66f5, 5.22:1 */
--color-success: #2f7a1f; /* adjusted from green #40a02b, 4.73:1 */
--color-warning: #8f5b08; /* adjusted from yellow #df8e1d, 5.06:1 */
--color-error: #d20f39; /* red, 4.80:1 */
--color-primary: #8230e8; /* adjusted from mauve #8839ef, 4.88:1 on surface */
--color-on-primary: #ffffff; /* 5.94:1 on primary */
--color-link: #1a5cd7; /* adjusted from blue #1e66f5, 4.86:1 on surface */
--color-success: #2c721d; /* adjusted from green #40a02b, 4.89:1 on surface */
--color-warning: #8f5b08; /* adjusted from yellow #df8e1d, 4.71:1 on surface */
--color-error: #c80e37; /* adjusted from red #d20f39, 4.83:1 on surface */
--color-focus: #1e66f5; /* blue, UI 3:1 requirement */
--color-primary-soft: #eadcfd; /* decorative wash behind hero art */

Expand Down
10 changes: 6 additions & 4 deletions src/main/resources/static/css/theme-soft-paper.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
theme): custom warm paper light palette; the dark side is essentially
Catppuccin Frappe.
Values marked "adjusted" are darkened from upstream to reach WCAG 2.1 AA
4.5:1 on --color-bg; ratios documented in docs/design/theme-exploration.md
4.5:1 on every background they sit on as text: --color-bg AND the darker
--color-surface (header, flash alerts, cards); ratios documented in
docs/design/theme-exploration.md
Same token names as theme-catppuccin.css: to activate this theme, point
the <link> in the page head at this file instead.
*/
Expand All @@ -19,9 +21,9 @@
--color-border: #dcd3cb;
--color-text: #575279; /* 5.89:1 */
--color-text-muted: #525252; /* 6.32:1 */
--color-primary: #286983; /* 4.94:1 */
--color-on-primary: #ffffff; /* 6.11:1 on primary */
--color-link: #286983; /* 4.94:1 */
--color-primary: #256278; /* adjusted from #286983, 4.98:1 on surface */
--color-on-primary: #ffffff; /* 6.78:1 on primary */
--color-link: #256278; /* adjusted from #286983, 4.98:1 on surface */
--color-success: #2f6a4a; /* adjusted from #3f7d5b, 5.18:1 */
--color-warning: #7d570c; /* adjusted from #96690f, 5.25:1 */
--color-error: #94425a; /* adjusted from #a34e63, 5.34:1 */
Expand Down