json-ui by actionbook

Decision brief

What it does: where it fits

Version: 1.0.0 | Last Updated: 2026-01-29

Best for

Not for

Tasks that require unconfirmed production actions or broad system permissions.
Environments where the pinned source and install steps cannot be inspected.

Compatibility matrix

Platform support, with evidence labels

Platform	Status	Evidence	What to check
Codex	Not declared	No explicit evidence	Portability before use
Claude Code	Not declared	No explicit evidence	Portability before use
Cursor	Not declared	No explicit evidence	Portability before use
Gemini CLI	Not declared	No explicit evidence	Portability before use

Open the compatibility checker

Installation

Inspect first. Install second.

The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.

Source-detected install commandSource

npx skills add https://github.com/actionbook/actionbook --skill "playground/json-ui-skill"

Safe inspection promptEditorial

Inspect the Agent Skill "json-ui" from https://github.com/actionbook/actionbook/blob/5a3eb05ec18fcebc09ef771008d6dda649295765/playground/json-ui-skill/SKILL.md at commit 5a3eb05ec18fcebc09ef771008d6dda649295765. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.

Workflow

What the source asks the agent to do

01
JSON Usage
Review the “JSON Usage” section in the pinned source before continuing.
Review and apply the “JSON Usage” source section.
02
Quick Reference
Review the “Quick Reference” section in the pinned source before continuing.
Review and apply the “Quick Reference” source section.
03
Documentation
Refer to local source files for detailed documentation: - packages/json-ui/src/catalog.ts - All Zod schemas and type definitions - packages/json-ui/src/cli.ts - HTML renderer and CLI entry point - packages/json-ui/src/components/index.tsx - React component implementations
packages/json-ui/src/catalog.ts - All Zod schemas and type definitionspackages/json-ui/src/cli.ts - HTML renderer and CLI entry pointpackages/json-ui/src/components/index.tsx - React component implementations
04
IMPORTANT: Documentation Completeness Check
Before answering questions, Claude MUST: 1. Read the relevant source file(s) listed above 2. If file read fails: Inform user "本地文档不完整，建议更新" 3. Still answer based on SKILL.md patterns + built-in knowledge
Read the relevant source file(s) listed aboveIf file read fails: Inform user "本地文档不完整，建议更新"Still answer based on SKILL.md patterns + built-in knowledge
05
Architecture
Reports are trees of nodes:
Reports are trees of nodes:

Permission review

Static risk signals and limitations

Reads files

low · line 32

The documentation asks the agent to read local files, directories, or repositories.

Read the relevant source file(s) listed above

Runs scripts

medium · line 308

The documentation asks the agent to run terminal commands or scripts.

node dist/cli.js render example-report-rich.json

Runs scripts

medium · line 311

The documentation asks the agent to run terminal commands or scripts.

node dist/cli.js render report.json -o output.html --no-open

Evidence record

Why each signal appears

EvidenceSourceComputedTestedEditorial

Signal	Value	Evidence type	Meaning
Quality score	91/100	Computed	Documentation, specificity, maintenance, and trust rules
Repository stars	1,583	Source	Repository attention, not individual Skill quality
Compatibility	0 platforms	Source	Declared in the catalog source record
Usage guide	automated source guide	Editorial	Generated or reviewed according to the visible evidence level

Pinned source

Provenance and original SKILL.md

Repository: actionbook/actionbook
Skill path: playground/json-ui-skill/SKILL.md
Commit: 5a3eb05ec18fcebc09ef771008d6dda649295765
License: Apache-2.0
Collected: 2026-08-25
Default branch: main

View the original SKILL.md

json-ui

Version: 1.0.0 | Last Updated: 2026-01-29

You are an expert at the json-ui package — a JSON-to-HTML report renderer with React component support, bilingual i18n, and a CLI tool. Help users by:

Writing components: Add new component types following existing patterns
Rendering reports: Generate HTML from JSON report definitions
Debugging: Fix rendering, build, or i18n issues
Answering questions: Explain architecture, component catalog, data flow

Quick Reference

Task	File	Pattern
Define component schema	`src/catalog.ts`	Add Zod schema + export in `catalog` object
Render component (HTML)	`src/cli.ts`	Add `case` in `renderNode()` switch
Render component (React)	`src/components/index.tsx`	Export React FC using catalog types
Add i18n text	Any JSON	`{ "en": "Hello", "zh": "你好" }` or plain `"Hello"`
Build	terminal	`pnpm build` (uses tsup, outputs ESM + DTS)
Render report	terminal	`json-ui render report.json [-o out.html] [--no-open]`

Documentation

Refer to local source files for detailed documentation:

packages/json-ui/src/catalog.ts - All Zod schemas and type definitions
packages/json-ui/src/cli.ts - HTML renderer and CLI entry point
packages/json-ui/src/components/index.tsx - React component implementations

IMPORTANT: Documentation Completeness Check

Before answering questions, Claude MUST:

Read the relevant source file(s) listed above
If file read fails: Inform user "本地文档不完整，建议更新"
Still answer based on SKILL.md patterns + built-in knowledge

Architecture

JSON Report Format

Reports are trees of nodes:

{
  "type": "Report",
  "props": { "title": "My Report", "theme": "auto" },
  "children": [
    {
      "type": "Section",
      "props": { "title": "Overview", "icon": "bulb" },
      "children": [
        { "type": "Abstract", "props": { "text": "..." } }
      ]
    }
  ]
}

Three Rendering Layers

Layer	File	Output	Use Case
Zod Schemas	`catalog.ts`	Type definitions	Validation, type safety
HTML Renderer	`cli.ts`	Static HTML string	CLI `render` command
React Components	`components/index.tsx`	React elements	Embedded usage

Data Flow

JSON file → CLI parse → renderNode() recursion → HTML string → file write → browser open

Component Catalog (38 types)

Layout

Component	Key Props	Description
`Report`	`title?, theme`	Root wrapper, 800px max-width
`Section`	`title, icon?, collapsible?`	Collapsible section with header
`Grid`	`cols, gap`	CSS grid layout
`Card`	`variant, padding, shadow`	Card container

Paper Info

Component	Key Props	Description
`PaperHeader`	`title, arxivId, date, categories?`	Paper title + metadata
`AuthorList`	`authors, layout?, maxVisible?`	Author names + affiliations
`Abstract`	`text, highlights?, maxLength?`	Abstract with keyword highlighting
`TagList`	`tags, variant`	Tag/category pills

Content

Component	Key Props	Description
`ContributionList`	`items, numbered?`	Numbered contributions with badges
`MethodOverview`	`steps, showConnectors?`	Step-by-step method pipeline
`Highlight`	`text, type, source?`	Blockquote (quote/important/warning/code)
`KeyPoint`	`icon, title, description`	Icon + title + description
`CodeBlock`	`code, language, showLineNumbers?`	Syntax-highlighted code
`Prose`	`content`	Markdown content block
`Callout`	`type, title?, content`	Info/tip/warning/important/note box

Rich Content

Component	Key Props	Description
`Image`	`src, alt?, caption?, width?`	Single image
`Figure`	`images, caption?, label?`	Multi-image figure
`Formula`	`latex, block?, label?`	LaTeX formula
`DefinitionList`	`items`	Term-definition pairs
`Theorem`	`type, number?, title?, content`	Theorem/lemma/proposition
`Algorithm`	`title, steps, caption?`	Algorithm pseudocode
`ResultsTable`	`columns, rows, highlights?`	Results with best-cell highlighting

Data Display

Component	Key Props	Description
`Metric`	`label, value, trend?, icon?`	Single metric card
`MetricsGrid`	`metrics, cols?`	Grid of metric cards
`Table`	`columns, rows, striped?, caption?`	Data table

Interactive

Component	Key Props	Description
`LinkButton`	`href, label, icon?, external?`	Styled link button
`LinkGroup`	`links, layout?`	Group of link buttons

Brand

Component	Key Props	Description
`BrandHeader`	`badge?, poweredBy?, showBadge?`	AI-generated badge header
`BrandFooter`	`timestamp, attribution?, disclaimer?`	Footer with attribution

I18n System

Backward-Compatible Bilingual Strings

The I18nString type accepts both plain strings and bilingual objects:

// catalog.ts
export const I18nString = z.union([
  z.string(),
  z.object({ en: z.string(), zh: z.string() }),
]);

JSON Usage

// Plain string (backward compatible)
{ "title": "Hello World" }

// Bilingual object
{ "title": { "en": "Hello World", "zh": "你好世界" } }

HTML Rendering (cli.ts)

For HTML output, i18n strings render as dual spans:

// renderI18n() outputs:
<span class="i18n-en">Hello</span><span class="i18n-zh">你好</span>

// CSS controls visibility:
html[lang="en"] .i18n-zh { display: none; }
html[lang="zh"] .i18n-en { display: none; }

For HTML attributes (alt, title) where only a plain string works:

// resolveI18n() picks one language:
const alt = resolveI18n(props.alt, 'en'); // returns plain string

React Rendering (components/index.tsx)

// Use <I18nText> component for JSX:
<I18nText value={props.title} />

// Use resolveI18nStr() for plain string contexts:
const altText = resolveI18nStr(props.alt, 'en');

Language Switcher

Fixed top-right button: EN | 中文
Toggles <html lang="en|zh"> attribute
Persists choice via localStorage.getItem('json-ui-lang')

Key Patterns

Pattern 1: Adding a New Component

Define schema in catalog.ts:

export const MyWidgetSchema = z.object({
  label: I18nString,        // Use I18nString for user-visible text
  count: z.number(),        // Use z.string()/z.number() for data
  variant: VariantType.default('default'),
});

// Add to catalog object:
export const catalog = {
  // ...existing...
  MyWidget: MyWidgetSchema,
} as const;

// Export type:
export type MyWidgetProps = z.infer<typeof MyWidgetSchema>;

Add HTML renderer in cli.ts renderNode() switch:

case 'MyWidget': {
  const { label, count, variant } = props;
  return `<div class="my-widget ${variant}">
    <span>${renderI18n(label)}</span>
    <strong>${escapeHtml(String(count))}</strong>
  </div>`;
}

Add React component in components/index.tsx:

export const MyWidget: React.FC<MyWidgetProps> = ({ label, count, variant = 'default' }) => (
  <div className={`my-widget ${variant}`}>
    <span><I18nText value={label} /></span>
    <strong>{count}</strong>
  </div>
);

Pattern 2: Handling I18n in Special Cases

For text that needs processing (e.g., Abstract highlights):

// HTML (cli.ts) - process each language separately:
if (isI18n(text)) {
  return `<span class="i18n-en">${processText(text.en)}</span>
          <span class="i18n-zh">${processText(text.zh)}</span>`;
} else {
  return processText(String(text));
}

// React (components/index.tsx):
if (typeof text === 'object' && 'en' in text && 'zh' in text) {
  return (
    <>
      <span className="i18n-en" dangerouslySetInnerHTML={{ __html: processText(text.en) }} />
      <span className="i18n-zh" dangerouslySetInnerHTML={{ __html: processText(text.zh) }} />
    </>
  );
}

Common Errors

Error	Cause	Solution
`Type 'I18nStringType' is not assignable to 'ReactNode'`	Passing i18n object directly to JSX	Wrap with `<I18nText value={...} />`
`Property 'length' does not exist on type 'I18nStringType'`	Calling string methods on i18n value	Use type guard: `typeof text === 'string' ? text : text.en`
Images not loading from arxiv	`crossorigin="anonymous"` on `<img>`	Remove `crossorigin`; keep only `referrerpolicy="no-referrer"`
Language switcher not working	Missing CSS rules or JS	Ensure `html[lang] .i18n-*` CSS rules and toggle JS are in template
Build fails with type errors	Schema changed but components not updated	Update all three files: catalog, cli, components

CRITICAL: Image Handling

Do NOT use crossorigin="anonymous" on <img> tags.

Sites like arxiv.org do not send CORS headers. Adding crossorigin="anonymous" causes the browser to require CORS, which fails and blocks the image.

<!-- WRONG - breaks images from arxiv and similar sites -->
<img src="..." referrerpolicy="no-referrer" crossorigin="anonymous" />

<!-- CORRECT -->
<img src="..." referrerpolicy="no-referrer" />

Chinese Translation Guidelines

When writing Chinese translations for ML/AI papers:

Wrong	Correct	Reason
评论器	价值函数（critic）	Standard ML term
运行估计	滑动估计	Running estimate = 滑动估计
重加权因子	加权系数	More natural Chinese
不断演化的	动态更新的	Clearer meaning
简单修复	改动小	Academic tone

Build & CLI

# Build (ESM + DTS via tsup)
cd packages/json-ui && pnpm build

# Render report to HTML
node dist/cli.js render example-report-rich.json

# With options
node dist/cli.js render report.json -o output.html --no-open

When Writing Code

Always use I18nString for user-visible text properties in schemas
Always handle both string and {en, zh} forms in renderers
Never use crossorigin="anonymous" on img tags
Keep referrerpolicy="no-referrer" on img tags for privacy
Test with pnpm build after any schema or component changes
Update all three layers (catalog, cli, components) when adding components

Frequently asked questions

What to verify before installation and use

What does the json-ui source document cover?

Version: 1.0.0 | Last Updated: 2026-01-29

How do I install json-ui?

The source record exposes this install command: npx skills add https://github.com/actionbook/actionbook --skill "playground/json-ui-skill". Inspect the command and pinned source before running it.

Which permission-related actions were detected?

Static rules flagged read-files, exec-script in the source; the page lists the matching lines and excerpts.

What it does: where it fits

Best for

Not for

Platform support, with evidence labels

Inspect first. Install second.

What the source asks the agent to do

JSON Usage

Quick Reference

Documentation

IMPORTANT: Documentation Completeness Check

Architecture

Static risk signals and limitations

Reads files

Runs scripts

Runs scripts

Why each signal appears

Provenance and original SKILL.md

json-ui

Quick Reference

Documentation

IMPORTANT: Documentation Completeness Check

Architecture

JSON Report Format

Three Rendering Layers

Data Flow

Component Catalog (38 types)

Layout

Paper Info

Content

Rich Content

Data Display

Interactive

Brand

I18n System

Backward-Compatible Bilingual Strings

JSON Usage

HTML Rendering (cli.ts)

React Rendering (components/index.tsx)

Language Switcher

Key Patterns

Pattern 1: Adding a New Component

Pattern 2: Handling I18n in Special Cases

Common Errors

CRITICAL: Image Handling

Chinese Translation Guidelines

Build & CLI

When Writing Code

What to verify before installation and use

Compare before choosing

moai-design-tools

unikit-docs

work-loop

team-review