CSS Themes

CSS themes change the look without replacing the behavior of the public page. No JavaScript runs; they fit color, typography, density, borders, state styling and responsive details.

Minimal Manifest

{
  "schema": "nie-sla-theme-v1",
  "id": "example-theme",
  "name": "Example Theme",
  "version": "1.0.0",
  "type": "theme",
  "mode": "css",
  "author": "Developer",
  "description": "A restrained NIE-SLA theme.",
  "license": "MIT",
  "styles": ["theme.css"],
  "files": ["manifest.json", "theme.css"]
}

schema is the current theme-package compatibility constant; use the literal value nie-sla-theme-v1.

Field Rules

Field	Rule
id	3-49 lowercase letters, digits or hyphens; must start with a letter
version	SemVer, e.g. 1.2.0 or 2.0.0-beta.1
type	Always theme
mode	css; treated as CSS when omitted
styles	1-4 packaged .css files, loaded in array order
files	Recommended; must match every file in the ZIP exactly
preview	Optional; points to a packaged PNG/JPEG/GIF/WebP/SVG
license	Optional SPDX-style identifier, e.g. MIT, Apache-2.0
repository / homepage	Optional HTTPS URL without credentials, up to 500 characters

name and author are capped at 64 characters, description at 240 and license at 32. The system reserves IDs such as admin, api, classic, extensions, plugins and themes. Unknown fields do not become runtime capabilities, and custom fields cannot be used to request script permissions.

Scoping

Theme rules stay inside your own ID:

body[data-extension-theme="example-theme"] {
  --bg: #f5f8f7;
  --paper: #ffffff;
  --text: #13201e;
  --muted: #64736f;
  --line: #d7e0dd;
  --green: #087d71;
  --red: #d9503f;
  --yellow: #b7791f;
  --blue: #2563a8;
  --radius: 6px;
  --shadow: 0 10px 28px rgba(17, 39, 35, 0.08);
}

Override the host public variables instead of relying on deep nth-child selectors, generated classes or the current DOM depth. A theme update should not require users to change production frontend source.

Styles may reference packaged fonts and images; remote URLs are subject to the site CSP and supply-chain policy, so real packages should be self-contained.

Design and Accessibility

• Body and background contrast meets WCAG AA.
• State is not conveyed by color alone; keep text or shape differences.
• Do not hide errors, focus, status notes or critical controls.
• Keep a clear :focus-visible.
• Respect prefers-reduced-motion.
• Fonts have local fallbacks.
• No horizontal overflow at 320, 375, 768, 1280 and 1440 pixel widths.
• Long VPS names, merchants, cities, lines and labels do not cover adjacent information.

Package Layout

manifest.json
theme.css
assets/
  display.woff2
preview.webp

The manifest sits at the ZIP root; do not wrap it in an extra project folder. CSS relative resource paths stay inside the package and do not depend on a CDN or a dev server. Runtime packages do not accept extensionless LICENSE/NOTICE or Markdown; keep the full license in the source repository and Release page, and use the manifest license field in the ZIP.

Versioning

• Color or layout defect fixes: PATCH.
• Additional compatible styles and new optional capabilities: MINOR.
• Changed existing UI semantics or new host structure requirements: MAJOR.

Before enabling, test at least install, disabled-by-default, enable, disable, same-ID upgrade and deletion.

Local Checks

find dist -type f -print | LC_ALL=C sort
(cd dist && zip -X -r ../release/example-theme-1.0.0.zip .)
shasum -a 256 release/example-theme-1.0.0.zip

Uploading a new version with the same ID removes the old revision and keeps it disabled; this is not an in-place hot swap. Validate on a test deployment first, then have an administrator verify the SHA-256 before enabling.