feat: unify background config with auto-detection and Figma component backgrounds (#17)

Author: 7nohe

CLAUDE.md

@@ -240,11 +240,20 @@ Global settings at file start, or per-slide after `---`:
 ```yaml
 ---
 figdeck: true                   # Required for VSCode extension to recognize file
-background: "#1a1a2e"           # Solid color
-gradient: "#0d1117:0%,#1f2937:50%,#58a6ff:100%@45"  # Gradient with angle
-template: "Style Name"          # Figma paint style name
-backgroundImage: "./bg.png"     # Local image (PNG, JPEG, GIF)
-backgroundImage: "https://..."  # Remote image URL
+background: "#1a1a2e"           # Solid color (auto-detect)
+background: "#0d1117:0%,#58a6ff:100%@45"  # Gradient (auto-detect)
+background: "./bg.png"          # Local image (auto-detect)
+background: "https://figma.com/...?node-id=123-456"  # Figma component (auto-detect)
+background:                     # Object format (explicit)
+  color: "#1a1a2e"              # Solid color
+  gradient: "#0d1117:0%,#58a6ff:100%@45"  # Gradient with angle
+  template: "Style Name"        # Figma paint style name
+  image: "./bg.png"             # Local image (PNG, JPEG, GIF) or URL
+  component:                    # Figma Component/Frame as background
+    link: "https://www.figma.com/design/xxx?node-id=123-456"
+    fit: "cover"                # cover | contain | stretch
+    align: "center"             # center | top-left | top-right | bottom-left | bottom-right
+    opacity: 0.8                # 0-1
 color: "#ffffff"                # Base text color for all elements
 headings:
   h1: { size: 72, color: "#fff" }
@@ -294,7 +303,7 @@ transition:                     # Full configuration
 ---
 ```
 
-**Background Priority:** templateStyle > gradient > solid > image
+**Background Priority (object format):** template > gradient > color > image
 
 **Transition Styles:** `none`, `dissolve`, `smart-animate`, `slide-from-*`, `push-from-*`, `move-from-*`, `slide-out-to-*`, `move-out-to-*` (where * = left, right, top, bottom)
 
@@ -338,7 +347,7 @@ Supported text override formatting: **bold**, *italic*, ~~strikethrough~~, [link
   - `fonts.md` - Custom font family configuration
   - `slide-numbers.md` - Slide number configuration
   - `figma-links.md` - Figma node embedding
-  - `backgrounds.md` - Background styles
+  - `backgrounds.md` - All background types (color, gradient, image, template, Figma component)
   - `rich-formatting.md` - Inline formatting
   - `transitions.md` - Slide transition animations
   - `images.md` - Image size and position specifications (Marp-style)

examples/backgrounds.md

@@ -4,9 +4,9 @@ background: "#1a1a2e"
 color: "#ffffff"
 ---
 
-# Background & Text Color Examples
+# Background Examples
 
-This presentation demonstrates background and text color options.
+This presentation demonstrates all background options.
 
 All slides use dark background with white text by default.
 
@@ -19,31 +19,21 @@ This slide uses the global settings from YAML frontmatter.
 No per-slide frontmatter needed!
 
 ---
-
+background: "#16213e"
 ---
 
-## background: "#16213e"
-
 ## Override with Different Color
 
 - This slide overrides the default with its own frontmatter
 - Per-slide settings take priority over global defaults
 
 ---
-
+background: "#0d1117:0%,#1f2937:50%,#3b82f6:100%@45"
 ---
 
-## gradient: "#0d1117:0%,#1f2937:50%,#3b82f6:100%@45"
+# Gradient Background
 
-# Gradient Override
-
-Gradients also override the default background.
-
----
-
-## Back to Default
-
-This slide has no frontmatter, so it uses the global default again.
+Gradients are auto-detected from the string format.
 
 ---
 background: "#f0f4f8"
@@ -55,20 +45,18 @@ color: "#020202"
 This slide uses light background with dark text.
 
 ---
-backgroundImage: "https://images.unsplash.com/photo-1557683316-973673baf926?w=1920&h=1080&fit=crop"
+background: "https://images.unsplash.com/photo-1557683316-973673baf926?w=1920&h=1080&fit=crop"
 color: "#ffffff"
 ---
 
 ## Remote Background Image
 
 This slide uses a remote image URL as background.
 
-The image is fetched by the Figma plugin.
+URLs are auto-detected as images.
 
 ---
-
----
-backgroundImage: "./local-bg.png"
+background: "./local-bg.png"
 color: "#ffffff"
 ---
 
@@ -79,21 +67,80 @@ This slide uses a local image file.
 The CLI reads and embeds the image as base64.
 
 ---
+background:
+  template: "Inter"
+---
 
-## Summary
+## Template Style
+
+Use a Figma paint style by name.
+
+---
+background: "https://figma.com/...?node-id=123-456"
+---
+
+## Figma Component (URL Shorthand)
 
-YAML frontmatter format:
+Copy a Figma link with node-id from your Component or Frame.
+
+The component will be scaled to cover the slide by default.
+
+---
+background:
+  component:
+    link: "https://figma.com/...?node-id=123-456"
+    fit: "contain"
+    align: "center"
+---
+
+## Figma Component Options
+
+- `fit`: cover (default), contain, stretch
+- `align`: center (default), top-left, top-right, bottom-left, bottom-right
+- `opacity`: 0-1
+
+---
+background:
+  color: "#1a1a2e"
+  component:
+    link: "https://figma.com/...?node-id=123-456"
+    fit: "cover"
+    opacity: 0.8
+---
+
+## Combined Background
+
+Component can be combined with color/gradient/image.
+
+The component renders as a layer on top of the base fill.
+
+---
+
+## Summary
 
 ```yaml
 ---
+# String format (auto-detect)
 background: "#1a1a2e"           # Solid color
-gradient: "#0d1117:0%,#58a6ff:100%@45"  # Gradient
-backgroundImage: "./bg.png"     # Local image
-backgroundImage: "https://..."  # Remote image URL
-color: "#ffffff"                # Text color
+background: "#000:0%,#fff:100%" # Gradient
+background: "./bg.png"          # Local image
+background: "https://..."       # Remote image
+background: "https://figma.com/...?node-id=123-456"  # Figma component
+
+# Object format (explicit)
+background:
+  color: "#1a1a2e"
+  gradient: "#000:0%,#fff:100%@45"
+  template: "Style Name"
+  image: "./bg.png"
+  component:
+    link: "https://figma.com/...?node-id=123-456"
+    fit: "cover"        # cover | contain | stretch
+    align: "center"     # center | top-left | ...
+    opacity: 0.8        # 0-1
 ---
 ```
 
-Global (file start) sets defaults, per-slide overrides.
+Priority: template > gradient > color > image
 
-Priority: template > gradient > solid > image
+Component works with same-file nodes only (MVP limitation).