# The stylesheet layers of a Kywi project

URL: https://kywi-docs-production.up.railway.app/developing/the-stylesheet-layers-of-a-kywi-project
Type: docPage

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'

## app/(site)/layout.tsx

## 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 rule

## confirm it on your own dev server

On 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 `@import`s 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.

## A shell cannot drop the token block or the sentinel

Both render from the layout, above the shell, and a `templates.shell` is never handed either. The sentinel is a dev-only client component that checks `--kywi-core-css-loaded` after mount and logs *"@kywi-software/core/site/styles.css is not loaded; keep its import in app/(site)/layout.tsx. The public site is rendering unstyled."* If you see that in a console, the import was removed — not the bundle order.

## 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](/developing/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](/developing/rendering-a-page-in-coupled-mode/) for what they now contain.
