主題

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、三個塗成同一種琥珀色的節點。風格把這些意思留成色組,每一組各給一個自己的顏色:

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 左側的圖示列可以切換到主題,上方有三個分頁。圖示列最底下的按鈕可以把左欄收到只剩圖示列,讓預覽佔滿畫面;按任何一個圖示就會展開到那個分頁。

主題庫列出可以選的,每一份旁邊有它五個顏色的色塊,分成兩段:

每一份自訂主題那一列的右邊有四個圖示按鈕,按了就作用在那一列,不必先選中它,也不會改變選中的是哪一份:

主題庫底下有一排按鈕:

自訂分頁逐項調整目前選中的自訂主題,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;去掉之後什麼都不剩,就照新增的規則叫「我的主題」。名字可以和現有的主題重複,也不會覆蓋任何現有的主題。讀檔的規則是:

用在自己的網站

在載入 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 直接消失,而且不會報錯。其他限制:

所有限制見 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。