opentui

作成者: msmps

OpenTUIを使用してターミナルユーザーインターフェースを構築するための包括的なスキル。コアの命令型API、Reactレコンサイラー、Solidレコンサイラーをカバーします。コンポーネント、レイアウト、キーボード処理、アニメーション、テストなど、あらゆるTUI開発タスクに使用します。

npx skills add https://github.com/msmps/opentui-skill --skill opentui

OpenTUI Platform Skill

Consolidated skill for building terminal user interfaces with OpenTUI. Use decision trees below to find the right framework and components, then load detailed references.

Critical Rules

Follow these rules in all OpenTUI code:

  1. Use create-tui for new projects. See framework REFERENCE.md quick starts.
  2. create-tui options must come before arguments. bunx create-tui -t react my-app works, bunx create-tui my-app -t react does NOT.
  3. Never call process.exit() directly. Use renderer.destroy() (see core/gotchas.md).
  4. Text styling requires nested tags in React/Solid. Use modifier elements, not props (see components/text-display.md).

How to Use This Skill

Reference File Structure

Framework references follow a 5-file pattern. Cross-cutting concepts are single-file guides.

Each framework in ./references/<framework>/ contains:

FilePurposeWhen to Read
REFERENCE.mdOverview, when to use, quick startAlways read first
api.mdRuntime API, components, hooksWriting code
configuration.mdSetup, tsconfig, bundlingConfiguring a project
patterns.mdCommon patterns, best practicesImplementation guidance
gotchas.mdPitfalls, limitations, debuggingTroubleshooting

Cross-cutting concepts in ./references/<concept>/ have REFERENCE.md as the entry point.

Reading Order

  1. Start with REFERENCE.md for your chosen framework
  2. Then read additional files relevant to your task:
    • Building components -> api.md + components/<category>.md
    • Setting up project -> configuration.md
    • Layout/positioning -> layout/REFERENCE.md
    • Keyboard/input handling -> keyboard/REFERENCE.md
    • Layered keybindings/commands -> keymap/REFERENCE.md
    • Animations -> animation/REFERENCE.md
    • Troubleshooting -> gotchas.md + testing/REFERENCE.md

Example Paths

./references/react/REFERENCE.md           # Start here for React
./references/react/api.md              # React components and hooks
./references/solid/configuration.md    # Solid project setup
./references/components/inputs.md      # Input, Textarea, Select docs
./references/core/gotchas.md           # Core debugging tips

Runtime Notes

OpenTUI runs on Bun and uses Zig for native builds. Read ./references/core/gotchas.md for runtime requirements and build guidance.

Quick Decision Trees

"Which framework should I use?"

Which framework?
├─ I want full control, maximum performance, no framework overhead
│  └─ core/ (imperative API)
├─ I know React, want familiar component patterns
│  └─ react/ (React reconciler)
├─ I want fine-grained reactivity, optimal re-renders
│  └─ solid/ (Solid reconciler)
└─ I'm building a library/framework on top of OpenTUI
   └─ core/ (imperative API)

"I need to display content"

Display content?
├─ Plain or styled text -> components/text-display.md
├─ Container with borders/background -> components/containers.md
├─ Scrollable content area -> components/containers.md (scrollbox)
├─ Standalone scrollbar -> components/containers.md (scrollbar)
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
├─ PNG/JPEG/WebP/GIF image -> components/text-display.md (image)
├─ First-draw diagnostic -> components/text-display.md (time-to-first-draw)
├─ QR code -> components/text-display.md (qr-code, @opentui/qrcode)
├─ Embedded child terminal/VT output -> components/containers.md (Core only)
├─ Data table with borders/wrapping -> components/code-diff.md (TextTable)
├─ Code with syntax highlighting -> components/code-diff.md
├─ Diff viewer (unified/split, hunk nav) -> components/code-diff.md
├─ Line numbers with diagnostics -> components/code-diff.md
└─ Markdown content (streaming) -> components/code-diff.md (markdown)

"I need user input"

User input?
├─ Single-line text field -> components/inputs.md (input)
├─ Multi-line text editor -> components/inputs.md (textarea)
├─ Select from a list (vertical) -> components/inputs.md (select)
├─ Tab-based selection (horizontal) -> components/inputs.md (tab-select)
├─ Value slider -> components/inputs.md (slider)
├─ Declarative/layered keybindings -> keymap/REFERENCE.md (@opentui/keymap)
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md

"I need layout/positioning"

Layout?
├─ Flexbox-style layouts (row, column, wrap) -> layout/REFERENCE.md
├─ Absolute positioning -> layout/patterns.md
├─ Responsive to terminal size -> layout/patterns.md
├─ Centering content -> layout/patterns.md
└─ Complex nested layouts -> layout/patterns.md

"I need animations"

Animations?
├─ Timeline-based animations -> animation/REFERENCE.md
├─ Easing functions -> animation/REFERENCE.md
├─ Property transitions -> animation/REFERENCE.md
└─ Looping animations -> animation/REFERENCE.md

"I need to handle input"

Input handling?
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
├─ Layered bindings, commands, leader keys -> keymap/REFERENCE.md
├─ Focus management -> keyboard/REFERENCE.md
├─ Paste events -> keyboard/REFERENCE.md
├─ Mouse events -> components/containers.md
├─ Text selection & copy-on-select -> keyboard/REFERENCE.md (selection)
└─ Host/terminal clipboard service or OSC 52 -> keyboard/REFERENCE.md (clipboard)

"I need to test my TUI"

Testing?
├─ Snapshot testing -> testing/REFERENCE.md
├─ Interaction testing -> testing/REFERENCE.md
├─ Test renderer setup -> testing/REFERENCE.md
└─ Debugging tests -> testing/REFERENCE.md

"I need platform capabilities (audio, images, clipboard, notifications, SSH)"

Platform capability?
├─ Play loaded sound or MP3/FLAC stream -> core/api.md (Audio)
├─ Capture microphone PCM / record WAV -> core/api.md (Audio)
├─ Decode, transform, or display images -> components/text-display.md (image)
├─ Read/write host or terminal clipboard -> keyboard/REFERENCE.md (clipboard)
├─ Desktop notifications (OSC 9/777/99) -> core/api.md (triggerNotification)
├─ Custom stdin/stdout (PTY, xterm.js) -> core/api.md (createCliRenderer)
└─ Serve a TUI over SSH -> core/REFERENCE.md (@opentui/ssh)

"I need to debug/troubleshoot"

Troubleshooting?
├─ Runtime errors, crashes -> <framework>/gotchas.md
├─ Layout issues -> layout/REFERENCE.md + layout/patterns.md
├─ Input/focus issues -> keyboard/REFERENCE.md
└─ Repro + regression tests -> testing/REFERENCE.md

Troubleshooting Index

  • Terminal cleanup, crashes -> core/gotchas.md
  • Text styling not applying -> components/text-display.md
  • Input focus/shortcuts -> keyboard/REFERENCE.md
  • Layout misalignment -> layout/REFERENCE.md
  • Flaky snapshots -> testing/REFERENCE.md

For component naming differences and text modifiers, see components/REFERENCE.md.

Product Index

Frameworks

FrameworkEntry FileDescription
Core./references/core/REFERENCE.mdImperative API, all primitives
React./references/react/REFERENCE.mdReact reconciler for declarative TUI
Solid./references/solid/REFERENCE.mdSolidJS reconciler for declarative TUI

Cross-Cutting Concepts

ConceptEntry FileDescription
Layout./references/layout/REFERENCE.mdYoga/Flexbox layout system
Components./references/components/REFERENCE.mdComponent reference by category
Keyboard./references/keyboard/REFERENCE.mdLow-level keyboard input handling
Keymap./references/keymap/REFERENCE.mdDeclarative layered keybindings (@opentui/keymap)
Animation./references/animation/REFERENCE.mdTimeline-based animations
Testing./references/testing/REFERENCE.mdTest renderer and snapshots

Component Categories

CategoryEntry FileComponents
Text & Display./references/components/text-display.mdtext, ascii-font, image, time-to-first-draw, styled text, qr-code
Containers./references/components/containers.mdbox, scrollbox, scrollbar, embedded-terminal, borders
Inputs./references/components/inputs.mdinput, textarea, select, tab-select, slider
Code & Diff./references/components/code-diff.mdcode, line-number, diff, markdown, text-table

Additional Packages

PackageDescriptionDocs
@opentui/keymapLayered keybinding/command engine (Bun or Node, no FFI)./references/keymap/REFERENCE.md
@opentui/qrcodeQR code component./references/components/text-display.md
@opentui/sshServe a TUI over SSH./references/core/REFERENCE.md
@opentui/threeThree.js WebGPU renderer (formerly core/src/3d)upstream packages/three
@opentui/examplesRunnable examples (formerly core/src/examples)upstream packages/examples

Core also ships loaded/streaming/captured Audio, native images, host and terminal clipboard services, and OSC desktop notifications.

Resources

Repository: https://github.com/anomalyco/opentui Core Docs: https://github.com/anomalyco/opentui/tree/main/packages/core/docs Examples: https://github.com/anomalyco/opentui/tree/main/packages/examples/src Awesome List: https://github.com/msmps/awesome-opentui

関連スキル

ui-sdk
vercel
Builds interfaces with ui-sdk in React, Vue, Svelte, Solid or web components. Covers choosing and composing its components, building a component or behavior it doesn't ship from @ui-sdk/core (like a stepper, splitter, transfer list or emoji picker), making the interface usable by agents through createAgent, agent tools and WebMCP, and testing keyboard, focus, ARIA, server rendering and right to left, including writing tests for an existing component. Use whenever a project has @ui-sdk/*...
testingdesigndevelopment
accessibility-engineering
addyosmani
既存のインターフェースを監査し、WCAG 2.2 AAへの適合性を確認して、見つかった違反を修正します。ページやコンポーネントのアクセシビリティ監査、axe-coreやpa11yの実行、a11y違反のトリアージ、リリース前のスクリーンリーダーやコントラストの問題の確認に使用します。
developmenttestingdesign
break-ui
emilkowalski
長い名前、改行できないメールアドレス、1文字の名前、欠落したフィールド、膨大な件数、項目なし、長いラベル、非ラテン文字、絵文字、極端な数値など、最悪のケースのデータを与えてUIの一部を壊してみてください。次に、「Demo data / Worst case」トグルの背後に表示し、壊れた箇所すべてと、それぞれの修正方法を報告します。ユーザーがコンポーネントや画面のストレステスト、破壊、エッジケースの発見、または「最悪のケースを試す」よう求めた場合に使用します。ビジュアルデザインの批評にはemil-design-engを使用してください。モーションについては…
testingdesigndevelopment
mobile-native
emilkowalski
Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or...
developmentdesigntesting
azure-resource-visualizer
microsoft
Azureリソースグループを、リソースの関係性や構成を示す詳細なアーキテクチャ図に変換します。リソースグループ内のすべてのリソースを検出し、その構成、依存関係、相互接続を分析します。論理レイヤー(ネットワーク、コンピュート、データ、セキュリティ、監視)ごとに整理されたMermaid図を生成し、SKUの詳細や接続ラベルを付与します。ネットワーク接続、データフロー、IDバインディング、構成依存関係など、リソース間の関係性をマッピングします。
devopsdesigndevelopment
expo-native-ui
expo
フレームワーク(OSS)。美しくネイティブ感のあるExpo画面を構築します。Apple HIGスタイリング、セマンティックカラー、ネイティブコントロール、SF Symbols、メディア、アニメーション、ビジュアルエフェクト、グラデーション、ストレージ、レスポンシブレイアウトをカバー。ルーティングとナビゲーションには、expo-routerスキルを使用してください。
designdevelopment
expo-router
expo
フレームワーク(OSS)。Expo Routerのナビゲーションとルーティング。ファイルベースのルート、グループと動的ルート、フォルダ構成、プレビューとコンテキストメニュー付きのLink、ネイティブStack、ページタイトル、モーダルとフォームシート、NativeTabs、ヘッダーとツールバー、ヘッダー検索バーをカバー。
apidesigndevelopment
expo-ui
expo
フレームワーク(OSS)。@expo/uiパッケージでネイティブUIを構築:iOSでは本物のSwiftUI、AndroidではJetpack ComposeをReactからレンダリングし、ExpoまたはReact Nativeアプリで動作。@expo/uiからインポートする汎用クロスプラットフォームコンポーネント(Host、Column、Row、Button、Text、Listなど)、人気のReact Nativeコミュニティライブラリのドロップイン代替(BottomSheet、DateTimePicker、Slider、Menuなど)、およびプラットフォーム固有のSwiftUI(@expo/ui/swift-ui、iOSのみ)とJetpack Composeをカバー。
designdevelopment