opentui

bởi msmps

Kỹ năng OpenTUI toàn diện để xây dựng giao diện người dùng terminal. Bao gồm API mệnh lệnh cốt lõi, bộ điều hợp React và bộ điều hợp Solid. Sử dụng cho bất kỳ tác vụ phát triển TUI nào bao gồm thành phần, bố cục, xử lý bàn phím, hoạt ảnh và kiểm thử.

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

Skills liên quan

ui-sdk
vercel
Xây dựng giao diện bằng ui-sdk trong React, Vue, Svelte, Solid hoặc web components. Bao gồm việc chọn và kết hợp các thành phần của thư viện, xây dựng thành phần hoặc hành vi mà thư viện không cung cấp từ @ui-sdk/core (như stepper, splitter, danh sách chuyển mục hoặc bộ chọn emoji), giúp agent sử dụng giao diện thông qua createAgent, công cụ dành cho agent và WebMCP, cũng như kiểm thử bàn phím, tiêu điểm, ARIA, kết xuất phía máy chủ và bố cục từ phải sang trái, bao gồm cả việc viết kiểm thử cho một thành phần hiện có. Sử dụng bất cứ khi nào dự án có @ui-sdk/*...
testingdesigndevelopment
accessibility-engineering
addyosmani
Kiểm tra các giao diện hiện có để xác minh mức độ tuân thủ WCAG 2.2 AA và khắc phục các lỗi được phát hiện. Sử dụng khi kiểm tra khả năng truy cập của trang hoặc thành phần, chạy axe-core hoặc pa11y, phân loại lỗi a11y, hoặc kiểm tra các vấn đề về trình đọc màn hình và độ tương phản trước khi phát hành.
developmenttestingdesign
break-ui
emilkowalski
Thử làm hỏng một phần giao diện bằng cách đưa vào dữ liệu ở trường hợp xấu nhất — tên dài, email không thể ngắt dòng, tên chỉ có một chữ cái, trường bị thiếu, số lượng cực lớn, không có mục nào, nhãn dài, văn bản phi Latin, emoji, số cực lớn — sau đó hiển thị giao diện với công tắc "Demo data / Worst case" và báo cáo mọi thứ bị lỗi, kèm cách khắc phục cho từng lỗi. Dùng khi người dùng yêu cầu kiểm thử sức chịu đựng, làm hỏng hoặc tìm các trường hợp biên trong một thành phần hay màn hình, hoặc yêu cầu "thử trường hợp xấu nhất". Để phê bình thiết kế trực quan, dùng emil-design-eng; để xử lý chuyển động...
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
Chuyển đổi các nhóm tài nguyên Azure thành sơ đồ kiến trúc chi tiết hiển thị mối quan hệ và cấu hình tài nguyên. Khám phá tất cả tài nguyên trong một nhóm tài nguyên và phân tích cấu hình, phụ thuộc, kết nối giữa chúng. Tạo sơ đồ Mermaid được tổ chức theo các lớp logic (Mạng, Tính toán, Dữ liệu, Bảo mật, Giám sát) với chi tiết SKU và nhãn kết nối. Ánh xạ mối quan hệ bao gồm kết nối mạng, luồng dữ liệu, ràng buộc danh tính và phụ thuộc cấu hình trên...
devopsdesigndevelopment
expo-native-ui
expo
Khung mã nguồn mở. Xây dựng các màn hình Expo đẹp, mang cảm giác native. Bao gồm kiểu dáng Apple HIG, màu sắc ngữ nghĩa, điều khiển native, SF Symbols, media, hoạt ảnh, hiệu ứng hình ảnh, gradient, lưu trữ và bố cục đáp ứng. Để định tuyến và điều hướng, hãy sử dụng kỹ năng expo-router.
designdevelopment
expo-router
expo
Khung mã nguồn mở. Điều hướng và định tuyến cho Expo Router. Bao gồm các tuyến dựa trên tệp, nhóm và tuyến động, tổ chức thư mục, Liên kết có xem trước và menu ngữ cảnh, Stack gốc, tiêu đề trang, modal và trang tính biểu mẫu, NativeTabs, tiêu đề và thanh công cụ, và thanh tìm kiếm tiêu đề.
apidesigndevelopment
expo-ui
expo
Khung (Mã nguồn mở). Xây dựng giao diện người dùng gốc với gói @expo/ui: SwiftUI thực trên iOS và Jetpack Compose trên Android được hiển thị từ React trong ứng dụng Expo hoặc React Native. Bao gồm các thành phần đa nền tảng phổ quát (Host, Column, Row, Button, Text, List, và nhiều hơn nữa được nhập từ @expo/ui), các thay thế trực tiếp cho các thư viện cộng đồng React Native phổ biến (BottomSheet, DateTimePicker, Slider, Menu, v.v.), và SwiftUI dành riêng cho nền tảng (@expo/ui/swift-ui, chỉ iOS) và Jetpack Compose...
designdevelopment