feat: add Relay themes and a theme provider

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,23 @@
+name: Bug report
+description: Report reproducible Relay UI behavior.
+body:
+  - type: textarea
+    id: behavior
+    attributes:
+      label: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Include the smallest component, props, and terminal width that reproduces the issue.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Relay UI version, Node.js version, terminal, and operating system.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest a focused improvement to a shared component.
+body:
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Describe the terminal tool and what it currently has to draw by hand.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Proposed behavior
+    validations:
+      required: true
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - label: This component would be useful to more than one Relay tool.
+          required: true

.github/metadata.md

@@ -0,0 +1,9 @@
+# Repository metadata
+
+- Name: `relay-ui`
+- Display name: Relay UI
+- Package: `@relay-cli/ui`
+- Accent: paired
+- Description: Shared Ink components for Relay terminal tools: theming, spinners, tables, and Markdown.
+- Homepage: `https://github.com/relay-cli/relay-ui#readme`
+- Topics: `typescript`, `react`, `ink`, `terminal-ui`, `tui`, `cli`, `components`, `developer-tools`

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node: [22, 24, 26]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check

.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release package
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm pack
+      - uses: actions/upload-artifact@v7
+        with:
+          name: relay-ui-package
+          path: '*.tgz'

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+tmp/

.prettierignore

@@ -0,0 +1,4 @@
+dist/
+coverage/
+node_modules/
+package-lock.json

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "bracketSpacing": false,
+  "trailingComma": "all"
+}

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## Unreleased
+
+- Added the package scaffold and the `relay-ui` component gallery.
+- Added `relayTheme` and `monoTheme`, `defineTheme`, `resolveTheme`, `ThemeProvider` and `useTheme`, `Swatches`, and the gallery's `--theme` option.

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Install Node.js 22 or newer, then run:
+
+```sh
+npm install
+npm run check
+```
+
+Changes should include tests for observable behavior. A component belongs in Relay UI once more than one Relay tool needs it. Each component gets a section in the gallery (`src/gallery/sections.tsx`) and an entry in [docs/api.md](docs/api.md).
+
+Components take colors from the theme rather than hard-coding them, and they must render the same way in `renderToString` as in an interactive terminal, apart from animation.

README.md

@@ -1,3 +1,36 @@
 # Relay UI
 
-Shared Ink components for Relay terminal tools.
+Relay UI holds the Ink components that Relay's terminal tools share, so each tool draws tables, spinners, Markdown, and colors the same way instead of keeping its own copy.
+
+## See the components
+
+```sh
+npm install
+npm run demo
+```
+
+The gallery shows every component with sample data. Press `q` to quit. To print it once without opening the interactive view:
+
+```sh
+npx tsx src/cli.tsx --snapshot
+```
+
+## Use it in a tool
+
+```sh
+npm install @relay-cli/ui ink react
+```
+
+Ink and React are peer dependencies, so the components render with your tool's own copy of each.
+
+## Develop
+
+```sh
+npm run check
+```
+
+`check` runs Prettier, ESLint, the TypeScript compiler, the Vitest suite, and the build. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+## Reporting
+
+Please report a vulnerability privately through GitHub's security advisory form for this repository. Include a minimal reproduction and the affected version.
+
+## Terminal output
+
+Relay UI renders whatever text a tool passes to it, including table cells and Markdown. Tools that display untrusted input, such as log lines, command output, or model replies, should strip terminal control sequences before rendering them so the input cannot move the cursor or change terminal settings.

docs/api.md

@@ -0,0 +1,43 @@
+# API
+
+Everything is exported from `@relay-cli/ui`.
+
+| Export           | Purpose                       |
+| ---------------- | ----------------------------- |
+| `relayUiVersion` | The installed package version |
+
+## Theme
+
+Components read their colors from the nearest `ThemeProvider`. Without one they use `relayTheme`.
+
+```tsx
+import {ThemeProvider, resolveTheme} from '@relay-cli/ui';
+
+<ThemeProvider theme={resolveTheme(options.theme)}>
+  <App />
+</ThemeProvider>;
+```
+
+| Export                             | Purpose                                                                 |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `relayTheme`                       | The Relay palette: orange accent, blue focus                            |
+| `monoTheme`                        | The same palette with grey highlights                                   |
+| `themes`                           | Both themes by name                                                     |
+| `resolveTheme(name, available?)`   | Look up a theme by name; throws with the list of names when it is wrong |
+| `defineTheme(name, colors, base?)` | A new theme that replaces only the colors given                         |
+| `ThemeProvider`, `useTheme`        | Set and read the current theme                                          |
+| `Swatches`                         | Every color in the current theme, for galleries and docs                |
+
+| Color           | Used for                                     |
+| --------------- | -------------------------------------------- |
+| `text`          | Body text                                    |
+| `muted`         | Labels, timestamps, hints                    |
+| `accent`        | The primary highlight, inline code, spinners |
+| `focus`         | Focus, selection, links                      |
+| `success`       | Success states                               |
+| `warning`       | Warnings                                     |
+| `danger`        | Errors and failures                          |
+| `rule`          | Borders, separators, table rules             |
+| `surfaceRaised` | Selected rows, raised panels                 |
+| `surface`       | Panels and cards                             |
+| `background`    | The screen, for tools that paint one         |

eslint.config.js

@@ -0,0 +1,25 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  {
+    ignores: [
+      'dist/**',
+      'coverage/**',
+      'eslint.config.js',
+      'examples/**/*.mjs',
+      'tests/fixtures/**',
+    ],
+  },
+  {
+    languageOptions: {
+      parserOptions: {projectService: true, tsconfigRootDir: import.meta.dirname},
+    },
+    rules: {
+      '@typescript-eslint/no-confusing-void-expression': 'off',
+      '@typescript-eslint/restrict-template-expressions': ['error', {allowNumber: true}],
+    },
+  },
+);