Opinionated design-system library for Ink CLIs — pre-styled components and design tokens for a consistent terminal UI.

Features • Quick Start • Components • Tokens • Development

✨ Features

• 🧱 Five ready-made components — Banner, Header, Badge, Spinner, and Table, all pre-styled and immediately usable
• 🎨 Design tokens included — a shared colour palette and spacing scale to keep every screen consistent
• 🟠 Accent-driven style — a warm #FF8C00 accent colour gives your CLI a distinctive, coherent identity
• ⚡ ESM only, zero config — ships compiled TypeScript with full type definitions; just import and render
• 🔒 Peer-dep friendly — works with any Ink ≥ 4 and React ≥ 18 setup, no version lock-in
• 🧩 Composable — every component accepts standard Ink primitives so you can mix them with your own layouts freely
• 🏷 Typed throughout — exported types (BadgeVariant, Column, Color, Spacing) make props self-documenting in any IDE

🚀 Quick Start

Install

npm install @kud/ink-ui

ink and react are peer dependencies — add them if you haven't already:

npm install ink react

Usage

import React from "react"
import { render } from "ink"
import { Banner, Header, Badge, Spinner, Table } from "@kud/ink-ui"

const App = () => (
  <>
    <Banner title="My CLI" subtitle="v1.0.0" icon="◆" />

    <Header subtitle="Fetching packages…">Dependencies</Header>

    <Badge variant="success">installed</Badge>
    <Badge variant="warning">outdated</Badge>

    <Spinner label="Loading…" />

    <Table
      columns={[
        { key: "name", header: "Package", width: 20 },
        { key: "version", header: "Version", width: 10 },
      ]}
      data={[
        { name: "ink", version: "5.0.0" },
        { name: "react", version: "18.3.1" },
      ]}
    />
  </>
)

render(<App />)

Expected output (approximate terminal rendering):

◆ My CLI v1.0.0

Dependencies
Fetching packages…

[installed] [outdated]

⠋ Loading…

Package              Version
ink                  5.0.0
react                18.3.1

🧩 Components

<Banner>

Full-width title block — ideal as an app header at the top of a screen.

| Prop | Type | Default | Description | | ---------- | -------- | ------- | ---------------------------------------- | | title | string | — | Bold title text | | subtitle | string | — | Optional dimmed subtitle rendered inline | | icon | string | "◆" | Leading icon rendered in accent colour |

<Banner title="Deploy Tool" subtitle="production" icon="🚀" />

<Header>

Bold, underlined section heading. Use it to separate logical groups within a screen.

| Prop | Type | Default | Description | | ---------- | -------- | ------- | ------------------------------------------ | | children | string | — | The heading text | | subtitle | string | — | Optional dimmed subtitle below the heading |

<Header subtitle="3 items">Results</Header>

<Badge>

Inline [label] tag with semantic colour variants.

| Prop | Type | Default | Description | | ---------- | -------------- | -------- | ------------------------------------ | | children | string | — | Label text displayed inside brackets | | variant | BadgeVariant | "info" | Colour variant (see table below) |

| Variant | Colour | | --------- | ------ | | success | green | | error | red | | warning | yellow | | info | cyan |

<Badge variant="error">failed</Badge>

<Spinner>

Animated dots spinner in accent colour, with an optional dimmed label.

| Prop | Type | Default | Description | | ------- | -------- | ------- | ----------------------------------------- | | label | string | — | Optional text rendered beside the spinner |

<Spinner label="Building…" />

<Table>

Structured data grid with bold muted column headers. Supports optional fixed column widths and truncates long values cleanly.

| Prop | Type | Description | | --------- | ------------- | ------------------------------ | | data | T[] | Array of row objects | | columns | Column<T>[] | Column definitions (see below) |

Column<T> shape:

| Field | Type | Description | | -------- | --------- | ---------------------------------- | | key | keyof T | Object key to read for this column | | header | string | Column heading text | | width | number | Optional fixed character width |

<Table
  columns={[
    { key: "name", header: "Name", width: 16 },
    { key: "status", header: "Status" },
  ]}
  data={[
    { name: "api", status: "ok" },
    { name: "db", status: "degraded" },
  ]}
/>

🎨 Design Tokens

Import colors and spacing to keep your own components aligned with the design system.

import { colors, spacing } from "@kud/ink-ui"

Colours

| Token | Value | Semantic use | | ---------------- | --------- | ---------------------------------- | | colors.accent | #FF8C00 | Primary highlight, icons, spinners | | colors.muted | gray | Dimmed text, table headers | | colors.success | green | Positive states | | colors.error | red | Failures and errors | | colors.warning | yellow | Caution states | | colors.info | cyan | Neutral informational |

Spacing

| Token | Value | Description | | ------------ | ----- | ---------------------------------- | | spacing.xs | 1 | Tight gap between inline elements | | spacing.sm | 2 | Small margin between grouped items | | spacing.md | 3 | Standard section margin | | spacing.lg | 4 | Large gap between major sections |

🔧 Development

Project structure

ink-ui/
├── src/
│   ├── components/
│   │   ├── Badge.tsx
│   │   ├── Banner.tsx
│   │   ├── Header.tsx
│   │   ├── Spinner.tsx
│   │   └── Table.tsx
│   ├── index.ts        # public API
│   └── tokens.ts       # colours + spacing
├── dist/               # compiled output (git-ignored)
├── tsconfig.json
└── package.json

Scripts

| Script | Command | Description | | ------- | ------------- | ------------------------------------ | | build | tsc | Compile TypeScript to dist/ | | dev | tsc --watch | Watch mode — recompile on every save |

Local setup

git clone https://github.com/kud/ink-ui.git
cd ink-ui
npm install
npm run build

To develop against a local project, link the package:

npm link
cd ../your-project
npm link @kud/ink-ui

🏗 Tech Stack

| Technology | Purpose | | ---------------------------------------------------------- | -------------------------------------- | | TypeScript | Strict typing, declaration file output | | Ink | React renderer for the terminal | | React | Component model and JSX | | ink-spinner | Animated spinner primitive | | ESM | Modern module format, no CommonJS |

MIT © kud — Made with ❤️