Spaces:

minchun
/

II_SpectraEngine

Sleeping

App Files Files Community

II_SpectraEngine / docs /design.md

minchun

Claude Sonnet 5

補齊「使用手冊」→「使用說明」更名的實際內容改動

9615d53 2 months ago

preview code

Raw History Blame Contribute Delete

19.7 kB

metadata

version: 1.3
project: SpectraEngine（譯彩紛呈 II 分析引擎）
brand: 致理科技大學應日系 鄧老師委託案
last_updated: 2026-08-12T00:00:00.000Z
source: assets/app.css（E4 抽出前為 app_agent.py 內嵌 _CUSTOM_CSS 常數）
colors:
  light:
    bg: '#f3f8fd'
    surface: '#ffffff'
    surface2: '#eef5fc'
    surface3: '#ffffff'
    surface3-border: '#e2e8f0'
    border: rgba(2,132,199,.16)
    border-hover: rgba(2,132,199,.35)
    border-strong: rgba(2,132,199,.30)
    divider: '#a9cbe8'
    thead-bg: '#d8e8f6'
    bubble-bg: '#ffffff'
    input-border: '#7fb0d9'
    accent: '#0284c7'
    accent-strong: '#0369a1'
    accent2: '#4f46e5'
    accent2-strong: '#4338ca'
    accent3: '#9333ea'
    text: '#1e293b'
    text-soft: '#334155'
    text-muted: '#475569'
    text-subtle: '#64748b'
    success: '#047857'
    warn: '#b45309'
    user-bubble-bg: '#dcfce7'
    user-bubble-border: '#86efac'
    user-bubble-text: '#166534'
  dark:
    bg: '#0b1424'
    surface: '#172136'
    surface2: '#1b2740'
    surface3: '#1e293b'
    surface3-border: '#334155'
    border: rgba(14,165,233,.11)
    border-hover: rgba(14,165,233,.30)
    border-strong: rgba(148,163,184,.28)
    divider: rgba(148,163,184,.18)
    thead-bg: '#1e2a42'
    bubble-bg: '#172136'
    input-border: rgba(14,165,233,.15)
    accent: '#0ea5e9'
    accent-strong: '#38bdf8'
    accent2: '#818cf8'
    accent2-strong: '#a5b4fc'
    accent3: '#c084fc'
    text: '#e2e8f0'
    text-soft: '#cbd5e1'
    text-muted: '#94a3b8'
    text-subtle: '#475569'
    success: '#34d399'
    warn: '#fbbf24'
    user-bubble-bg: rgba(34,197,94,.18)
    user-bubble-border: rgba(34,197,94,.42)
    user-bubble-text: '#bbf7d0'
  primary-cta-gradient: 'linear-gradient(135deg, #0284c7 0%, #4f46e5 100%)'
  accent-gradient: linear-gradient(100deg, var(--c-accent) 10%, var(--c-accent2) 90%)
  heading-gradient: >-
    linear-gradient(120deg, var(--c-accent-strong) 0%, var(--c-accent2) 55%,
    var(--c-accent3) 100%)
typography:
  fontFamily:
    ui: Inter, Noto Sans TC, system-ui, sans-serif
    mono: JetBrains Mono, monospace
    heading-latin: Crimson Pro
    heading-zh: Noto Sans TC
  unit: rem
  remBase: 16px
  base:
    fontSize: 0.875rem
    cssVar: '--font-size-base'
    note: 全站內文字級唯一來源，任何內文字級改動一律引用這個變數，不手寫 rem 數值
  scale:
    display-lg: 2.1rem
    display-md: 1.8rem
    display-sm: 1.6rem
    title-lg: 1.4rem
    title-md: 1.25rem
    title-sm: 1.15rem
    body-lg: 1.05rem
    body-base: var(--font-size-base)
    caption: 0.78rem
    badge: 0.70rem
    step-pill: 0.62rem
rounded:
  sm: 4px
  md: 9px
  lg: 10px
  xl: 12px
  card: 14px
  card-lg: 16px
  pill: 20px
shadow:
  card: 0 4px 16px rgba(15,23,42,.18)
  card-hover: 0 16px 40px rgba(79,70,229,.35)
  card-hover-strong: 0 20px 46px rgba(79,70,229,.45)
  overlay: 0 16px 50px rgba(15,23,42,.20)
  drawer: 4px 0 24px rgba(15,23,42,.28)
layout:
  columns: 'nav-col : chat-col : canvas-col = 2 : 3 : 7（gr.Column scale）'
  nav-col-width: 220px（收合 60px，@media min-width:901px 才套用收合樣式）
  chat-col-min-width: 280px
  canvas-col-min-width: 380px
  homepage-max-width: 50rem
  base-padding: 16px（nav-col／輸入框基準，20px canvas 內容區）

SpectraEngine 設計系統

本文件包含兩層：YAML front matter 為機器可讀的 design tokens（供 AI agent 或 Stitch 等工具直接使用）；Markdown 本文記錄「為什麼」與人的判斷準則。實作以 assets/app.css 為準——這份 CSS 原本內嵌在 app_agent.py，2026-08-05（E4）抽成獨立檔案，改用 app.launch(css_paths=...) 載入。

專案定位

SpectraEngine（譯彩紛呈 II 分析引擎）是一套針對重譯文本語言特徵的量化分析平台，技術上是 Python + Gradio 單頁研究工具，服務對象是進行重譯研究的學術使用者（大學教師、研究生）。介面分兩種截然不同的使用情境，視覺語言刻意分兩派：

對話區（左側導覽＋對話串＋輸入框）：參考 AI-Native UI 風格——訊息泡泡、打字中三點跳動動畫、串流文字顯示，對應報告撰寫等待期間的載入體感需求。介面語彙上參考 Claude.ai／ChatGPT 網頁版的排版與操作體驗。
結果分頁（表格／圖表區）：參考 Data-Dense Dashboard 風格——多圖表/資料表並存、緊湊排版、最大化資訊密度，對應 75 項指標表格與 4 種統計圖表的呈現需求。

兩種風格共用同一套色彩與間距 token，差異只在密度與動效，不是兩套獨立設計系統。

配色

雙主題（淺色／深色）系統，經 WCAG AA 對比度驗算（叫 ui-ux-pro-max skill 對執行中實機量測，非套用通則）：淺色模式主要文字對比度約 7.24–14.63:1、深色模式約 7.87–14.78:1，9 個關鍵文字元素全數通過 AA。

配色決策原則：本次改版不重新設計配色——業主原本版本已建立完整雙主題 token（sky + indigo + slate 系），驗算品質良好，只在使用場景上做微調，不更換色相。

一般強調色 vs 加強強調色

淺色模式的一般強調色 #0284c7（accent）用於一般大小的內文文字時，對比度 4.09:1 略低於 WCAG AA 的 4.5:1 門檻，但用於按鈕/圖示/大字等允許 3:1 門檻的地方完全合格。系統另外準備了 accent-strong（#0369a1，5.93:1）供小字/連結專用。兩者不能混用：一般強調色用在按鈕/圖示/大字，加強強調色用在小字/連結文字。

底色體系：三層（2026-08-12 新增）

業主回報「純黑或純白背景面積很大，整個視覺壓力也變大」。量過之後確認抱怨的來源不只對話欄：淺色的頁面底 #f8fafc 幾乎等於白，而真正的大面積純白是 --c-surface（表格資料列與所有 Gradio 區塊）；深色則是 #020617 近乎純黑。

改成三層結構，淺色與深色共用同一套邏輯：

層	Token	淺色	深色	鋪在哪
底	`--c-bg`	`#f3f8fd`	`#0b1424`	頁面、canvas、導覽列、對話欄
浮起物	`--c-bubble-bg`	`#ffffff`	`#172136`	對話氣泡，比底亮一階
資料紙張	`--c-surface`	`#ffffff`	`#172136`	表格資料列、卡片、輸入框、Gradio 區塊

兩個判斷準則：

淺色的資料紙張維持純白，不跟著染藍。75 項指標表格是資料密集區，白底的可讀性優先於「消滅所有純白」；染藍的是它下面那層底，白色表格因此變成浮在淡藍上的紙張，層次比原本白疊白更清楚。
氣泡比底亮一階、浮在上面，深淺一致。深色本來就是這個關係（原 #0d1526 浮在 #020617 上），這輪讓淺色跟上，兩個主題不再各講各的。近白區間的填色差本來就只有一階，邊界靠細線邊框補（見下）。

邊界與分隔線：兩級線條（2026-08-12 新增）

WCAG 1.4.11 對「UI 元件與圖形物件的邊界」要求 3:1，這條在淺色模式一直沒被滿足：--c-border（rgba(2,132,199,.16)）疊在白／近白底上只有約 1.2:1，區塊外框、水平分界線、表格框線在淺色模式等於看不見（深色模式當初已針對 .app-header、欄邊框、標題底線個別補成 rgba(148,163,184,.28)，淺色端從沒補）。業主 2026-08-12 回報「淺色版看不清楚區塊的顏色」即為此。

線條因此分兩級，新增元件時二選一，不要再直接用 --c-border 畫可見邊界：

Token	用途	淺色	深色
`--c-border-strong`	結構線：區塊外框、欄位分隔、頂部列底線、標題底線、`hr`、表格外框與表頭分界	`rgba(2,132,199,.30)`（＝ `button.secondary` 的邊框色，對底約 1.46:1）	`rgba(148,163,184,.28)`
`--c-divider`	細線：表格資料列之間這種密集重複的線	`#a9cbe8`	`rgba(148,163,184,.18)`
`--c-bubble-border`	對話氣泡邊框（獨立一級，兩個主題實測對齊 1.61:1）	`#a9cbe8`	`rgba(148,163,184,.26)`
`--c-input-border`	輸入框邊界	`#7fb0d9`（約 2.0:1）	`rgba(14,165,233,.15)`

密集重複的線刻意不拉到 3:1：整張資料表如果每一條線都是結構線強度，會變成網格紙、反而更難讀，1.4.11 的門檻也只針對「識別元件所必需」的邊界。

淺色線條一律走 sky 相，不用中性灰藍。 中間版本曾用 #a3aebd／#b6c0cd（同樣的亮度級距、但偏灰），配上淡藍底會顯灰顯髒，業主明確要求「維持亮麗的淺藍」。換色相時亮度級距不動，手感才不會又跑掉。

結構線最終落在 1.46:1，是連續三輪往柔和方向調的結果，已明確離開 1.4.11 的 3:1 門檻。 沿革：#7c8798（3.64:1，符合規範）→ 業主嫌太搶眼改 #a3aebd（2.25:1）→ 嫌偏灰改 sky 相 #6ba3d6（2.3:1）→ 業主指定「跟『重新選擇研究情境』按鈕的邊框同一個色」，定案 rgba(2,132,199,.30)。

這是業主拍板的視覺取捨，不是疏忽：線條顏色從此與 button.secondary 共用同一個值，全站次要邊界只有一個來源，改一處全站跟著走。文字對比完全不受影響，仍全數通過 AA。日後若無障礙稽核要求嚴格達標，把這個 token 換成同色相但更深的 sky 值即可，19 處線條會一起跟上。

--c-border 本身維持原值，因為它同時餵給 --block-border-color 與 --border-color-primary 兩個 Gradio 原生元件變數，改動會牽連一整批沒盤點過的元件。

對話氣泡（2026-08-12 更新）

淺色氣泡原本是白底無框，疊在對話欄底 #f8fafc 上只有 1.07:1。定案改成 填色＋淡邊框：底色 --c-bubble-bg（淺色 #ffffff、深色 #172136），外加 1px --c-bubble-border。氣泡比欄底亮一階、浮在上面（見上方「底色體系」）。

邊框比結構線明顯，因為填色差只有一階（白氣泡疊 #f3f8fd 只有 1.07:1），邊界全靠它。「深淺一致」是用量測對齊的，不是兩邊各挑一個看起來順眼的值：淺色 #a9cbe8 疊白 1.69:1、深色 rgba(148,163,184,.26) 疊 #172136 1.61:1。

這裡踩過一次坑值得記下來：中間版本讓氣泡邊框共用 --c-divider，淺色值卻是對著「深色結構線那一級（alpha .28）」挑的，而深色 --c-divider 其實是更淡的 .18——結果深色氣泡邊框只有 1.37:1、淺色 1.61:1，兩個主題看起來不一樣。跨主題要對齊的視覺元素，就給它自己的 token，不要借用剛好數值接近的鄰居。

可見邊界畫在內層 .md，不是外層 .message（量測時要認這層）。使用者訊息與 AI 訊息共用同一層，目前兩側同款氣泡、只靠左右對齊區分，是 2026-08-12 業主確認過的現況。

漸層文字與漸層背景的已知踩坑

background: linear-gradient(...) 簡寫在這版瀏覽器會把 background-image 這個子屬性解析成空值（實測用 devtools 讀 getPropertyValue('background-image') 回傳空字串），視覺上等於文字消失。規則：漸層一律寫 background-image: linear-gradient(...) 這個子屬性本身，不用 background 簡寫。全站三處漸層文字／按鈕（.app-header .title-line、.homepage-hero h1、CTA 按鈕）都遵守這條。

判斷漸層文字的 WCAG 對比度時，不能用 getComputedStyle().color（漸層文字用 -webkit-text-fill-color:transparent，會讀到透明），要用截圖取樣實際渲染像素計算。

字體

英文／數字：Crimson Pro（學術感、研究工具調性），標題與強調數字用
中文本文：Noto Sans TC（維持業主原設定；Stitch 等工具的字體庫多為西文導向、不含中文字體，中西混搭是人工判斷後的決定，非工具庫建議）
UI 介面文字：Inter（Gradio 主題 font= 設定，中文 fallback 到 Noto Sans TC）
等寬／資料：JetBrains Mono（指標數值、程式碼片段）

字級規範

全站基礎內文字級統一 0.875rem（14px），唯一來源是 CSS 變數 --font-size-base，任何內文字級改動都要引用這個變數，不允許手寫 rem 數值（2026-07-24 曾經手寫 .88rem 被業主當場糾正，需求文件第十一節的既有規範）。標題、步驟列 pill、小徽章這類刻意做出層級差異的地方例外，可以有自己的固定字級（見 YAML typography.scale）。

造型與間距

圓角：卡片類 14–16px、按鈕/輸入框 9–10px、徽章/pill 20px（全圓）
陰影：僅用在懸浮／強調狀態（卡片 hover、彈窗、抽屜），靜態卡片不加陰影——2026-07-23 業主實機回饋「原本的強調色外框＋大範圍陰影＋漸層底色讓卡片像浮起來的彈窗」，改成扁平化：外框、陰影、底色拿掉，只留圓角與內距維持呼吸空間；彈出動畫保留（負責「這塊剛出現」的狀態提示，跟視覺重量無關）
版面比例：三欄式工作區 nav-col : chat-col : canvas-col = 2 : 3 : 7，寬螢幕滿版貼齊左右邊界（不做置中留白），首頁例外維持 max-width: 50rem 置中，避免寬螢幕上被拉滿版
結果頁內容順序：標題 → 圖表／表格 → 下載按鈕，六個結果頁一致（2026-08-12 業主要求把「語言指標分析」的下載從頁面頂部改回最下方，統一順序）
表單欄位不包卡片（2026-08-12）：語料說明表單的欄位一律「小標題＋內容直接攤開」，不要 Gradio 自動包的白色 .form 卡片。Gradio 這層卡片是兩件事疊起來的——.form 出框線、內層 .block／fieldset 出白底與內距——兩層都要清掉才會消失。內距清掉之後欄位左緣自然對齊小標題與下方表格。另外 .form 的 align-items 要改 flex-start：預設的 stretch 會把每個欄位的高度鎖成整列高度，而那個列高不含欄位標籤，radio 這種「標籤在上、選項在下」的元件會被裁掉一截
欄位標籤只有一種樣式（2026-08-12）：.7rem／700／--c-text-muted。這是 Gradio 給文字欄位標籤的既有值，不是另訂的字級，所以不套 --font-size-base（標籤比內文小一階是這張表單本來的層級設計）。radio 的 fieldset 標籤走 Gradio 另一條規則、預設是一般大小的深色字，要另外對齊，否則同一張表單裡兩種欄位的標籤長得不一樣
表格不自己出捲軸（2026-08-12）：dataframe 的內部容器一律 scrollbar-width: none。Gradio 預設 max-height: 500px + overflow-y: auto，列多時捲軸會佔掉 10px 版面寬度，表格因此比外框窄一截，右側露出一條空白帶，看起來像最後一欄被切掉（業主回報過）。滾輪／觸控／鍵盤照常可捲。不要改用移除 max-height 的做法：這個表格是虛擬捲動，靠自身捲動位置決定渲染哪些列，移除後會變成「保留整表高度卻只渲染 1 列」的空表。也**不要用 ::-webkit-scrollbar**：Gradio 在該元件設了標準屬性 scrollbar-width／scrollbar-color，Chrome 見到標準屬性就會忽略 legacy 偽元素
導覽列末項：「使用說明」固定在左側導覽列最後一項（技術執行紀錄下方，用分隔線隔開），與分析進度無關、全程可見；它是下載動作不是頁面，不參與導覽列的 active 狀態
基準留白：導覽列與輸入框四邊留白 16px 為基準，其餘區塊（對話氣泡、Canvas 內容區）對齊同一基準線，避免同一頁面出現兩種留白邏輯

圖示

Heroicons outline 風格 SVG，24×24、stroke-width="1.75"、fill="none"，手繪 path（非套件逐點對照）。業主明確否決沿用專案既有的 emoji 慣例。

新增導覽圖示時要量「實際上色範圍」，不能只看 viewBox。 所有圖示的 viewBox 都是 24×24、容器都是 22px，但畫出來的大小取決於 path 撐到哪裡。現有導覽圖示的上色範圍多落在 18×16 附近（folder／chat-bubble／table-cells 皆是），2026-08-12 新增的 book-open 初版只有 16×15，肉眼看得出比別人小一圈、卻不容易指出原因，是截圖逐一量非背景像素才確認。新增圖示畫完後量一次，對齊 18×16 這個量體。

AI 頭像（2026-08-12 新增）

AI 訊息左側的頭像是 28px 圓形，紫→藍漸層底＋白色四角星（sparkle），漸層與標題字共用同一條 heading-gradient。

實作分工是刻意的：漸層畫在 CSS 的 .avatar-container，SVG 檔（assets/icons/ai-avatar.svg）只放白色 glyph。原因是 gr.Chatbot(avatar_images=...) 是 Python 端參數，同一個檔案沒辦法隨明暗主題換色；把漸層交給 CSS 才吃得到 --c-accent-strong / --c-accent2 / --c-accent3 這組會跟著主題切換的 token。白色圖形疊在任一主題的漸層上都夠亮。頭像寬高固定並設 flex: none，避免重蹈「圖示被 flex 壓縮」的舊坑。

glyph 規格與其他導覽圖示不同，另立一套：兩顆星都是實心 fill、不描邊，path 撐到接近滿版（大星 x3.9–17.1／y2.2–17.2、小星 x15.3–21.5／y13.6–20.7），img 內距 3px，圖案在 28px 圓內的可用範圍 22px。實心與放大要一起做才有效——只縮內距是把細線稿放大，只放大 path 又會被內距框住。

深色模式處理：gr.Button(icon=...) 在這版 Gradio 渲染成 <img> 標籤而非行內 <svg>，CSS currentColor 對它無效，因此淺色版固定 stroke 顏色，深色模式改用 filter: grayscale(1) invert(1) brightness(1.55) contrast(.85) 反相逼近深色版文字色，不另外準備第二份深色 SVG 檔案。需要 currentColor 正常運作（例如收合鈕、明暗切換鈕這類不需要 Python .click() 的裝飾性圖示）則改用 gr.HTML() 內嵌行內 SVG。

動效

對話訊息串流顯示、打字中三點跳動動畫（AI-Native UI 語彙）
運算中狀態用轉圈動畫，避免使用 Gradio 預設的 .generating 呼吸藍框（視覺上與本站的呼吸動畫語彙衝突，需求文件已列為既有修正項）
手機抽屜／確認彈窗用 transform 位移或 overlay 淡入，不做過度炫技的轉場

已知技術限制（設計時務必納入考量）

沒有測試套件，任何視覺改動都要手動走一次流程驗證，純美感/主觀判斷的改動先截圖給業主看過再定案
Gradio 6 的 CSS pipeline 會自動幫 css=/css_paths= 內的所有選擇器加上 .gradio-container .contain 前綴，:root 選擇器包進 @media 區塊後永遠無法命中；系統深色模式的 token 覆寫因此改放在 app.launch(head=...) 注入的獨立 <style>（見 _DARK_MODE_HEAD_CSS），繞過這個轉換管線
部分 Gradio 原生元件（gr.Column(visible=False) 等）在特定時序下會有可見性狀態的非直覺行為，改版面配置前建議先查 app_agent.py 裡累積的相關踩坑註解，避免重踩

本文件為本次 UI/UX 改版團隊（吳千卉）依既有實作彙整，非全新設計提案。配色與整體風格方向延續業主原有版本，未來調整請同步更新本文件與 assets/app.css，保持兩者一致。