quan0715 QJudge UI Carbon Owner
Quick start
- 先確認需求屬於：元件/UI 行為、樣式、版面或 Storybook。
- 先讀：
references/carbon-policy.md。 - Carbon component、icon、Charts 或 Labs API 不確定時，套用
carbon-builder的 MCP Discover → Canonicalize → Target 流程；QJudge 專案規則仍以本 skill 為準。 - 若是捲動/裁切問題，再讀：
references/overflow-layout-playbook.md。 - 變更 shared/component 時同步更新 colocated stories；
.storybook/main.ts會自動探索，沒有 manual registry。 - 若 Carbon API、variant 或 accessibility 規則可能變動，先用 IBM Carbon MCP 查
docs_search，再用code_search取得目前 React 範例；Carbon Charts 只用get_charts。
責任邊界（Owner Scope）
- ✅ Carbon-first 樣式規範與 UI 實作落地。
- ✅ Storybook 撰寫規範與自動探索契約。
- ✅ overflow / split pane / full-bleed 版面修復。
- ❌ 不定義 git/PR 流程（交給
qjudge-github-workflow-owner）。 - ❌ 不定義 layer/import rule（交給
qjudge-architecture-owner）。 - ❌ 不定義 compose 執行命令（交給
qjudge-env-compose-owner）。
核心規則
- 禁止新增或依賴
.cds--*/.bx--*internal selector；只使用 Carbon public API、app-owned class 與 token。 - 禁止
!important。 - React SCSS 禁止
var(--cds-spacing-*)：Carbon React 不會輸出這組 runtime custom properties，瀏覽器會直接丟棄整條 spacing declaration。使用@use "@carbon/layout";與layout.$spacing-*；plain CSS 則使用 canonical rem value 或遷移成 SCSS。 - Layout 優先 Carbon
Grid/Column與 2x Grid 節奏。 - 單視圖只保留一個主垂直捲動容器。
- 操作回饋（成功/失敗）優先使用
useToast；避免在內容區堆疊InlineNotification。 - 原生
<button>/<input>/<select>/<textarea>原則上改用 Carbon；shared/copilotpackage boundary、file input、editor/canvas 等例外仍須具備完整 HTML semantics 與 accessible name。
Toolbar / Navbar 設計偏好（QJudge 預設）
- Answering toolbar 視覺語言對齊 Global Nav bar（高度、按鈕尺寸、密度一致）。
- Toolbar 背景使用
var(--cds-background)，避免做出明顯色塊分層；優先淡化 chrome，讓使用者聚焦題目內容。 - Action Button 預設使用 Carbon
medium，高度與 navbar 一致（3rem）。 - Header / Navbar / Toolbar 的 action button 一律使用 default size（禁止
size="sm"），確保高度一致且對齊3remnav bar；若需緊湊只調整內文，不調整按鈕高度。 - Answering toolbar 預設不保留左右內距（移除常見
16pxside padding），避免內容區視覺被擠壓。 - Demo 模式不顯示 toolbar 返回上一頁按鈕，只保留必要資訊（標題、狀態）。
- 監考提示採低干擾呈現：使用中性色 tag（如
cool-gray）與簡短文案（例如「監控中」），避免高警示色造成多餘壓力。
檢查命令
- 全量稽核（列出 blocker、review、exception-review）：
node .codex/skills/qjudge-quality-gates-owner/scripts/audit-carbon-practices.js --root frontend/src
- staged hard gate：
bash .codex/skills/qjudge-quality-gates-owner/scripts/check-carbon-style.sh --staged
- 全量 strict gate：
bash .codex/skills/qjudge-quality-gates-owner/scripts/check-carbon-style.sh --all
- spacing token 自動修復（先 dry-run，再寫入）：
node .codex/skills/qjudge-quality-gates-owner/scripts/fix-carbon-spacing-tokens.js --root frontend/srcnode .codex/skills/qjudge-quality-gates-owner/scripts/fix-carbon-spacing-tokens.js --root frontend/src --write
參考文件
- Carbon 規範：
references/carbon-policy.md - Storybook：
references/storybook.md - Overflow 修復：
references/overflow-layout-playbook.md
Cross-skill handoff
- 若 UI 任務牽涉路徑歸屬/層級邊界，先走
qjudge-architecture-owner。 - 若需要 PR/release 決策，轉交
qjudge-github-workflow-owner。
Portable notes
- 可移植核心：Design-system-first、單 scroll owner、stories 與元件同演進。
- 若換 design system，只替換 token/class 禁止策略與 Storybook discovery 設定。