@oyster-lib/ui
v0.15.0
Published
AI-friendly, accessible React component library built with TypeScript, Tailwind CSS v4, and shadcn/ui
Maintainers
yuto_taniReadme
@oyster-lib/ui
React/TypeScript ベースの UI コンポーネントライブラリです。
インストール
npm install @oyster-lib/uiCSS のセットアップ
推奨設定（Tailwind CSS v4 との共存）
@oyster-lib/ui は Tailwind CSS v4 を使用しています。アプリ側で unprefixed（bg-primary 等）の
ユーティリティを Oyster のデザイントークンに解決させるため、@oyster-lib/ui/theme.css（トークン橋渡し）
を取り込みます。これ一発で --color-*・--spacing・--radius-*・dark variant が配線されるので、
アプリ側で @theme や --spacing を手書きする必要はありません。
layout.tsx（または _app.tsx）:
// @oyster-lib/ui のスタイルを先にインポート
import '@oyster-lib/ui/styles.css'
// 利用側のグローバルスタイル
import './globals.css'globals.css:
/* Tailwind CSS v4 の分割インポート（preflight は styles.css が供給するためスキップ） */
@import 'tailwindcss/theme.css';
@import '@oyster-lib/ui/theme.css'; /* ← Oyster トークン橋渡し（bg-primary 等がこれで解決） */
/* @import 'tailwindcss/preflight.css'; */
@import 'tailwindcss/utilities.css';
/* プロジェクト固有のスタイル */
@import "tailwindcss"をまとめて使う場合は、その直後に@import "@oyster-lib/ui/theme.css";を置けば トークンは解決されます。ただし@oyster-lib/ui/styles.cssも preflight を含むため、 preflight の二重ロードを避けたい場合は上記の分割インポートを推奨します。
提供される CSS export
| import | 内容 | 用途 |
| --------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------- |
| @oyster-lib/ui/styles.css | コンパイル済みコンポーネントスタイル（oy: utilities + preflight + --oy-* トークン） | コンポーネントを使うため必須 |
| @oyster-lib/ui/theme.css | トークン橋渡し（source）: @theme で --color-*/--spacing/--radius-* を --oy-* に接続 + dark variant + layer 順 | アプリ側の unprefixed utility を Oyster トークンに解決 |
| @oyster-lib/ui/generated-tokens.css | theme.css が内部 @import する実体（--oy-* 値 + @theme inline） | 高度な用途（個別取込） |
theme.css は Tailwind v4 のソースディレクティブ（@theme 等）を含むため、アプリ側の
@import "tailwindcss" がある CSS から @import してビルド時に展開する必要がある
（コンパイル済みの styles.css には @theme は残らない）。
よくある問題
bg-primary / text-foreground などの トークン系ユーティリティが効かない
原因: アプリ側の Tailwind に Oyster トークンの橋渡し（@theme）が無い。
解決: @import '@oyster-lib/ui/theme.css'; をアプリの Tailwind エントリに追加してください。
pt-16, mt-4 などの 素のユーティリティが効かない
原因: @import "tailwindcss" と @oyster-lib/ui/styles.css の preflight 二重ロード。
解決: 上記の分割インポートを使用してください。
スタイルの優先度がおかしい
原因: CSS のインポート順序が不適切
解決: @oyster-lib/ui/styles.css を 先に インポートしてください。
// ✅ 正しい順序
import '@oyster-lib/ui/styles.css'
import './globals.css'
// ❌ 間違った順序
import './globals.css'
import '@oyster-lib/ui/styles.css'使用例
import { Button, Stack } from '@oyster-lib/ui'
function App() {
return (
<Stack space="md">
<Button>プライマリボタン</Button>
<Button variant="outline">アウトラインボタン</Button>
</Stack>
)
}スタイルのカスタマイズ
className prop
// oy: プレフィックスで Oyster のユーティリティを使用
<Button className="oy:bg-red-500 oy:hover:bg-red-600">
カスタムボタン
</Button>
// 利用側の Tailwind ユーティリティも併用可能
<Button className="oy:bg-red-500 mt-4">
カスタムボタン
</Button>ダークモード
<html> 要素に .dark クラスを付与することでダークモードが有効になります:
<html class="dark">
<body>...</body>
</html>ドキュメント
詳細は src/docs/getting-started.md を参照してください。
ライセンス
MIT