---
name: cedros-theme-authoring
description: Design, validate, review, package, and distribute a Cedros theme using the version-matched manifest contract.
---

# Cedros Theme Authoring

Use this public guide for presentation-only site customization. A theme changes
tokens, typography, chrome, route presentation, and block treatment. It does
not add data, routes, navigation content, React components, or behavior.

## Scope the work

For an existing theme edit, read its current manifest and the contract sections
for the changed fields, then validate and preview the affected surfaces. Reuse
unchanged version-matched kit references. A new portable theme or release needs
the complete asset and compatibility checks below; a small token edit does not
authorize marketplace packaging, import, or changing the live theme.

## Source-of-truth boundary

- This guide and the [public skill index](/skill.md) are public even while the
  main site is gated.
- The complete field catalog, examples, validators, and distribution rules are
  in the versioned **theme authoring kit** downloaded from Admin **Theme
  builder**. In a Cedros source checkout, start at
  `docs/theme-authoring/README.md`.
- Current site tools, schemas, permissions, saved themes, and selected theme
  come from the authenticated MCP registry. Follow
  [Admin Site Operator](/skills/admin-site-operator.md), then read
  `cedros://admin/areas/extensions/build-theme`.
- Do not invent a token, route surface, block key, variant, permission, or MCP
  input. Use the kit for the manifest contract and the authenticated registry
  for live operations.

## Choose an authoring path

- **Guided editor:** create and save a theme inside Theme builder, review it,
  then apply it from Appearance.
- **File-based theme:** download the versioned kit and author a portable
  `cedros-theme-library-package` JSON artifact for a site library or
  marketplace.
- **Built-in theme:** change the checked-in host theme only when contributing
  to Cedros itself; use the in-repository validation and snapshot workflow.

If the request needs behavior, use
[extension authoring](/skills/cedros-extension-authoring.md). If it needs new
page content or layout, use
[custom page authoring](/skills/cedros-custom-page-authoring.md).

## End-to-end workflow

Standalone forms inherit the active theme's colors and fonts. For a different
form composition, use **Forms → Edit → Design** or the saved definition's
`presentation` field through the live Forms MCP schema. This controls layout,
imagery, spacing, progress, and motion without a theme CSS override; it also
styles the confirmation screen. See
[Form design](/page-docs/add-edit-form.md#design). Embedded forms
retain their containing page's presentation.

1. **Capture a theme brief.** Define audience, visual direction, density,
   typography, light and dark palettes, route-specific intent, and block
   treatments. Plan light and dark together.
2. **Obtain the matching contract.** Download the kit, verify
   `AUTHORING-KIT.json`, and read its `README.md`, `01`, `03`, and `04`.
3. **Author one manifest.** A theme uses `kind: "cedros-theme"` and
   `schemaVersion: 1`. Keep identity stable. Use only the tokens, shell values,
   route surfaces, block keys, and variants enumerated by `04`-`08`.
4. **Keep content and behavior out.** Themes consume site and extension block
   contracts; they do not define routes, content, data access, permissions, or
   executable code. Use documented namespace selectors and fallbacks for
   extension blocks.
5. **Handle assets safely.** Portable themes include the required brand kit
   and portable font/preview assets described by `09`. Do not include secrets,
   tracking credentials, or mutable remote code. Routine-safe portable and
   built-in themes do not use external stylesheets or `customCss`.
6. **Validate and compile.** Use the kit's documented validator. Reject unknown
   keys, invalid colors, incomplete modes, unstable IDs, missing assets, and
   non-portable references. When no Cedros runtime is available and the user authorizes sending the artifact to that service, submit the
   final JSON or ZIP through the
   [centralized Forge authoring scan](https://cedros.ai/extensions/cedros-forge/skill.md) for a pinned
   routine-safe validation and runtime plan. A parser or scan success alone is
   not a visual pass.
7. **Review the real runtime.** Use a draft preview or test site; do not change a live site merely to test variants. Preview through Cedros, not a parallel mock
   renderer. Check light/dark, responsive widths, public chrome, all relevant
   route surfaces, core and extension blocks, focus/contrast, long content,
   missing media, and reduced motion. Compare a saved artifact, not unsaved
   editor state.
8. **Package and test.** Follow `12`. Validate the final JSON envelope and, for
   marketplace delivery, the final ZIP. Run the kit's checks plus the
   repository's targeted tests for built-in themes. Record screenshots or
   review notes for representative routes and both color modes.
9. **Import without applying.** Add the artifact to the site's theme library
   first. Saving or importing must not silently change the live site. Review
   the stored version and preview it.
10. **Publish deliberately.** Apply the exact reviewed theme only with explicit
    operator intent, then smoke test public pages and admin previews. Keep the
    prior active theme available for rollback. Marketplace review and
    deployment follow the current authenticated host/registry workflow; a
    locally valid ZIP is not proof of publication.

## Guide map in the versioned kit

| Need | Read |
| --- | --- |
| Model, quickstart, brief | `01-theming-system-overview.md` through `03-theme-brief.md` |
| Manifest and visual contract | `04-manifest-reference.md` through `09-brand-kit-assets-and-preview.md` |
| Ownership and host application | `10-theme-lifecycle-owners-and-admin.md`, `11-runtime-application-hosts.md` |
| Validation, distribution, example, fixes | `12-validation-review-and-distribution.md` through `14-troubleshooting-and-faq.md` |

Release evidence should identify the theme/package version, artifact checksum,
target host compatibility, validator and test results, reviewed routes and
color modes, import result, apply confirmation, rollback target, and actual
distribution status.