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

The web-video-presentation skill implements a design-token-driven theming system that uses CSS custom properties defined in theme-specific 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 for metadata and tokens.css for visual implementation.

The theme.json file stores human-readable metadata that the demo gallery and scaffold script use for theme selection and documentation:

{
  "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

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

All React components in the generated Vite app reference these variables via var(), ensuring that swapping the 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, 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:

# 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 in the new project
3. Copies themes/<theme-id>/theme.json to src/design/theme.json for metadata reference
4. Injects the CSS import into the generated 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:

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

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

/* 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, 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 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:

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 must include a link element with the appropriate ID:

<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 (metadata) and 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 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 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 (with metadata and preview colors) and 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 so components render correctly.

Can I switch themes after scaffolding the project?

Yes, though it requires exchanging the tokens.css file. Replace the contents of 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.

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

The 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, keeping concerns separated between presentation (JSON) and implementation (CSS).

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