安裝方法

用 Composer 安裝、用 ui:install 接線、再建置。三步之後，全部元件與 55 套主題 × 13 套調音即可使用。

前提條件

• PHP 8.2 以上
• Laravel 11 / 12 / 13
• Tailwind CSS v4（Laravel 11+ 的 Vite 標準配置）
• Node.js（供 Vite 建置使用）

1. 加入套件

composer require sparrowhawk-labs/pinion-ui

圖示套件（pinion-icons）會作為相依自動安裝，無需另外安裝。

2. 用 ui:install 完成接線

php artisan ui:install --ai

這個指令會完成所有必要的接線:

• 加入 npm 相依 — daisyui ^5 / alpinejs ^3 / @alpinejs/focus / @alpinejs/collapse
• 在 resources/css/app.css 加入一行 pinion-ui 預設集的 @import（一次載入主題、調音與 @source 萬用字元）
• 在 resources/js/app.js 接入 Alpine 及其外掛
• 為版型的 <html> 補上 data-theme 屬性
• 加上 --ai 後，會在專案的 CLAUDE.md 追加對 AGENTS.md 的引用，讓 AI 代理能讀到正確的使用規則

3. 建置

npm install && npm run build

到此完成。<x-button> 等元件即可直接在 Blade 模板中使用。

選擇主題與調音

外觀由 <html> 上的兩個屬性決定: data-theme 控制配色（55 套調色盤 × 亮/暗），data-tune 控制形狀、間距與字體（13 套預設）。兩軸相互正交，可自由組合。

<html data-theme="pinion" data-tune="default">

可以用導覽列右上角的 Theme / Tune 切換器即時切換、挑選組合 —— 本頁也會一起變化。

第一個元件

<x-button color="primary" icon="rocket">Hello Pinion</x-button>

驗證安裝只需一顆按鈕。從元件目錄可以連到每個元件的用法頁面。 元件目錄 →

與 AI 代理一起使用

pinion-ui 為 AI 輔助開發而設計。ui:install --ai 接入的 AGENTS.md 彙整了呼叫慣例、易錯點與類別詞彙規則，Claude Code 等代理據此從一開始就寫出正確的程式碼。同時也會安裝一個 Claude Code 掛鉤，在編輯 Blade 後自動執行 ui:lint（可用 --skip-hooks 略過）。