Qaid
ARTICLE

Design and Publish a Quest Theme

Build a reusable quest theme from colour, type and spacing tokens, publish a version, and wire it to your site from Customize.

Qaid Team
TL;DR

Quest themes belong to your account and style any quest through the embed’s themeUrl. Sites only get a theme’s published version, never the draft. Customize writes a themeUrl with your project key in it, so a private theme works on your own sites; ticking Public only lists it in the gallery at /quest-themes.

A quest theme is a named set of style tokens plus optional CSS. It belongs to you, not to a project, so one theme can style quests in every project you work on.

There are three ways in: the Customize Theme link over the quest editor’s preview (it opens a new tab), Make one under Customize → QUEST PREVIEW when you have no themes yet, or /dashboard/quest-themes. Each lands on Quest Themes, a list of your themes with Edit and Delete. Badges on a row show Default, Public and the live version.

Design a theme

  1. Start one

    On Quest Themes, click + New theme. Give it a Name and, if you like, a Description.

  2. Set the tokens

    Pick colours with the swatches or type any CSS colour. Drag the sliders for sizes. The Live preview redraws after each change.

  3. Create it

    Click Create theme. The page moves to the theme’s own address, and the button becomes Save draft.

Group Tokens
Colors Accent / progress fill, Background, Text, Button, Button text, Progress track, Muted text, Focus, Error
Type Base size, Button size
Radius Card, Button, Option, Input
Padding Card, Button Y, Button X
Spacing Field gap, Section gap
Padding (extras) Option, Input (each with a Y and an X slider)
Marker Marker radius

Above the preview, the first menu swaps the Sample questionnaire for one of the project’s quests. Fit content lets the preview grow to the quest’s height; otherwise drag the handle under it.

Loading the film…

Split light and dark

By default each colour applies in both colour modes. Click +D beside a colour to split it: two swatches appear, the first for light mode and the second for dark. ×D joins them back into one.

Use Render as over the preview to check each mode: light, dark, or Saved, which follows the theme’s own mode. On a visitor’s page, the embed follows their system setting unless the theme or the page forces one.

Loading the film…

The maker has no control for a theme’s preset, forced mode or unstyled setting. A theme copied from the gallery can carry them, and the list shows them as badges.

Add your own CSS

The Custom CSS box takes any rules for the quest’s shadow root, such as .qaid-q-card { border-width: 2px; }. It is applied after the tokens and the preset, and before any css the page itself passes. The class names are listed in Style the quests embed.

Publish a version

Your site never sees the draft. It gets the version you publish.

Button Does
Save draft (or Cmd/Ctrl+S) Saves your edits. Only your own dashboard previews show them
Publish first version, then Publish new version Saves the draft, snapshots it as the next version, and serves that version at the theme’s URL
Versions, then Live: vN Lists every version. Make live serves an older one again; Unpublish (set live to none) stops serving the theme

A page whose theme stops serving draws its quest with the embed’s defaults; the quest itself keeps working. The × in the corner closes the theme, and asks “Discard unsaved changes?” if you have unsaved edits.

Loading the film…

Use it on your site

  1. Open Customize

    Open your project and click Customize in its header.

  2. Pick the theme

    Under QUEST PREVIEW, choose it in Quest theme. Your default theme is marked “(default)” and public ones ”· public”. The preview below redraws in it.

  3. Copy the snippet

    Pick your quest in Preview quest, then copy QUEST CODE. It now carries data-theme-url, or themeUrl in the ESM form.

Loading the film…

That URL ends in ?key= and the project’s embed key, the same key the snippet already carries. The key is what lets a private theme serve on your sites: the theme works on any project you own or belong to. Revoke the key, archive the project or leave it, and the theme stops serving there.

Warning

A snippet copied before this key was added has no ?key=, so a private theme on it gets a 404 and the quest draws unthemed. Copy the snippet again from Customize.

Customize also offers themes with no version yet. Publish one first, or the site gets nothing.

Tick Public Theme, then Save draft. The public gallery at /quest-themes lists every public theme that has a live version, newest first, with its author’s name.

While the box is ticked, a Public theme URL row shows the address with Copy. That URL has no key, so it only works while the theme stays public. Untick the box to take the theme out of the gallery; snippets from Customize keep working.

Make Default does not apply the theme anywhere. It sorts the theme first and marks it “(default)” in the Customize menu.

Start from a public theme

  1. Browse the gallery

    Open Quest Themes in the site header. Click a theme to preview it on a sample quest, and switch Render as to see light and dark.

  2. Copy it

    Click Use as starting point. Sign in if asked. A private copy named after the theme with a letter added, such as “Harbor A”, lands in your Quest Themes.

  3. Make it yours

    Edit the copy, then publish a version before you use it. A copy starts with none.

Loading the film…

The copy takes the author’s latest saved draft, which can differ from the version the gallery shows.

Copy URL gives the theme’s public URL without making a copy. That URL stops working if the author unpublishes it or makes it private. The BUILDER half of the gallery page lets anyone try tokens and copy the CSS it generates; it cannot save.

Point the embed at a theme by hand

Pass the URL as themeUrl:

new QaidQuests({
  endpoint: "https://qaid.dev/api/quests/responses",
  configUrl: "https://qaid.dev/api/quests/YOUR_QUEST_ID/definition",
  apiKey: "YOUR_PROJECT_KEY",
  themeUrl: "https://qaid.dev/api/quest-themes/YOUR_THEME_ID/public?key=YOUR_PROJECT_KEY",
});

The URL serves the live version and may be cached for up to 60 seconds. To freeze one version, use /api/quest-themes/YOUR_THEME_ID/v/2/public instead; the same key rule applies. Options you set on the page, such as preset or css, win over the theme’s. See Style the quests embed.

Back to all articles