Reacticle Component Protocol in beautiful-article: A Prose-First Publishing System

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 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 with source code maintained at 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, 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, 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 <div> 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 <ThemeProvider theme="..."> 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 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 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 <ThemeProvider>. The 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. For archival distribution, 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:

import {
  ThemeProvider,
  Article,
  Hero,
  Lead,
  Section,
  Aside,
  Raw,
} from "reacticle";

export function MyArticle() {
  return (
    <ThemeProvider theme="tufte">
      <Article>
        <Hero title="The Power of Reacticle" subtitle="A prose‑first approach" />
        <Lead>
          This article demonstrates the minimal scaffold required to write an
          article with the Reacticle component protocol.
        </Lead>

        <Section index="01" title="Why Prose‑First?">
          <p>
            The core idea is to keep the narrative dominant. Components are only
            added when the structure truly demands them.
          </p>

          <Aside tone="principle" label="Key Insight">
            Semantic components improve readability and accessibility.
          </Aside>

          <Raw title="Custom SVG Illustration">
            <svg viewBox="0 0 240 60" width="100%">
              <polyline
                points="0,50 40,42 80,46 120,20 160,28 200,8 240,14"
                fill="none"
                stroke="var(--ra-color-accent)"
                strokeWidth="2"
              />
            </svg>
          </Raw>
        </Section>
      </Article>
    </ThemeProvider>
  );
}

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

import { Table, CodeBlock } from "reacticle";

<Table
  columns={["Name", "Score"]}
  rows={[
    ["Alice", "95"],
    ["Bob", "87"],
  ]}
/>

<CodeBlock language="tsx">
{`function greet(name: string) {
  return \`Hello, \${name}!\`;
}`}
</CodeBlock>

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 – Overview of the skill and its dependency on the Reacticle npm package
• skills/beautiful-article/references/component-policy.md – Formal specification of allowed components, prop interfaces, and usage constraints
• 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 – Reference implementation showing protocol-compliant component composition
• 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}