8.7 KiB

Raw Blame History

新アプリ作成ガイド

最終更新: 2026-04-11

posimai-project で新しい PWA アプリを作成し、エコシステムに統合するための完全な手順書。

0. テンプレート選択

テンプレート	使うべきアプリ
`_template-minimal/`	全ての新規アプリ（現行標準）

_template/（旧フル版）は廃止予定。_template-minimal/ が唯一の基準。

テンプレートに含まれるもの

index.html — posimai-ui 参照・JWT token handoff・PWA meta 完備
sw.js — stale-while-revalidate + skipWaiting（即時反映）
manifest.json — PWA 必須ファイル
package.json — npm run deploy スクリプト

1. アプリ分類と技術選定

実装パターンの選び方

パターン	対象	具体例
A: 静的 HTML + posimai-ui	単機能ツール・表示系	diff, clean, timer, lens, ambient
B: 静的 HTML + posimai-ui + Alpine.js	状態管理が必要なアプリ	brain, feed, journal, habit, pulse 相当の新アプリ
C: Next.js	複雑なデータダッシュボード・管理画面	dashboard, analytics 相当のみ

迷ったらパターン A から始める。 後から Alpine.js を足す方が、最初から Next.js にするより簡単。

Alpine.js の追加（パターン B）

<!-- </body> 直前の base.js の後に追記 -->
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.3/dist/cdn.min.js"
        integrity="sha384-GHo7DVRmCTRSFRzLMbZ4YtNhX4mJRqtGSZ6+j5RqbzW8i3KO/pFqGmNE7qJBg1t"
        defer></script>

バージョンは 3.14.3 固定（@latest 禁止）。使い方:

<div x-data="{ count: 0 }">
  <button x-on:click="count++">+</button>
  <span x-text="count"></span>
</div>

2. 実装前チェック（0 番台）

0. アクセントカラーを確定する

デフォルトの Teal (#6EE7B7) で問題なければ何もしない。変更する場合は docs/design-system.md の「アプリ別アクセントカラー」テーブルに先に追記してから実装を開始する。

カテゴリ別ガイドライン:

カテゴリ	推奨アクセント
input / routine / create / tools	`#6EE7B7` Teal（デフォルト）
インフラ / 開発ツール	`#22D3EE` Cyan または `#A78BFA` Violet
公開サイト / CMS	`#80CAEE` Sky-Blue
和風 / 特殊テーマ	デザインシステム外で独自定義

0.5. logo.png 用 Gemini プロンプトを作成する

共通プロンプト（全アプリ固定）:

App icon, 512x512px, squircle shape with rounded corners.
A small translucent glass orb character, soft matte-frosted surface with
inner teal (#6EE7B7) luminescence glowing from within, gentle light refraction.
Two tiny calm black dot eyes, subtle implied smile.
Background: deep charcoal (#0D0D0D) with barely visible teal ambient gradient.
Style: Apple Liquid Glass, multi-material, 2026 premium minimal.
No outline, no harsh edges. Soft depth, subsurface scattering.

アプリ固有の追加プロンプトを末尾に付ける（「持っているもの」「背景の変化」等の感覚的な表現でよい）。

3. 新規アプリ作成（コマンド 1 行）

bash create-app.sh posimai-myapp "My App Name" "アプリの説明"

このコマンドで自動完了するもの:

ステップ	内容
1	`_template-minimal/` をコピーして APP_ID/APP_NAME/APP_DESC を置換
2	Git 初期化・初回コミット
3	Gitea にリポジトリ作成（git credential store から自動認証）
4	GitHub にリポジトリ作成（`gh` CLI）
5	2リモート（gitea + github）に push
6	Vercel と GitHub を連携
7	初回本番デプロイ（空 commit で trigger）
8	`projects.json` にカード追加
8	`timeline/page.tsx` に launch エントリ追加
8	`roadmap.json` に追加
8	dashboard / roadmap をデプロイ

4. 手動で追加が必要なもの（判断が必要なため自動化不可）

4-A. apps/page.tsx の projectIds に追加

posimai-dashboard/src/app/apps/page.tsx の APP_CATEGORIES から適切なカテゴリを選んで projectIds に追加する。

カテゴリ一覧: input / routine / create / tools / business / infra / ideas

4-B. ecosystem/page.tsx のノード/エッジに追加

posimai-dashboard/src/app/ecosystem/page.tsx の NODES と EDGES に追加する。接続関係（VPS API を使うか・他アプリからデータを受け取るか）を判断して記述する。

4-C. logo.png の配置とデプロイ

Gemini で生成した logo.png をアプリディレクトリに配置後:

cd posimai-[app-name]
git add logo.png
git commit -m "feat: logo 追加"
npm run deploy

4-D. Dashboard をデプロイ（4-A / 4-B 完了後）

cd posimai-dashboard
git add src/app/apps/page.tsx src/app/ecosystem/page.tsx
git commit -m "feat: [app-name] をエコシステムに追加"
npm run deploy

5. アプリ固有の実装ガイドライン

CSS の書き方

<style>
    /* posimai-ui のトークンを使う — 直接カラーコードを書かない */
    .my-card {
        background: var(--surface);
        border: 1px solid var(--border);
        border-radius: var(--radius);
        color: var(--text);
    }

    /* アクセントを使う場合 */
    .my-btn {
        background: var(--accent);
        color: #0D0D0D;  /* アクセント上のテキストのみ直書き可 */
    }
</style>

禁止:

color: #6EE7B7 のような直接カラーコード（var(--accent) を使う）
posimai-ui のトークン外の色（--champions --teal-dim 等は analytics 専用）

API 呼び出しの書き方

const API_BASE = 'https://api.soar-enrich.com/brain/api';
const token = localStorage.getItem('posimai_token');

const res = await fetch(`${API_BASE}/your-endpoint`, {
    headers: { 'Authorization': `Bearer ${token}` }
});
if (!res.ok) throw new Error('API error');
const data = await res.json();

VPS API を使う新アプリの場合

server.js に新しいエンドポイントを追加する場合は bash deploy-server.sh でバックエンドをデプロイする。スキーマ変更（ALTER TABLE / DROP TABLE）は mai 確認必須。

SW キャッシュバージョンの管理

sw.js の const CACHE = 'APP_ID-v2'; の数値を変更すると旧キャッシュが削除される。機能追加・デザイン変更のたびに更新する必要はない。ファイル追加・削除時のみ更新する。

6. 実装チェックリスト（完了確認）

アプリ実装完了前に以下を全て確認すること:

[ ] index.html の <html data-app-id="posimai-[app-name]"> が正しいか
[ ] manifest.json の "id" が "/posimai-[app-name]/" になっているか
[ ] sw.js の CACHE 名に APP_ID が入っているか
[ ] posimai-ui の base.css / base.js を参照しているか
[ ] デザイントークン外の色を直書きしていないか
[ ] 外部リンクに rel="noopener" が付いているか
[ ] 絵文字が含まれていないか（コード・UI・コミット全て）
[ ] Lucide のバージョンが @0.344.0 固定になっているか
[ ] 空状態（Empty State）が実装されているか
[ ] PWA インストール可能か（manifest + SW + HTTPS）
[ ] logo.png が配置されているか

7. デプロイ手順（再掲）

# フロントエンド（全アプリ共通）
git add . && git commit -m "feat/fix/chore: ..." && npm run deploy
# = git push gitea main && git push github main → Vercel 自動デプロイ

# VPS バックエンド（server.js 変更時）
bash deploy-server.sh

# Ubuntu PC（posimai-dev / Station 変更時）
npm run deploy:dev  # git push + scp + systemctl restart