Out of the box a box with a border. In this template a tint without a border — enough to
separate, too little to interrupt. Set slightly smaller (0.9em), because the mono next to
the text face otherwise looks too big.
Blocks
The surface comes from the template, not from the syntax theme: keepBackground: false makes shiki
set only the character colours. Only that way does the block fit in both colour schemes.
Since 2026-09-05 it is lighter than the rest of the tint and has a token of its own
(--tpl-surface-code, #F1EFE9 in light mode, still lightgray in dark). A block is a large
area, and the tint that is right for one word of inline code turns twenty lines into a grey slab.
Measured, what it buys:
Colour
on the old surface
on the new one
Text (#24292E)
10.69 : 1
12.76 : 1
Blue (#005CC5)
4.59 : 1
5.47 : 1
Purple (#6F42C1)
4.75 : 1
5.66 : 1
Orange (#E36209)
2.54 : 1
3.04 : 1
It is paid for in separation: the surface now stands at 1.12 : 1 against the page ground instead of
1.34 : 1. That is why the block takes its border from --tpl-rule — exactly the colour its fill
used to be.
Five colours of the syntax theme are corrected
The lighter ground was not enough. So the count was made over the whole built site: every
--shiki-light and --shiki-dark value on all 333 pages, with its frequency and its contrast
against the code surface. Five pairs failed:
Every correction keeps the hue and the saturation and changes only the lightness — github-light
still reads as github-light. It is the same thing this template does with Quartz’s callout
colours.
They have been checked on every run since: --check-contrast reads the five values out of
content.scss and measures them against --tpl-surface-code. 78 pairs have become 83; with the thirteenth callout, no longer skipped since 2026-09-05, and two control borders, it is 93 today.
How that works technically
shiki writes the colour inline onto every single <span>
(style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"), and an inline declaration beats any
author rule that is not !important. So what is overridden is the variable, not color — then
Quartz’s own light/dark switch carries on doing what it should.
What this does not cover: a language whose tokens produce a tenth colour would arrive unmeasured.
The count is repeatable — grep --shiki-light: out of public/.
Long lines do not wrap, they scroll inside the block.
The language label
At the top left stands the language — as an ::after in the stylesheet, not as an element. So it
does not end up in a copy, nor in the reading order.
The copy button
Out of the box it appears only on hover with a pointer — on a smartphone it is therefore
unreachable.
In this template it appears on hover, on focus and permanently on devices without a
pointer (@media (hover: none)). It measures 44 px, while the symbol inside stays small. It is
hidden through opacity, never through display — otherwise it would not be there for the
keyboard at all.
And it is the icon alone: no border, no surface. Its state is the colour of the icon, from
gray to dark.
The exception to the layering rule
“Everything in custom.scss is unlayered and therefore beats the plugin styles” — true for
component CSS, not for resource stylesheets. Quartz ships this button’s styling in
static/resource-style-….css, unlayered and linked afterindex.css. At equal specificity the
later rule wins:
Measured on the built page: the button still reported a 1px border and --light behind it,
although every rule in this template said border: none and background: transparent. One
descendant in the selector (pre .clipboard-button) settles it.
Highlighted lines
Surface and a bar on the left. A tint alone is too weak on a block that is tinted anyway.
Which variables apply here
These 22 variables are read by the section body-code in content.scss. They can be changed in QuartzControl under Styles → Variables — without a line of CSS.
Variable
Value
also applies to
--codeFont
"Noto Sans Mono", ui-monospace, SFMono-Re…
4 other components
--dark
#17171A · dark #FCFCFA
13 other components
--darkgray
#333333 · dark #DDDDDD
18 other components
--gray
#5F5F5F · dark #A1A1A1
22 other components
--headerFont
"Noto Sans", system-ui, "Segoe UI", Robot…
15 other components
--secondary
#1463A3 · dark #699DC3
19 other components
--tpl-accent-bar
3px
6 other components
--tpl-motion
150ms ease
13 other components
--tpl-radius-md
8px
17 other components
--tpl-radius-sm
4px
10 other components
--tpl-rule
var(--lightgray) = #DDDDDD
19 other components
--tpl-rule-width
1px
25 other components
--tpl-space-2xs
0.25rem
16 other components
--tpl-space-lg
1.5rem
12 other components
--tpl-space-md
1rem
18 other components
--tpl-space-xs
0.5rem
20 other components
--tpl-surface
var(--lightgray) = #DDDDDD
6 other components
--tpl-surface-code
color-mix(in srgb, var(--lightgray) 40%, … · dark var(--lightgray)
only here
--tpl-surface-tint
var(--highlight) = rgba(42, 78, 108, 0.10)
14 other components
--tpl-target
44px
12 other components
--tpl-text-xs
0.78rem
10 other components
--tpl-tracking-caps
0.06em
6.4 – Variables, 3.1 – Bases
This table is generated: it is read out of the stylesheets rather than kept by hand.
Read on
This page belongs to Example — the example template for QuartzControl. An overview of every area is on the English home page.
Properties3
description
Inline, blocks, the language label and the copy button.
