astro-github-pageslisted
Install: claude install-skill yao-care/astro-pages-kit
# astro-github-pages — Astro + GitHub Pages 建站 SOP
從零到「Pages 上線、兩道守門生效、搜尋引擎收得到」。
**不要自行發明頁面內容或資訊架構。** 骨架上線後就去問使用者要網站地圖與發展方向。這條是刻意的:AI 自己編出來的頁面結構通常對不上真實業務。
模板檔在本 skill 目錄的 `templates/`。
## 為什麼要有守門
兩個問題只有在 CI 擋下來才會真的被解決:
1. **設計會漂。** 一個人寫 `#3a7`、一個人寫 `rgb(51,119,85)`、下一個人寫 `var(--color-primary)`,三個月後沒人知道哪個是對的。字級同理,`font-size: 14px` 一旦混進來就會繁殖。
2. **AI 寫的中文有指紋。** 「不僅…更」「值得注意的是」「隨著…的發展」「這不是 X,而是 Y」。單獨看每���句都通順,整篇讀起來就是機器味。人工複核會累、會鬆,正則不會。
所以 `build` 一定串這兩支腳本,CI fail 就不上線。
## 守門規則
### 設計守門 `scripts/check-design.mjs`
掃 `src/` 下所有 `.css/.astro/.svelte`,違規 exit 1:
1. 禁 px 字���。一律 `var(--text-*)` 階梯,最小 18px,內文不小於 `--text-base`。
2. 顏色只准出現在 `src/styles/variables.css`。oklch 為準、hex 作 fallback。
3. 禁 `!important`。
4. 禁外部 CDN(fonts.googleapis、gstatic、cdnjs、unpkg、jsdelivr)。字型用系統堆疊。
5. **css 檔白名單**:`src/` 下的 `.css` 只准 `styles/variables.css` 與 `styles/global.css`。新增 css 檔即 fail,元件樣式寫 scoped `<style>`。
6. **階梯下限**:`--text-*` 的 token 值本身一律不小於 18px(1.125rem),`clamp()` 以最小值計。少了��條,前面第 1 條會被「把 token 值調小」繞過。
### 去 AI 味守門 `scripts/check-content.mjs`
掃 `src/**/*.md(x)`,兩級判定:
- **ERROR(單一命中即擋)**:誤判率接近零的強 AI 指紋。「不是 X 而是 Y」、「不僅…更」、「值得注意的是」、「換句話說」式的空泛收束、「隨著…的發展」開場、模糊引用(研究顯示/專家認為)、模板化的第一人稱開場。
- **WARN(軟訊號)**:分詞彙、句式、結構、語氣四層。破折號、「這是一個 X,也是一個 Y」、拔高收尾、賦能/助力這類詞。單一命中不擋;**同一檔跨三個以上不同層級才升級成 ERROR**。
那條「跨三層才算」是重點。單一特徵人類也會用,只憑一個就擋會產生大量誤判,接著團隊就會開始忽略守門,守門就死了。
**掃描範圍刻意只掃變動檔**(相對 `origin/main`)。抓不到 git base 時掃 0 個檔並 exit 0,永不誤擋。這樣既有內容不必先全部改乾淨才能用,新內容從今天開始守住。另有 `pnpm check:content:all` 做全站普查,恆 exit 0,只報告不擋。
**