discourse screenshots

Design Community

Skill notes

How it works

Spec authors place screenshot_marker(label: "my-label") at the moment they want to capture. The orchestrator auto-discovers those specs and runs only the it blocks that contain a marker, skipping everything else. The only: kwarg restricts a capture to one device leg: Output files: tmp/theme-screenshots/raw/{device}-{theme}-{mode}-{label}.png Comparison viewer: tmp/theme-screenshots/compare.html (tabs for device and color mode)

Matrix (default)

Theme · Modes · Devices Foundation · light, dark · desktop, mobile Horizon · light, dark · desktop, mobile

How to run

LOAD_PLUGINS=1 is always included so chat routes work.

Arguments (env vars)

Var · Default · Purpose TAKE_SCREENSHOTS · (required) · Must be 1 for the spec to run. LOAD_PLUGINS · 1 · Always set so chat and plugin routes work. SCREENSHOTS_DIR · tmp/theme-screenshots · Where PNGs and the HTML viewer are written. SCREENSHOTS_MODES · light,dark · Comma-separated color modes.

Invocation instructions

When this skill is invoked: Build the command from $ARGUMENTS. If no arguments are given, use the default matrix. Parse free-form args into env vars (composable — handle multiple at once): "dark only" / "light only" → SCREENSHOTS_MODES=… "desktop only" / "mobile only" → SCREENSHOTS_DEVICES=…

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Design
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@discourse · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# Discourse screenshots

Drives a system spec (`spec/system/theme_screenshots_spec.rb`) that discovers all system specs containing `screenshot_marker` marker calls, runs them under each combination of theme × device × color mode, and outputs PNGs plus a single `compare.html` viewer.

## How it works

Spec authors place `screenshot_marker(label: "my-label")` at the moment they want to capture. The orchestrator auto-discovers those specs and runs only the `it` blocks that contain a marker, skipping everything else. The `only:` kwarg restricts a capture to one device leg:

```ruby
screenshot_marker(label: "search-menu", only: :desktop)
```

Output files: `tmp/theme-screenshots/raw/{device}-{theme}-{mode}-{label}.png`
Comparison viewer: `tmp/theme-screenshots/compare.html` (tabs for device and color mode)

## Matrix (default)

| Theme      | Modes       | Devices         |
|------------|-------------|-----------------|
| Foundation | light, dark | desktop, mobile |
| Horizon    | light, dark | desktop, mobile |

## How to run

```bash
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 bin/rspec spec/system/theme_screenshots_spec.rb
```

`LOAD_PLUGINS=1` is always included so chat routes work.

### Arguments (env vars)

| Var                     | Default             | Purpose                                                       |
|-------------------------|---------------------|---------------------------------------------------------------|
| `TAKE_SCREENSHOTS`      | *(required)*        | Must be `1` for the spec to run.                             |
| `LOAD_PLUGINS`          | `1`                 | Always set so chat and plugin routes work.                    |
| `SCREENSHOTS_DIR`       | `tmp/theme-screenshots` | Where PNGs and the HTML viewer are written.              |
| `SCREENSHOTS_MODES`     | `light,dark`        | Comma-separated color modes.                                  |
| `SCREENSHOTS_DEVICES`   | `desktop,mobile`    | Comma-separated devices. Mobile uses Playwright WebKit.       |
| `SCREENSHOTS_THEMES`    | `foundation,horizon`| Comma-separated built-in theme names to include.              |
| `SCREENSHOTS_THEME_URL` | *(unset)*           | Git URL of a remote theme to install and add to the matrix.   |
| `SCREENSHOTS_THEME_NAME`| repo name           | Filename label for the remote/extra theme.                    |
| `SCREENSHOTS_SUBSET`    | *(unset)*           | Substring filter on marker labels — only captures markers whose label contains this string. |

### Examples

```bash
# Default — all themes × light/dark × desktop/mobile
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 bin/rspec spec/system/theme_screenshots_spec.rb

# Desktop, light mode only
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 SCREENSHOTS_DEVICES=desktop SCREENSHOTS_MODES=light \
  bin/rspec spec/system/theme_screenshots_spec.rb

# Foundation only, dark only
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 SCREENSHOTS_THEMES=foundation SCREENSHOTS_MODES=dark \
  bin/rspec spec/system/theme_screenshots_spec.rb

# Add a remote theme alongside the built-ins
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 \
  SCREENSHOTS_THEME_URL=https://github.com/org/my-theme \
  SCREENSHOTS_THEME_NAME=my-theme \
  bin/rspec spec/system/theme_screenshots_spec.rb

# Only capture markers whose label contains "topic"
TAKE_SCREENSHOTS=1 LOAD_PLUGINS=1 SCREENSHOTS_SUBSET=topic \
  bin/rspec spec/system/theme_screenshots_spec.rb
```

## Invocation instructions

When this skill is invoked:

1. Build the command from `$ARGUMENTS`. If no arguments are given, use the default matrix.
2. Parse free-form args into env vars (composable — handle multiple at once):
   - "dark only" / "light only" → `SCREENSHOTS_MODES=…`
   - "desktop only" / "mobile only" → `SCREENSHOTS_DEVICES=…`
   - "foundation only" / "just horizon" → `SCREENSHOTS_THEMES=…`
   - A git URL for a theme → `SCREENSHOTS_THEME_URL=…`; also set `SCREENSHOTS_THEME_NAME=<label>` if the user provides a name
   - A label substring (e.g. "only topic markers", "just signup") → `SCREENSHOTS_SUBSET=…`
   - A directory path (e.g. "save to /tmp/foo") → `SCREENSHOTS_DIR=…`
3. Always include `LOAD_PLUGINS=1`.
4. Always prefix with `TAKE_SCREENSHOTS=1`.
5. If the user requests an unknown built-in theme name, tell them only `foundation` and `horizon` are supported — for any other theme use `SCREENSHOTS_THEME_URL`.
6. Run via `bin/rspec spec/system/theme_screenshots_spec.rb` from the repo root.
7. After the run, list the files saved (`ls` on the raw dir) and surface the `compare.html` path to the user. Show failures if `bin/rspec` exits non-zero.

## Adding markers to a spec

In any system spec, `include ThemeScreenshotMarker` and call `screenshot_marker` at the point you want to capture:

```ruby
describe "Search" do
  include ThemeScreenshotMarker

  it "shows search results" do
    visit "/search"
    search_page.type_in_search("test")
    search_page.click_search_button

    screenshot_marker(label: "search-results")               # captured on all devices
    screenshot_marker(label: "search-menu", only: :desktop)  # desktop only
  end
end
```

The `include ThemeScreenshotMarker` line is required — without it, `screenshot_marker` is undefined when the spec is run directly. The orchestrator also auto-includes it as a safety net, but relying on that alone will break direct spec runs.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.