Skip to content

Developer guide

What a theme package contains, what the validator refuses, and how a release reaches a storefront.

Start here

The shortest path from nothing to a theme a reviewer can approve. Every step below is checked by the same validator, so a theme that passes on your machine passes on submission.

  1. Create the package: New theme in this studio, or restro-theme init on the command line. Both write the same starter with every required file.
  2. Set the palette in both light.json and dark.json. The studio shows contrast failures as you type, before you submit anything.
  3. Edit or add components: a component.json describing its props, a template.hbs using the allowed helpers, and a styles.css with logical properties.
  4. Validate, then preview in Arabic and English, light and dark, at phone and desktop widths.
  5. Add at least three screenshots and submit. The automatic scan runs first; a person reviews what passes.
npx restro-theme init my-theme
cd my-theme
npx restro-theme validate      # the same checks as the studio
npx restro-theme dev           # a live preview on your machine
npx restro-theme login
npx restro-theme publish       # submits for review

The package

A theme is a manifest, two palettes, one or more components, and a layout per page type. Every path below is fixed: the installer, the validator and this studio all read the same names.

my-theme/
├── theme.manifest.json
├── tokens/
│   ├── light.json
│   └── dark.json          mandatory
├── components/
│   └── <key>/
│       ├── component.json props schema + slots + regions
│       ├── template.hbs   allowed helpers only
│       └── styles.css     sanitized and scoped on upload
├── layouts/
│   ├── <page-type>.json
│   └── home.site-first.json  optional: "homeMode": "site_first" — a second home page
├── assets/
├── preview/               at least three screenshots
├── LICENSE
└── CHANGELOG.md

The manifest, field by field

theme.manifest.json describes the theme to the marketplace and the installer. Every field is required and unknown fields are refused, so a typo is an error rather than a setting that silently does nothing.

schemaVersion
Which manifest format this is. Use the one the starter writes.
key
Your theme’s permanent identifier: lowercase letters, digits and hyphens. It cannot change after the first release.
name
The marketplace name, in Arabic and English.
description
One or two sentences for the marketplace card, in both languages.
version
Semver, raised on every release.
author
Who made it, and how a merchant reaches you.
license
The licence the theme is offered under, by its SPDX name or your own.
platformCompat
The platform versions the theme works with, as a semver range.
businessTypes
The kinds of venue it is made for — restaurant, café, bakery and so on. Merchants see themes that match their venue.
supportedLocales
Languages the theme’s own text exists in. Arabic and English are required.
colorModes
Must list both light and dark.
defaultColorMode
The mode a visitor sees before choosing: light, dark or system.
pricing
Free, or a one-time or recurring price.
capabilities
What the theme asks for beyond templates and CSS — custom JavaScript, external resources. Each one adds review.
entry
Where the installer finds the tokens, components and layouts inside the package.
presentation
Presentation
motion
Motion
content
Content

Design tokens

Each palette file defines every key below, in both modes. The storefront reads them as CSS variables, so a component that uses var(--color-primary) follows the merchant when they recolour the theme.

Colours

  • primary
  • secondary
  • accent
  • background
  • surface
  • surfaceRaised
  • foreground
  • foregroundMuted
  • border
  • success
  • warning
  • danger
  • info

Typography

  • headingFont
  • bodyFont
  • baseSize
  • scale
  • headingWeight
  • bodyWeight

Spacing and shape

  • radius
  • containerWidth
  • sectionPadding
  • gap

Component styles

  • buttonStyle
  • cardStyle
  • navbarStyle
  • menuItemStyle

Layout choices

  • headerType
  • footerType
  • menuLayout
  • checkoutLayout

Both colour modes are mandatory

A theme ships light.json and dark.json, declaring exactly the same token keys. The validator rejects a theme with one mode, and it rejects one whose modes disagree about which tokens exist. The platform cannot synthesise the missing mode safely, and a dark visitor on a light-only theme gets an unreadable page.

Contrast is a gate, not advice

Body text on every surface must reach 4.5:1, and meaningful fills 3:1, in both modes. A failure is an error and blocks submission. Border contrast is checked too but only warns, because one border role covers both input outlines and decorative hairlines.

Colour pairs the validator measures in both modes
Foreground / backgroundMinimumWhy
foreground / background4.5:1Body copy must be legible on every surface the theme paints (SC 1.4.3).
foreground / surface4.5:1Body copy must be legible on every surface the theme paints (SC 1.4.3).
foreground / surfaceRaised4.5:1Body copy must be legible on every surface the theme paints (SC 1.4.3).
foregroundMuted / background4.5:1Captions, prices and helper text are still text; SC 1.4.3 does not exempt them.
foregroundMuted / surface4.5:1Captions, prices and helper text are still text; SC 1.4.3 does not exempt them.
foregroundMuted / surfaceRaised4.5:1Captions, prices and helper text are still text; SC 1.4.3 does not exempt them.
primary / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
primary / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
secondary / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
secondary / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
accent / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
accent / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
success / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
success / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
warning / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
warning / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
danger / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
danger / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
info / background3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
info / surface3:1This role identifies a control or a state, so it must be visible as a mark, not only as a colour (SC 1.4.11).
border / background3:1 · warning onlyWhere this role draws an input outline or a focus ring it must reach 3:1 (SC 1.4.11); at hairline-divider duty it may stay lower.
border / surface3:1 · warning onlyWhere this role draws an input outline or a focus ring it must reach 3:1 (SC 1.4.11); at hairline-divider duty it may stay lower.

Components

A component is a folder with component.json, template.hbs and styles.css. The JSON declares the props a merchant can edit — each becomes a control in the page builder — and the regions of the page it may sit in.

Prop types

  • string
  • text
  • richtext
  • number
  • boolean
  • color
  • image
  • url
  • select
  • object
  • array

Regions

  • header
  • hero
  • main
  • sidebar
  • footer
  • floating

Slots let a component hold other components, optionally limited to certain keys and counts. Colour props reach the template as CSS custom properties scoped to the instance (--cmp-<prop>), never as inline styles, which the sanitizer removes.

{
  "key": "hero-banner",
  "regions": ["hero"],
  "props": {
    "title":   { "type": "string",  "label": { "en": "Title", "ar": "العنوان" }, "required": true },
    "image":   { "type": "image",   "label": { "en": "Image", "ar": "الصورة" } },
    "overlay": { "type": "color",   "label": { "en": "Overlay", "ar": "التظليل" } },
    "align":   { "type": "select",  "label": { "en": "Align", "ar": "المحاذاة" },
                 "options": [ { "value": "start", "label": { "en": "Start", "ar": "البداية" } },
                              { "value": "center", "label": { "en": "Centre", "ar": "الوسط" } } ] }
  },
  "slots": []
}

Templates

Handlebars with a fixed helper set and nothing else. Triple-stache, the ampersand form and raw blocks are refused because they emit unescaped HTML; partials and decorators are refused because their target is resolved at render time and cannot be checked before it runs.

Allowed helpers

  • if
  • unless
  • each
  • t
  • money
  • date
  • img
  • url
  • eq
  • ne
  • gt
  • lt
  • and
  • or
  • not
  • concat

Allowed data variables

  • @index
  • @key
  • @first
  • @last

Refused by name

  • with
  • log
  • lookup
  • blockHelperMissing
  • helperMissing

Stylesheets

Your CSS is sanitized and scoped to the component instance before it is stored. Imports, expression(), behavior and -moz-binding are removed; url() may point only at a data image or at an origin the manifest declares; position: fixed becomes absolute so a component cannot cover the checkout.

Use logical properties. padding-inline and margin-inline-start are correct in Arabic and English from one rule; padding-left is correct in one of them.

JavaScript

Declaring capabilities.customJs sends the release to a human reviewer, always. The script runs inside an iframe on a separate origin with no access to the storefront: no cookies, no storage, no parent document. It reaches the page only through a closed set of DOM intents addressed at data-ref names your own template declared.

From draft to storefront

A release you submit becomes submitted, is scanned automatically, then moves to in review. A reviewer approves it or rejects it with reasons you read on the theme page. Approval and publication are separate acts with separate permissions, so an approved release still waits to be put in front of merchants.

Why releases are rejected

The automatic scan refuses a release with a code; the code is shown on your theme page. These are the ones developers meet most, and what to change.

TOKENS_MODE_KEY_MISMATCH
light.json and dark.json define different keys. Define every key in both files.
TOKENS_CONTRAST_FAIL
A required colour pair is below its minimum in one mode. The table above lists each pair; fix the darker or lighter side.
MANIFEST_SCHEMA
A manifest field is missing, misspelt or of the wrong type. The message names the field.
MANIFEST_PLATFORM_LOCALE_MISSING
Arabic or English is missing from supportedLocales.
HB_TRIPLE_STACHE
A template uses {{{ }}}, which prints unescaped HTML. Use {{ }} and the provided helpers.
HB_UNKNOWN_HELPER
A template calls a helper outside the allowed list. Use one from the list above.
CSS_URL_HOST
A url() points at a host the manifest does not declare. Declare it under capabilities, or embed the image.
CSS_POSITION_FIXED
position: fixed is rewritten to absolute so nothing can cover checkout. Lay the component out without it.
JS_STORAGE
The script touches localStorage or sessionStorage. Theme scripts get no storage; keep state in the page.
CHECKSUM_UNSAFE_PATH
A file path leaves the package (../ or an absolute path). Keep every file inside the theme folder.

What a reviewer sends back

  • Fewer than three screenshots, or screenshots that do not show the theme as submitted.
  • Arabic layout broken: text running the wrong way, icons not mirrored, or padding on the wrong side.
  • Pages that break with no menu, no photos or no reviews — a new restaurant has all three.
  • A page type without a layout, so the installer falls back to the platform default for it.
  • Fonts, images or code included without a licence that allows it.

Versions

Semver, and release notes from the second release on. A patch reaches merchants who opted into automatic updates; a minor or major waits for each merchant to accept it. Withdrawing a release stops new installs without breaking the stores already running it.

The command line

This studio and theme-cli run the same validators against the same package format, so a theme that passes here passes there. The CLI is what you want for a repository, a pipeline and a signed .rtheme archive; the studio is what you want for a palette and a preview.

Limits

Manifest
64 KiB
Template
128 KiB
Stylesheet
256 KiB
Script
128 KiB
Screenshots
3 to 12