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)

Stars 5
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/akiojin/skills/tree/main/cli-inkjs/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

  1. Determine component type: Screen / Part / Common
  2. Reference component-patterns.md for similar patterns
  3. Add type definitions
  4. Implement component
  5. 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:

typescript
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:

typescript
useInput((input, key) => {
  if (disabled) return;  // Early return when inactive
  // Handle input...
}, { isActive: isFocused });

3. Ctrl+C Handling

typescript
render(<App />, { exitOnCtrlC: false });

// In component
const { exit } = useApp();
useInput((input, key) => {
  if (key.ctrl && input === "c") {
    cleanup();
    exit();
  }
});

4. Dynamic Height Calculation

typescript
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

typescript
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

typescript
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.

Expand your agent's capabilities with these related and highly-rated skills.

akiojin/skills

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)

5 2
Explore
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フロー実行が求められるときに使用。

5 2
Explore
akiojin/skills

speckit-update

GitHub Spec Kit (https://github.com/github/spec-kit) のベースバージョン更新やテンプレート/スクリプト同期を行うための手順。Spec Kitの更新、上流リリースとの差分適用、templates/commands/scriptsの取り込み、ローカル運用(日本語化・ブランチ非操作・SPEC-[UUID8桁])の維持が必要なときに使用する。

5 2
Explore
akiojin/skills

gh-fix-ci

Backward-compatible wrapper skill. The current workflow is `gh-fix-pr`.

5 2
Explore
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.

5 2
Explore
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.

5 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results