Creating or importing a custom theme

Give your site its own colors, typography, and presentation by importing a Cedros theme JSON file. You can use a file supplied by a designer or developer, or create one with the theme authoring guide.

Importing saves a theme to your library. Applying it changes the live website. An import can replace an existing library version before you apply anything, so keep the previous file when updating a design.

For logo and brand-accent changes, use Changing your logo, colors, and typography.

Choose your starting point

If a library theme already meets your needs, use Choosing and applying a theme. For a custom design, prepare a brief and ask for an importable Cedros theme file using the checklist below.

You need permission to manage themes and save settings. If the upload or apply controls are missing or disabled, see Why can’t I see or edit a feature?.

Prepare the design and preserve the current version

Before building or importing, note the currently applied theme and keep its earlier JSON file if it is a custom design. Ask its creator for a copy if you do not have one.

A useful design brief includes:

• The audience and the kind of site: for example, a studio portfolio with a journal and project enquiries.
• The desired mood, approved colors, heading and body fonts, and brand assets.
• The pages that matter most, including long articles, forms, product pages, or docs.
• How the design should work on phones and in both light and dark modes.
• What should stay recognizable from the current design.

For example: “Keep our existing logo. Use warm neutral backgrounds, dark readable body text, serif headings, and one restrained blue accent. Make long docs comfortable to read and ensure buttons remain clear on mobile and in dark mode.”

Keep a copy of the brief with the final theme. A theme controls presentation; a new booking process, payment behavior, or other application feature needs separate product or extension work.

Import a supplied theme file

Ask for an importable Cedros theme JSON file, commonly named like studio-theme.theme.json. The site's Upload theme page accepts JSON; it is not the upload path for a marketplace ZIP, a website ZIP, a screenshot, or a theme made for another platform.

Before selecting the file, ask whether it is a new theme or an update to one you already have. Uploading a file with the same theme ID replaces that saved library entry. A different filename, display name, or version number does not by itself create a separate entry. If you want to keep both designs, ask the creator to supply a separate theme ID.

To import:

1. Open Settings → Appearance → Theme and select Browse themes.
2. Select Upload theme.
3. Click Drop a theme file here or its Upload theme control to browse, or drop the JSON file onto the upload area.
4. Wait while Cedros reads, validates, and saves the file. Selecting or dropping it starts the import immediately.
5. Check any error shown on the page. A successful import opens the theme for review.
6. Review the theme name and, under Advanced details, its ID and version before considering application.

If the uploader stays open or reports an error, do not rely on a brief upload notification alone. Confirm that the expected theme actually appears in the library and opens for review.

Importing stores the theme; it does not apply it. An updated version of your current theme can appear as Saved update while visitors continue seeing the previously applied design.

What validation checks mean

Cedros checks whether the file follows the supported theme format. A valid JSON file can still be an invalid Cedros theme.

Common rejection reasons include an incompatible format or schema version, missing required brand guidance, invalid color or typography values, a custom theme using a reserved built-in theme ID, or unsupported CSS declarations.

Send the exact validation message to the theme's creator and ask for a corrected site-library file. Do not rename a ZIP to .json or remove required fields just to get past an error.

A compatibility message confirms that Cedros accepts the theme definition. It does not confirm readable contrast, good mobile layout, working font URLs, or a satisfactory result on your content. Those need a visual check.

Work with a designer or your own code editor

For a site-specific handoff, ask for:

• A validated JSON theme ready for Upload theme.
• The theme's name, ID, and version, with a clear statement of whether it replaces an existing library entry.
• Both light and dark palettes and the intended heading/body font assignments.
• Any required font or image files, where they will be hosted, and confirmation that they can be used on your site.
• Screenshots or review notes covering the homepage, a normal page, a blog post, and docs where relevant.
• The previous working theme file and a short explanation of what changed.

A JSON download is not a backup of every asset it references. When moving a theme between sites, have the creator check the referenced font and image URLs. Files that exist only on the original site or the creator's computer may need to be supplied and hosted for the destination site.

For developers, Building a reusable theme links to the authoring kit and explains how to create, validate, and package the design. Request the site-library JSON file for this upload flow; marketplace distribution uses a separate package.

Review, apply, and verify the theme

Open the saved theme through Browse themes. Compare it with the current design using Preview theme, and inspect both Light and Dark under Preview appearance.

Check the available Home, Docs, Blog, and page previews. Distinguish actual published content from sample content: samples help you judge a layout, but cannot verify your own long titles, images, forms, or article formatting.

Pay particular attention to:

• Readable body text, links, buttons, and form labels.
• Headings and navigation that fit on narrow screens.
• Font and image loading on a device that does not have your local design files.
• Existing page-specific styling that may differ from the theme defaults.

When the result is ready, select Apply theme, read the confirmation, and confirm Apply theme. Then inspect the public site on desktop and mobile. See Choosing and applying a theme for the full comparison, application, and recovery walkthrough.

Keep the known-good file after applying the new version. To restore it, import the preserved version if necessary, review it, and apply it again. Replacing a saved library entry is not undone simply by closing the review.

Fix common creation and import problems

The file is rejected. Confirm that it is a Cedros theme JSON file, read the validation message, and ask its creator for a corrected export. Keep the original file and error for comparison.

The theme saved, but the site did not change. Open the saved theme for review and apply it. Uploading alone does not change the live design.

My earlier library version disappeared. The new file may have reused its theme ID. Ask the creator for the previous JSON file or use the copy you retained. Check which version is live before importing and applying a replacement.

Fonts or images are missing after import. Ask the creator to check the referenced files on the destination site. Test the corrected design on a device that does not have those assets installed locally.

The upload failed or the new theme is absent from the library. Keep the JSON file, note the exact error, and check your access and connection. Confirm whether the theme was saved before uploading it again.

If you need help, include the theme name and version, exact error, and affected public page address when contacting support.