Intergrate tiddlywiki palette colors and settings to custom CSS properties (#9333)

* Expose tiddlywiki palette colors and settings to custom CSS properties * Rename & use --tc prefix * Add colors and CSS settings * Make CSS settings properties' name readable * Add all CSS settings * Add all palette colors * Remove macrocallblock rule * Indent with tabs * Use --tc-color prefix * Update docs * Use --tpc prefix * Add change note * Simplify palette color rules with list widget * Update docs * Hardcode custom properties * Update docs * Remove cascades * Update docs * Add more docs * Update docs * Update docs * Add --tp-animation-duration * Update change note The previous example actually doesn't work at all * Update docs about limits of CSS variables
2026-09-10 11:59:13 +00:00 · 2026-02-04 11:37:04 +00:00
parent d15398fc09
commit b236373064
22 changed files with 305 additions and 0 deletions
@@ -0,0 +1,30 @@
+title: $:/core/stylesheets/custom-properties
+
+\rules only transcludeinline macrocallinline html transcludeblock
+
+/* Tiddlywiki's CSS properties */
+
+:root {
+	<$list filter="[[$:/palettes/Vanilla]indexes[]]">
+	--tpc-<<currentTiddler>>: <$transclude $variable="colour" $mode="inline" name=<<currentTiddler>>/>;
+	</$list>
+
+	/* CSS settings */
+	--tp-code-wrapping: {{$:/themes/tiddlywiki/vanilla/options/codewrapping}};
+	--tp-font-family: {{$:/themes/tiddlywiki/vanilla/settings/fontfamily}};
+	--tp-code-font-family: {{$:/themes/tiddlywiki/vanilla/settings/codefontfamily}};
+	--tp-editor-font-family: {{$:/themes/tiddlywiki/vanilla/settings/editorfontfamily}};
+	--tp-font-size: {{$:/themes/tiddlywiki/vanilla/metrics/fontsize}};
+	--tp-line-height: {{$:/themes/tiddlywiki/vanilla/metrics/lineheight}};
+	--tp-body-font-size: {{$:/themes/tiddlywiki/vanilla/metrics/bodyfontsize}};
+	--tp-body-line-height: {{$:/themes/tiddlywiki/vanilla/metrics/bodylineheight}};
+	--tp-story-left: {{$:/themes/tiddlywiki/vanilla/metrics/storyleft}};
+	--tp-story-top: {{$:/themes/tiddlywiki/vanilla/metrics/storytop}};
+	--tp-story-right: {{$:/themes/tiddlywiki/vanilla/metrics/storyright}};
+	--tp-story-width: {{$:/themes/tiddlywiki/vanilla/metrics/storyrwidth}};
+	--tp-tiddler-width: {{$:/themes/tiddlywiki/vanilla/metrics/tiddlerwidth}};
+	--tp-sidebar-breakpoint: {{$:/themes/tiddlywiki/vanilla/metrics/sidebarbreakpoint}};
+	--tp-sidebar-width: {{$:/themes/tiddlywiki/vanilla/metrics/sidebarwidth}};
+
+	--tp-animation-duration: {{{ [{$:/config/AnimationDuration}addsuffix[ms]] }}};
+}
@@ -8,6 +8,8 @@ code-body: yes

 <$set name="languageTitle" value={{!!name}}>

+<$transclude $tiddler="$:/core/stylesheets/custom-properties" $mode="block"/>
+
 <$list filter="[all[shadows+tiddlers]tag[$:/tags/Stylesheet]!has[draft.of]]">
 <$transclude mode="block"/>
 </$list>
@@ -0,0 +1,11 @@
+created: 20251108075028089
+modified: 20260130070027124
+tags: Reference
+title: Core CSS Variables
+type: text/vnd.tiddlywiki
+
+<<.from-version 5.4.0>> Tiddlywiki CSS variable definitions starts with `--tp-*` and `--tpc-*`. They are mainly used to [[Write stylesheets in vanilla CSS|Writing stylesheets in vanilla CSS]]. These prefixes ''are reserved'' for Tiddlywiki, so it should not be used for user defined CSS variables. It is also not recommended to override these core CSS variables.
+
+Core CSS variables are defined in [[$:/core/stylesheets/custom-properties]].
+
+<<list-links "[tag[Core CSS Variables]]" class:"multi-columns">>
@@ -0,0 +1,69 @@
+created: 20251108075645447
+modified: 20260201043953311
+title: Writing stylesheets in vanilla CSS
+type: text/vnd.tiddlywiki
+
+<<.from-version 5.4.0>> Before v5.4.0, theme developers have to mix wikitext syntax with CSS syntax when writing stylesheets to intergrate Tiddlywiki color palettes and theme settings. With the introduction of [[Core CSS Variables]] in v5.4.0, theme developers can intergrate most Tiddlywiki palettes with vanilla CSS.
+
+! Getting Tiddlywiki palette colors
+Tiddlywiki's custom properties for colors are prefixed `--tpc-`. Before v5.4.0, theme developers have to use the following wikitext to get a color value of a palette:
+
+```
+.tag {
+	background: <<colour tag-background>>;
+}
+```
+
+Since v5.4.0, theme developers can use the following CSS to get the palette color:
+
+```css
+.tag {
+	background: var(--tp-color-tag-background);
+}
+```
+
+! Getting and processing Tiddlywiki CSS settings
+See [[Core CSS Variables]] for the available CSS variables. Before v5.4.0, theme developers have to use macros with filters to get and process theme settings:
+
+```
+.tc-sidebar-header {
+	padding: 14px;
+	min-height: 32px;
+	margin-top: {{$:/themes/tiddlywiki/vanilla/metrics/storytop}};
+	transition:  min-height {{$:/config/AnimationDuration}}ms ease-in-out, padding-top {{$:/config/AnimationDuration}}ms ease-in-out, padding-bottom {{$:/config/AnimationDuration}}ms ease-in-out;
+}
+```
+
+Since v5.4.0, the theme settings are also available as the CSS variables, so theme developers can use the following code:
+
+```css
+.tc-sidebar-header {
+	padding: 14px;
+	min-height: 32px;
+	margin-top: var(--tp-story-top);
+	transition: min-height var(--tp-animation-duration) ease-in-out, padding-top var(--tp-animation-duration) ease-in-out, padding-bottom var(--tp-animation-duration) ease-in-out;
+}
+```
+
+! Limits
+CSS variables can only be used in rules, while wikitext can be used everywhere. See this example:
+
+Old way of using wikitext in media query definitions:
+
+```
+\define sidebarbreakpoint()
+<$text text={{$:/themes/tiddlywiki/vanilla/metrics/sidebarbreakpoint}}/>
+\end
+
+@media (min-width: <<sidebarbreakpoint>>) {
+	/* CSS rules */
+}
+```
+
+While using CSS variables in media quert definitions doesn't work at all:
+
+```css
+@media (min-width: var(--tp-sidebar-breakpoint)) {
+	/* Doesn't work */
+}
+```
@@ -0,0 +1,8 @@
+caption: --tp-animation-duration
+created: 20260130075755351
+modified: 20260130075855780
+tags: [[Core CSS Variables]]
+title: --tp-animation-duration CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-animation-duration` CSS variable represents the "Animation duration" setting in the control panel. The `ms` suffix is added.
@@ -0,0 +1,8 @@
+caption: --tp-body-font-size
+created: 20260122111308483
+modified: 20260130045633904
+tags: [[Core CSS Variables]]
+title: --tp-body-font-size CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-body-font-size` CSS variable represents the "Font size for tiddler body" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-body-line-height
+created: 20260122111249446
+modified: 20260130045720240
+tags: [[Core CSS Variables]]
+title: --tp-body-line-height CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-body-line-height` CSS variable represents the "Line height for tiddler body" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-code-font-family
+created: 20260122110850673
+modified: 20260130045333134
+tags: [[Core CSS Variables]]
+title: --tp-code-font-family CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-code-font-family` CSS variable represents the "Code font family" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-code-wrapping
+created: 20260122110618231
+modified: 20260130045345387
+tags: [[Core CSS Variables]]
+title: --tp-code-wrapping CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-code-wrapping` CSS variable represents the "Wrap long lines in code blocks" setting in Theme Tweaks. Its value is `pre` when the setting is set to "No", and `pre-wrap` when set to "Yes".
@@ -0,0 +1,8 @@
+caption: --tp-editor-font-family
+created: 20260122110858791
+modified: 20260130045422071
+tags: [[Core CSS Variables]]
+title: --tp-editor-font-family CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-editor-font-family` CSS variable represents the "Editor font family" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-font-family
+created: 20260122110741282
+modified: 20260130045301357
+tags: [[Core CSS Variables]]
+title: --tp-font-family CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-font-family` CSS variable represents the "Font family" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-font-size
+created: 20260122110956954
+modified: 20260130045455466
+tags: [[Core CSS Variables]]
+title: --tp-font-size CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-font-size` CSS variable represents the "Font size" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-line-height
+created: 20260122111115266
+modified: 20260130045757204
+tags: [[Core CSS Variables]]
+title: --tp-line-height CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-line-height` CSS variable represents the "Line height" setting in Theme Tweaks.
@@ -0,0 +1,8 @@
+caption: --tp-sidebar-breakpoint
+created: 20260130065756457
+modified: 20260130065841355
+tags: [[Core CSS Variables]]
+title: --tp-sidebar-breakpoint CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-sidebar-breakpoint` CSS variable represents the minimum page width at which the story river and sidebar will appear side by side.
@@ -0,0 +1,8 @@
+caption: --tp-sidebar-width
+created: 20260130065850825
+modified: 20260130065925595
+tags: [[Core CSS Variables]]
+title: --tp-sidebar-width CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-sidebar-width` CSS variable represents the width of the sidebar in fluid-fixed layout.
@@ -0,0 +1,8 @@
+caption: --tp-story-left
+created: 20260130065252380
+modified: 20260130065342364
+tags: [[Core CSS Variables]]
+title: --tp-story-left CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-story-left` CSS variable represents how far the left margin of the story river (tiddler area) is from the left of the page.
@@ -0,0 +1,8 @@
+caption: --tp-story-right
+created: 20260130065417448
+modified: 20260130065457358
+tags: [[Core CSS Variables]]
+title: --tp-story-right CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-story-right` CSS variable represents how far the left margin of the sidebar is from the left of the page.
@@ -0,0 +1,8 @@
+caption: --tp-story-top
+created: 20260130065351753
+modified: 20260130065451132
+tags: [[Core CSS Variables]]
+title: --tp-story-top CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-story-top` CSS variable represents how far the top margin of the story river is from the top of the page.
@@ -0,0 +1,8 @@
+caption: --tp-story-width
+created: 20260130065510314
+modified: 20260130065552027
+tags: [[Core CSS Variables]]
+title: --tp-story-width CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-story-width` CSS variable represents the overall width of the story river.
@@ -0,0 +1,8 @@
+caption: --tp-tiddler-width
+created: 20260130065558913
+modified: 20260130065746707
+tags: [[Core CSS Variables]]
+title: --tp-tiddler-width CSS Variable
+type: text/vnd.tiddlywiki
+
+The `--tp-tiddler-width` CSS variable represents the tiddler width within the story river.
@@ -0,0 +1,16 @@
+caption: --tpc-*
+created: 20260122104142525
+modified: 20260122104847331
+tags: [[Core CSS Variables]]
+title: --tpc-* CSS Variables
+type: text/vnd.tiddlywiki
+
+`--tpc-*` variables are CSS variables of palette colors. They can be accessed via appending the palette color names to the bottom. For example:
+
+```css
+.code {
+	background-color: var(--tpc-code-background);
+	color: var(--tpc-code-foreground);
+}
+```
+
@@ -0,0 +1,49 @@
+title: $:/changenotes/5.4.0/#9333
+description: Intergrate Tiddlywiki palette colors and settings to custom CSS properties
+release: 5.4.0
+tags: $:/tags/ChangeNote
+change-type: feature
+change-category: developer
+github-links: https://github.com/TiddlyWiki/TiddlyWiki5/pull/9333
+github-contributors: Leilei332
+
+Adds `--tpc-*` (for palettes colors) and `--tp-*` (for CSS settings) [[custom CSS properties|https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/--*]] to allow writing stylesheets with vanilla CSS, for example:
+
+```
+/* Old way to get a palette color, which requires using wikitext */
+.tag {
+	background: <<colour tag-background>>;
+}
+```
+
+```css
+/* New way to get a palette color without wikitext */
+.tag {
+	background: var(--tp-color-tag-background);
+}
+```
+
+```
+/* Old way to get CSS settings with transclusion */
+.tc-sidebar-header {
+	padding: 14px;
+	min-height: 32px;
+	margin-top: {{$:/themes/tiddlywiki/vanilla/metrics/storytop}};
+	transition:  min-height {{$:/config/AnimationDuration}}ms ease-in-out, padding-top {{$:/config/AnimationDuration}}ms ease-in-out, padding-bottom {{$:/config/AnimationDuration}}ms ease-in-out;
+}
+```
+
+```css
+/* New way to get CSS settings */
+.tc-sidebar-header {
+	padding: 14px;
+	min-height: 32px;
+	margin-top: var(--tp-story-top);
+	transition: min-height var(--tp-animation-duration) ease-in-out, padding-top var(--tp-animation-duration) ease-in-out, padding-bottom var(--tp-animation-duration) ease-in-out;
+}
+```
+
+See:  
+
+* [[Writing stylesheets in vanilla CSS]] and [[Core CSS Variables]] for details.  
+* https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/var