themes
Theme Check and CSS policy
What Theme Check validates, how findings are reported, and the CSS rules every theme stylesheet must follow.
Theme Check runs when you run saas theme check locally (a quick pre-flight), when you push a version (authoritative) and again during automated review. Each finding has a rule id, a file, a path, a message and a severity. Errors block the version; warnings are shown to you and to the reviewer.
Rule families
| Prefix | What it covers |
|---|---|
package.* | Safe extraction: allowed paths and file types, sizes, compression ratio, encryption, duplicate or special entries, JSON syntax and size |
manifest.* | theme.json keys, id, version, locales, Arabic and right-to-left support, platform compatibility, templates, migrations |
schema.* | Setting definitions: ids, types, labels, defaults, ranges and select options |
check.section.*, check.block.* | Schemas, primitives, placement, block counts and containers |
check.dynamic_source.* | Dynamic source names, types and template availability |
check.locale.* | Missing locale files and strings; a missing translation is a warning |
check.asset.*, check.template.*, check.reference.* | References to files, templates and blocks that do not exist |
tree.* | Template trees: node ids, nesting depth, block rules and limits |
CSS policy
Your CSS is compiled before it is stored:
- Every selector is scoped under your theme's root,
[data-saas-theme="…"].:root,htmlandbodymap to that root. - Allowed at-rules are
@media,@supports,@font-face,@keyframesand@container.@importand other statement at-rules are rejected. Keyframe names are namespaced. url()must point to a file in your package. It is rewritten to a content-addressed asset URL; external URLs are rejected.position: fixedis dropped, because it could cover platform UI.- Expressions, legacy behaviours and script-like values are rejected.
- The compiled CSS may be up to 256 KB.
Rendered review
After Theme Check passes, the platform renders every template of your theme on a fixture catalogue in three states — empty (no products or categories), typical, and stress (long names, long descriptions, no images, many products) — in Arabic and English. Nothing from your package runs: the platform renderer draws your declarative sections and blocks. The same review runs on push, on saas theme dev and on submission.
| Rule | Severity | Meaning |
|---|---|---|
review.render.section_failed | error | A section or block fails to render in some state or language; customers would see it missing |
review.render.template_failed | error | A whole template fails to render |
review.a11y.image_alt | warning | Images render without a text alternative |
review.a11y.link_name | warning | Links have no accessible name |
review.a11y.contrast | warning | Default text/background contrast is below 4.5:1, or accent/background below 3:1 |
review.rtl.physical_property | warning | Physical left/right CSS that does not mirror in Arabic; use logical properties |
review.perf.html_size | warning | A rendered page is over 300 KB |
review.perf.css_size | warning | Compiled CSS is over 100 KB |
review.perf.image_size | warning | An image asset is over 1 MB |
review.perf.assets_size | warning | All assets together are over 8 MB |
review.perf.font_count | warning | More than four font files |
Render errors block the version (theme_render_failed); warnings are shown to you and to the reviewer. Preview the same states yourself in your development store (see CLI, review and release).
Fixing findings
Fix every error and push again; the platform never partially accepts a package. If a finding looks wrong, include the rule id and file when you contact support.