# How Authoring Theme Profiles Work in the beautiful-article Skill: Visual Design Meets AI Guidance

> Discover how authoring theme profiles in the beautiful-article skill work. Learn how structured markdown and JSON indexing blend visual design with AI guidance for aesthetic intent.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Authoring theme profiles in the beautiful-article skill separate runtime CSS from AI authoring guidance, using structured markdown files to define aesthetic intent while JSON indexing maps content types to appropriate themes.**

The beautiful-article skill in the ConardLi/garden-skills repository implements a sophisticated theming architecture that decouples visual rendering from editorial planning. This system allows AI agents to select appropriate design constraints based on article content type, ensuring that the final rendered output matches the intended tone and structure.

## What Are Authoring Theme Profiles?

Authoring theme profiles serve as **editorial blueprints** that guide AI agents during article planning, distinct from the runtime stylesheets that control visual presentation. Each profile stored in `skills/beautiful-article/theme-profiles/<id>.md` defines the aesthetic intent, suitable article types, Raw component styling preferences, media guidelines, and density-dependent suggestions for a specific visual theme.

The system maintains a strict separation between *authoring guidance* (what the AI reads while planning) and *runtime styling* (the CSS applied during rendering). According to the source code, the authoring profile describes the "aesthetic intent, suitable article types, Raw style, media guidelines, code/formula styling, and density-dependent suggestions" that an AI should follow when structuring content.

## Profile Storage and Indexing

The profile collection is organized through a central registry at [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json). This JSON index serves as the master directory, mapping each profile `id` to its corresponding runtime theme used by the component library in `src/theme/themes/<id>/`.

The index.json structure contains critical metadata fields that the AI evaluates during selection:

- **`bestFor`**: Array of content types ideally suited to this theme (e.g., `essay`, `tutorial`, `report`)
- **`mood`**: Descriptive tags indicating the emotional or tonal characteristics
- **`notFor`**: Content types that should avoid this theme
- **`runtimeTheme`**: The identifier linking the authoring profile to its visual implementation

```json
// Example structure from theme-profiles/index.json
{
  "id": "tufte",
  "label": "Tufte Style",
  "bestFor": ["longform", "full-report", "explainer"],
  "runtimeTheme": "tufte"
}

```

Individual profiles like [`theme-profiles/tufte.md`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/tufte.md) contain detailed markdown documentation specifying typography rules, component preferences, and content density recommendations that guide the AI's structural decisions.

## The Theme Selection Workflow

The selection process follows a four-stage pipeline defined in [`skills/beautiful-article/references/theme-selection.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/theme-selection.md):

### 1. Read the Index

The AI first parses [`theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/index.json) to obtain the complete catalog of available themes, extracting `bestFor`, `mood`, and `notFor` tags for each candidate.

### 2. Match Source Material

Based on the source document's content type, tone, or explicit requirements, the AI selects one to two candidate themes. For example, technical documentation maps to the `tufte` theme, while narrative journalism aligns with the `press` theme.

### 3. Load Detailed Guidance

The AI reads the full profile markdown file (`theme-profiles/<id>.md`) for the selected candidates, accessing specific constraints regarding typography, Raw component usage, and media styling.

### 4. Record the Decision

Finally, the AI writes the chosen theme identifier and selection rationale into [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md) under the **Theme** section, following the structure defined in [`skills/beautiful-article/references/plan-template.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/references/plan-template.md).

```markdown
<!-- Excerpt from plan.md output -->

## Theme

**Selected:** tufte  
**Rationale:** Technical tutorial requiring dense marginalia and 
formal typography consistent with academic publishing standards.

```

## Runtime Coupling and Validation

A critical architectural constraint ensures consistency between planning and rendering: the authoring profile's `runtimeTheme` field must match an existing runtime theme registered in [`ThemeProvider.tsx`](https://github.com/ConardLi/garden-skills/blob/main/ThemeProvider.tsx). If a profile exists without a corresponding runtime theme implementation, the theme remains a candidate only and cannot be used for final article generation.

This coupling prevents the AI from selecting aesthetic guidelines that lack visual implementations. The runtime themes (`tufte`, `press`, etc.) perform the actual visual rendering, while the authoring profiles ensure the AI structures content appropriately for those visual constraints.

## Scaffolding Support with CLI Validation

The [`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh) script enforces theme validity during workspace creation. When creating a new article, the script validates that the `--theme` argument corresponds to an `id` present in [`theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/index.json), then copies the selected profile into the workspace for reference during development.

```bash

# List available theme ids

bash skills/beautiful-article/scripts/scaffold.sh --list-themes

# Scaffold a new article using the "press" theme

bash skills/beautiful-article/scripts/scaffold.sh ./my-article --theme=press

```

The script prevents invalid theme selection at the scaffolding stage, ensuring that only indexed themes with complete authoring profiles can initialize new article workspaces.

## Practical Implementation Examples

When building external tooling or extensions for the beautiful-article skill, you can programmatically access the theme index:

```typescript
// Example: reading the index in a Node script (used by the skill’s planner)
import fs from 'fs';

const index = JSON.parse(
  fs.readFileSync('skills/beautiful-article/theme-profiles/index.json', 'utf-8')
);

const candidate = index.find(t => t.bestFor.includes('essay'));
console.log(`Pick theme ${candidate.id} (${candidate.label})`);

```

Theme profiles utilize structured markdown sections to define constraints:

```markdown
<!-- Excerpt from theme-profiles/tufte.md -->

## 适合 / 不适合的文章类型

- **适合**：`longform`、`full-report`、`explainer`、`review`、`tutorial`
- **不适合**：需要 10 米外观看的幻灯片…

```

## Summary

- **Authoring theme profiles** are markdown-based editorial guidelines stored in `theme-profiles/<id>.md` that direct AI content planning.
- The **index.json** registry maps profiles to runtime themes and tags them with `bestFor`/`notFor` content classifications.
- **Selection workflow** involves reading the index, matching content types, loading detailed profiles, and recording decisions in [`plan/plan.md`](https://github.com/ConardLi/garden-skills/blob/main/plan/plan.md).
- **Runtime coupling** requires every authoring profile to reference a valid `runtimeTheme` implemented in the component library's [`ThemeProvider.tsx`](https://github.com/ConardLi/garden-skills/blob/main/ThemeProvider.tsx).
- **Scaffolding validation** ensures only registered themes can initialize workspaces through [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh).

## Frequently Asked Questions

### What is the difference between an authoring profile and a runtime theme?

An **authoring profile** is a markdown file read by AI agents during article planning that defines editorial constraints, suitable content types, and stylistic intent. A **runtime theme** is the actual CSS and component configuration in `src/theme/themes/<id>/` that renders the final visual output. The profile guides what to write; the runtime theme determines how it looks.

### How does the AI choose between multiple suitable themes?

The AI evaluates the `bestFor`, `mood`, and `notFor` tags in [`theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/index.json) to identify 1-2 candidate themes matching the source material's content type and tone. It then reads the detailed markdown profiles for these candidates to assess which specific aesthetic guidelines best fit the article's structural requirements before recording the final decision.

### What happens if I specify a theme that exists only as a profile but has no runtime implementation?

According to the source code in [`references/theme-selection.md`](https://github.com/ConardLi/garden-skills/blob/main/references/theme-selection.md), if a profile's `runtimeTheme` field references a non-existent implementation, that theme is treated as a candidate only and **cannot be used for final generation**. The [`scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scaffold.sh) script prevents this by validating against the index, but manual workspace creation should verify that the chosen profile has a corresponding runtime theme registered in [`ThemeProvider.tsx`](https://github.com/ConardLi/garden-skills/blob/main/ThemeProvider.tsx).

### Can I create custom theme profiles for specialized content types?

Yes, custom profiles can be added by creating new markdown files in `theme-profiles/` and registering them in [`theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/theme-profiles/index.json) with appropriate `bestFor` tags and a valid `runtimeTheme` mapping. The profile should define specific aesthetic intent and content constraints, and the scaffolding script will automatically recognize any theme ID present in the index.