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
1---
2name: json-ui
3description: |
4 CRITICAL: Use for json-ui component rendering and development. Triggers on:
5 json-ui, json render, component catalog, report render, HTML report,
6 I18nString, i18n, bilingual, language switch, dual language,
7 PaperHeader, AuthorList, Abstract, MetricsGrid, Section, Highlight,
8 Zod schema, catalog.ts, cli.ts, components/index.tsx,
9 "how to add a component", "how to render JSON",
10 JSON 渲染, 组件目录, 报告渲染, 多语言, 中英文切换
11metadata:
12 source: https://skillmd.com/skills/actionbook/json-ui
13---
14
15# json-ui
16
17> **Version:** 1.0.0 | **Last Updated:** 2026-01-29
18
19You 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:
20- **Writing components**: Add new component types following existing patterns
21- **Rendering reports**: Generate HTML from JSON report definitions
22- **Debugging**: Fix rendering, build, or i18n issues
23- **Answering questions**: Explain architecture, component catalog, data flow
24
25## Quick Reference
26
27| Task | File | Pattern |
28|------|------|---------|
29| Define component schema | `src/catalog.ts` | Add Zod schema + export in `catalog` object |
30| Render component (HTML) | `src/cli.ts` | Add `case` in `renderNode()` switch |
31| Render component (React) | `src/components/index.tsx` | Export React FC using catalog types |
32| Add i18n text | Any JSON | `{ "en": "Hello", "zh": "你好" }` or plain `"Hello"` |
33| Build | terminal | `pnpm build` (uses tsup, outputs ESM + DTS) |
34| Render report | terminal | `json-ui render report.json [-o out.html] [--no-open]` |
35
36## Documentation
37
38Refer to local source files for detailed documentation:
39- `packages/json-ui/src/catalog.ts` - All Zod schemas and type definitions
40- `packages/json-ui/src/cli.ts` - HTML renderer and CLI entry point
41- `packages/json-ui/src/components/index.tsx` - React component implementations
42
43## IMPORTANT: Documentation Completeness Check
44
45**Before answering questions, Claude MUST:**
461. Read the relevant source file(s) listed above
472. If file read fails: Inform user "本地文档不完整,建议更新"
483. Still answer based on SKILL.md patterns + built-in knowledge
49
50## Architecture
51
52### JSON Report Format
53
54Reports are trees of nodes:
55
56```json
57{
58 "type": "Report",
59 "props": { "title": "My Report", "theme": "auto" },
60 "children": [
61 {
62 "type": "Section",
63 "props": { "title": "Overview", "icon": "bulb" },
64 "children": [
65 { "type": "Abstract", "props": { "text": "..." } }
66 ]
67 }
68 ]
69}
70```
71
72### Three Rendering Layers
73
74| Layer | File | Output | Use Case |
75|-------|------|--------|----------|
76| Zod Schemas | `catalog.ts` | Type definitions | Validation, type safety |
77| HTML Renderer | `cli.ts` | Static HTML string | CLI `render` command |
78| React Components | `components/index.tsx` | React elements | Embedded usage |
79
80### Data Flow
81
82```
83JSON file → CLI parse → renderNode() recursion → HTML string → file write → browser open
84```
85
86## Component Catalog (38 types)
87
88### Layout
89
90| Component | Key Props | Description |
91|-----------|-----------|-------------|
92| `Report` | `title?, theme` | Root wrapper, 800px max-width |
93| `Section` | `title, icon?, collapsible?` | Collapsible section with header |
94| `Grid` | `cols, gap` | CSS grid layout |
95| `Card` | `variant, padding, shadow` | Card container |
96
97### Paper Info
98
99| Component | Key Props | Description |
100|-----------|-----------|-------------|
101| `PaperHeader` | `title, arxivId, date, categories?` | Paper title + metadata |
102| `AuthorList` | `authors, layout?, maxVisible?` | Author names + affiliations |
103| `Abstract` | `text, highlights?, maxLength?` | Abstract with keyword highlighting |
104| `TagList` | `tags, variant` | Tag/category pills |
105
106### Content
107
108| Component | Key Props | Description |
109|-----------|-----------|-------------|
110| `ContributionList` | `items, numbered?` | Numbered contributions with badges |
111| `MethodOverview` | `steps, showConnectors?` | Step-by-step method pipeline |
112| `Highlight` | `text, type, source?` | Blockquote (quote/important/warning/code) |
113| `KeyPoint` | `icon, title, description` | Icon + title + description |
114| `CodeBlock` | `code, language, showLineNumbers?` | Syntax-highlighted code |
115| `Prose` | `content` | Markdown content block |
116| `Callout` | `type, title?, content` | Info/tip/warning/important/note box |
117
118### Rich Content
119
120| Component | Key Props | Description |
121|-----------|-----------|-------------|
122| `Image` | `src, alt?, caption?, width?` | Single image |
123| `Figure` | `images, caption?, label?` | Multi-image figure |
124| `Formula` | `latex, block?, label?` | LaTeX formula |
125| `DefinitionList` | `items` | Term-definition pairs |
126| `Theorem` | `type, number?, title?, content` | Theorem/lemma/proposition |
127| `Algorithm` | `title, steps, caption?` | Algorithm pseudocode |
128| `ResultsTable` | `columns, rows, highlights?` | Results with best-cell highlighting |
129
130### Data Display
131
132| Component | Key Props | Description |
133|-----------|-----------|-------------|
134| `Metric` | `label, value, trend?, icon?` | Single metric card |
135| `MetricsGrid` | `metrics, cols?` | Grid of metric cards |
136| `Table` | `columns, rows, striped?, caption?` | Data table |
137
138### Interactive
139
140| Component | Key Props | Description |
141|-----------|-----------|-------------|
142| `LinkButton` | `href, label, icon?, external?` | Styled link button |
143| `LinkGroup` | `links, layout?` | Group of link buttons |
144
145### Brand
146
147| Component | Key Props | Description |
148|-----------|-----------|-------------|
149| `BrandHeader` | `badge?, poweredBy?, showBadge?` | AI-generated badge header |
150| `BrandFooter` | `timestamp, attribution?, disclaimer?` | Footer with attribution |
151
152## I18n System
153
154### Backward-Compatible Bilingual Strings
155
156The `I18nString` type accepts both plain strings and bilingual objects:
157
158```typescript
159// catalog.ts
160export const I18nString = z.union([
161 z.string(),
162 z.object({ en: z.string(), zh: z.string() }),
163]);
164```
165
166### JSON Usage
167
168```json
169// Plain string (backward compatible)
170{ "title": "Hello World" }
171
172// Bilingual object
173{ "title": { "en": "Hello World", "zh": "你好世界" } }
174```
175
176### HTML Rendering (cli.ts)
177
178For HTML output, i18n strings render as dual spans:
179
180```typescript
181// renderI18n() outputs:
182<span class="i18n-en">Hello</span><span class="i18n-zh">你好</span>
183
184// CSS controls visibility:
185html[lang="en"] .i18n-zh { display: none; }
186html[lang="zh"] .i18n-en { display: none; }
187```
188
189For HTML attributes (alt, title) where only a plain string works:
190
191```typescript
192// resolveI18n() picks one language:
193const alt = resolveI18n(props.alt, 'en'); // returns plain string
194```
195
196### React Rendering (components/index.tsx)
197
198```typescript
199// Use <I18nText> component for JSX:
200<I18nText value={props.title} />
201
202// Use resolveI18nStr() for plain string contexts:
203const altText = resolveI18nStr(props.alt, 'en');
204```
205
206### Language Switcher
207
208- Fixed top-right button: EN | 中文
209- Toggles `<html lang="en|zh">` attribute
210- Persists choice via `localStorage.getItem('json-ui-lang')`
211
212## Key Patterns
213
214### Pattern 1: Adding a New Component
215
2161. **Define schema** in `catalog.ts`:
217```typescript
218export const MyWidgetSchema = z.object({
219 label: I18nString, // Use I18nString for user-visible text
220 count: z.number(), // Use z.string()/z.number() for data
221 variant: VariantType.default('default'),
222});
223
224// Add to catalog object:
225export const catalog = {
226 // ...existing...
227 MyWidget: MyWidgetSchema,
228} as const;
229
230// Export type:
231export type MyWidgetProps = z.infer<typeof MyWidgetSchema>;
232```
233
2342. **Add HTML renderer** in `cli.ts` `renderNode()` switch:
235```typescript
236case 'MyWidget': {
237 const { label, count, variant } = props;
238 return `<div class="my-widget ${variant}">
239 <span>${renderI18n(label)}</span>
240 <strong>${escapeHtml(String(count))}</strong>
241 </div>`;
242}
243```
244
2453. **Add React component** in `components/index.tsx`:
246```typescript
247export const MyWidget: React.FC<MyWidgetProps> = ({ label, count, variant = 'default' }) => (
248 <div className={`my-widget ${variant}`}>
249 <span><I18nText value={label} /></span>
250 <strong>{count}</strong>
251 </div>
252);
253```
254
255### Pattern 2: Handling I18n in Special Cases
256
257For text that needs processing (e.g., Abstract highlights):
258
259```typescript
260// HTML (cli.ts) - process each language separately:
261if (isI18n(text)) {
262 return `<span class="i18n-en">${processText(text.en)}</span>
263 <span class="i18n-zh">${processText(text.zh)}</span>`;
264} else {
265 return processText(String(text));
266}
267
268// React (components/index.tsx):
269if (typeof text === 'object' && 'en' in text && 'zh' in text) {
270 return (
271 <>
272 <span className="i18n-en" dangerouslySetInnerHTML={{ __html: processText(text.en) }} />
273 <span className="i18n-zh" dangerouslySetInnerHTML={{ __html: processText(text.zh) }} />
274 </>
275 );
276}
277```
278
279## Common Errors
280
281| Error | Cause | Solution |
282|-------|-------|---------|
283| `Type 'I18nStringType' is not assignable to 'ReactNode'` | Passing i18n object directly to JSX | Wrap with `<I18nText value={...} />` |
284| `Property 'length' does not exist on type 'I18nStringType'` | Calling string methods on i18n value | Use type guard: `typeof text === 'string' ? text : text.en` |
285| Images not loading from arxiv | `crossorigin="anonymous"` on `<img>` | Remove `crossorigin`; keep only `referrerpolicy="no-referrer"` |
286| Language switcher not working | Missing CSS rules or JS | Ensure `html[lang] .i18n-*` CSS rules and toggle JS are in template |
287| Build fails with type errors | Schema changed but components not updated | Update all three files: catalog, cli, components |
288
289## CRITICAL: Image Handling
290
291**Do NOT use `crossorigin="anonymous"` on `<img>` tags.**
292
293Sites like arxiv.org do not send CORS headers. Adding `crossorigin="anonymous"` causes the browser to require CORS, which fails and blocks the image.
294
295```html
296<!-- WRONG - breaks images from arxiv and similar sites -->
297<img src="..." referrerpolicy="no-referrer" crossorigin="anonymous" />
298
299<!-- CORRECT -->
300<img src="..." referrerpolicy="no-referrer" />
301```
302
303## Chinese Translation Guidelines
304
305When writing Chinese translations for ML/AI papers:
306
307| Wrong | Correct | Reason |
308|-------|---------|--------|
309| 评论器 | 价值函数(critic) | Standard ML term |
310| 运行估计 | 滑动估计 | Running estimate = 滑动估计 |
311| 重加权因子 | 加权系数 | More natural Chinese |
312| 不断演化的 | 动态更新的 | Clearer meaning |
313| 简单修复 | 改动小 | Academic tone |
314
315## Build & CLI
316
317```bash
318# Build (ESM + DTS via tsup)
319cd packages/json-ui && pnpm build
320
321# Render report to HTML
322node dist/cli.js render example-report-rich.json
323
324# With options
325node dist/cli.js render report.json -o output.html --no-open
326```
327
328## When Writing Code
329
3301. Always use `I18nString` for user-visible text properties in schemas
3312. Always handle both string and `{en, zh}` forms in renderers
3323. Never use `crossorigin="anonymous"` on img tags
3334. Keep `referrerpolicy="no-referrer"` on img tags for privacy
3345. Test with `pnpm build` after any schema or component changes
3356. Update all three layers (catalog, cli, components) when adding components