元件
pinion-ui

Theme

Tune

Lang

安裝方法

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

前提條件

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

1. 加入套件

bash 
composer require sparrowhawk-labs/pinion-ui

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

2. 用 ui:install 完成接線

bash 
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. 建置

bash 
npm install && npm run build

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

選擇主題與調音

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

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

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

第一個元件

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

<button class="inline-flex items-center justify-center whitespace-nowrap font-medium tracking-wide transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 rounded-[var(--radius-field)] border-[length:var(--border)] h-[var(--h-field-md)] px-[var(--px-field-md)] text-[length:var(--text-field-md)] gap-2 bg-primary text-primary-content border-primary hover:bg-primary/90 focus-visible:ring-primary cursor-pointer"><svg class="w-4 h-4" viewbox="0 0 24 24">
<path fill="currentColor" fill-rule="evenodd" d="m14.447 16.377l5.847-5.83c.842-.839 1.263-1.259 1.484-1.792S22 7.627 22 6.44v-.567c0-1.826 0-2.739-.569-3.306S19.947 2 18.116 2h-.57c-1.19 0-1.785 0-2.32.221c-.536.221-.957.641-1.8 1.48L7.58 9.531c-.984.98-1.594 1.589-1.83 2.176a1.5 1.5 0 0 0-.112.562c0 .802.647 1.448 1.942 2.739l.174.173l2.038-2.069a.75.75 0 1 1 1.069 1.053L8.816 16.24l.137.137c1.295 1.29 1.943 1.936 2.747 1.936c.178 0 .348-.031.519-.094c.603-.222 1.219-.836 2.228-1.842m2.747-6.846a1.946 1.946 0 0 1-2.747 0a1.93 1.93 0 0 1 0-2.738a1.946 1.946 0 0 1 2.747 0a1.93 1.93 0 0 1 0 2.738" clip-rule="evenodd"></path>
<path fill="currentColor" d="M9.034 5.963L6.491 8.5c-.467.466-.896.893-1.235 1.28a6 6 0 0 0-.619.82l-.024-.025l-.095-.094a4.9 4.9 0 0 0-1.532-1.004l-.123-.05l-.379-.15a.764.764 0 0 1-.259-1.252C3.345 6.907 4.69 5.566 5.34 5.297a3.4 3.4 0 0 1 1.788-.229c.546.081 1.063.362 1.907.895m4.342 13.35c.205.208.34.355.464.512q.243.311.434.658c.142.26.253.537.474 1.092a.69.69 0 0 0 1.126.224l.084-.083c1.12-1.117 2.465-2.458 2.735-3.105a3.35 3.35 0 0 0 .229-1.782c-.081-.545-.362-1.06-.897-1.902l-2.552 2.544c-.478.477-.916.914-1.313 1.256c-.237.206-.497.41-.784.586" opacity=".3"></path></svg> Hello Pinion</button>

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

與 AI 代理一起使用

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