Understanding the Reacticle Component Protocol in Beautiful‑Article

The Reacticle component protocol is a lightweight React-based interface that enables the beautiful-article skill to delegate all UI rendering to prose-first components while maintaining theme consistency through a unified token system.

The beautiful-article skill from the ConardLi/garden-skills repository functions as an editorial harness rather than a direct renderer. It orchestrates the article-creation workflow by writing components against the Reacticle component protocol, ensuring that content remains prose-centric while supporting complex customizations through a standardized React interface.

What Is the Reacticle Component Protocol?

Reacticle serves as the runtime component protocol that defines how beautiful-article generates React elements. Rather than rendering articles itself, the skill delegates UI work to Reacticle's lightweight component set, enabling a clean separation between content orchestration and presentation.

This protocol mandates three architectural principles: components must be prose-first for natural authoring, provide an escape hatch for raw JSX injection, and integrate with a unified theme token system. By adhering to these constraints, the skill produces articles that are simultaneously easy to author and visually consistent across different themes.

Core Architecture of Reacticle

The Reacticle protocol architecture centers on three primary mechanisms that balance simplicity with flexibility.

Prose‑First Components

Reacticle components are designed to mirror natural language structures. The Paragraph and Heading components accept text content directly, allowing authors to write JSX that reads like standard HTML prose tags while remaining fully React-compliant.

These components reside in the reacticle package imports and abstract away complex styling logic. When used in assets/scaffold-template/article/Article.tsx, they automatically resolve theme tokens without requiring manual CSS management from the author.

The Raw Token Escape Hatch

When articles require content that breaks the prose-first paradigm—such as embedded SVG graphics, custom HTML layouts, or third-party widgets—the Raw token provides a bypass mechanism. This component accepts raw JSX or HTML strings and injects them directly into the render tree.

Despite bypassing normal prose rendering, Raw still participates in the theme system. Content wrapped in <Raw> tags can reference CSS custom properties like var(--ra-primary), ensuring that even hand-crafted markup inherits the selected article theme's visual language.

Unified Theme System

Both prose-first components and the Raw escape hatch receive resolution against a theme token map. Tokens such as --ra-primary (primary color) and --ra-bg (background color) are resolved contextually based on the active theme configuration.

The ThemeProvider component, imported from reacticle, establishes this context. Wrapping the article component in <ThemeProvider theme="tufte"> injects the specific token values for the "tufte" theme, guaranteeing that every UI element follows a single visual language regardless of whether it uses standard components or the Raw escape hatch.

Implementation Example

The following code demonstrates typical Reacticle protocol usage within a beautiful-article project, illustrating the interplay between prose components, raw markup injection, and theme provision.

// src/article/Article.tsx
import { Paragraph, Heading, Raw } from 'reacticle';

export const MyArticle = () => (
  <>
    <Heading level={1}>The Future of AI Writing</Heading>
    <Paragraph>
      AI‑assisted writing is reshaping how content is created. In this article we
      explore the key trends and practical tips.
    </Paragraph>

    {/* Using the Raw escape hatch to embed a custom SVG */}
    <Raw>
      {`
        <svg width="100" height="100" viewBox="0 0 100 100">
          <circle cx="50" cy="50" r="40" fill="var(--ra-primary)" />
        </svg>
      `}
    </Raw>

    {/* Theme token applied automatically */}
    <Paragraph>
      The article’s color palette is controlled by the selected theme, so
      `--ra-primary` resolves to the theme’s primary hue.
    </Paragraph>
  </>
);

The Raw component here embeds an SVG that references --ra-primary, which resolves to the current theme's primary color. This demonstrates how the escape hatch maintains theme consistency despite bypassing standard component rendering.

To supply the theme context, the ThemeProvider wraps the article component:

// src/article/ThemeProvider.tsx
import { ThemeProvider } from 'reacticle';

export const withTheme = (Component: React.FC) => () => (
  <ThemeProvider theme="tufte">
    <Component />
  </ThemeProvider>
);

This HOC pattern ensures that all Reacticle components within the article tree have access to the "tufte" theme's token map.

Key Source Files in ConardLi/garden-skills

Understanding the Reacticle protocol requires examining specific files within the beautiful-article skill repository:

• manifest.json — Defines skill metadata including name, homepage, and version information. This file identifies the skill within the larger garden-skills ecosystem.

• README.md — Contains the high-level description of the skill and conceptual documentation for the Reacticle protocol interface.

• SKILL.md — Provides the detailed skill definition including front-matter specifications, checkpoints, and workflow orchestration logic that drives the article creation process.

• assets/scaffold-template/article/Article.tsx — Serves as the scaffolded implementation template demonstrating prototypical Reacticle component usage and file structure for new articles.

Summary

The Reacticle component protocol enables beautiful-article to function as a prose-centric editorial harness while maintaining full React flexibility:

• Prose-first design allows natural authoring through Paragraph and Heading components that abstract React complexity.
• Raw token escape hatch permits custom JSX and HTML injection via the Raw component without breaking theme inheritance.
• Unified theme system ensures visual consistency through CSS custom properties like --ra-primary and --ra-bg across all rendering paths.
• Implementation files in ConardLi/garden-skills demonstrate the protocol through Article.tsx templates and ThemeProvider configurations.

Frequently Asked Questions

How does the Raw component maintain theme consistency if it bypasses normal rendering?

The Raw component accepts arbitrary JSX or HTML strings but does not isolate them from the React context. Because theme tokens are implemented as CSS custom properties injected by ThemeProvider, any markup within Raw can reference var(--ra-primary) or other tokens. The browser resolves these variables against the current stylesheet, ensuring that hand-crafted SVG or HTML inherits the active theme's colors and spacing regardless of the rendering bypass.

What is the difference between beautiful-article and Reacticle?

beautiful-article is the skill harness that orchestrates the article-creation workflow, manages checkpoints, and defines content structure. Reacticle is the component protocol or interface that the skill writes against—a lightweight React library that handles the actual UI rendering. The skill does not render articles directly; instead, it delegates presentation to Reacticle components, creating a clean separation between content logic and presentation layer.

Can I use custom themes with the Reacticle protocol?

Yes, the theme system supports custom configurations through the ThemeProvider component. While the scaffold defaults to themes like "tufte", you can pass any theme identifier to the theme prop. The CSS custom properties (--ra-* tokens) will resolve based on the provided theme configuration, allowing complete visual customization while maintaining the prose-first authoring experience.

Where is the Reacticle protocol defined in the source code?

According to the ConardLi/garden-skills repository, the protocol is documented in skills/beautiful-article/README.md and implemented in skills/beautiful-article/assets/scaffold-template/article/Article.tsx. The SKILL.md file defines how the orchestration logic interacts with these components, while manifest.json registers the skill's metadata. These files collectively define the contract between the article skill and its Reacticle rendering layer.

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