Building a reusable theme

A reusable theme packages your site's colors, typography, spacing, navigation and footer styling, and page presentation into a file you can use across Cedros sites. You can upload it to a site's theme library, preview it on real content, and apply it when it is ready.

A theme changes presentation. It does not create pages, add navigation links, run React components, or provide server-side behavior. For those needs, see Choosing between a custom page, theme, and extension.

Start with the authoring kit

Download the theme authoring kit and unpack it into your project. Read AUTHORING-KIT.json for its version and compatibility information, then open docs/theme-authoring/README.md.

Use the kit's 13 · Worked Example as your starting point. It contains a complete manifest; keep its required structure while changing the identity, design, and assets. The example is written as TypeScript, so convert the manifest object to valid JSON for upload. A .json file cannot contain imports, type annotations, comments, or trailing commas.

Keep the source and released files in version control. For an existing theme, start from its current manifest and retain a copy of the version the site is using before you make changes.

Write a short design brief: who the site serves, the reading density, heading and body fonts, light and dark palettes, and any differences between home, article, and custom-page layouts. Design both color modes together.

Build a complete manifest

The theme manifest uses kind: "cedros-theme" and schemaVersion: 1. Give it a unique theme.id, a readable theme.label, and a release version in theme.version. Use an ID such as acme-editorial; do not reuse the built-in IDs minimalist, editorial, product, or commerce.

Keep the same ID for updates to the same theme. Give a separate design its own ID: importing an existing ID updates that saved library entry rather than creating another theme.

The main design fields are:

Field	What to put there
tokens	Color palettes, typography, spacing, radii, shadows, and container sizes.
shell and routeSurfaces	Site chrome and presentation choices for supported page types, including the authoredPage surface.
blockVariants	Supported visual treatments for core and extension blocks.
brandKit	Brand guidance and asset references that travel with the theme.
assets.fonts	Font sources and any ordered format fallbacks.

Portable themes use mode: "light" with complete light and dark palettes in tokens.colors and tokens.darkColors. This does not force visitors to stay in light mode. Both palettes support the site's light, dark, and system appearance choices. Each palette needs all 12 color entries listed in the kit's 05 · Design Tokens reference.

Include a complete brand kit: a summary, audience, voice, visual direction, logo guidance, assistant guidance, at least one personality keyword, and at least one brand asset URL. Replace the example's brand text and image paths with your own. The guidance is descriptive information; including it does not run an AI service.

Use the exact fields and values in the kit's 04–09 references. Unknown fields are rejected. For block variants, choose a documented treatment: a new name can pass structural validation without having any styling behind it.

Portable themes follow the declarative, routine-safe contract. They can include fonts, but cannot include customCss or assets.stylesheets. If a page needs custom markup or interactions, use Building a custom page and let that page inherit the theme.

Package the theme and its assets

For the site library, save a .json file containing the portable package envelope. Copy the envelope from the kit’s 12 · Validation, Review, and Distribution reference. Keep its kind value and schemaVersion: 1, and place your complete theme manifest inside its manifest field. The package kind and the inner manifest kind are different; keep both at their proper level.

The site importer also accepts a bare valid manifest, but the envelope is the standard form for distributing a theme. Changing a filename's extension does not convert TypeScript or a ZIP into a valid JSON package.

Choose font sources for the way you will deliver the theme:

• JSON upload: use system font stacks or font URLs that the destination site can actually reach. A JSON file does not include font binaries, so a source such as ./fonts/display.woff2 cannot travel with it.
• Marketplace package: follow the kit's separate ZIP rules. Put the envelope in manifest.json and include referenced font files at matching package paths. The ordinary Upload theme page accepts JSON, not this ZIP.

For a reusable package, check every font, logo, icon, and preview reference on the destination site. A root-relative URL points to that site's origin; it does not copy an asset from the site where you designed the theme. Use assets you have permission to distribute, and avoid dependencies on private or temporary URLs.

Keep the package free of credentials, tracking secrets, and executable code. A theme should describe the design, not carry access to another service.

Upload and preview without applying

1. Open Appearance → Theme → Browse themes, then choose Upload theme.
2. Select your .json package and click Upload theme. If validation reports a field path and message, fix the source file and upload the corrected package.
3. Open the uploaded theme's review. Check its name, ID, and version in Advanced details, especially when you are updating an existing theme.
4. Use Preview theme to compare the candidate with the current theme, and Preview appearance to check both Light and Dark. Expand the previews to inspect full pages.
5. Review What changes when you apply and return to the catalog if you are not ready to change the site.

Uploading saves the theme for review; it does not apply it to the live site. An update to an existing ID replaces its saved library copy, so keep your previous release file for recovery.

Access to the library and permission to change settings are required. If upload or apply is unavailable, ask your administrator to review your access. For the complete owner workflow, see Choosing and applying a theme.

Validation confirms that the package follows the accepted contract. It does not prove that the design is readable, that external assets load, or that every chosen variant looks right.

Review the design on real content

Check a home page, a docs article, a blog post, and a page built with page blocks. Include extension content that your target site uses. Look at desktop and mobile widths in both color modes.

Pay particular attention to:

• Long titles, paragraphs, tables, code examples, and sidebar navigation.
• Text contrast, links, buttons, keyboard focus, and readable font sizes.
• Font loading and fallbacks, missing images, and layout shifts.
• Navigation and footer spacing, page width, and horizontal overflow.
• Custom pages or extension blocks that may use their own fixed styling.

Use the actual Cedros preview and, where needed, a test site with representative content. A color swatch or isolated design mockup cannot show how all these pieces work together. Do not change a live site's theme just to experiment with unreviewed variants.

After a correction, validate and review the saved package again. Keep brief notes on the version, pages, screen sizes, and color modes you checked so another site owner can repeat the review.

Apply, update, and share a release

When the saved version is ready, click Apply theme in its review and confirm the change. Then open public pages and check the same representative content as a visitor. Verify that the intended theme is marked Current.

Applying changes the site's visual style while keeping its pages and content. To switch back, apply the previous theme again. If you replaced a saved theme with an update, you may need to upload the retained earlier package and apply it; a version number alone does not restore its old contents.

For each release, keep theme.id stable and increase theme.version. Share the exact reviewed package along with its version, compatible theme schema, asset requirements, and installation notes. Test it on each destination site before applying it there; installed extensions, content, and available assets can differ.

Marketplace distribution is a separate release process through Cedros Theme Manager. Follow the kit's 12 · Validation, Review, and Distribution instructions and the receiving catalog's current requirements. A valid local ZIP or a successful site upload does not mean a marketplace listing has been published.

If you manage themes through MCP, read the target site's theme library and current tool schemas first. Saving a custom theme and applying it are separate operations. Review the saved manifest and intended site before authorizing the apply action; see MCP permissions and publishing controls.