# design.md — 給 agent 的單一約束入口

要用這套元件基準做東西，抓這一份就拿到全部約束：載入順序、視覺規則、手機外框、
組裝接縫、禁止事項。更深的細節才需要往下抓：

- 元件索引與接縫契約全文：[COMPONENTS.md](./COMPONENTS.md)
- 各 domain 完整契約：[shell](./contracts/shell_nav.md)、[lists](./contracts/feed_list.md)、[read](./contracts/read_swipe.md)
- 工作區邊界：[AGENTS.md](./AGENTS.md)
- 人看的 catalog：[index.html](./index.html)

> **先讀這一段。這整套工具還是一個未驗證的假設。** 尚未有任何通過使用者 eval 的
> prototype 從它產出。它是待驗證的起點，不是已證明有效的規範。**目前也沒有產品意圖
> 的 source of truth**——不存在任何可引用的決策紀錄。遇到未定的產品問題（要呈現什麼
> 資訊、放哪個版位、教哪一段），回報並問使用者，不要因為畫面需要一個值就填上去。

## 載入順序

```html
<link rel="stylesheet" href="tokens.css">
<link rel="stylesheet" href="utilities.css">
<!-- 之後才是你需要的 domain CSS，可只載其一 -->
<link rel="stylesheet" href="shell.css">
<link rel="stylesheet" href="lists.css">
<link rel="stylesheet" href="read.css">
```

順序不要換。互動行為在 `shell.js`（app 導航）與 `read.js`（滑動判讀）。

## 視覺規則

- 一律 `var(--token)`，**不得寫死 hex 或 px**。缺變數不要自己加，回報建議。
- 灰階為主。**唯一允許的彩色是漲跌語意**：`--color-up`／`--color-down`／`--color-flat`。
- **資訊位不得填真資訊**，一律用 `--color-skeleton` 骨架佔位，不要編數字、編股名。
  唯一允許畫出真實形狀的是 K 線（用假數據），因為 K 線形狀是滑動判讀互動的一部分。

## 手機外框

產品原型**主動用手機外框呈現**，引用 [`device-frame.css`](./device-frame.css)，
不要自己重畫。規格頁（含縮放展示、安全區、螢幕校準、使用規則）：
[preview-device.html](./preview-device.html)。

```html
<link rel="stylesheet" href="device-frame.css">

<div class="device" data-phone-frame>
  <div class="device-screen">
    <div class="device-statusbar"><!-- 骨架見 preview-device.html --></div>
    <div class="device-viewport"><!-- 你的 prototype 放這裡 --></div>
  </div>
</div>
```

- 尺寸 393 × 852（iPhone 15 邏輯像素），與 `tokens.css` 的 `--shell-width`／`--shell-height` 同一組值。**不要引入第三組尺寸。**
- **狀態列固定保留**：它是裝置外殼，不得移除、不得放產品資訊。
- 內容一律放進 `.device-viewport`，那是唯一的縱向 scroller。
- 這個檔刻意自足、不 import tokens；深色在 `.device` 上加 `data-device-theme="dark"`。

catalog 本身不受此限——局部呈現（半台手機、只露 nav）在 catalog 裡是可以的。

## 組裝接縫（最常踩的五條）

完整版在 [COMPONENTS.md](./COMPONENTS.md) 的「接縫契約」，衝突時以那節為準。

1. 內容只掛在 `.shell-slot[data-shell-slot]`，必要結構鏈一層都不能省：
   `.shell-root > .shell-stack > .shell-stack-page > .shell-page-scroll > .shell-slot`。
2. 可用高度由 shell 算好，內容端不要再扣 status bar／nav／safe bottom。
3. 縱向 scroll 只有一個 owner：預設 `.shell-page-scroll` 捲；滑動判讀必須改走
   `data-shell-scroll-mode="fill"`。
4. `.shell-slot` 不自帶水平 padding；header 與 back 歸 shell，內容裡不要放第二套。
5. 事件往上冒泡（`lila:shell-change`、`read:*`），不要反向讀別人的 DOM。

## 邊界

- **這個資料夾對 agent 唯讀。** import 它、照它組裝；產品原型裡可以自由新增自己的
  component，那是新檔案，不是修改這裡。
- `../LILA_v2/` 是**過去的探索紀錄，不是權威**——不得引用它、不得把 D／O 代號當成
  已定案的約束。
- **不做決策狀態標記**：不要在元件旁加 Approved／Candidate／OPEN 之類的標籤。
  完整度不等於已採用——一個做得很完整的畫面，不代表那個方向被選中了。
- 不得抄 token 值。要展示 token 一律 `var()` 渲染＋`getComputedStyle` 讀值。