Local Assets

Local Assets

Instead of embedding images and fonts as data: URIs inside theme.css, you may drop them in an assets/ folder next to your theme and reference them relatively:

[data-theme='<id>'] {
  --sidebar-logo: url("assets/logo.svg");
}

Rules enforced by CI

• Paths must resolve under assets/ only — no leading /, no .., no backslashes, no remote URLs.
• Allowed file types: .webp .png .jpg .jpeg .gif .avif .svg .woff2 .woff.
• Budgets: 1 MB per file, 4 MB per theme, 32 files max. A total over 1.5 MB produces a warning (not a hard failure) so you're nudged to keep things light.
• SVGs are scanned for <script>, inline on…= event handlers, <foreignObject>, javascript:, and external references — any of these gets the file rejected.
• Ship only files your CSS actually references. Unreferenced files in assets/ produce a warning.

Versioning implications

Assets need a supporting app build, so set manifest.minAppVersion to 1.51.0 or later if you use assets. Just like editing theme.css, any change under assets/ requires a version bump in manifest.json — see Registry & Versioning.

Why this exists at all

The alternative — inlining everything as data: URIs — works fine for small SVGs (that's how --select-arrow works, for example) but gets unwieldy fast for anything larger, and there's a hard 256 KB cap on theme.css itself. assets/ exists for themes that need a real image or a custom font without blowing that budget.

See Validator & CI for how this fits into the rest of the safety floor, and Theme-Anatomy for where assets/ sits in the folder layout.