夜航塔羅 Night Voyage Tarot

依照 Rider–Waite 體系製作的線上塔羅抽牌網站，包含完整 78 張牌。整個網站只有一個 HTML 檔，不需要後端、資料庫或圖片檔，雙擊就能開啟。

🔮 線上使用：https://zhengkimi.github.io/night-voyage-tarot/

靜下心、默想問題、選好牌陣，從扇形牌堆中憑直覺抽牌，再一張張翻開，閱讀牌面給你的訊息。

---

功能

• 完整 78 張牌：22 張大阿爾克那與 56 張小阿爾克那。每張牌都有正逆位關鍵字，以及一段專屬的正位建議和逆位建議
• 四種牌陣：今日指引（1 張）、時間之流（3 張）、二選一（5 張）、凱爾特十字（10 張）
• 公平洗牌：Fisher–Yates 演算法，搭配瀏覽器的密碼學隨機數，每種牌序的機率相等
• 逆位可開關：開啟時，每張牌正逆位的機率各 50%
• 逐張解讀：每翻開一張牌，下方立刻出現這張牌的解讀，依位置順序排列
• 整體訊息：全部翻開後，依規則分析整個牌陣，包括大牌比例、主導花色、重複數字、宮廷牌與逆位數量
• 一鍵複製：把整份解讀複製成純文字，方便記錄或分享
• 手機與電腦都能用：支援鍵盤操作、螢幕閱讀器，以及「減少動態效果」設定

快速開始

# 方法一：直接雙擊 index.html

# 方法二：開本機伺服器（跑端對端測試時需要）
python3 -m http.server 8000
# 瀏覽器開啟 http://localhost:8000/

部署時只需要上傳 index.html 到任何靜態主機，例如 GitHub Pages、Netlify 或 Cloudflare Pages。

檔案結構

塔羅牌/
├── index.html          網站本體（唯一需要部署的檔案）
├── package.json        測試指令捷徑（沒有任何相依套件）
├── README.md           專案介紹（本檔）
├── TESTING.md          完整測試流程
├── tests/
│   ├── core.test.mjs   單元測試（Node 內建 node:test，39 項）
│   └── e2e.html        端對端測試（在瀏覽器執行，20 個情境）
└── .claude/skills/tarot-reading/
    ├── SKILL.md        Claude 解牌技能：把複製出來的解讀串成故事，以正面反饋為主
    └── examples/
        ├── celtic-cross-work.md   範例：凱爾特十字 · 工作問題
        └── time-flow-love.md      範例：時間之流 · 感情是非題

用 Claude 深入解牌

在網站按「複製解讀文字」，把內容貼給 Claude Code（在這個資料夾中開啟），它會自動套用 tarot-reading 技能。技能會依牌陣的閱讀路線，把牌串成一個故事，再給出依時間排列的行動建議。也可以輸入 /tarot-reading 直接呼叫。

---

網站架構

index.html 裡的程式分成三層。前兩層放在 <script id="tarot-core">，完全不碰 DOM，所以可以直接在 Node 裡測試。第三層放在 <script id="tarot-ui">。

┌─ tarot-core ───────────────────────────────────────────┐
│ 1. 資料層   MAJORS · SUITS → CARDS[0..77] · SPREADS    │
│ 2. 渲染層   faceSVG(card) → SVG 字串                    │
│    純邏輯   shuffle() · interp() · summaryLines()      │
│             readingText()                              │
└───────────────────────── 掛在 globalThis.Tarot ─────────┘
┌─ tarot-ui ─────────────────────────────────────────────┐
│ 3. 互動與狀態層                                         │
│    newDeck → layoutFan → pick → flip → addEntry        │
│                                  └→ finishReading     │
└────────────────────────────────────────────────────────┘

1. 資料層：牌與牌陣都寫成資料

資料	內容
MAJORS	22 張大阿爾克那：[中文名, 英文名, 正位關鍵字, 逆位關鍵字, 正位建議, 逆位建議]
SUITS	四個花色，各有元素、主管領域、代表色，以及 14 張牌（王牌～十、侍者、騎士、王后、國王）。每張是 [正位關鍵字, 逆位關鍵字, 正位建議, 逆位建議]
CARDS	把上面兩組攤平成 78 個物件，之後一律用編號 0–77 取用：0–21 大牌，22–35 權杖，36–49 聖杯，50–63 寶劍，64–77 錢幣
SPREADS	每個牌陣是一組位置清單：位置名稱 l、位置意義 h、格線欄列 c／r、是否橫放 x

資料和畫面分開，擴充就很容易。例如想新增「愛情牌陣」，只要在 SPREADS 加一筆，再在 HTML 的牌陣選單加一個選項，不必改任何渲染程式：

love:{name:"愛情牌陣",cols:3,rows:2,pos:[
  {l:"你",h:"你在這段關係中的狀態",c:1,r:2},
  {l:"對方",h:"對方呈現給你的樣子",c:3,r:2},
  {l:"關係",h:"兩人之間的連結",c:2,r:1},
  {l:"建議",h:"讓關係更好的方向",c:2,r:2}]}

<label><input type="radio" name="spread" value="love" id="sp-love"><b>愛情牌陣</b><small>4 張 · 兩人關係</small></label>

另外要在 CSS 加一行牌寬，例如 .board.love{--cw:clamp(80px,24vw,140px)}。

2. 渲染層：牌面用程式畫出來

faceSVG() 依每張牌的資料即時產生 SVG：

牌	畫法
數字牌（王牌～十）	依照馬賽塔羅「點數牌」的傳統，把花色符號依點數排列。例如聖杯七就排 7 個杯子
宮廷牌	一個大的花色符號，上方加身分記號：侍者是圓點、騎士是箭形、王后是新月、國王是皇冠
大阿爾克那	中央是羅馬數字，外圍一圈 16 道放射光芒，象徵原型的力量

不用圖片檔，所以載入很快，放大也不會模糊，也不必處理牌面圖的版權。

3. 互動與狀態層：一條單向流程

狀態只有四個變數：spreadKey（選了哪個牌陣）、deck（洗好的牌序與正逆位）、picks（已抽的牌）、flippedN（已翻幾張）。

洗牌 newDeck() → 扇形展開 layoutFan() → 抽牌 pick() 放進牌位 → 翻牌 flip()
                                                       ├→ 每翻一張：addEntry() 顯示該張解讀
                                                       └→ 全部翻開：finishReading() 補上整體訊息

技術重點：

• 洗牌：Fisher–Yates 演算法，搭配 crypto.getRandomValues。取隨機整數時使用「拒絕取樣」，連取餘數造成的極微小偏差也一併消除，所以每種牌序出現的機率確實相等。單元測試用卡方檢定驗證這一點
• 扇形牌堆：在畫面下方設一個看不見的圓心，78 張牌繞著它旋轉排成弧形。半徑依螢幕寬度計算，手機和電腦都排得下。洗牌時先把牌收攏，再依序展開
• 翻牌：使用 CSS 3D，牌背與牌面背對背貼合，翻轉 180° 就換面。逆位牌的牌面額外再轉 180°，和實體牌倒過來一樣
• 逐張解讀：第一次翻牌時開啟解讀區，整體訊息先顯示翻牌進度。每段解讀依位置編號插入，跳著翻也會照 1、2、3 排列。逐張翻牌時不自動捲動，讓你留在牌陣繼續翻；全部翻開後才捲到整體訊息
• 重置保護：洗牌動畫期間暫停抽牌。每次重置時遞增一個世代編號，讓已排程的翻牌與解讀在重置後自動失效，不會跑出舊結果
• 安全：使用者輸入的問題一律以 textContent 顯示，不會被當成 HTML 執行

整體訊息的規則

條件	訊息
大阿爾克那 ≥ 一半	這件事是人生的重要課題，順勢而為比強求更重要
全為小阿爾克那	事情落在日常層面，可透過具體行動調整
某花色最多且 ≥ 2 張	指出主導元素與領域。平手時不下結論
同一數字 ≥ 2 張	點出數字主題。例如多張「五」代表衝突與變動
宮廷牌 ≥ 2 張	可能代表參與其中的人，或你需要展現的特質
逆位 0 張／少數／過半	能量順暢／部分環節需調整／宜先向內整理

關閉逆位時，整體訊息不會評論正逆位。

---

構圖設計原理

流程就是儀式

頁面由上而下編號 i 到 iv：設定占卜、洗牌抽牌、牌陣、解讀，對應真實占卜「靜心提問 → 洗牌 → 抽牌 → 翻牌 → 解讀」的順序。這些編號代表真正的先後步驟，不是裝飾。

扇形牌堆放在視覺中心

塔羅最有代表性的動作，是攤開一整副牌、憑直覺抽一張。所以畫面的主角是 78 張牌背排成的弧形，而不是大標題。滑鼠移到牌上時牌會微微浮起，模擬手指觸碰牌的感覺。

配色：夜空、黃銅與羊皮紙

• 背景是深靛藍的星空，帶出夜間、潛意識的氛圍
• 金屬黃銅色用在按鈕、編號與牌背紋樣，像傳統牌背的燙金
• 牌面是羊皮紙色，翻開時從暗到亮的對比本身就是一種揭曉

四花色各有對應元素的顏色，大阿爾克那用紫色，代表靈性與原型層次：

花色	元素	牌面色	主管領域
權杖	火	赭紅 #a94b2a	行動、熱情、事業
聖杯	水	深藍 #2c6688	情感、關係、直覺
寶劍	風	灰藍 #4b5674	思想、溝通、抉擇
錢幣	土	橄欖綠 #6a7230	金錢、工作、身體
大阿爾克那	—	紫 #5a3f84	靈性、原型

字體分工

• 標題與牌名用宋體（思源宋體 Noto Serif TC），帶有古典、典籍的味道
• 解讀內文用黑體（思源黑體 Noto Sans TC），長文比較好讀
• 羅馬數字用 Cormorant Garamond 義大利斜體，呼應古典塔羅牌上的數字

牌陣照傳統排法

• 凱爾特十字：左邊是十字（現況、阻礙、根基、過去、目標、近未來），右邊是一根由下往上讀的權杖（自我、環境、希望與恐懼、結果）。第 2 張橫壓在第 1 張上，和實際擺牌一樣
• 二選一：「現況」放在底部中央，兩條路往左上與右上分岔，看起來就像站在岔路口
• 牌的長寬比是 10:16，接近實體塔羅牌的比例

動畫只在兩個時刻

只有洗牌展開與翻牌兩處有動畫（翻牌後解讀段落的輕微淡入也屬於翻牌），其他地方保持安靜，讓注意力留在牌上。若裝置開啟「減少動態效果」，動畫會自動關閉。

---

解牌注意事項

1. 問法決定解讀品質：用開放式的問法，例如「我在這段關係中需要注意什麼？」，避免「他會不會回來？」這類是非題。塔羅擅長呈現狀態與趨勢，不擅長回答是或否。問題盡量聚焦在自己身上，問「我能怎麼做」，比問「對方在想什麼」更有幫助，也尊重對方。同一個問題不要一直重抽到出現想要的答案
2. 一定要結合位置來讀：同一張牌在不同位置意思不同。例如「寶劍三」在「過去」代表已經歷過的傷痛，在「近未來」則是提醒你預先準備。先讀「此位置代表」，再讀牌
3. 逆位不等於壞牌：逆位通常表示能量受阻、轉向內在，或過多與不足。例如「惡魔」逆位代表掙脫束縛，「聖杯四」逆位代表走出低潮
4. 不要照字面解讀牌名：「死神」幾乎不代表死亡，而是一個階段的結束與轉化。「高塔」是舊結構崩解，常常為新局清出空間
5. 把牌串成一個故事：牌與牌之間的關係才是重點。大牌多、同花色多、重複的數字、宮廷牌、彼此矛盾的牌，都是線索。兩張牌意思相衝時，通常點出內心的拉扯，這本身就是重要訊息
6. 牌面是趨勢，不是命定：塔羅呈現的是「照現在的方向走下去，可能的發展」。你改變做法，結果也會跟著改變
7. 重大事情請找專業人士：健康、法律、財務投資、心理危機這類問題，塔羅可以幫你整理想法，但不能取代醫師、律師、財務顧問或心理諮商師的專業判斷

這個網站的解讀限制

• 78 張牌都有專屬的正逆位建議，但每段只有一到兩句，屬於提示，不是完整的牌義解說
• 單張牌的建議不會因位置而改寫。同一張牌出現在「過去」或「未來」，顯示的是同一段建議，需要你搭配「此位置代表」自行連結
• 「整體訊息」是依規則統計產生，不是真正的直覺解讀
• 建議把網站的解讀當成起點，同時留意翻牌那一刻你的第一個感受與聯想，那往往最準

---

開發與測試

npm test          # 單元測試（約 10 秒）
npm run serve     # 開本機伺服器，再開啟 http://localhost:8000/tests/e2e.html

完整的測試流程、手動驗收清單與牌義審稿方法，請見 TESTING.md。

修改牌義

所有牌義都在 index.html 的 MAJORS 與 SUITS 陣列中。修改後執行 npm test，確認每張牌仍有四個欄位，而且建議文字沒有重複。

瀏覽器支援

支援近兩年的 Chrome、Edge、Safari、Firefox（需要 CSS :has()、aspect-ratio、backface-visibility）。

---

塔羅是自我覺察的鏡子，不是命定的判決。牌義供參考，最終的選擇在你手中。