# How the Theme Architecture Works in web-video-presentation: A Design-Token Deep Dive

> Explore the theme architecture in web-video-presentation. Learn how CSS custom properties and design tokens enable seamless visual identity switching without altering component code.

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

---

**The web-video-presentation skill implements a design-token-driven theming system that uses CSS custom properties defined in theme-specific [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) files to enable complete visual identity switching without modifying component code.**

The **theme architecture** in the ConardLi/garden-skills repository allows a single React-based presentation to adopt radically different visual identities—ranging from dark cinematic modes to light editorial styles—through a declarative token system. By isolating visual primitives into JSON metadata and CSS custom properties, the architecture separates design decisions from component implementation, enabling theme switching via file replacement rather than code changes.

## Theme Definition and Metadata Configuration

Each theme resides in a dedicated folder under `skills/web-video-presentation/themes/<theme-id>/` and requires two core files: [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) for metadata and [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) for visual implementation.

The [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) file stores **human-readable metadata** that the demo gallery and scaffold script use for theme selection and documentation:

```json
{
  "id": "indigo-porcelain",
  "name": "Indigo Porcelain",
  "description": "Deep-indigo ink on porcelain white …",
  "mood": ["light","indigo","porcelain","academic","editorial","scholarly"],
  "bestFor": ["学术 / 研究 / 论文解读","AI / 数据 / 工程深度"],
  "preview": {
    "shell":   "#e4e8ec",
    "surface": "#f1f3f5",
    "text":    "#0a1f3d",
    "accent":  "#1e3a8a"
  }
}

```

Source: [`skills/web-video-presentation/themes/indigo-porcelain/theme.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/themes/indigo-porcelain/theme.json)

This JSON file is **read-only** during runtime. The scaffold script copies it into generated projects so developers can reference which theme is active, but the actual visual rendering depends entirely on the accompanying CSS token file.

## Design Tokens and CSS Custom Properties

The visual implementation lives in [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css), which declares **CSS custom properties** (`--*`) for every primitive the presentation requires. These variables create a single source of truth for the entire visual language.

### Token Categories and Purpose

The [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) file organizes design decisions into four semantic categories:

**Palette tokens** control color foundations:
- `--shell`: Background color for the outer stage
- `--surface`: Card and container backgrounds
- `--text`: Primary typography color
- `--accent`: Interactive element highlighting

**Typography tokens** define the type hierarchy:
- `--font-display-en`: Hero numbers and headlines (e.g., "Playfair Display")
- `--font-body`: Paragraph and UI text (e.g., "IBM Plex Sans")
- `--font-mono`: Code and data displays

**Motion tokens** standardize timing:
- `--dur-base`: Standard transition duration (680ms)
- `--dur-slow`: Emphasis animations (1050ms)

**Design identity tokens** capture thematic signatures:
- `--r-card`: Border radius for cards
- `--hero-num-font`: Hero number typeface
- `--hero-num-weight`: Hero number font weight

Source: [`skills/web-video-presentation/themes/indigo-porcelain/tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/themes/indigo-porcelain/tokens.css)

All React components in the generated Vite app reference these variables via `var()`, ensuring that swapping the [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) file instantly transforms the entire presentation aesthetic.

## Theme Selection via the Scaffold Script

The **scaffold script** automates theme installation when creating new presentations. Located at [`skills/web-video-presentation/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/scripts/scaffold.sh), this CLI tool validates theme IDs against the available folder list and copies the necessary assets into the generated project structure.

To scaffold a presentation with a specific theme:

```bash

# List all 23 available themes

bash skills/web-video-presentation/scripts/scaffold.sh --list-themes

# Create a new presentation using the indigo-porcelain theme

bash skills/web-video-presentation/scripts/scaffold.sh ./my-presentation --theme=indigo-porcelain

```

The script performs three critical operations:
1. Validates the theme ID against the directory structure
2. Copies `themes/<theme-id>/tokens.css` to [`src/design/tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/src/design/tokens.css) in the new project
3. Copies `themes/<theme-id>/theme.json` to [`src/design/theme.json`](https://github.com/ConardLi/garden-skills/blob/main/src/design/theme.json) for metadata reference
4. Injects the CSS import into the generated [`index.html`](https://github.com/ConardLi/garden-skills/blob/main/index.html)

This approach ensures that the theme architecture remains **file-based and deterministic**, with no runtime computation required to resolve styles.

## Runtime Implementation and Component Consumption

Components consume tokens through standard CSS variable references, creating a **cascading design system** that updates automatically when token values change.

For example, a card component implementation:

```tsx
// Card.tsx
import './design/tokens.css';

export const Card = ({ children }: { children: React.ReactNode }) => (
  <section className="card">
    {children}
  </section>
);

```

```css
/* Card.css */
.card {
  background: var(--surface);
  border-radius: var(--r-card);
  box-shadow: var(--card-shadow);
  transition: transform var(--dur-base) ease;
}

```

Because variables are declared on `:root` in [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css), they cascade naturally to all child components. The **stage container** reads `--shell` for its background, while **hero components** read `--hero-num-font` and `--hero-num-weight` for typographic styling.

The design-system contract documented in [`skills/web-video-presentation/references/THEMES.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/THEMES.md) specifies the required token names. Any custom theme must expose this complete set of properties; missing tokens fall back to browser defaults.

## Advanced: Runtime Theme Switching

While the scaffold script sets the initial theme, advanced implementations can switch themes dynamically by manipulating the CSS import at runtime:

```tsx
function switchTheme(themeId: string) {
  const link = document.getElementById('theme-tokens') as HTMLLinkElement;
  if (link) {
    link.href = `/src/design/themes/${themeId}/tokens.css`;
  }
}

```

The [`index.html`](https://github.com/ConardLi/garden-skills/blob/main/index.html) must include a link element with the appropriate ID:

```html
<link id="theme-tokens" rel="stylesheet" href="/src/design/tokens.css">

```

This technique enables **audience-controlled presentation modes** or adaptive themes based on time of day, though it requires all theme variants to be built and available in the deployment bundle.

## Summary

- **Theme architecture** relies on paired [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) (metadata) and [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) (visual primitives) files located in `skills/web-video-presentation/themes/<theme-id>/`.
- **Design tokens** are CSS custom properties scoped to `:root`, covering palette, typography, motion, and spatial design identity.
- **Scaffold script** at [`skills/web-video-presentation/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/scripts/scaffold.sh) handles theme validation and file copying during project initialization.
- **Component consumption** uses standard `var()` references, ensuring themes change without JSX modifications.
- **Design contract** documented in [`references/THEMES.md`](https://github.com/ConardLi/garden-skills/blob/main/references/THEMES.md) mandates specific token names for compatibility across all 23 shipped themes.

## Frequently Asked Questions

### How do I create a custom theme for web-video-presentation?

Create a new folder under `skills/web-video-presentation/themes/` with your theme ID, then add both [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) (with metadata and preview colors) and [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) (declaring all required CSS custom properties like `--shell`, `--text`, and `--dur-base`). Ensure your tokens follow the naming convention documented in [`references/THEMES.md`](https://github.com/ConardLi/garden-skills/blob/main/references/THEMES.md) so components render correctly.

### Can I switch themes after scaffolding the project?

Yes, though it requires exchanging the [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) file. Replace the contents of [`src/design/tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/src/design/tokens.css) with your new theme's CSS variables, or implement dynamic switching by changing the `href` of the theme link element in the DOM. All components will update immediately since they reference CSS variables rather than hardcoded values.

### What happens if a theme token is missing?

Components fall back to browser defaults for undefined CSS custom properties. However, this breaks the visual cohesion of the **theme architecture**, so the scaffold script validates that themes include the full token set defined in the design-system contract at [`references/THEMES.md`](https://github.com/ConardLi/garden-skills/blob/main/references/THEMES.md).

### Why does theme.json exist if tokens.css controls the visuals?

The [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) file serves **metadata and discovery** purposes. It provides human-readable names, mood tags, and preview colors for the theme gallery interface, while the scaffold script copies it into projects for documentation. The actual rendering depends entirely on [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css), keeping concerns separated between presentation (JSON) and implementation (CSS).