Assets, styling & theming

Sites are styled with Tailwind CSS driven by a themeable set of design tokens, and they host their own assets — images, documents, video — on the platform's CDN.

Styling with Tailwind

You style pages with Tailwind utility classes. The stylesheet is generated for you when you publish based on what your templates actually use, so you don't manage a build pipeline for CSS.

Theming

A site's look is driven by a theme — a design-token file defining colors, fonts, spacing, and the like. Changing the theme restyles the site consistently, which makes it easy to match a brand or reskin a site without editing every page. It's also how the AI agent keeps a site visually coherent as it builds.

Fonts

Google Fonts and Font Awesome are available, so you can use a wide range of typefaces and icons without hosting them yourself.

Assets

Static assets are hosted for you and served from the CDN:

• Immutable, cache-busted URLs — when a file changes it gets a fresh URL, so caches never serve a stale version.
• Responsive images — appropriately sized variants are generated so pages load the right image for each screen.
• Public vs. private — files under the assets area are publicly addressable by URL; anything sensitive should be a database attachment served through access control instead.

Asset URLs live on the CDN's asset domain, which is a different origin from your site — ideal for an image, a video, or a document. Code is the exception: reference a script bundle or a stylesheet by its plain path under the assets folder rather than by its asset URL, because your site serves those from its own origin, and that is what keeps the file's own imports and references resolving. Anything whose URL is itself the contract goes in the public folder instead.

Files served at a fixed path

Some files have to be reachable at one exact URL, decided by someone other than you: a search-console verification file, ads.txt, /.well-known/security.txt, a web app manifest, a service worker, your favicon.

Those go in the site's public/ folder. Each file there is served at its own path with the folder name stripped — public/favicon.ico at /favicon.ico, public/.well-known/security.txt at /.well-known/security.txt — from your site's own domain, byte for byte, and you reference it by that plain path: <link rel="icon" href="/favicon.ico">. A public file is never an asset URL, and shouldn't be turned into one.

The site's robots.txt and a hand-authored sitemap.xml are authored here too — see pages & templating.

Assets folder or public folder?

	Assets	Public
URL	its own path under the assets folder on your site, and an immutable cache-busted URL on the CDN asset domain	the file's own path, on your site's domain
Referenced by	the asset URL filter — except code, which uses its plain path	the plain path, written literally
Images	responsive variants generated automatically	untouched — exactly the bytes you published
Caching	cached by URL, so a changed file gets a new one and is never served stale	cached briefly, and refreshed when you publish
Use it for	images, video, documents, app bundles	files whose URL is the contract

Almost everything a page renders belongs in the assets folder. The public folder is for the small set of files where the path is the point — and because they're served byte-for-byte, an image there gets no resized variants. If you want a responsive image, put it in assets.

What the public folder won't accept

Any file type is publishable there — any extension, no extension at all, even a zero-byte marker file. What's restricted is the name and the resulting URL, and each of these is reported when you lint or publish rather than failing silently once live:

• Page templates — files here are served as they are, so a template would publish its own source.
• Paths the platform already answers, and paths belonging to the other publishing areas (assets, database attachments).
• Configuration files — config, theme, and chatbot files are read at publish and are never served.
• A first path segment that is a language code — locale routing owns those, so the file would be unreachable at its own URL.
• Credential-shaped names, at any depth and whatever the file type: .env files, private keys and certificates, .npmrc, .netrc, credentials, database files. The folder is world-readable at a predictable URL; a value your code needs belongs in configuration.
• Dot-prefixed paths other than /.well-known/, which is the one such subtree a site can publish into.
• A path one of your pages already serves — the page wins, so the file would never appear.

Two cases warn rather than fail: a file with no extension outside /.well-known/, since locale routing can still redirect a visitor away from its URL — give it an extension — and a public folder large enough that it looks like build output, which is what the assets folder is for.

Tailwind classes don't apply there

The stylesheet is built from your templates, not from the public folder. An HTML file you drop there is a standalone document — it doesn't pick up the site's generated stylesheet, so Tailwind classes in it render unstyled. Give such a file its own self-contained styles, or build it as a real page instead.

It's the same `public/` your bundler uses

If you build a front-end app in the project, its public/ folder and the site's are the same folder and mean the same thing: public/favicon.ico serves at /favicon.ico under vite dev and on the published site identically, with no configuration. One caveat if your bundler writes its output into the site's assets/ folder — it will also copy public/ into that output, leaving a redundant second copy under /assets/. Set publicDir: false (or your bundler's equivalent) to skip that, or ignore it.

Generated files

Two files in a site's assets — the compiled stylesheet and the client-side script bundle — are produced by the platform on every publish. Don't hand-edit them; they're regenerated each time.

Bringing your own CSS build

If your own toolchain already produces the stylesheet — most often when a site is largely a bundled single-page app — you can turn the platform's CSS build off in the site's root configuration. The stylesheet then becomes an ordinary asset that you publish exactly as your bundler wrote it, instead of being regenerated, and the theme file is no longer required. Everything else about the site is unchanged. Leave the build on for normal Liquid sites: it's what makes Tailwind classes in your templates work.