Design System — Glamour Tutorial Site

注意：這份文件是 Glamour Dental Care 既存設計系統的文件化，不是新提案。系統的Single Source of Truth來源是 app/assets/tutorial-shared/styles/_tokens.scss 的 :root design tokens。這份 DESIGN.md 是人類可讀的解釋與決策記錄。

Product Context

什麼是 Glamour Tutorial Site：穆樂牙醫院內學習平台，累積 [ 依據內容動態更新 ] 篇內容，涵蓋穆樂牙醫的所有治療理念與技術範疇。
目標讀者：穆樂牙醫院內的醫師、臨床工作者、行政管理者、櫃檯人員與企業內訓師；以及部分想透過這些技術放大專業力的外部學員。
產品類型：醫療品牌驅動的數位學習＋醫療知識複合平台，主要流量目標是加速高階牙科、醫學美容治療的學習，打破傳統醫學學習流程，加速專業養成，打破傳統醫療訓練需要以長時間培養醫師的問題，為穆樂牙醫團隊賦能，以滿足未來高齡化社會，醫療勞動力缺乏的缺口，透過美學導向的全科牙科治療為穆樂牙醫的客戶建立更完善的自信心。
空間/產業：牙醫診所，人類外貌美學的Full-stack，整合牙科、醫美，透過微創、仿生、再生概念，解決患者牙科問題的同時達成美學的結果（而非傳統診所只解決疼痛卻不在意患者自信，也不是傳統醫美或美學牙科診所的美學僅執行單點式美學治療，導致客戶外貌越來越人造感）。
多語系：繁體中文為主，內容可能會中英混雜，未來若有擴展多國語系，各語言會有獨立路由（/、/en）

Aesthetic Direction

一句話方向：極簡 × 專業 × 雜誌質感（品牌視覺核心原則）
情緒：像一本厚實的紙本雜誌，不浮誇，不冷漠，有重量感，讀起來安靜但不疏離
裝飾層級：intentional——以 typography 為主角，配上米色暖底與深藍色為強調色，不依賴圖形裝飾、漸層、3D、插畫
反模式（明確避開）：
- 紫色、霓虹、彩虹漸層
- 圓潤卡通風（border-radius 保守）
- AI slop 的三欄圖示網格、置中一切、泡泡按鈕
可類比的參考系：Medium、Mckinsey
設計起源：穆樂牙醫認為美原本就在每個人身上，每個人有獨特的美，當我們接受不完美、無常與簡樸，就能在不完美的狀態（如裂痕、歲月痕跡）中淬鍊出深沉、自然且純粹的寧靜與魅力。

禁止花俏配色，設計系統的核心是「一致性與克制」，有多套視覺主題會稀釋品牌。

Color

Approach：restrained——一個強烈的品牌藍作為唯一彩色，其他全部是暖調中性色。色彩是稀有且有意義的語意工具，不是裝飾。

Core Palette

Token	值	用途
`--color-bg`	`#f9f5f1`	暖紙色背景（全站主背景，CLAUDE.md 指定）
`--color-bg-alt`	`#f5f0ea`	次要背景（區段交替、資訊塊）
`--color-bg-card`	`#ffffff`	卡片背景（內容卡、引用塊）
`--color-primary`	`#2c2c2c`	黑灰主文字（CLAUDE.md 指定）
`--color-secondary`	`#4a3f35`	中棕（正文）
`--color-muted`	`#8a7e72`	淡棕（次要文字、日期、meta）
`--color-accent`	`#1d3557`	品牌藍（連結、CTA、強調）
`--color-accent-hover`	`#25416b`	品牌藍 hover
`--color-danger`	`#d13a3a`	警示紅（強調）
`--color-danger-hover`	`#b82e2e`	警示紅 hover
`--color-danger-light`	`#fef2f2`	品牌紅淡底（徽章背景）
`--color-border`	`#e8e2da`	主邊框色
`--color-border-light`	`#f0ebe4`	淡邊框（分隔線、次要卡）
`--color-code-bg`	`#f3efe9`	程式碼背景

Dark mode

非必要不使用 這套視覺系統的核心情感建立在 「暖紙色底」 所帶來的安全感與安定感，若貿然切換為深色模式，恐會破壞品牌或介面原有的核心情緒。在功能面上，則有以下兩點關鍵考量：

散光使用者的閱讀障礙：散光是現代人極為普遍、卻常被忽視的眼疾。與近視不同，散光患者往往自覺病識感較低，未察覺視覺質量的下降。在深色模式下，黑底白字的對比容易產生「暈光」現象，導致閱讀性大幅變差，增加散光者的視覺負擔。
舒適度並不等同於保護力：雖然深色模式能讓用戶在低光環境下感覺較為舒適，但這絕不代表它具有「護眼」功能。事實上，在光線充足的環境下強行使用深色模式，反而會因為螢幕反光與瞳孔縮放調整，更容易引發眼睛疲勞。

色彩對比

色彩對比規範 (WCAG 2.2 AA) 所有核心文字與背景組合均經過計算，確保在 var(--color-bg) 暖紙色背景下具備優異的可讀性。

主要與次要文字

主標題／內文 (#2c2c2c on #f9f5f1): 13.4:1

    結果： 遠超 AAA 級標準 (7:1)，提供極致的清晰度。

次要正文 (#4a3f35 on #f9f5f1): 9.3:1

    結果： 完美符合 AA 級正文標準，且保有棕色調的溫潤感。

輔助/詮釋文字 (#8a7e72 on #f9f5f1): 4.6:1

    結果： 通過 AA 級正文門檻 (4.5:1)，建議字重不低於 400。

強調與動作色 (Accent)

品牌藍連結 (#1d3557 on #f9f5f1): 11.2:1

    結果： 非常安全，即便是在較小的字體下依然清晰可見。

警示紅強調 (#d13a3a on #f9f5f1): 5.1:1

    結果： 通過 AA 級正文標準。

互動與特殊狀態

品牌藍 Hover (#25416b on #f9f5f1): 9.0:1

警示紅 Hover (#b82e2e on #f9f5f1): 6.2:1

UI 邊框與裝飾 (#e8e2da 與 #f0ebe4)

    僅作為視覺分割，不承載關鍵資訊，不強制要求 3:1 的非文字對比度，以維持極簡風格。

Typography

哲學：襯線體擔任情緒（標題），無襯線體擔任功能（內文、UI）。兩者都是繁中優先的 Noto 字族，載入穩定。

Font Stack

用途	Token	實際字體	來源
標題／Display	`--font-heading`	`Noto Serif TC` → `Georgia` → `serif`	`@fontsource/noto-serif-tc`
內文／UI	`--font-body`	`Noto Sans TC` → `system-ui` → `sans-serif`	`@fontsource/noto-sans-tc`

字重：

Regular (400) — 一般內文
Bold (700) — 標題、強調
標題 h2 在 .prose-content 內用 800（更重的視覺錨點）
字重補償：由於背景色帶有暖調，使用 --color-muted (#8a7e72) 時，建議在字級小於 14px 時將字重設為 Medium (500) 以補償視覺上的輕盈感。
程式碼區塊：在 --color-code-bg (#f3efe9) 上書寫程式碼時，建議直接延用 --color-primary，其對比度為 12.5:1，確保技術文件的易讀性。

載入策略：

透過 @fontsource 套件自建 npm 包，不依賴 Google Fonts CDN
只 import 必要 weights（400、700、800），避免載入整個字族
降低 LCP、遵守 CSP（不需外連 fonts.googleapis.com）

Type Scale

--font-size-xs:    0.75rem  /* 12px */
--font-size-sm:    0.875rem /* 14px */
--font-size-base:  1rem     /* 16px */
--font-size-md:    1.125rem /* 18px */
--font-size-lg:    1.25rem  /* 20px  ← mobile body */
--font-size-xl:    1.5rem   /* 24px  ← desktop body */
--font-size-2xl:   1.875rem /* 30px */
--font-size-3xl:   2.25rem  /* 36px */
--font-size-4xl:   3rem     /* 48px */
--font-size-5xl:   3.75rem  /* 60px  ← hero display */

Body base（全站 UI）：

Mobile：20px（--font-size-lg）
Desktop：24px（--font-size-xl）
放大兩級：刻意把全站 UI 字級拉大，因為讀者是臨床人員，不是工程師，對小字不耐

文章內文（.prose-content override）：

Desktop：19px
Mobile：18px
比全站 body 小，因為 24px 是給 UI 元素（按鈕、導覽、表單）的尺寸。
長文閱讀 19px 配合 1.9 行高是人類閱讀舒適的設定。

Headings

層級	Desktop	Mobile	字體	字重
h1	48px	30px	Noto Serif TC	700
h2	36px	24px	Noto Serif TC	700（`.prose-content` 內 800）
h3	30px	20px	Noto Serif TC	700
h4	24px	—	Noto Serif TC	700
h5	20px	—	Noto Serif TC	700

Line Height & Letter Spacing

--line-height-tight:   1.25  /* 標題 */
--line-height-normal:  1.6   /* UI */
--line-height-relaxed: 1.85  /* 正文 */
/* .prose-content 使用 1.9（更寬鬆，適合長文中文） */

--letter-spacing-tight:  -0.02em  /* 標題（中文稍微負值收緊） */
--letter-spacing-normal: 0
--letter-spacing-wide:   0.05em   /* UPPERCASE labels */

Tabular Numbers

日期、統計數字（SocialProof 的「18,000+ / 1,700+ / 20 / 200+」）使用 font-variant-numeric: tabular-nums 避免跳動。

Spacing

Base unit：4px（但主要使用 8px grid 的倍數） Density：spacious——偏鬆，呼吸感優先

--space-1:  0.25rem /* 4px  */
--space-2:  0.5rem  /* 8px  */
--space-3:  0.75rem /* 12px */
--space-4:  1rem    /* 16px */
--space-5:  1.25rem /* 20px */
--space-6:  1.5rem  /* 24px */
--space-8:  2rem    /* 32px */
--space-10: 2.5rem  /* 40px */
--space-12: 3rem    /* 48px */
--space-16: 4rem    /* 64px */
--space-20: 5rem    /* 80px */
--space-24: 6rem    /* 96px */

使用規則：

相關元素（段落內的字詞）：space-1 ~ space-3
段落間：space-4 ~ space-6
區段（section）內的子區塊：space-8 ~ space-12
大區段間：space-16 ~ space-24
觸控目標最小 44×44 px（a11y 規範）

文字排版工具：

使用 text-pretty 避免段末孤字（orphan word）。
使用 text-balance 平衡標題行長。

Layout

Max Widths

--max-width-content: 760px   /* 最佳閱讀寬度（中文 30-35 字/行） */
--max-width-wide:    1080px  /* 寬版內容（首頁 Hero、Topic Grid） */
--max-width-full:    1200px  /* 全寬容器（header、footer） */
--header-height:      64px

文章內文：.prose-content 用 850px（比 --max-width-content 略寬，配合 19px 字級維持舒適行長）
首頁與 Pillar Pages：max-width-wide (1080px)
Topic Pages（en/ja）：860px（比主頁窄，更像雜誌內頁）

Grid

主要 breakpoints：

Mobile：預設
Tablet：@media (min-width: 768px) — body 切換到 desktop size
Desktop：@media (min-width: 1024px) — 多欄 grid 啟用

Grid 原則：

首頁 Topic Cluster：1 欄（mobile）→ 2 欄（sm）→ 3 欄（lg）
Blog 列表：1 欄（mobile）→ 2 欄（sm）→ 3 欄（lg）
文章頁：雙欄佈局（內文 850px + 右側 sticky TOC 220px）在 > 991px 生效，窄螢幕單欄

左對齊取代置中：

Hero 區域優先使用左對齊。
嘗試 Split Headline：標題佔 3/5 寬（左），副標與描述佔 2/5 寬（右），頂部對齊。

裝飾性網格 (Canvas Grid)：

在 Section 之間加入裝飾性線條。水平線延伸全寬，垂直線保持在 Container 內，形成網格框架。

Borders & Border Radius

--radius-none: 0       /* 預設，主圖、大多數卡片 */
--radius-sm:   4px     /* 按鈕、徽章、小卡 */
--radius-md:   8px     /* 模態、大卡 */
--radius-lg:   12px    /* 特殊強調 */
--radius-full: 9999px  /* Pill buttons、頭像 */

Outer Ring 取代實色邊框：

避免在有陰影的元素上使用傳統 border。
使用 ring-1 ring-gray-950/10 放置在元素外側。這能讓陰影與邊緣的過度更銳利、更乾淨。 同心圓角 (Concentric Radius)：
當容器內有圓角元素時，內層圓角半徑必須等於「外層半徑減去 Padding」。
公式：$R_{inner} = R_{outer} - Padding$。 Inset Ring 做邊緣定義：
在淡色背景容器上，用 ring-inset ring-gray-950/5 取代傳統 border，提供微妙的邊界感。

關鍵決策：文章圖片一律方角：

Article images should use square corners, not rounded corners，圓角破壞雜誌質感。

Motion

Approach：minimal-functional 只做輔助認知的過渡。沒有入場動畫、沒有 scroll-driven choreography、沒有 hover 翻轉。

--transition-fast: 150ms ease  /* 按鈕 hover、連結色變 */
--transition-base: 250ms ease  /* 卡片 hover、小元件位移 */
--transition-slow: 400ms ease  /* 圖片放大 scale(1.03) */

使用規則：

連結 color 變化：fast
按鈕 background/transform：fast
卡片 transform / box-shadow：base
圖片 hover zoom：slow

Shadows

--shadow-sm: 0 1px 3px  rgba(0, 0, 0, 0.04)  /* 靜態卡片 */
--shadow-md: 0 4px 16px rgba(0, 0, 0, 0.06)  /* hover state、Author Card */
--shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.08)  /* Hero 圖片 */
--shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.1)  /* 浮動元件（sticky newsletter） */

所有陰影都偏低透明度（0.04–0.10），避免破壞暖紙色底的柔和感。

Components

共用元件規則

Scoped CSS 優先——元件內的 <style> 只影響自己
需要穿透時用 :global()——例如 .prose-content :global(a) 覆蓋文章內的連結樣式
互動元素最小 44×44 px（a11y）
所有 <a> / <button> 必須有 :focus-visible 焦點環

Accessibility

目標：WCAG 2.2 AA 合規

Skip-to-main link（Header 頂部）
全站 :focus-visible 紅色焦點環（2px outline + 2px offset）
鍵盤 Tab 順序：Header → main-content → Footer
語意化 HTML：<main>, <nav aria-label>, <article>, <figure>/<figcaption>, <blockquote>
JSON-LD 結構化資料：BlogPosting、Person、BreadcrumbList、FAQPage、HowTo、Course、Event

Writing Style

屬於 design system 的一部分，因為文字是內容型站點的第一視覺元素。規則見 CLAUDE.md：

用字偏好：「愈來愈」取代「越來越」、「臺」取代「台」、「批次」取代「批量」
書名號：《》放在連結外 《[書名](url)》
圖說文字：必須以三角符號開頭 *▲ 說明*
文章結尾：每篇都要 ☕️ [請 Vista 喝杯咖啡](https://vista.im/coffee)
TL;DR block（2026-04-13 後新規範）：新文章應在 Hero 後加一段 > **TL;DR**：... 方便 LLM 摘取引用

Brand Voice

不做：廣告文案感、技術宅炫技、焦慮行銷、FOMO、「you must」「crucial」「delve」等 AI 味詞彙
要做：像朋友聊天但保有專業感、具體例子、短段落混合長段落

Tech Stack 對設計的影響

Tailwind 4：utility classes 配合 design tokens 使用
@fontsource：字體自建 npm 包，不依賴 CDN

Performance Budget

Core Web Vitals 目標（行動版中位數）：

LCP ≤ 2.5s
CLS ≤ 0.1
INP ≤ 200ms
A11y score ≥ 95（Lighthouse）
SEO score ≥ 95

為達成這些目標的設計選擇：

首屏圖片強制 fetchpriority="high" + WebP + @nuxt/image 優化
非首屏圖片全部 loading="lazy"
字體只載必要 weights
Hero 區塊避免大型背景圖，改用 typography + 邊距營造張力
相關文章/熱門文章透過 app/data/*.json 預計算，避免 per-page O(N²)

File Map

檔案	角色

| DESIGN.md | 用字、圖片、視覺約束總綱 |

Decisions Log

日期	決策	理由

| 2026-04-20 | 這份 DESIGN.md 首次產出 | 整份由 Peter Tung 初步確認 |

How to Use This File

任何視覺或 UI 變動前，先讀這份文件和 app/assets/tutorial-shared/styles/內的檔案
所有字級、色彩、間距優先用 CSS variables（var(--color-accent) 而非 hex）
不要偏離這裡定義的 token，要偏離必須更新這份文件並留下決策記錄
QA 測試時把 DESIGN.md 當作規範清單，違反的程式碼應該被指出
這份文件版本化——design system 有任何變動，都要同步更新這份文件的 Decisions Log 條目

設計語彙（DESIGN.md）