The stylesheet layers of a Kywi project
Three stylesheet layers stack in an order Next decides rather than the order your layout imports them: core’s sheet, yours, and per-request tokens.
Three stylesheet layers paint a public Kywi page: the theme's per-request token block, core's site stylesheet, and your project's stylesheet. A fourth thing sits beside them but is not a layer in the same sense — inline styles resolved on individual sections, which apply after all three regardless of bundle order. Of the three, only the token block is rendered by core; the other two are bundled together by Next, in an order that is not the one your layout writes.
Both stylesheets are imported from your file
Core imports no CSS at all. Next admits a global stylesheet only from a file inside the app directory, and a published package cannot reach into your project to import yours — so the generated layout keeps both import lines, and they are the only two lines in it that are not wiring.
import { createSiteLayout } from '@kywi-software/core/next'
import '@kywi-software/core/site/styles.css'
import './site.css'
import { kywi } from '../../lib/kywi'
import { layers } from '../../kywi.layers'
const layout = createSiteLayout({ runtime: kywi, layers })
export default layout.default
export const dynamic = 'force-dynamic'Specificity, not order
In dev, Next bundles both sheets into a single app/(site)/layout.css and emits your file first, core's second — the reverse of the import order above. A production build's CSS chunking can split the two into separate files instead of one; either way, the ordering an override can rely on is specificity, not source position. An override that merely ties core's selector loses. This is the single most expensive thing to discover by trial and error on this stack, because the failing rule looks correct and the import order looks like it should settle it.
curl -s "http://localhost:3000/_next/static/css/app/(site)/layout.css" -o layout.css
grep -bo -- "--kywi-core-css-loaded" layout.css # core's first declaration
grep -bo -- "site-shell" layout.css | head -1 # your first ruleOn this project's own 449 KB dev bundle, core's opening declaration sits at byte 395,310 — almost the whole file in. Your sheet is the front of the bundle, its own @imports included; core's is the back. Write every override to out-specify rather than to follow. A .site-shell, .site-main, .site-footer or body prefix is usually enough; core's nav rules are rooted at .kywi-nav[data-kywi-nav-variant], so an override there has to repeat that root.
What core gives you to hook onto
Core's stylesheet styles .kywi-* classes on everything it renders — the region grid, the prose body, embedded forms, and each built-in module — and every value it sets reads a --kywi-* token with a neutral fallback. Retheming through tokens is therefore always cheaper than overriding rules; reach for a rule only where the design needs something the token vocabulary does not carry. The default chrome adds .site-shell, .site-header, .site-main and .site-footer, and a templates.shell that replaces it is free to drop those names — this project's docs site does exactly that, which is why its stylesheet is scoped under .docs-shell and cannot collide with the marketing site's rules in the shared bundle.
The admin stylesheet is a copy step
The admin's sheet does not travel through the site bundle. The scaffold writes scripts/sync-kywi-admin-css.mjs and hangs it off predev and prebuild, so every dev start and every build re-copies the installed package's stylesheet to public/kywi-admin.css alongside a .version sibling. Both are generated and both are gitignored: after upgrading core, a stale admin is usually a build that never ran the sync. See Upgrading core inside your project.
site.css is yours, permanently
app/(site)/site.css is on the short list of files create-kywi-app upgrade never touches, alongside kywi.config.ts, lib/modules.tsx, components/site-nav.tsx and everything under sites/. It is unstamped and stays where it is — an earlier plan to move it into the theme folder was reversed. Everything else on the render path is regenerated, so keep project styling out of those files; see Rendering a page in coupled mode for what they now contain.