ReActicle

June 10, 2026 · View on GitHub

An HTML article protocol for the AI era — instead of letting AI hand-write raw HTML, give it a constrained, semantic React component contract that produces stable, beautiful, interactive, self-contained HTML articles and reports.

中文文档 · GitHub · npm package · Companion skill: beautiful-article

Why ReActicle

Markdown made it lightweight for humans to write long-form. ReActicle makes it controllable for AI to generate long-form HTML.

When an AI agent has to materialize a long article — a research note, a post-mortem, a tutorial, a visual essay — letting it free-write HTML and CSS is a losing game: theme drift, broken layout, AI smell, accidental web-app sprawl. ReActicle replaces that surface with a small, prose-first component vocabulary plus a single escape hatch (<Raw>), all wired into a token-based theme system.

The result is an HTML article that is:

Stable — the agent only composes components; structure and typography are guaranteed by the library.
Beautiful — every theme is an editorial-grade design system, not a color swap.
Coherent — Raw can hold any HTML/SVG/CSS/React, but it must consume --ra-* theme tokens. Switch theme, all Raw blocks rewire.
Self-contained — produces a single HTML file, CSS and JS inlined, openable offline, shareable as a file.
Fit for AI authoring — every theme ships a Markdown authoring profile the agent reads before writing. Themes are contracts, not stylesheets.

Markdown lightens human writing. ReActicle controls AI writing.

How it pairs with the `beautiful-article` skill

ReActicle is the runtime component protocol. It does not prescribe the editorial workflow — that lives in a separate, AI-agent-targeted skill called beautiful-article, which is the recommended way to use ReActicle end-to-end.

┌──────────────────────────────────────────────────────────┐
│ beautiful-article  (AI-agent skill / methodology + harness) │
│   Source → Plan → Build → Review → Repair → Deliver      │
│   Hard checkpoints · per-section sub-agents · theme picker  │
└─────────────────────────┬────────────────────────────────┘
                          │  composes
                          ▼
┌──────────────────────────────────────────────────────────┐
│ reacticle  (this repo · npm package)                     │
│   Components · Themes · ThemeProvider · Raw · Export     │
└──────────────────────────────────────────────────────────┘

Layer	What it does	Where it lives
`beautiful-article` skill	Tells the agent how to plan, write, review and deliver an article from any source (URL / PDF / DOCX / Markdown / text). Six numbered phases, three hard checkpoints, theme picker, sub-agent reviewers.	`ConardLi/garden-skills`
`reacticle` (this repo)	The component protocol the skill compiles into: structure, insight, media, decision, technical, interaction and a `Raw` escape hatch — all on a token-based theme system.	This repo · npm `reacticle`

You can use them independently: the skill works because it has ReActicle to target, and ReActicle is a perfectly usable React library on its own. They simply pair very, very well.

Highlights

One npm package, many components. A single import surface (reacticle) — no submodule paths, no plug-in installs.
11 editorial themes. From Tufte / Stripe Press density to Bayer / Vignelli / Sottsass posters and Knuth / Shannon technical-press. Each theme is both a CSS token bundle and a Markdown contract.
Prose-first components. Article, Hero, Lead, Section, Subsection, Summary, Aside, Quote, Table, Image, Video, Audio, Formula, CodeBlock, DiffReview, RiskList, Decision, ActionList, Checkpoint, Tradeoff, Incident, Detail, Tabs, TOC, Conclusion, Raw.
Raw escape hatch — under contract. Any custom HTML / SVG / CSS / React is allowed inside Raw, but it must use --ra-* theme tokens. Switching theme rewires every Raw block in one place.
Self-contained build. Vite + vite-plugin-singlefile produce one HTML file with all CSS and JS inlined — works offline, shareable as a file, printable to PDF.
Designed for AI authoring. Each theme directory ships a <theme>.md profile telling the agent what photography, what code style, what Raw idioms, what anti-patterns belong to that theme.
Editorial Console docs site. apps/site is a unified docs + component reference + Gallery, deployed as one app — itself written entirely in ReActicle.

Documentation

The full developer & authoring docs live at the official site — https://rearticle.mmh1.top/. The README is just the pitch; everything else is there.

Track	Page	What it covers
Start	Get started	Install, minimal scaffold, build & export, missing-field UX
Theming	Theme contracts	`--ra-*` token system · how a theme is two artifacts (`.css` + `.md`) · adding a theme
Authoring	Raw free-layer guide	When to reach for `<Raw>`, the token contract, anti-patterns & checklists
	Export & distribution	`ExportBar`, PDF / single-file HTML, `actionItemsToMarkdown` / `decisionToPrompt`
	Writing recipes	Skeletons for incident, spec, essay, explainer, decision, math, raw-interactive
	Markdown migration	One-to-one mapping table from Markdown to ReActicle components
Pairing	Skill integration	How ReActicle pairs with the `beautiful-article` skill (Source → Plan → Build → Review → Repair → Deliver)
Reference	Components	Live preview + props table + copyable code for every component
	Theme Gallery	One specimen long-form article per theme
Engineering	Architecture	Engineering boundaries, dependency rules, single-file build
	Contributing	PR checklist for adding a component / theme / gallery entry
Help	FAQ	Concept, Raw, export, missing fields, install, ReActicle vs neighbors

Showcase — articles built with ReActicle + `beautiful-article`

Real long-form articles, each authored end-to-end by an AI agent running the beautiful-article skill against ReActicle. Click any cover to open the live, single-file HTML article.

Agent Tools 设计的最佳实践 _{Theme · Freddie · 长文 · 21 min} ^{Anthropic 工程团队关于 Tools 的五条原则，与一套评测驱动的方法。}	Agent Skill 是如何进化的？ _{Theme · Freddie · 解释文 · 8 min} ^{把 Skill 文档当成被训练的对象，而不是被复制粘贴的 prompt。}
Agent Harness 的解剖图 _{Theme · Vignelli · 长文 · 12 min} ^{智能在模型里；让智能变得有用的，是它周围的那套系统。}	提示词缓存对 Agent 有多重要？ _{Theme · Bayer · 长文 · 15 min} ^{缓存命中率是 Agent 的 SLO，Claude Code 团队的反直觉经验。}
面向 Agent 的高效上下文工程 _{Theme · Tufte · 长文 · 16 min} ^{本文探讨如何高效地筛选与管理驱动 AI Agent 运转的上下文。}	Attention Is All You Need _{Theme · Tufte · 长文 · 30 min} ^{一篇重塑现代 AI 的论文，逐层拆给你看。}
把 AI Agent 的评测讲清楚 _{Theme · Tufte · 长文 · 25 min} ^{让 Agent 有用的那些能力，恰恰让它难以评测 — 来自 Anthropic 的指南。}	Codex 的 Agent Loop 是怎么做的？ _{Theme · Sottsass · 长文 · 18 min} ^{OpenAI 官方分享：在 Responses API 之上，一条对话是如何被反复"展开"的。}

Theme Gallery — one specimen article per theme

11 themes shipped. Full theme contracts (.css token bundle + .md authoring profile, anti-patterns, code/media style) are documented at Theming.

Every theme ships with a long-form specimen article that lives the theme end-to-end — typography, photography, code, formulas, Raw blocks, the works. Click any cover to read the live article; click the theme name to jump to that theme's section in the docs.

Tufte · Data-Ink _{咖啡因与睡眠 · 数据笔记} ^{Edward Tufte 数据墨水，证据优先，发丝级图表与最朴素的版式。}	Press · 书卷 _{活字之后 · 随笔} ^{Stripe Press 式书卷长读物：会落定的标题、氧化血红首字母、纯正文之美。}	Shannon · 工程暗色 _{连接池耗尽 · 故障复盘} ^{贝尔实验室技术论文血统，暗底黄金信号、回压依赖、夜间作战气质。}
Vignelli · 瑞士网格 _{Orbit 设计系统规格 · 规格} ^{Massimo Vignelli 网格至上、grotesque 字族、瑞士红只承载结构。}	Knuth · 学术 _{线性化自注意力 · 预印本} ^{Donald Knuth / Computer Modern，编号小节、命题与证明、arXiv 草稿气质。}	Freddie · 暖黄 _{第一封 Newsletter · 上手指南} ^{Mailchimp Freddie 黑字荧光，亲和插画 + 不端着的产品上手语气。}
Andy · 静谧 _{把呼吸放慢 · 练习} ^{柔软圆润、呼吸-神经跷跷板，让人慢下来的练习气质。}	Bodoni · 报刊 _{头版的消亡 · 特稿} ^{高对比 Didone 报刊气质，黑白大报、对折线之上的分量。}	Bayer · 包豪斯 _{形、色、网格 · 教学} ^{Herbert Bayer 包豪斯三原色几何，形有性格、色有重量。}
Fuller · 蓝图 _{限流器设计规格 · 系统设计} ^{Buckminster Fuller 工程蓝图，方格纸拓扑、令牌桶模拟，可照着实现。}	Sottsass · 孟菲斯 _{撞色不翻车 · 设计随笔} ^{Memphis 80s 撞色，黑描边、硬投影、轻微旋转的不正经语法。}

Browse all specimens with theme switching, search and filters at the live gallery: https://rearticle.mmh1.top/#/gallery.

When not to use ReActicle

You're building a web app, dashboard, form-heavy product or generic landing page — go use a UI kit, not an article protocol.
You need a CMS-style editor — ReActicle is an output protocol, not an editing UI.
You only need a single Markdown render — that's what Markdown is for.

ReActicle is for when the deliverable is the long-form HTML article itself, especially when an AI agent is composing it.

Acknowledgements

The component vocabulary is shaped by Edward Tufte, Stripe Press, Pentagram, Vignelli, Bayer, Sottsass, Bucky Fuller, Donald Knuth and the Bell Labs technical-paper tradition.
The AI authoring methodology is developed and shipped as the beautiful-article skill.

License

MIT