# Reacticle Component Protocol in beautiful-article: A Prose-First Publishing System > Explore the Reacticle component protocol, a semantic React library for beautiful-article. Discover how it enforces prose-first authoring and eliminates raw markup with theme-driven components and a token-based design system. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: api-reference - Published: 2026-08-28 --- **The Reacticle component protocol is a semantic React component library that powers the beautiful-article skill, enforcing prose-first authoring through theme-driven components like `Article`, `Section`, and `Hero` while eliminating raw markup via a token-based design system.** The `beautiful-article` skill in the [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) repository relies entirely on the Reacticle component protocol to transform editorial workflows into consistently rendered HTML documents. Instead of allowing arbitrary JSX or inline styles, the protocol mandates a fixed vocabulary of semantic components wrapped in a global `ThemeProvider`, ensuring every generated article maintains visual consistency through CSS custom properties (`--ra-*` tokens). ## What Is the Reacticle Component Protocol? The Reacticle component protocol is a prose-first React publishing framework distributed as the npm package [`reacticle`](https://www.npmjs.com/package/reacticle) with source code maintained at [github.com/ConardLi/reacticle](https://github.com/ConardLi/reacticle). Within the `beautiful-article` skill—located at `skills/beautiful-article/`—this protocol serves as the exclusive rendering layer, converting structured TypeScript components into self-contained HTML files. According to [`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md), the skill orchestrates a complete editorial pipeline (source → plan → checkpoints → build → review → delivery) but delegates all visual rendering to the Reacticle library. The authoritative specification resides in [`references/component-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/references/component-policy.md), which defines the allowed component inventory, prop interfaces, and thematic constraints. ## Core Tenets of the Protocol ### Prose-First, Component-as-Semantic Article bodies are written as plain text inside `Section` components. Semantic wrappers like `Quote`, `Aside`, or `Table` are only introduced when the content structure explicitly demands them, ensuring the narrative remains dominant rather than the layout machinery. ### No Hand-Written Markup Authors are prohibited from writing raw `
` elements, `className` attributes, or inline styles. All presentation is expressed through the provided component API or the specialized `Raw` escape hatch, guaranteeing that style mutations cannot bypass the global theme system. ### Theme-Driven Styling A global `` wraps the entire article tree, injecting CSS token bundles (prefixed with `--ra-*`). Individual components do **not** accept custom style props; visual variations are achieved exclusively by switching themes (e.g., `tufte`, `minimal`, `technical`), not by mutating component styles. ### One-Section-Per-File Architecture Each article section lives in its own file within `article/sections/NN-*.tsx`, while [`Article.tsx`](https://github.com/ConardLi/garden-skills/blob/main/Article.tsx) merely assembles these sections. This structure enables parallel sub-agent work during the authoring phase and keeps component files focused and manageable. ### The Raw Escape Hatch For content that cannot be expressed through semantic components—such as custom SVG illustrations or interactive widgets—the `Raw` component allows arbitrary HTML/JSX embedding. However, even `Raw` content must rely on theme tokens (e.g., `var(--ra-color-accent)`) to maintain visual consistency. ## Component Vocabulary and Architecture The protocol organizes components into functional groups, all exported from the `reacticle` package: ### Core Structure Components These define the document skeleton: - **`Article`** – Root container for the entire document - **`Hero`** – Title and subtitle presentation - **`Lead`** – Introductory paragraph or abstract - **`Section`** – Primary content containers with `index` and `title` props - **`Subsection`** – Nested structural units - **`Conclusion`** – Terminal content block - **`TOC`** – Automated table of contents generation ### Insight and Commentary Components - **`Summary`** – Synthesized takeaways - **`Aside`** – Tangential notes with `tone` and `label` props (e.g., `tone="principle"`) - **`Quote`** – Styled block quotations ### Data and Technical Components - **`Table`** – Structured data with `columns` and `rows` props - **`CodeBlock`** – Syntax-highlighted code with `language` specification - **`Formula`** – Mathematical expressions ### Media and Free Layer - **`Image`** – Responsive figure handling - **`Raw`** – Untyped escape hatch for custom markup ### Domain-Specific Extensions Optional components for specialized workflows include `RiskList`, `Decision`, `ActionList`, `Checkpoint`, `Tradeoff`, `DiffReview`, `Detail`, `Tabs`, `Video`, and `Audio`. All components expose strict TypeScript prop interfaces; required props generate placeholder warnings when omitted, ensuring type safety throughout the authoring process. ## Implementation Workflow The skill implements the Reacticle protocol through three distinct phases, each supported by specific scripts and templates. ### Scaffold Phase The [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh) script initializes a Vite + React + TypeScript workspace and installs the latest `reacticle` npm package. This creates the directory structure where the protocol will be applied, including the `article/sections/` directory for per-file section authoring. ### Authoring Phase Agents compose articles by importing components from `reacticle` and arranging them within a ``. The [`assets/scaffold-template/article/Article.tsx`](https://github.com/ConardLi/garden-skills/blob/main/assets/scaffold-template/article/Article.tsx) file provides a minimal reference implementation demonstrating proper component hierarchy and import patterns. ### Build and Delivery Phase Running `npm run build` bundles the TypeScript source, inlines all CSS and JS dependencies, and emits a self-contained HTML file at [`article/article.html`](https://github.com/ConardLi/garden-skills/blob/main/article/article.html). For archival distribution, [`scripts/html-to-pdf.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/html-to-pdf.sh) converts the HTML output to PDF without introducing additional dependencies. ## Code Examples ### Minimal Article Implementation This example from the scaffold template demonstrates the core protocol patterns: ```tsx import { ThemeProvider, Article, Hero, Lead, Section, Aside, Raw, } from "reacticle"; export function MyArticle() { return (
This article demonstrates the minimal scaffold required to write an article with the Reacticle component protocol.

The core idea is to keep the narrative dominant. Components are only added when the structure truly demands them.

); } ``` Note that the `Raw` component embeds custom SVG while still accessing the theme token `--ra-color-accent`, maintaining visual consistency even for bespoke content. ### Data Presentation Components ```tsx import { Table, CodeBlock } from "reacticle"; {`function greet(name: string) { return \`Hello, \${name}!\`; }`} ``` These components accept only semantic data props—no styling parameters—ensuring that typography and color schemes remain governed by the active theme. ## Key Files and References - **[`skills/beautiful-article/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/README.md)** – Overview of the skill and its dependency on the Reacticle npm package - **[`skills/beautiful-article/references/component-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/component-policy.md)** – Formal specification of allowed components, prop interfaces, and usage constraints - **[`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh)** – Workspace generator that installs `reacticle` and sets up the section-per-file architecture - **[`skills/beautiful-article/assets/scaffold-template/article/Article.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/assets/scaffold-template/article/Article.tsx)** – Reference implementation showing protocol-compliant component composition - **[`skills/beautiful-article/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/manifest.json)** – Release metadata for the skill ## Summary - The Reacticle component protocol is a prose-first React library that enforces semantic structure through a fixed vocabulary of components like `Article`, `Section`, and `Hero`. - Theme-driven styling via CSS tokens (`--ra-*`) prevents style drift; components do not accept custom style props. - The `Raw` escape hatch allows arbitrary HTML for complex visualizations while requiring theme token usage for consistency. - One-section-per-file architecture (`article/sections/NN-*.tsx`) enables parallel authoring workflows. - The build pipeline (`npm run build`) outputs self-contained HTML, with optional PDF conversion via [`scripts/html-to-pdf.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/html-to-pdf.sh). ## Frequently Asked Questions ### What is the Reacticle component protocol? The Reacticle component protocol is a semantic publishing framework distributed as the npm package `reacticle`. It provides a fixed set of React components—such as `Article`, `Section`, and `CodeBlock`—that enforce prose-first authoring and theme-consistent output by prohibiting raw markup and inline styles. ### How does theme-driven styling work in Reacticle? A global `ThemeProvider` wraps the article tree and injects CSS custom properties prefixed with `--ra-*`. Components reference these tokens internally and do not expose style props to authors. Changing the theme attribute (e.g., `theme="tufte"` to `theme="technical"`) globally alters typography, color, and spacing without modifying component code. ### What is the Raw component used for? The `Raw` component serves as an escape hatch for content that cannot be expressed through the semantic component vocabulary, such as custom SVG graphics or interactive widgets. While it allows arbitrary HTML injection, it requires authors to use theme tokens (e.g., `var(--ra-color-accent)`) for colors and spacing to maintain visual consistency with the rest of the article. ### Where is the Reacticle component protocol documented? The canonical documentation resides in [`skills/beautiful-article/references/component-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/component-policy.md) within the ConardLi/garden-skills repository. This file lists the core component inventory, domain-specific extensions, prop interfaces, and the authoring rules that enforce the prose-first, theme-driven architecture.