# How Themes Are Selected in the web-video-presentation Skill: A Technical Deep Dive

> Discover how the web-video-presentation skill selects themes by validating user input against a theme catalogue or defaulting to a random selection. Learn the technical process.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: deep-dive
- Published: 2026-09-02

---

**The web-video-presentation skill selects themes by validating the user-provided `theme` parameter against the catalogue in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json), automatically falling back to a random theme when no preference is specified.**

The web-video-presentation skill in the ConardLi/garden-skills repository generates visually consistent video presentations by integrating with the Beautiful Article theme engine. Understanding how this skill resolves visual styling requires examining the theme catalogue structure, the selection algorithm, and the runtime injection mechanism that applies design tokens to the final output.

## Theme Catalogue Architecture

The skill relies on a centralized JSON manifest to discover available visual styles. This catalogue-based approach decouples theme definitions from the selection logic, enabling modular additions of new design profiles without modifying core skill code.

### Index.json Structure

All valid theme identifiers are registered in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json). This manifest maps theme keys to corresponding markdown definition files:

- **Theme keys**: String identifiers such as `vignelli`, `tufte`, or `knuth`
- **Value mapping**: Each key points to a relative path for the theme's markdown specification containing palette definitions, typography scales, and layout constraints
- **Location**: [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json) serves as the single source of truth for theme availability

### Markdown Theme Definitions

Individual themes are stored as markdown files within the same directory (e.g., [`vignelli.md`](https://github.com/ConardLi/garden-skills/blob/main/vignelli.md), [`tufte.md`](https://github.com/ConardLi/garden-skills/blob/main/tufte.md), [`knuth.md`](https://github.com/ConardLi/garden-skills/blob/main/knuth.md)). These files contain the actual design system parameters—color hex codes, font stack declarations, spacing units, and component-specific styling rules—that the skill injects into the generated presentation markup.

## Theme Selection Algorithm

The selection logic resides in the skill's entry point at [`skills/web-video-presentation/skill.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/skill.ts) (or the equivalent JavaScript implementation). The algorithm follows a deterministic priority order:

### 1. Parameter Validation

When the skill executes, it first inspects the incoming parameters for a `theme` property. If `params.theme` exists and matches a key present in the theme index, the skill immediately selects that theme:

```typescript
import themeIndex from '../../skills/beautiful-article/theme-profiles/index.json';

const themeKeys = Object.keys(themeIndex);
const selectedTheme = params.theme && themeKeys.includes(params.theme)
    ? params.theme
    : getRandomTheme(themeKeys);

```

### 2. Random Fallback Mechanism

If the `theme` parameter is omitted or contains an invalid identifier, the skill executes a pseudorandom selection from the available catalogue keys:

```typescript
function getRandomTheme(keys: string[]): string {
    const randomIndex = Math.floor(Math.random() * keys.length);
    return keys[randomIndex];
}

```

This ensures every presentation renders with a valid design system even when users do not specify a visual preference.

## Theme Application Process

After resolving the theme name, the skill performs two additional operations to apply the visual layer:

### Loading Theme Definitions

The skill constructs the file path to the selected theme's markdown definition using string interpolation:

```typescript
import { readFileSync } from 'fs';

function loadThemeDefinition(themeName: string): string {
    const themePath = `../../skills/beautiful-article/theme-profiles/${themeName}.md`;
    return readFileSync(themePath, 'utf-8');
}

```

### Style Injection

The raw markdown content containing CSS variables and component styles is injected into the HTML/React component tree that renders the video presentation. This occurs in the skill's rendering pipeline, ensuring the `videoUrl` asset displays within the context of the selected visual language (Swiss minimalism for `vignelli`, academic typography for `tufte`, etc.).

## Practical Usage Examples

### Explicit Theme Selection

Force a specific visual style by providing the theme identifier in the skill parameters:

```json
{
  "skill": "web-video-presentation",
  "params": {
    "theme": "tufte",
    "videoUrl": "https://example.com/lecture.mp4"
  }
}

```

### Random Theme Selection

Omit the theme parameter to trigger the random selection behavior:

```json
{
  "skill": "web-video-presentation",
  "params": {
    "videoUrl": "https://example.com/intro.mp4"
  }
}

```

## Summary

- **Theme registration**: All valid themes are catalogued in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json), mapping identifiers to markdown definition files.
- **Selection priority**: The skill checks `params.theme` first; if missing or invalid, it selects randomly from available keys using `Math.random()` and `Object.keys()`.
- **File resolution**: Selected themes load from `skills/beautiful-article/theme-profiles/${themeName}.md` using filesystem reads.
- **Visual application**: Theme markdown is injected into the presentation markup, styling the video container according to the chosen design system (Vignelli, Tufte, or Knuth).

## Frequently Asked Questions

### How do I specify a theme when calling the web-video-presentation skill?

Pass the `theme` parameter with a valid string identifier (e.g., `"vignelli"`, `"tufte"`, or `"knuth"`) in the skill's JSON payload. The skill validates this against the keys defined in [`skills/beautiful-article/theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/theme-profiles/index.json) before resolving the corresponding markdown file.

### What happens if I don't provide a theme parameter?

When the `theme` parameter is omitted or contains an unrecognized value, the skill automatically executes a random selection algorithm. It generates a random index based on `Object.keys(themeIndex).length` and selects the corresponding theme from the catalogue, ensuring the presentation always renders with a valid design system.

### Where are the actual theme styles defined?

Theme-specific styling—including color palettes, typography scales, and layout constraints—is defined in markdown files located at `skills/beautiful-article/theme-profiles/`. Each theme has its own `.md` file (such as [`vignelli.md`](https://github.com/ConardLi/garden-skills/blob/main/vignelli.md) or [`tufte.md`](https://github.com/ConardLi/garden-skills/blob/main/tufte.md)) that the skill reads and injects into the final HTML output during the rendering phase.