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.
- 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.
- Set the palette in both light.json and dark.json. The studio shows contrast failures as you type, before you submit anything.
- Edit or add components: a component.json describing its props, a template.hbs using the allowed helpers, and a styles.css with logical properties.
- Validate, then preview in Arabic and English, light and dark, at phone and desktop widths.
- 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.
| Foreground / background | Minimum | Why |
|---|---|---|
| foreground / background | 4.5:1 | Body copy must be legible on every surface the theme paints (SC 1.4.3). |
| foreground / surface | 4.5:1 | Body copy must be legible on every surface the theme paints (SC 1.4.3). |
| foreground / surfaceRaised | 4.5:1 | Body copy must be legible on every surface the theme paints (SC 1.4.3). |
| foregroundMuted / background | 4.5:1 | Captions, prices and helper text are still text; SC 1.4.3 does not exempt them. |
| foregroundMuted / surface | 4.5:1 | Captions, prices and helper text are still text; SC 1.4.3 does not exempt them. |
| foregroundMuted / surfaceRaised | 4.5:1 | Captions, prices and helper text are still text; SC 1.4.3 does not exempt them. |
| primary / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 | This 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 / surface | 3:1 | This 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 / background | 3:1 · warning only | Where 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 / surface | 3:1 · warning only | Where 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.
eval, the Function constructor, import(), require, WebSocket, workers, document.cookie, localStorage and anything that writes innerHTML are refused by static analysis before the script is ever stored.
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