---
name: sidecars-themes
description: Give Sidecars pages the workspace's look — read the workspace's design.md before any page work, write pages with the classes and variables its css defines, and set one up or change it from a product's codebase over MCP. Use when asked to set up or change the workspace theme or design.md, to create or restyle a page, to mock up a screen, or when a page must match the workspace's brand.
compatibility: Needs the Sidecars MCP server connected (https://mcp.sidecars.ai/mcp, tools named sidecars/*). Any MCP host.
metadata:
  homepage: https://docs.sidecars.ai/skills
---

# Pages take the workspace's look

A Sidecars workspace has one design.md: a few short paragraphs on how pages
should look, and one ```css block. Every page in the workspace renders with
that css, injected ahead of the page's own styles, so a page uses its classes
and variables instead of inventing a look. Saving design.md restyles every
page. Tool reference: https://docs.sidecars.ai/reference/themes and
https://docs.sidecars.ai/reference/pages.

## 1. Read design.md before any page work

Call `read_theme` (no arguments) before `create_page` or `write_page`. It
returns `source` (the whole file) and `css` (the block pages render with).
Read the prose as instructions for the words and the layout, not only the
look. `source: null` means the workspace has none: pages render with only
their own styles, so style the page yourself — and if the person wants a
look, set one up (§4).

## 2. Write pages with its classes and variables

- Use the classes the css defines (a masthead with the logo class, a chip for
  status) and its `--variables` for anything you add.
- Keep your own `<style>` to arranging things. Do not restate a colour or font
  design.md already sets.
- Put nothing inside an element the theme draws, like the logo — it is a box
  the css paints; text inside it overflows.
- Any layout is fine if it holds together: nothing overlaps, text wraps inside
  its container, no fixed width wider than a phone (use `max-width` or a
  scrolling wrapper for a wide table), rows wrap on a narrow screen.
- No scripts (they are stripped), no external fetches; inline SVG for icons.
- Write the page to a local `.html` file, then send it by reference when you
  can run a shell: `request_upload_url` with `format: "html"`, run the
  returned `curl` with the file's path, and pass `upload_id` to
  `create_page` / `write_page` instead of `html`. A page cannot be chunked
  (`write_page` replaces it whole), so a large page pasted inline costs the
  full file in output tokens — or fails.

## 3. Changing the look means editing design.md, not a page

When asked to change how pages look ("make the accent green", "use a serif
for headings"):

1. `read_theme`, and keep its `fingerprint`.
2. Change the smallest thing — one variable, one rule, one sentence — and
   `write_theme` the whole file back with that `fingerprint`. If it answers
   `design_changed`, someone saved meanwhile: merge your change onto the
   `source` it returns and write again with the new `fingerprint`.
3. If the result carries `compile_error`, fix the css block and write again;
   pages keep the last good css meanwhile.
4. Tell the person every page now renders with the change.

Only workspace admins can write design.md. If `write_theme` refuses, give the
person the exact change to pass to an admin.

## 4. Set one up from a product

1. Find the design in the product's code: colours, fonts, spacing, dark mode,
   the logo, and the pieces the product repeats (a card, a status chip, a
   table, a header). If it isn't in the code, ask for a website or a
   screenshot.
2. Write design.md:
   - A few short paragraphs: the voice, the layout, what a report opens and
     closes with, and what a page should never do.
   - One ```css block: `:root` variables for colours and fonts (and a
     `:root[data-theme="dark"]` block if the product has dark mode), base
     rules for `body` and headings, and one class per repeated piece.
   - The logo as an SVG data URL in a variable, drawn by a class:
     `--logo: url("data:image/svg+xml,…")` and
     `.logo { width: 44px; height: 23px; background: var(--logo) center/contain no-repeat; }`.
     The css may use data: URLs only, up to 64 KB, so prefer SVG.
3. `write_theme` it (with the `fingerprint` `read_theme` returned), then tell the person what you chose and which files you
   took it from.

## 5. Do not

- Do not invent a look when design.md exists; use its classes.
- Do not put external URLs, `@import` or scripts in the css block.
- Do not keep a second copy of design.md anywhere; the workspace's file is the
  one pages render with.