主題
Siren 圖表的外觀全部來自 42 個 CSS 自訂屬性,叫做設計 token,名稱都是 --siren-*。這 42 個 token 各取一個值,就是一份主題。換主題不必改文件,也不必寫程式:重新宣告這些 token 就好。
主題只管圖表本身。頁面的背景和 board 的控制列不歸它管;控制列有自己的 --siren-board-* token。
設計 token
下表的預設值是 Siren 內建的那一套,也就是網站淺色模式下看到的樣子。
顏色
| Token | 用途 | 預設值 |
|---|---|---|
--siren-node-fill |
節點、class、participant、state 等方框的底色 | #f3efff |
--siren-node-stroke |
方框的外框 | #6d3fd6 |
--siren-node-text |
圖表裡的文字 | #1d1730 |
--siren-edge-stroke |
連線、箭頭與訊息線 | #6f6a84 |
--siren-highlight-color |
highlight 的 outline 與 glow 用的強調色 |
#0d9488 |
--siren-label-link |
label 裡連結(<a href>)的文字顏色 |
#0000ee |
--siren-label-mark-fill |
label 裡標記文字(<mark>)的底色 |
#ff0 |
--siren-label-mark-text |
那塊底色上的文字顏色 | #000 |
--siren-edge-label-fill |
連線標籤的底色,線從標籤底下經過時不會劃過文字 | rgb(255 255 255 / 0.8) |
--siren-subgraph-fill |
flowchart subgraph、ER subgraph 與複合 state 外框的底色 | none |
文字
| Token | 用途 | 預設值 |
|---|---|---|
--siren-font-family |
字型 | system-ui, sans-serif |
--siren-font-size |
一般文字大小 | 14px |
--siren-title-font-size |
圖表標題(title)的大小 |
18px |
--siren-label-font-size |
次要文字:自動編號、區塊的種類與條件 | 12px |
線條
| Token | 用途 | 預設值 |
|---|---|---|
--siren-stroke-width |
外框與連線的粗細 | 1.5 |
--siren-highlight-stroke-width |
outline 強調時的外框粗細 |
3 |
--siren-edge-thick-stroke-width |
粗連線(==>)的粗細;預設是一般粗細的兩倍 |
calc(var(--siren-stroke-width) * 2) |
--siren-lifeline-dash |
序列圖生命線的虛線樣式 | 4 4 |
--siren-edge-dash |
虛線連線(-.->)的虛線樣式 |
4 3 |
--siren-note-link-dash |
註解連到元素的虛線樣式 | 4 4 |
形狀
| Token | 用途 | 預設值 |
|---|---|---|
--siren-node-border-radius |
矩形與 subroutine 節點的圓角;其他形狀不受影響 | 6px |
--siren-box-fill-opacity |
序列圖 box 底色的不透明度 |
0.35 |
動畫
| Token | 用途 | 預設值 |
|---|---|---|
--siren-fade-duration |
fade 進場、退場的時間 |
600ms |
--siren-slide-duration |
slide-* 進場、退場的時間 |
500ms |
--siren-slide-distance |
slide-* 移動的距離 |
60px |
--siren-highlight-duration |
highlight 生效的時間 |
300ms |
--siren-edge-march-dash |
動態連線(e1@{ animate: true })流動的虛線樣式 |
9 5 |
--siren-edge-march-offset |
流動一輪移動虛線的距離 | 900 |
--siren-edge-march-fast-duration |
快速動態連線流動一輪的時間 | 20s |
--siren-edge-march-slow-duration |
慢速動態連線流動一輪的時間 | 50s |
甘特圖
一般 task 的長條就是節點,用 --siren-node-fill 和 --siren-node-stroke;task 文字、section 標題和刻度文字都用 --siren-node-text。下表的 token 畫的是只有甘特圖才有的部分。
| Token | 用途 | 預設值 |
|---|---|---|
--siren-gantt-band-fill |
第一、第三個 section 的 task 底下的列帶,之後的 section 依此類推 | #f7f4ff |
--siren-gantt-band-alt-fill |
夾在中間的 section 的列帶,和上一個交替 | #ffffff |
--siren-gantt-grid-stroke |
時間軸每個刻度上的直向格線 | #e4e1ec |
--siren-gantt-active-fill |
active task 長條的底色 |
#ddd0ff |
--siren-gantt-active-stroke |
active task 長條的外框 |
#6d3fd6 |
--siren-gantt-done-fill |
done task 長條的底色 |
#e6e4ec |
--siren-gantt-done-stroke |
done task 長條的外框 |
#6f6a84 |
--siren-gantt-crit-fill |
crit task 長條的底色 |
#ffe0e6 |
--siren-gantt-crit-stroke |
crit task 長條的外框;同時是 crit 的 active、done task 也用它當外框 |
#d6336c |
--siren-gantt-today-stroke |
標出今天的那條線 | #d6336c |
--siren-gantt-exclude-fill |
excludes 排除的日子(例如週末) |
#eeecf3 |
--siren-gantt-vert-stroke |
vert 標記的線和它的文字 |
#4b3fa8 |
風格
網站畫的每一張圖,不是在一個風格下,就是在一份自訂主題下。風格是網站自己的一套外觀:有淺色、深色兩套值,跟著網站頁首的淺色/深色切換,每一套都是 42 個設計 token 加上網站自己的 36 個分類色與角色色。風格是鎖定的,誰都不能修改。網站有好幾個風格,各自有自己的顏色、線條和動畫;預設的叫 Siren,就是這個網站紫色的樣子。新來的訪客看到的圖都在 Siren 風格下,首頁 demo 和範例頁也永遠畫 Siren。這一頁的說明和數值都以 Siren 為例,其他風格的規則相同,只是值不一樣。
文件可以用 Mermaid 的 style、classDef/class/:::name 和 linkStyle 替自己的元素寫樣式。在風格下,風格接管作者寫的這些屬性:fill、stroke、color、stroke-width、stroke-dasharray、stroke-dashoffset、stroke-linecap、stroke-linejoin、stroke-opacity、fill-opacity、opacity、font-weight、font-style、font-size、font-family、rx、ry、filter、text-decoration、letter-spacing;這張清單是固定的,不能調整。每一組作者上過色的元素改用風格的分類色與角色色重新上色,整張圖因此都在風格裡。作者沒有寫樣式的元素,照 token 畫。選了自訂主題也一樣:它接管同一張清單,改用它自己的分類色與角色色重新上色。甘特圖 todayMarker 後面寫的樣式也一樣被接管,但不算色組、不重新上色:今日線一律照 --siren-gantt-today-stroke 畫。
風格怎麼保留作者的意思
作者的顏色是有意思的:一塊 classDef error、三個塗成同一種琥珀色的節點。風格把這些意思留成色組,每一組各給一個自己的顏色:
- 具名分類:一個有給 fill 或 stroke 的
classDef,加上它上色的元素。只設粗細或字重的 class 不算。 - 匿名色組:顏色來自
style或linkStyle、正規化之後是同一個顏色的所有元素:#f00、red、rgb(255,0,0)是同一組。分組看 fill,沒有 fill 才看 stroke。 - class 名稱在語意角色詞彙表裡的具名分類會自動拿到角色,不分大小寫:error(也接受
danger、fail、failure、critical)、warning(warn、caution)、success(ok、pass、done)、info(note、hint)。角色從不看顏色推斷:紅色不等於 error。 - 有角色的色組用那個角色色。其餘每一組用色相最接近作者顏色的那個分類色(比的是目前風格在網站當下模式那一套的分類色,切換淺色、深色會重新配一次;選的是自訂主題時,比的是它自己的分類色,不跟模式);分類色有八個,還有空的時候,兩組不會共用同一個。八個都用掉之後,一組拿到的是衍生色,也就是最接近的分類色調亮或調暗的變化,圖表顏色分頁會提示分類太多了。
Playground 主題面板的第三個分頁圖表顏色列出每一組和它分到的顏色,風格下和自訂主題下都一樣:最上面是目前的風格或自訂主題,底下分成 Class(具名分類)和直接上色(匿名色組)兩段,每一組一張卡片,直接上色的色組會並排顯示作者的原色和它換成的顏色。在這裡可以設定或取消一組的角色、合併兩個匿名色組再拆開,以及清掉圖上已經找不到目標的顏色設定。每一次確認的改動都立刻寫進文件 frontmatter 最上層的 siren: 底下,算一次編輯(Ctrl+Z 可以還原);文件其他部分一個字都不動。拿掉這個 key,文件仍然是同一份 Mermaid。
siren:
groups:
- match: [stage]
role: info
寫在 label 自己標記裡的顏色(<span style="color:…">、<font color>、background-color)不會被接管:在風格下和自訂主題下都照原樣畫。
分類色與角色色
風格的每一套值,除了 42 個設計 token,還帶 8 個分類色和 4 個角色色,各有底色、外框、文字三個值:共 36 個值,名稱都是 --sirenchart-*。每個風格的分類色各自挑選,色相不一定相同。下表是 Siren 風格的淺色那一套;要看深色那一套,可以把網站切到深色模式,在 Playground 從 Siren 風格新增一份自訂主題再下載,主題檔裡就有。風格的這些顏色誰都不能修改。每一份自訂主題也有自己的一套 36 個值,名稱相同,只有一套、不跟網站的淺色/深色切換,可以在自訂分頁逐色調整。在網站更早的版本建立、還沒有這些顏色的自訂主題,缺的顏色會一個一個補上:舊版網站若在主題的 token 裡存了一份,就用那一份;否則看它的節點底色(--siren-node-fill)在亮度上比較接近 Siren 風格淺色還是深色那一套的節點底色,補上那一套的值;節點底色不是顏色時補淺色那一套。
| Token | 用途 | 淺色預設值 |
|---|---|---|
--sirenchart-category-1-fill |
分類色 1(紅):底色 | #fee2e2 |
--sirenchart-category-1-stroke |
分類色 1(紅):外框 | #dc2626 |
--sirenchart-category-1-text |
分類色 1(紅):文字 | #7f1d1d |
--sirenchart-category-2-fill |
分類色 2(橙):底色 | #ffedd5 |
--sirenchart-category-2-stroke |
分類色 2(橙):外框 | #ea580c |
--sirenchart-category-2-text |
分類色 2(橙):文字 | #7c2d12 |
--sirenchart-category-3-fill |
分類色 3(黃):底色 | #fef9c3 |
--sirenchart-category-3-stroke |
分類色 3(黃):外框 | #a16207 |
--sirenchart-category-3-text |
分類色 3(黃):文字 | #713f12 |
--sirenchart-category-4-fill |
分類色 4(綠):底色 | #dcfce7 |
--sirenchart-category-4-stroke |
分類色 4(綠):外框 | #15803d |
--sirenchart-category-4-text |
分類色 4(綠):文字 | #14532d |
--sirenchart-category-5-fill |
分類色 5(青):底色 | #ccfbf1 |
--sirenchart-category-5-stroke |
分類色 5(青):外框 | #0d9488 |
--sirenchart-category-5-text |
分類色 5(青):文字 | #134e4a |
--sirenchart-category-6-fill |
分類色 6(天藍):底色 | #e0f2fe |
--sirenchart-category-6-stroke |
分類色 6(天藍):外框 | #0284c7 |
--sirenchart-category-6-text |
分類色 6(天藍):文字 | #0c4a6e |
--sirenchart-category-7-fill |
分類色 7(靛):底色 | #e0e7ff |
--sirenchart-category-7-stroke |
分類色 7(靛):外框 | #4f46e5 |
--sirenchart-category-7-text |
分類色 7(靛):文字 | #312e81 |
--sirenchart-category-8-fill |
分類色 8(粉紅):底色 | #fce7f3 |
--sirenchart-category-8-stroke |
分類色 8(粉紅):外框 | #db2777 |
--sirenchart-category-8-text |
分類色 8(粉紅):文字 | #831843 |
--sirenchart-role-error-fill |
error 角色:底色 | #fecaca |
--sirenchart-role-error-stroke |
error 角色:外框 | #b91c1c |
--sirenchart-role-error-text |
error 角色:文字 | #450a0a |
--sirenchart-role-warning-fill |
warning 角色:底色 | #fde68a |
--sirenchart-role-warning-stroke |
warning 角色:外框 | #b45309 |
--sirenchart-role-warning-text |
warning 角色:文字 | #451a03 |
--sirenchart-role-success-fill |
success 角色:底色 | #bbf7d0 |
--sirenchart-role-success-stroke |
success 角色:外框 | #15803d |
--sirenchart-role-success-text |
success 角色:文字 | #052e16 |
--sirenchart-role-info-fill |
info 角色:底色 | #bfdbfe |
--sirenchart-role-info-stroke |
info 角色:外框 | #1d4ed8 |
--sirenchart-role-info-text |
info 角色:文字 | #172554 |
Siren 的分類色依色相排列,從紅到粉紅,所以一組最接近的分類色就是看起來最像作者顏色的那個。Siren core 本身不讀這些值:它們是網站的,只在網站於風格或自訂主題下重新上色時用到。
在 Playground 換主題
Playground 左側的圖示列可以切換到主題,上方有三個分頁。圖示列最底下的按鈕可以把左欄收到只剩圖示列,讓預覽佔滿畫面;按任何一個圖示就會展開到那個分頁。
主題庫列出可以選的,每一份旁邊有它五個顏色的色塊,分成兩段:
- 預設風格:網站的風格,每個底下一句說明它的樣子。風格都跟著網站的淺色/深色切換,而且是鎖定的:不能重新命名、複製、下載或刪除,列上也沒有這些按鈕。新來的訪客選的是 Siren。
- 自訂主題:你自己的主題,有名字,存在這個瀏覽器裡;建立第一份之後才會出現這一段。選了其中一份,網站切換淺色、深色都不會改變圖表;它和風格一樣接管文件寫的樣式,用自己的分類色與角色色重新上色,從匯出面板匯出時也會用它。
每一份自訂主題那一列的右邊有四個圖示按鈕,按了就作用在那一列,不必先選中它,也不會改變選中的是哪一份:
- 重新命名:那一列變成名稱輸入框,按 Enter 或點到別處就確定,按 Escape 取消。
- 複製:在原本那份後面多一份「X 的副本」,並選中它。
- 下載:把那一份存成主題檔,見下一節。
- 刪除:用警示色,會先問過你;刪掉正在用的主題,圖表就回到 Siren 風格。
主題庫底下有一排按鈕:
- 新增:從選中的風格(沒選就是預設的 Siren)目前模式(淺色或深色)那一套的 42 個 token 和 36 個分類色與角色色開始,建立「我的主題」(已經有了就是「我的主題 2」,依此類推)。
- 上傳:選一個主題檔,新增成一份自訂主題,見下一節。隨時都可以按。
自訂分頁逐項調整目前選中的自訂主題,42 個 token 分成顏色、文字、線條、形狀、動畫、甘特圖六個群組,後面再接分類色、角色色兩組:每個顏色一列,有底色、外框、文字三個色票,旁邊一個小節點顯示它的樣子。預覽會立刻跟著變;也可以「從淺色開始」或「從深色開始」整份重來(會先問過你),token 和分類色、角色色一起換成 Siren 風格的那一套。選的是風格時,這裡只說明風格不能修改,按「以此建立」就會從它新增一份自訂主題開始改。
圖表顏色分頁就是上面風格一節說的那個:每一個色組和它分到的顏色。選的是自訂主題時也一樣列出來,用的是那份自訂主題自己的顏色。這裡沒有任何開關。
Playground 裡不能直接編輯 CSS。想用 CSS 寫主題,就寫好一個主題檔再上傳,見下一節。
主題檔(.siren.css)
按自訂主題那一列的下載,就會把那一份存成一個 .siren.css 檔,檔名就是主題的名字(名字裡不能放進檔名的 \ / : * ? " < > | 換成 -)。內容是一般的 CSS:開頭一段註解,接著 :root 底下 78 個宣告,先是 42 個 --siren-* 設計 token,再來是分類色和角色色各一段。從 Siren 風格淺色那一套新增、還沒改過的主題,下載下來大致是:
/* 開頭的說明:在 siren-core/theme.css 之後載入;--sirenchart-* 只有 Siren Playground 會讀 */
:root {
--siren-node-fill: #f3efff;
--siren-node-stroke: #6d3fd6;
/* ……其餘 */
/* Category colours */
--sirenchart-category-1-fill: #fee2e2;
/* ……其餘 */
/* Role colours */
--sirenchart-role-error-fill: #fecaca;
/* ……其餘 */
}
把這種檔案上傳到 Playground,主題庫最後會多一份自訂主題並選中它,名字是檔名去掉 .siren.css 或 .css;去掉之後什麼都不剩,就照新增的規則叫「我的主題」。名字可以和現有的主題重複,也不會覆蓋任何現有的主題。讀檔的規則是:
- 只讀這 78 個名稱:42 個
--siren-*設計 token,和 36 個--sirenchart-*分類色與角色色。不管它們寫在哪個 selector 或@media之類的 at-rule 底下;同一個名稱寫了好幾次,取最後一個。註解裡的不算。 - 檔案裡沒寫到的 token,用 Siren 的預設值;甘特圖的 token 例外,從檔案自己的節點底色、外框、文字和連線顏色推算,所以深色主題會得到深色的甘特圖,只要主題自己的文字顏色留得出對比,就看得清楚。網站還沒有甘特圖時存下的舊自訂主題,甘特圖的顏色也這樣補。沒寫到的分類色、角色色一個一個補,和上面說的舊自訂主題同一條規則:看節點底色(
--siren-node-fill)在亮度上比較接近 Siren 風格淺色還是深色那一套,補那一套的值;節點底色不是顏色時補淺色那一套。 - 其他所有宣告都會略過並計入略過的數量,包括
--siren-board-*、不認得的--siren-*或--sirenchart-*名稱和一般的 CSS 屬性;值裡有url(、expression(、分號、反斜線或!important的宣告也會略過,所以下面說的漸層與圖樣不能從主題檔帶進 Playground。上傳後會告訴你略過了幾個宣告。 - 78 個名稱一個都讀不到的檔案會顯示錯誤,主題庫不會改變。
用在自己的網站
在載入 siren-core/theme.css 之後,在 :root 宣告你要改的 --siren-* token 就生效了,沒寫到的維持 Siren 的預設值。也可以直接貼上主題檔的內容;裡面的 --sirenchart-* 在這個網站以外沒有作用,可以刪掉。Siren 本身只有一套值,不會自己切換深色;要第二套主題(深色、高對比、投影用),就用你自己的 selector 再宣告一次:
[data-theme="dark"] {
--siren-node-fill: #2a2144;
--siren-node-stroke: #b69cff;
--siren-node-text: #ece8f8;
--siren-edge-stroke: #8e88a3;
--siren-highlight-color: #2dd4bf;
--siren-label-link: #9cc7ff;
/* 預設是 80% 的白,在深色畫布上會像一張白貼紙:改成同樣透明度的畫布色 */
--siren-edge-label-fill: rgb(20 17 29 / 0.8);
}
Siren 的 12 個甘特圖 token 預設只有淺色,深色主題要連 --siren-gantt-* 一起宣告,不然甘特圖還是淺色的。要一整組現成的深色值,可以把網站切到深色模式,在 Playground 從 Siren 風格新增一份自訂主題再下載,主題檔裡就有。
把 token 宣告在某個容器上而不是 :root,就只有那個容器裡的圖表會變。完整說明見 siren-core 的 Theming。--sirenchart-* 顏色在那裡不起作用:風格和自訂主題的這些顏色是這個網站的,不是 Siren 的。
漸層與圖樣
顏色 token 是以 SVG paint 畫出來的,所以除了顏色,也可以填 url(#id),指向你的頁面在自己的 <svg> 裡定義的 <linearGradient>、<radialGradient> 或 <pattern>:
<svg width="0" height="0" aria-hidden="true">
<defs>
<linearGradient id="node-paint" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#fef3c7" />
<stop offset="1" stop-color="#fbcfe8" />
</linearGradient>
</defs>
</svg>
:root {
--siren-node-fill: url(#node-paint);
}
除了 --siren-highlight-color,每個顏色 token 都可以這樣填;它一定要是顏色,因為 glow 會把它包進 drop-shadow(),填 url() 會讓 glow 直接消失,而且不會報錯。其他限制:
- CSS 漸層不是 SVG paint:
--siren-node-fill: linear-gradient(…)會畫成黑色,也不會報錯。 - 用在線條上的漸層(
--siren-edge-stroke,或--siren-node-stroke畫直線的地方)要加gradientUnits="userSpaceOnUse";用預設值的話,完全水平或垂直的邊會連同箭頭一起消失。 - 漸層定義在你的頁面上,不在圖的
<svg>裡,所以單獨複製出去的 SVG 會失去漸層。
所有限制見 siren-core 的 Gradients and patterns。
照原樣畫的只有 label 標記裡的顏色
在這個網站上,不論選的是風格還是自訂主題,文件自己寫的 style、classDef、class、linkStyle、:::name 和甘特圖 todayMarker 裡那張清單上的屬性都會被接管,每一組上過色的元素都重新上色(今日線則一律照 --siren-gantt-today-stroke 畫),見上面的說明。照原樣畫的只有寫在 label 自己標記裡的顏色(<span style="color:…">、<font color>、background-color)。
在自己的網站用 siren-core 則沒有接管:文件寫的樣式會蓋過 token,作者指定的是「這一個元素」,token 指定的是「所有元素」。所以在文件裡寫死 fill:#fdd 的方框,換主題時也不會變色。想要跟著主題走的外觀,就交給 token。