Astryx

ルートは Node.js 22+ と pnpm 11（Corepack）で管理。公開 npm パッケージは packages/、検証用アプリは apps/、eslint プラグインや vibe-tests などは internal/ に分かれる。

astryx/
├── packages/
│   ├── core/      # @astryxdesign/core
│   ├── cli/       # @astryxdesign/cli
│   ├── build/     # StyleX ビルドプラグイン
│   ├── themes/    # @astryxdesign/theme-*
│   ├── lab/       # 実験コンポーネント（内部利用）
│   ├── vega/      # Vega / Vega-Lite（@canary）
│   └── charts/    # D3 ベースのチャート（@canary）
├── apps/
│   ├── docsite/   # 公式ドキュメント
│   ├── storybook/ # コンポーネントカタログ
│   ├── sandbox/   # テーマ・トークン検証
│   └── example-*  # Next.js / Vite 各種例
└── internal/
    ├── eslint-plugin-astryx/
    └── vibe-tests/  # ビジュアル/a11y 評価

flowchart TB
  subgraph consumer["利用者アプリ"]
    APP["React ページ"]
  end
  subgraph css["CSS レイヤー（import 順固定）"]
    R["reset.css
@layer reset"]
    B["astryx.css
@layer astryx-base"]
    T["theme.css
@layer astryx-theme"]
    R --> B --> T
  end
  subgraph runtime["ランタイム"]
    TH["Theme プロバイダ"]
    CMP["@astryxdesign/core コンポーネント"]
    TH --> CMP
  end
  subgraph tooling["CLI / JSON API"]
    CLI["astryx search / component / template"]
    JSON["--json エンベロープ"]
    CLI --- JSON
  end
  APP --> css
  APP --> runtime
  tooling -.->|"docs / scaffold"| APP
      

利用者は StyleX を意識しない。作者側だけ StyleX でコンポーネントを実装し、利用者には pre-built CSS と React API だけが見える。

# install
npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

# globals.css（順序がカスケード契約）
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

'use client';
import { Theme } from '@astryxdesign/core/theme';
import { neutralTheme } from '@astryxdesign/theme-neutral/built';

export function Providers({ children }: { children: React.ReactNode }) {
  return <Theme theme={neutralTheme}>{children}</Theme>;
}

Vite・Tailwind 併用・CDN 配布などフレームワーク別手順は @astryxdesign/core の README Quick Start を参照。

• Guidance over enforcement — コンポーネントは能力を提供し、渡した値はそのまま描画する。設計上の意見は docs と example に置く。
• Strong, documented conventions — 命名・props・合成ルールが全コンポーネントで統一。少数を覚えれば未知の部品も予測しやすい。
• One system for humans and AI — API・docs・CLI を同時に設計。AI 向け改善は人間向け UX 改善と同型。
• Earned by measurement — 規約は断言ではなくテストで検証し、状況が変われば見直す。