Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
7nohe merged 1 commit into from
Dec 17, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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)
Expand Down
105 changes: 76 additions & 29 deletions examples/backgrounds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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"
Expand All @@ -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"
---

Expand All @@ -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).
Loading