Agent skill
inkjs-design
Ink.js (React for CLI) design and implementation guide. Use when: (1) Creating or modifying Ink.js components (2) Implementing Ink-specific hooks (useInput, useApp, useFocus) (3) Handling emoji/icon width issues (string-width workarounds) (4) Building terminal-responsive layouts (5) Managing multi-screen navigation (6) Implementing animations (spinners, progress bars) (7) Optimizing performance (React.memo, useMemo) (8) Handling keyboard input and shortcuts (9) Testing CLI UI (ink-testing-library)
Install this agent skill to your Project
npx add-skill https://github.com/akiojin/skills/tree/main/cli-design/skills/inkjs-design
SKILL.md
Ink.js Design
Comprehensive guide for building terminal UIs with Ink.js (React for CLI).
Quick Start
Creating a New Component
- Determine component type: Screen / Part / Common
- Reference component-patterns.md for similar patterns
- Add type definitions
- Implement component
- Write tests
Common Issues & Solutions
| Issue | Reference |
|---|---|
| Emoji width misalignment | ink-gotchas.md |
| Ctrl+C called twice | ink-gotchas.md |
| useInput conflicts | ink-gotchas.md |
| Layout breaking | responsive-layout.md |
| Screen navigation | multi-screen-navigation.md |
Directory Conventions
src/cli/ui/
├── components/
│ ├── App.tsx # Root component with screen management
│ ├── common/ # Common input components (Select, Input)
│ ├── parts/ # Reusable UI parts (Header, Footer)
│ └── screens/ # Full-screen components
├── hooks/ # Custom hooks
├── utils/ # Utility functions
└── types.ts # Type definitions
Component Classification
Screen (Full-page views)
- Represents a complete screen/page
- Handles keyboard input via
useInput - Implements Header/Content/Footer layout
- Manages screen-level state
Part (Reusable elements)
- Reusable UI building blocks
- Optimized with
React.memo - Stateless/pure components preferred
- Accept configuration via props
Common (Input components)
- Basic input components
- Support both controlled and uncontrolled modes
- Handle focus management
- Provide consistent UX
Essential Patterns
1. Icon Width Override
Fix string-width v8 emoji width calculation issues:
const WIDTH_OVERRIDES: Record<string, number> = {
"⚡": 1, "✨": 1, "🐛": 1, "🔥": 1, "🚀": 1,
"🟢": 1, "🟠": 1, "✅": 1, "⚠️": 1,
};
const getIconWidth = (icon: string): number => {
const baseWidth = stringWidth(icon);
const override = WIDTH_OVERRIDES[icon];
return override !== undefined ? Math.max(baseWidth, override) : baseWidth;
};
2. useInput Conflict Avoidance
Multiple useInput hooks all fire - use early return or isActive:
useInput((input, key) => {
if (disabled) return; // Early return when inactive
// Handle input...
}, { isActive: isFocused });
3. Ctrl+C Handling
render(<App />, { exitOnCtrlC: false });
// In component
const { exit } = useApp();
useInput((input, key) => {
if (key.ctrl && input === "c") {
cleanup();
exit();
}
});
4. Dynamic Height Calculation
const { rows } = useTerminalSize();
const HEADER_LINES = 3;
const FOOTER_LINES = 2;
const contentHeight = rows - HEADER_LINES - FOOTER_LINES;
const visibleItems = Math.max(5, contentHeight);
5. React.memo with Custom Comparator
function arePropsEqual<T>(prev: Props<T>, next: Props<T>): boolean {
if (prev.items.length !== next.items.length) return false;
for (let i = 0; i < prev.items.length; i++) {
if (prev.items[i].value !== next.items[i].value) return false;
}
return prev.selectedIndex === next.selectedIndex;
}
export const Select = React.memo(SelectComponent, arePropsEqual);
6. Multi-Screen Navigation
type ScreenType = "main" | "detail" | "settings";
const [screenStack, setScreenStack] = useState<ScreenType[]>(["main"]);
const currentScreen = screenStack[screenStack.length - 1];
const navigateTo = (screen: ScreenType) => {
setScreenStack(prev => [...prev, screen]);
};
const goBack = () => {
if (screenStack.length > 1) {
setScreenStack(prev => prev.slice(0, -1));
}
};
Detailed References
Core Patterns
- Component Patterns - Screen/Part/Common architecture
- Hooks Guide - Custom hook design patterns
Advanced Topics
- Multi-Screen Navigation - Screen stack management
- Animation Patterns - Spinners and progress bars
- State Management - Complex state patterns
- Responsive Layout - Terminal size handling
- Performance Optimization - Optimization techniques
- Input Handling - Keyboard input patterns
Troubleshooting
- Ink Gotchas - Common issues and solutions
- Testing Patterns - ink-testing-library usage
Examples
See examples/ for practical implementation examples.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
akiojin/skills
speckit-require
GitHub Spec Kit (https://github.com/github/spec-kit) を使って要件定義や仕様作成（仕様策定・仕様書作成・仕様設計を含む）を新規作成または既存仕様へ追記し、spec.md/plan.md/tasks.mdまで生成・更新する。要件定義、要件追加/変更、TDD前提の要件整理、仕様の明文化、Spec Kitのspecify/clarify/plan/tasksフロー実行が求められるときに使用。
akiojin/skills
speckit-update
GitHub Spec Kit (https://github.com/github/spec-kit) のベースバージョン更新やテンプレート/スクリプト同期を行うための手順。Spec Kitの更新、上流リリースとの差分適用、templates/commands/scriptsの取り込み、ローカル運用（日本語化・ブランチ非操作・SPEC-[UUID8桁]）の維持が必要なときに使用する。
akiojin/skills
gh-fix-ci
Backward-compatible wrapper skill. The current workflow is `gh-fix-pr`.
akiojin/skills
gh-pr-check
Check GitHub PR status with the gh CLI, including unmerged PR detection and post-merge new-commit detection for the current branch.
akiojin/skills
gh-fix-issue
Analyze a GitHub Issue to extract error context, stack traces, file references, and cross-references. Classify the issue, search the codebase for relevant files, produce a structured Issue Analysis Report, and propose a concrete fix plan. Post progress updates to the issue.
akiojin/skills
gh-fix-pr
Inspect GitHub PR for CI failures, merge conflicts, update-branch requirements, reviewer comments, change requests, and unresolved review threads. Create fix plans and implement after user approval. Reply to ALL reviewer comments with action taken or reason for not addressing, then resolve threads. Notify reviewers after fixes.
Didn't find tool you were looking for?