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
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 —
Rawcan 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.
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.
- 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. Rawescape hatch — under contract. Any custom HTML / SVG / CSS / React is allowed insideRaw, but it must use--ra-*theme tokens. Switching theme rewires every Raw block in one place.- Self-contained build. Vite +
vite-plugin-singlefileproduce 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>.mdprofile telling the agent what photography, what code style, what Raw idioms, what anti-patterns belong to that theme. - Editorial Console docs site.
apps/siteis a unified docs + component reference + Gallery, deployed as one app — itself written entirely in ReActicle.
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 (
.csstoken bundle +.mdauthoring 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.
- 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.
- 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-articleskill.