Theme Submission Process

Submitting a theme follows the same CLI flow as plugins. Build a tarball with velocms build, then push the draft with velocms publish. The review pipeline runs visual checks in a sandbox tenant, measures Lighthouse scores, and flags accessibility violations before a human reviewer looks at it.

Required assets

The automated stage will soft-reject themes without both of these in the package:

  • preview/thumbnail.png — 400×300 px, shows the blog index view with sample content. No placeholder lorem ipsum visible.
  • preview/screenshot-1.png — 1440×900 px full-page screenshot of the blog index. Additional screenshots welcome.

Take screenshots with real content, not the scaffold placeholder. Use a local VeloCMS tenant with three or four sample posts. The thumbnail is what appears in the themes gallery — it's the first thing a potential customer sees.

Review criteria

Human reviewers check these in order. Failing the first two is a hard reject; the rest are soft rejects with a note explaining what to fix.

  • Lighthouse Performance ≥ 80 — tested on a 4G throttled connection. Themes that import large fonts without font-display: swap or ship unoptimized images regularly fail this.
  • WCAG AA contrast — body text must have ≥ 4.5:1 contrast against the background. Large text ≥ 3:1.
  • Semantic HTML — one <h1> per page, no skipped heading levels, dates wrapped in <time datetime="...">.
  • Mobile-first — must be usable at 375px viewport. The most common reason for a soft reject is a fixed-width layout that overflows horizontally on phones.
  • No hardcoded tenant data — blog name, bio, social links must come from props. Reviews reject themes that hardcode placeholder text in the component.

Pricing for paid themes

Declare pricing in theme.manifest.json. VeloCMS takes 20%; you keep 80%:

{
  "pricing": {
    "model": "paid",
    "price_usd": 2900
  }
}

price_usd is in cents (2900 = $29). Connect a Stripe account at /developers/stripe-connect before publishing a paid theme — the review pipeline will hold paid themes in draft until you complete onboarding.

What makes a theme stand out

The marketplace already has strong options in the minimal-dark and editorial-serif categories. Niche themes convert better. A photography portfolio theme with a masonry grid and EXIF display, a restaurant theme with a menu block and reservation call-to-action, a podcast theme with embedded audio players — these fill gaps that the generic catalog doesn't cover. Pick a niche where the design vocabulary is different from what a generic blog theme would do, and build for that use case specifically.