What a theme is on Lidarc
Lidarc has three layers. The foundation is the technology all themes share. A theme is a design family on top of it: typography, shapes, spacing and how each block looks. A template is a ready starting point on a theme, with a look, sample pages and copy for one kind of business.
Customers see templates and blocks. Agents and the page builder work with block types and fields, and those are the same in every theme. So there is one rule for you as a theme maker: your theme draws the shared blocks, it never renames them.
Two themes run on the foundation today: Luna (the default) and Orbit. A website switches between them and keeps every page, every post, its header and its footer.
What the foundation defines
Block types. Every theme draws all 15 shared types. Field names follow the block library: title, subtitle, eyebrow, buttons as primary_label and primary_href, lists in items.
| Type | For |
|---|---|
hero |
The top of a page |
features |
Services or benefits in a grid |
split |
Text next to an image |
steps |
A process in steps |
stats |
Key figures |
logos |
Customers, partners |
testimonials |
Customer quotes |
quote |
One large quote |
pricing |
Plans with prices |
faq |
Questions and answers |
cta |
A call to action |
contact |
Ways to get in touch |
text |
Long text (also for the legal notice and privacy policy) |
image |
One large photo |
posts |
The newest blog posts |
Each type has exactly the same fields and select options in every theme. EmDash checks blocks strictly against the active theme when it renders: a field one theme knows and another does not breaks the render after a switch. If your theme needs a field that does not exist yet, propose it for the foundation, and every theme gets it.
Header and footer are blocks (site_header, site_footer) in the collection “Header and footer”. Their fields are the same in all themes. Customers pick a style, and your theme draws the ones it supports:
- Header: floating, bar, plain, centred.
- Footer: columns, plain, centred.
Styles your theme does not know are drawn in its default form.
Blog. Posts live at /blog/<slug>, the overview at /blog, topics at /blog/thema/<slug>. The fields are title, excerpt, featured_image and content.
Language. Fixed words such as “Skip to content”, “All rights reserved” or “Read more” come from the website’s language, never hard-coded in the theme.
Design. Colours, fonts, radius and style reach every page as design tokens (--ed-primary, --ed-radius …). A look changes all of them at once. Your theme binds its own variables to these tokens instead of inventing its own colour pickers.
What you do not build: placeholders for business details ({{phone}}, {{hours}}), data for search engines (schema.org), the blocks of the library and input validation. Lidarc does that for every theme.
A theme package
A theme is an Astro theme for EmDash, built into a package that renders in the browser:
| File | Contents |
|---|---|
theme.json |
Name, version, schema (collections, block types), design options, token mapping, sample content |
renderer/entry.mjs |
The theme and the EmDash runtime as a browser bundle |
client/… |
CSS, scripts, fonts and images of the pages |
preview.png |
Store preview, 1280 × 800 |
The canister does not render. When someone publishes, the browser renders every page with your theme, and the canister then serves finished HTML.
Step by step
- An Astro theme for EmDash. Start from an EmDash template or bring an existing Astro theme. Your changes go into an overlay next to the original, so upstream updates stay possible.
- Schema from the foundation. Your seed script takes over the shared types with their fields and the migration table for older names (
blocks.add), plus header and footer (frame.add). - Layout. Your layout reads header and footer from their blocks (
loadFrame) and takes fixed words fromwords(). - Draw the blocks. Each shared type gets a component. If your theme uses its own field names, a table translates them while drawing (
blocks-legacy.json); the data keeps the shared names. - Bind the design tokens.
theme.json → tokenssays which variable of your theme stands behind which token. Design options get their role (brand,bg,fontHeading,fontBody…) so looks apply. - Build. The theme kit turns the Astro project into the browser package.
- Check.
node scripts/check-theme.mjs <package>must pass without errors (next section). - Submit to the store, see below.
Rules
- No block types of your own. What only your theme can do becomes a block in the library, and then it runs in every theme.
- No requests to third parties: fonts, scripts and images come from the website itself. No analytics, no CDN.
- Light and dark: colours as pairs (
light-dark()), readable in both modes. - Everything that comes from content is escaped. Links only with
/,https://,mailto:,tel:or#. - No network while rendering: everything a page needs is in the seed or in the package.
- Keep the package small. For comparison: Luna is 1.3 MB compressed.
The acceptance check
scripts/check-theme.mjs checks a built package before it goes to the store:
- all 15 types, each with exactly the shared fields and options, no types of its own
- header and footer as blocks, collection “Header and footer”
- pages at
/{slug}, blog at/blog/{slug}, topic taxonomy - migration table: older names point to shared types
- design tokens bound, design options with a role
- package size, preview image
- no fonts, scripts or trackers from third parties
What a script cannot see we check in the browser when you submit: every block in every look, light and dark, without contrast or overflow errors, and a theme switch there and back.
Submitting to the store
Theme makers upload their packages to the store with a key of their own. A new package is “in review” and is not delivered until Lidarc approves it. You submit updates with a higher version number, and websites using your theme are offered the update.
Blocks instead of themes: if you want to build a single section, such as a price calculator or a gallery, build a block (React or Svelte). It reads only design tokens and runs in every theme.
Status in the pilot
Lidarc is in its pilot. The theme kit, the foundation (blocks.py, types.json, frame) and the check will be published with the open core under AGPL after the pilot. Until then developers get them through pilot access: tell us which theme you want to build.