npm package: @harry4869/css-tokens
Description: Design tokens (CSS variables) and minimal Tailwind theme for Team Mirai projects
Author: Team Mirai
Latest version: 0.1.2

# @harry4869/css-tokens

Minimal design-tokens package for Team Mirai.

**shadcn/Radix 風の洗練されたカラーパレット、タイポグラフィ、コンポーネント CSS を備えたデザイントークンパッケージです。**

## 主な内容

- `src/index.css` — shadcn/Radix インスパイアのカラーパレット、トークン定義（ソース）
- `src/components/` — 再利用可能なコンポーネント CSS（カード、ボタン、入力フィールド）
- `dist/index.css`, `dist/index.min.css` — ビルド済みの配布ファイル
- `tailwind.config.cjs` — トークンを Tailwind クラスとして使うための設定
- `examples/sample/index.html` — 実際の使用例＆スタイルガイド

インストール

公開パッケージを使う場合:

```bash
npm install @harry4869/css-tokens
```

GitHub リポジトリから直接インストールする場合（公開前のテスト等）:

```bash
# 最新の main ブランチをインストール
npm install github:harry2480/Team-Mirai-CSS-Package

# 特定のタグ/バージョンを指定してインストール
npm install github:harry2480/Team-Mirai-CSS-Package#v0.1.0
```

ローカルから直接インストールする場合:

```bash
npm install file:../path/to/mirai-css-tokens
```

クイックスタート

1. パッケージをビルド（パッケージルートで実行）:

```bash
npm run build       # dist/index.css を生成
npm run build:prod  # minified 版（dist/index.min.css）も生成
```

2. アプリに読み込む

次のいずれかの方法で利用できます。

使い方（3通り）

1) 直接 CSS をインポート（例: Next.js / SvelteKit 等）

```ts
import '@harry4869/css-tokens/dist/index.css'
```

CSS 内でトークンを使用:

```css
body {
  background: hsl(var(--background));
  color: hsl(var(--foreground));
}

.card {
  background: hsl(var(--card));
  color: hsl(var(--card-foreground));
  border: 1px solid hsl(var(--border));
  border-radius: var(--radius-lg);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
}

.button {
  background: hsl(var(--primary));
  color: hsl(var(--primary-foreground));
  border-radius: var(--radius-lg);
  padding: 0.5rem 1rem;
  font-weight: 500;
  transition: all 0.2s ease-in-out;
}
```

2) Tailwind と統合

プロジェクトの `tailwind.config` にパッケージの拡張をマージする例:

```js
// tailwind.config.js
const mirai = require('@harry4869/css-tokens/tailwind.config.cjs')

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx,html}'],
  theme: {
    extend: mirai.theme.extend,
  },
}
```

その後エントリで CSS を読み込みます:

```ts
import '@harry4869/css-tokens/dist/index.css'
```

テンプレート例:

```html
<button class="bg-primary text-primary-foreground px-4 py-2 rounded-lg">
  Primary Button
</button>

<div class="bg-card border border-border rounded-lg p-6 shadow-sm">
  <h3 class="text-lg font-semibold">Card Title</h3>
  <p class="text-muted-foreground mt-2">Card description goes here.</p>
</div>
```

3) CSS 変数のみを使用

```css
@import '@harry4869/css-tokens/dist/index.css';

:root { 
  --my-primary: hsl(var(--primary)); 
}

.component { 
  color: var(--my-primary); 
  background: hsl(var(--background));
  padding: var(--radius-lg);
}
```

## コンポーネント（オプション）

パッケージに含まれる再利用可能なコンポーネント CSS を使うことで、一貫性のある UI をすぐに実装できます。

### カード

```html
<div class="card">
  <div class="card-header">
    <h3 class="card-title">Card Title</h3>
    <p class="card-description">Card description</p>
  </div>
  <div class="card-content">
    Content goes here.
  </div>
  <div class="card-footer">
    <button class="btn btn-secondary">Cancel</button>
    <button class="btn btn-primary">Save</button>
  </div>
</div>
```

### ボタン

```html
<!-- Variants -->
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-ghost">Ghost</button>
<button class="btn btn-destructive">Delete</button>

<!-- Sizes -->
<button class="btn btn-primary btn-sm">Small</button>
<button class="btn btn-primary btn-lg">Large</button>

<!-- Disabled -->
<button class="btn btn-primary" disabled>Disabled</button>
```

### フォーム

```html
<div class="form-group">
  <label class="label">Email</label>
  <input type="email" class="input" placeholder="your@email.com">
  <p class="helper-text">We'll never share your email.</p>
</div>
```

## ダークモード

パッケージは `.dark` セレクタ内のダークトークン定義を含みます。Tailwind をクラスベースのダークモードにする場合の例:

```js
module.exports = { darkMode: 'class' }
```

HTML のルートに `class="dark"` を付与するとダークトークンが自動的に適用されます:

```html
<html class="dark">
  <body>
    <!-- Dark mode tokens apply here -->
  </body>
</html>
```

JavaScript でも切り替え可能:

```js
function toggleDarkMode() {
  document.documentElement.classList.toggle('dark');
}
```

## 開発・ビルド

```bash
npm run build       # 通常ビルド（dist/index.css）
npm run build:prod  # 本番向け（minified 版を生成）
npm run lint        # stylelint を実行
npm run test        # テストを実行
```

## トークンの編集

1. `src/index.css` を編集（ソースが単一の真実）
2. `npm run build` または `npm run build:prod` を実行
3. `src/` と `dist/` をコミットしてプッシュ

## Prepare スクリプトについて

このパッケージは `prepare` スクリプトを持ちます。GitHub 経由でインストールされた場合、インストール後に自動的に `prepare` が走り `dist/` を生成します。受け手側にビルドツールが無いと失敗する可能性があるため、確実性を重視する場合は `dist/` をコミットして配布することを推奨します。

## 利用可能なトークン

### カラー

- `--primary`, `--primary-accent`, `--primary-foreground` — 鮮やかなインディゴ/ブルー系
- `--secondary`, `--secondary-foreground` — セカンダリカラー
- `--background`, `--foreground` — ページ背景とテキスト色
- `--card`, `--card-foreground` — カード背景とテキスト色
- `--muted`, `--muted-foreground` — 無効な状態、淡い色
- `--accent`, `--accent-foreground` — アクセント色
- `--destructive`, `--destructive-foreground` — エラー・危険状態
- `--border`, `--input`, `--ring` — ボーダー、入力フィールド、フォーカスリング

### スペーシング・タイポグラフィ

- `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` — 角丸の大きさ
- `--leading-relaxed` — 行間（1.875）
- `--tracking-tight`, `--tracking-normal` — 文字間隔
- `--font-size-sm`, `--font-size-base`, `--font-size-lg`, `--font-size-xl`, `--font-size-2xl` — フォントサイズ

### チャート色

- `--chart-1` ～ `--chart-5` — データ可視化用の色

## リリース・公開

```bash
# バージョン更新とタグ付け
npm version patch              # または minor/major に応じて
git push && git push --tags

# npm に公開（2FA が有効な場合は OTP を入力）
npm publish --access public

# GitHub Release 作成
gh release create v0.1.1 --generate-notes
```

**詳細手順:**
1. `package.json` の version を更新
2. `CHANGELOG.md` にリリースノートを記載
3. Git にコミット＆プッシュ、タグを作成
4. `npm publish --access public` で npm に公開
5. GitHub Release を作成して `dist/` ファイルを添付（オプション）

## トラブルシューティング

- **dist が見つからない**: `npm run build` を実行してください。
- **トークンが反映されない**: エントリで `dist/index.css` を確実に読み込んでいるか確認してください。
- **ダークモードが効かない**: Tailwind で `darkMode: 'class'` を有効にし、ルートに `class="dark"` を付与してください。
- **コンポーネント CSS がスタイルされない**: `@import './components/*.css'` が `src/index.css` に含まれていることを確認し、ビルドを実行してください。

## Examples（ローカルサンプル）

リポジトリには詳細なサンプルが含まれています: [examples/sample/index.html](../../examples/sample/index.html)

ローカルで確認：

```bash
cd examples/sample
npx http-server -p 8080
# ブラウザで http://127.0.0.1:8080 を開く
```

サンプルには以下が含まれます:
- カラーパレット（プライマリ、ミュート、デストラクティブなど）
- コンポーネント（カード、ボタン、フォーム）
- タイポグラフィ例
- ダークモード切り替えボタン