Theme packages (beta)

Beta. First-party Sites theme packages are in beta. Package ids, install modes, and response shapes may change before general availability.

Theme packages are data-only installable units for Sites websites on styrar.site. A package is JSON: theme tokens, optional sample pages and sections, and optional chrome blocks. Styrar renders that data to HTML on the public host. Install always copies into a draft SiteVersion. The public site never live-links remote theme code.

Plan requirement: API access requires Team or Agency. See pricing.

Base URL: https://api.styrar.com/v1

How authoring works

Not supported in a package (and not planned for v0):

• Uploading a zip of HTML / Liquid / React files
• Custom JavaScript (no theme script.js, no arbitrary client JS in packages)
• Live-linked remote themes or third-party marketplace upload

If you need motion or behavior beyond CSS, use Sites interactions and block config in the editor (or via version PATCH), not package JS.

Package structure

First-party packages follow this shape (v0):

{
  "schemaVersion": 1,
  "id": "styrar.studio",
  "name": "Studio",
  "description": "Light editorial look with image+text and a CTA banner.",
  "author": "Styrar",
  "version": "1.0.0",
  "category": "portfolio",
  "swatch": { "background": "#f7f5f0", "accent": "#1a1a1a" },
  "theme": {
    "colorScheme": {
      "background": "#f7f5f0",
      "text": "#1a1a1a",
      "accent": "#1a1a1a",
      "buttonBg": "#1a1a1a",
      "buttonText": "#f7f5f0"
    },
    "fontFamily": "'Playfair Display', Georgia, serif",
    "backgroundType": "color",
    "backgroundValue": "#f7f5f0",
    "buttonStyle": "outline",
    "buttonRadius": "none",
    "avatarShape": "square",
    "containerWidth": "wide",
    "customCss": ""
  },
  "pages": ["/"],
  "pageMeta": {
    "/": {
      "title": "Home",
      "description": "Studio portfolio",
      "sections": [
        {
          "title": "Story",
          "layoutMode": "flow",
          "styles": null,
          "blocks": [
            {
              "kind": "text",
              "config": { "content": "Hello", "align": "left" },
              "styles": null
            }
          ]
        }
      ]
    }
  },
  "blocks": [
    {
      "pagePath": "/",
      "sortOrder": 0,
      "kind": "hero",
      "config": {
        "headline": "Craft with clarity",
        "subtext": "A calm studio presence.",
        "ctaLabel": "View work",
        "ctaUrl": "#"
      },
      "styles": null
    }
  ],
  "components": []
}

Fetch a real package with GET /v1/sites/theme-packages/:packageId to inspect a full example.

Theme tokens → CSS variables

Published Sites (and bio) pages set CSS custom properties from theme. Use these in theme.customCss:

Other useful fields on theme:

Styling with CSS (not raw HTML)

You do not ship HTML files. Layout comes from blocks and sections in the package (or the live editor). Visual polish beyond tokens goes in theme.customCss, targeting the classes Styrar emits.

Example:

.bio-link-btn {
  letter-spacing: 0.02em;
  box-shadow: 0 8px 24px color-mix(in srgb, var(--bio-accent) 25%, transparent);
}

.bio-hero-headline {
  font-weight: 600;
}

.bio-site-nav a[data-active="true"] {
  color: var(--bio-accent);
}

.bio-footer {
  border-top: 1px solid color-mix(in srgb, var(--bio-text) 12%, transparent);
}

Common selectors:

In the dashboard Theme editor, Open reference lists the full selector and variable set used on published pages.

Building a layout (blocks, not HTML templates)

Sample layout in a package is structured JSON:

1. Chrome blocks on each path: for example site_nav, hero, footer.
2. pageMeta[path].sections: each section has title, layoutMode (flow | grid | canvas), and blocks[].
3. Each nested block has kind (text, image, group, link_button, …), config, and optional styles.

Reuse first-party section presets from GET /v1/sites/section-catalog when composing packages (the built-in catalog does this for Studio, Midnight, Soft, and Contrast).

IDs inside sections are optional in the package snapshot. On create or install-theme-package with mode: "full", Styrar materializes fresh section and block ids.

Catalog

Authorization: Bearer sty_live_your_api_key

Authorization: Bearer sty_live_your_api_key

List responses are gallery metadata. Get-by-id returns the full package for preview.

Create a site from a package

Pass a package id as templateId (or use a structural starter: blank, portfolio, booking, store).

Authorization: Bearer sty_live_your_api_key
Content-Type: application/json

{
  "companyId": "clxyz_company",
  "title": "Studio site",
  "templateId": "styrar.studio"
}

Install onto a draft

Authorization: Bearer sty_live_your_api_key
Content-Type: application/json

{
  "packageId": "styrar.midnight",
  "mode": "theme"
}

Publish with POST /v1/sites/:id/versions/:versionId/publish when the draft should go live.

Workspace theme presets

Save reusable token snapshots for Sites (not full packages):

Pass companyId as a query param for company scope.

Related

• Sites overview - create sites and related routes (beta)
• Sites API - full Sites route table
• Authentication - scopes and API keys