包裹裡的那份說明書，
長什麼樣

規格裡有六件事

一顆元件的規格書固定回答六個問題。少一項，工程端就得靠猜——而猜出來的東西，驗收時一定對不上。

• 1. Component 對應Storybook component id 對應 iOS / Android 的真實元件名稱。
  button → ChipKButton
• 2. Props 與 variants支援哪些尺寸、樣式、狀態與 slot。
  size, variant, disabled, leadingIcon
• 3. Tokens要使用哪些 design token，避免 native 手抄色碼與間距。
  --cm-comp-button-corner-radius
• 4. Accessibilityrole、label、disabled、selected 等 native 可存取行為。
  iconOnlyRequiresLabel: true
• 5. Events互動事件名稱，讓 flow、QA、分析追蹤能對齊。
  button.click
• 6. Gap reportnative 尚未支援的 props、states、tokens 或平台差異。
  status: partial

id: button
storybookSource: components-button--primary
nativeName:
  ios: ChipKButton
  android: ChipKButton
props:
  variant: [primaryFill, primaryOutline]
  size: [tiny, small, medium, large]
  disabled: boolean
slots:
  leadingIcon: IconName
  label: string
tokens:
  cornerRadius: --cm-comp-button-corner-radius
  labelColor: --cm-comp-button-primary-fill-default-label-color
accessibility:
  iconOnlyRequiresLabel: true
events:
  press: button.click

• AI從 Storybook 與 tokens 產出六項規格。對不上的不要硬湊——寫進 gap report。
• 工程師六項逐項對照自己的實作，缺哪一項就回報，不要靠猜補上。
• 設計師規格產不出來，通常是元件規格本身有缺（少了某個狀態或 token）——回頭補目錄。

提醒：這份規格讓 Storybook、iOS、Android 用完全不同的技術實作，但對外能力保持一致——這正是驗收時能拿真機截圖和 Storybook 並排比對的原因。

背後的指令：npm run contracts:native-spike　·　驗證：npm run check:native-spike

如果 native 已經有元件，怎麼接

先 mapping，再決定是否 wrapper 或重做。不要一開始就要求 native 全部重寫——那會讓這件事在第一週就停擺。每顆既有元件先標一個狀態，再逐步收斂。

• adoptednative 元件已符合規格，直接沿用。
• partial只符合部分 props 或 states，缺的記進 gap report。
• wrapped需要 adapter 對齊命名、props 或 tokens。
• rebuild-required差異太大，未來應逐步重做——但不是現在。

storybookId: button
ios:
  existingComponent: PrimaryActionButton
  status: partial
  propMap:
    variant.primaryFill: style.filled
    variant.primaryOutline: style.outline
    disabled: isEnabled = false
  unsupported:
    - trailingIcon

• 工程師逐顆既有元件標一個狀態，誠實標——標成 adopted 但其實只做一半，驗收時才會爆。
• 設計師看 unsupported 清單，決定哪些要補進目錄、哪些接受平台差異。
• AI產 mapping 草稿，不捏造 native 元件名稱；查不到就留空等人填。

提醒：unsupported 不是失敗，是把已知落差寫下來。沒寫下來的落差，會在驗收時變成「怎麼跟 Demo 不一樣」的爭論。

建議協作方法：從小範圍開始

不要一次把整本目錄丟過去。先用少數幾顆元件跑通一輪，確認規格夠不夠用、格式對不對得上，再擴大。

1. 先從小範圍 spike 開始——選 1–2 個元件（例如 Button、Switch、RealtimeQuoteRow），再加上一個 Prototype flow。
2. 先輸出 tokens——讓 iOS / Android 先確認顏色、字體、間距、圓角、motion 能不能接。
3. 再輸出 component contracts——確認 props、variants、states、slots、events、a11y 是否足夠 native 實作。
4. 產生 native preview 或 starter——用來檢查規格是否可用，不把它當成 production app。
5. native team 回 gap report——回報缺 token、缺 prop、狀態不支援、平台行為不同、a11y 差異。

• 設計師挑第一批要 spike 的元件——挑用得最多的，不要挑最漂亮的。
• AI依序產出 tokens → component contracts → preview，每一步做完停下來給人看。
• 工程師每一步都回一句「接得上／接不上」，接不上就說是哪一項。

提醒：第 4 步產出的 preview 是驗證工具，不是產品。它存在的唯一目的是回答「這份規格夠不夠工程端實作」。

預覽：npm run preview:ios-native（需要 Xcode toolchain）

和 native 工程師開會要定下來的事

這六件事沒定下來，規格書產出來也沒人接。一次會議就能定完——但要六項都有明確答案，不能留「之後再說」。

• Native 端正式消費的 artifact 是什麼。是 JSON？是產出的原生套件？講清楚工程端每次要拿哪一個檔案。
• 第一批要 spike 的 component 與 prototype flow。具體到元件名稱，不要說「幾個常用的」。
• iOS / Android 的 token 格式與單位轉換規則。顏色格式、pt / dp 換算、字級對應。
• 既有 native 元件的 adoption mapping 狀態。逐顆標 adopted / partial / wrapped / rebuild-required。
• 哪些平台行為由 native 自己決定。手勢、focus、haptics、navigation——白紙黑字寫下來，之後不爭論。
• Gap report 要怎麼回到 design-system repo。誰開、開在哪、誰收、多久回應。

• 設計師帶著目錄和一份 contract 範例去開會，用實物談比用概念談快。
• 工程師六項逐項給明確答案，不要留「之後再說」——留下的每一項都會變成之後的返工。