Build for Baseet

Baseet is an Arabic-first commerce platform for MENA. This is where you learn to build on it — starting with storefront themes, and soon apps and the API.

What you can build today

• Themes — complete storefront designs, expressed as data, not code, rendered by one trusted engine. Available
• Apps & the public API — extend a store's functionality and data. Coming

A theme you publish can be installed by any Baseet merchant. You keep the majority of every sale (70/30 in your favor).

Quickstart

Scaffold, design, preview, and submit a theme — the whole loop — in about ten minutes.

1 · Get your key

The Baseet team issues you a scoped developer key (bth_live_…). It's the only credential you need, and it only authorizes submitting your own themes. Sign in at developers.baseet.dev and keep it somewhere safe — treat it like a password.

2 · Scaffold a theme

From a Baseet workspace checkout:

# creates the two DATA files + auto-registers the theme
npm run theme -- init my-theme --name-en "My Theme" --name-ar "ثيمي" --industry fashion

That's it — no React, no build config. You now have a manifest and a preset to edit.

3 · Make it yours

Edit the two generated files — the preset (design tokens + starter content) and the manifest (which sections, in what order). Point a demo store's theme_id at your id to see it live, then validate:

npm run theme -- validate my-theme

4 · Submit for review

export BASEET_THEME_KEY=bth_live_…
npm run theme -- submit my-theme --changelog "First release"

Your version lands as Pending and appears on your dashboard. The Baseet team reviews it, then publishes it or returns notes. Once published, it renders live for merchants with no deploy.

Core concepts

A few ideas explain every decision on the platform. Learn these and the rest follows.

Data, not code

A Baseet theme ships no executable code. It's a manifest (structure) plus a preset of design tokens (look). One trusted renderer turns that data into a storefront. This is the platform's core safety property: the least-privileged thing you can build is a theme, so themes are safe to install, review, and run at scale — and a theme can go live without a code deploy.

Two planes

They're deliberately separate: a product change can never break a contract you built against.

Stable contracts

Everything you depend on — the theme manifest schema, the CLI, and (soon) the API and webhooks — is a versioned contract. Changes are additive by default; anything removed is deprecated on a published schedule with a migration guide. See Versioning & stability.

Least-privilege credentials

Your key is scoped to exactly one capability and nothing else. It can't reach billing, other developers' themes, or any other data. A leaked key's worst case is "a theme that gets rejected in review." See Security.

Theme anatomy

A theme is exactly two files of data, plus the one engine that renders them.

The manifest — structure

Declares the theme's identity and its ordered list of sections (hero, categories, featured products, testimonials, …), each with a layout variant and animation. The manifest defines availability + order; every section still gates on the merchant's own store config at render time.

export const MyThemeManifest = {
  id: 'my-theme',
  name: { en: 'My Theme', ar: 'ثيمي' },
  version: '1.0.0',
  industry: 'fashion',
  directions: ['rtl', 'ltr'],
  sections: [
    { schemaId: 'hero', layoutVariant: 'split', animation: 'fadeUp' },
    { schemaId: 'categories', animation: 'fadeUp' },
    { schemaId: 'featured', animation: 'staggerCards' },
    // …reorder / remove / re-variant freely
  ],
};

The preset — look + starter content

Design tokens (colors, radii, fonts) plus demo hero/benefits content. The theme's entire visual language lives in tokenOverrides.

export const MY_THEME_PRESET = {
  id: 'my-theme', themeId: 'my-theme',
  accentColor: '#1C1917',
  tokenOverrides: {
    '--color-background': '#FAFAF9',
    '--color-accent': '#1C1917',
    '--radius-card': '14px',
    '--font-display': "'Fraunces', serif",
    '--font-body': "'Manrope', 'IBM Plex Sans Arabic', sans-serif",
  },
  homeContent: { /* demo hero, benefits, … */ },
};

The engine — one renderer for every theme

The storefront engine reads your manifest + tokens and dispatches each section to the shared component registry. You never write render code — which is why a new theme is a manifest + a preset, and nothing else.

Authoring guide

The end-to-end process for building a theme that's distinct, correct, and publishable.

Step 1 — Brief before pixels

Write one page: target merchant (fashion / food / beauty / electronics / home), three real-brand inspirations (not other themes), a one-sentence intent, and your density × shape × tone choice. A theme that doesn't move at least two of those axes vs. existing themes is "minor variant noise."

Step 2 — Tokens before layout

Design the token map first — color roles, radius scale, shadow vocabulary, and the type pair (verify it covers Latin + Arabic + numerals). The shadow scale is often the most differentiating dimension: sharp themes have none, soft themes layer them.

Step 3 — Compose sections

Pick the section order and variants in the manifest. There's no new code — choosing the right defaults per section is the only decision. Alternate section weights so the page has rhythm; never place two hero-weight sections back to back.

Step 4 — Validate & preview

Run npm run theme -- validate and view it on a demo store in both EN/LTR and AR/RTL, mobile and desktop. See Testing & preview.

Step 5 — Pass the design bar, then submit

Score against the design bar (anti-AI checklist ≤ 2 hits), then submit.

Sections & tokens

The building blocks you compose, and the token vocabulary that colors them.

Sections

Each manifest entry references a schemaId. The engine renders it from the merchant's store data. Common sections:

Design tokens

Sections read CSS variables, never raw colors — so your preset's tokens re-skin every section at once. Token names are roles, not adjectives (--color-accent, not --color-blue). Core roles:

• Color — --color-background, --color-surface, --color-on-surface, --color-accent, --color-on-accent, --color-muted, status roles.
• Radius — --radius-card, --radius-button, --radius-input.
• Type — --font-display, --font-body, and always an Arabic-capable stack.

The design bar

Every theme must clear this standard before it publishes. It's what keeps the marketplace worth browsing.

Engineering rules (must)

• Never hardcode a color, radius, or shadow in a section — read a token.
• A theme is data, never React. If you want to write JSX, you've found a missing section, not a theme.
• Every theme ships every token the schema requires.
• Token names are roles, not adjectives.

Design rules (the taste bar)

• A distinct design language across all surfaces — home, product, checkout, profile, empty/error states — not "the home page styled."
• One icon family, one stroke weight, one fill style.
• Mobile and desktop are equal first-class targets; touch targets ≥ 44px.
• WCAG AA contrast (4.5:1 body); focus rings always visible; color never the only signal.

The anti-AI checklist — block at 3+ hits

Score your theme against these; three or more and it won't pass review:

1. Indigo/purple gradient as the primary accent.
2. 3D blobs or floating geometric shapes in the hero.
3. Sparkle / wand / star icons in a storefront section.
4. "Get Started Free →" or "Modern. Fast. Beautiful." copy.
5. Cards rotated "for energy."
6. Every card using the same hover:-translate-y-1 hover:shadow-2xl.
7. Tailwind default slate greys as the only surface tone.
8. Aurora / mesh-gradient backgrounds without purpose.
9. Glassmorphism as the default surface.
10. Stock Unsplash placeholder photography.

RTL & Arabic

Baseet is Arabic-first. RTL is a first-class design target, not a mirror of the LTR version.

• Design in EN (LTR) and AR (RTL) simultaneously — flipping later reliably breaks layouts.
• Ship --font-arabic separately — a Latin font's fallback silently covers Arabic with the wrong glyphs. Lead Arabic stacks with the Arabic font.
• Arabic body copy usually needs +0.1–0.2 line-height vs. Latin.
• Directional icons (chevrons, arrows) flip automatically; brand and object icons must not.
• Numerals, prices, phone numbers, SKUs, and codes stay LTR inside RTL text.
• Use logical CSS (padding-inline-start, not padding-left). Note: logical props resolve per-element direction — inside a dir="ltr" island (a price, a phone input) they don't flip with the page.

Testing & preview

Prove the theme works before you submit — the review is faster when you've already checked.

Validate

npm run theme -- validate my-theme

Checks bilingual names, RTL support, that every section resolves in the schema, known field types, and that your preset and manifest are wired consistently.

Preview on a demo store

Point a demo store's theme_id at your theme id and open it. Check, in this order: home, product listing, product detail (with several sections on), cart, checkout, thank-you, profile, and the empty / error / loading states — each in EN + AR, mobile + desktop.

The pre-submit checklist

• Header/footer identical on every page.
• Same button, input, and modal style everywhere.
• Long product page has rhythm (alternating section weights).
• Empty states are designed, not blank.
• Anti-AI checklist ≤ 2 hits.

Submit & review

How a theme goes from your machine to the review queue, and what reviewers look for.

Submitting

export BASEET_THEME_KEY=bth_live_…
npm run theme -- submit my-theme --changelog "what changed"

The CLI validates locally first, then submits the manifest + tokens to Baseet over an authenticated, scoped-key endpoint. The version lands as Pending and shows on your dashboard. Each release is an immutable version — to iterate, bump the semver and resubmit.

What review checks

• Design quality — the design bar (distinct language, anti-AI ≤ 2).
• RTL / Arabic correctness — native-feeling in both directions.
• Accessibility — contrast, focus, touch targets.

Outcomes

A reviewer approves (→ ready to publish), requests changes (with specific notes on your dashboard — fix and resubmit a new version), or rejects. You see every decision and note in the Theme detail view.

Publishing

What happens when your theme goes live — and the promise that comes with it.

Once a reviewer publishes an approved version, it enters the Baseet theme library and any merchant can install it. Because a theme is data, publishing takes effect with no deploy — the storefront engine picks it up from the registry.

Lifecycle states

Your dashboard shows install/usage analytics per theme so you can see your reach.

Versioning a theme

Ship improvements without breaking merchants already using your theme.

• Every submission carries a semver (x.y.z) and is immutable once submitted.
• Patch (1.0.1) — safe, additive fixes.
• Minor (1.1.0) — new sections/options, backwards-compatible.
• Major (2.0.0) — a redesign that changes the look meaningfully; treat it as a distinct offering so merchants opt in deliberately.

The manifest also declares the schema version it targets. Baseet keeps published themes rendering across schema changes; when a required capability changes, you'll get a deprecation window and a migration note — see Versioning & stability.

CLI reference

The theme developer kit. One tool: scaffold, validate, list, submit.

init <id>

Scaffolds the manifest + preset for a new engine theme and auto-registers it.

npm run theme -- init <id> [--name-en X] [--name-ar X] [--industry fashion] [--accent #hex]

validate [<id>]

Runs the acceptance gate: bilingual names, RTL, sections resolve, field types, preset/manifest consistency. Add --all to validate every theme.

npm run theme -- validate <id>

list

Lists every registered theme and whether it's engine-enabled.

npm run theme -- list

submit <id>

Validates locally, then submits the theme for review. Requires your key.

export BASEET_THEME_KEY=bth_live_…
npm run theme -- submit <id> [--changelog "…"]

Sections & fields reference

The complete section vocabulary the engine renders — generated from the code (SECTION_SCHEMA), so it can never drift from what actually ships.

Versioning & stability

The promise that lets you build on Baseet without fear of it moving under you.

• Additive by default. New capability = a new field / option / version. Existing fields don't change meaning or disappear inside a version.
• Deprecation is scheduled, never silent. Anything going away is announced on the changelog with a migration guide and a support window (target: ≥ 12 months) before removal.
• Contracts are versioned. The theme manifest schema, the CLI, and — soon — the public API and webhooks each carry a version you can pin against.
• Calendar versioning for the platform API (dated, e.g. 2026-07): a version you adopt never changes underneath you.

Security

The model that makes building on Baseet safe for you and for merchants.

Your key

• Scoped to one capability (submit your own themes) — nothing else. It cannot reach billing, tenants, or other developers' data.
• Stored hashed — the raw value is shown once. Rotate or revoke it any time from the dashboard.
• A leaked key's worst case is a theme that gets rejected in review.

Why data-not-code is a security feature

A theme carries no executable code and no secrets — it's the least-privileged thing on the platform. That's what lets Baseet review, install, and run third-party themes across thousands of stores with confidence.

Your responsibilities

• Never commit or expose your key.
• Never ship placeholder secrets or third-party tokens inside a theme.
• Report anything that looks like a way to exceed a theme's privileges.

Changelog

Every change to the developer platform, dated and categorized. This page is a contract — nothing changes without appearing here.

2026-07 · Developer platform — early access

• Added — the theme marketplace: scoped developer keys, CLI submit, the review queue, and publish-with-no-deploy.
• Added — the developer dashboard at developers.baseet.dev.
• Added — these docs at docs.baseet.dev.

Roadmap

What we're building, roughly in order. Directional, not a commitment on dates.

Now

• Theme platform to GA — the developer dashboard, submission, review, and publish loop.

Next

• Generated reference — manifest, section, and CLI reference generated from the code schemas so they can't drift.
• The public API — a versioned REST API + a typed SDK, designed so the same schema powers the SDK and AI/MCP tools.
• Webhooks — a signed, versioned event contract.

Later

• Apps & extensions · a partner program · earnings statements & payouts.