Styling and assets
There is no build. A stylesheet is a file in assets/css/, a script a file in assets/js/, an image a file in assets/images/. You link them; the server serves them.
Linking assets
Link with a version string so browsers cache an asset exactly as long as it is unchanged:
<link rel="stylesheet" href="/assets/css/site.css?v=<?= v('/assets/css/site.css') ?>">
<script src="/assets/js/site.js?v=<?= v('/assets/js/site.js') ?>"></script>
v() is the file’s modification time: it changes when that file changes and only then, so no other asset’s cache is touched.
Icons are inline: svg('arrow-right', 'class="icon"') prints assets/icons/arrow-right.svg into the page, so it takes currentColor and scales with the text.
What may live in assets/
A fixed list, enforced wherever a file enters through the MCP. Two things are absent on purpose and cannot be added: PHP (no server-side execution in a public folder) and HTML (a page with script under the site’s origin is phishing ground under the lowest trust right). An offline page or a landing page is a template or an engine route, never a file in assets/.
SVG is allowed and guarded: a vector file may carry no script. The server is additionally advised to serve .svg with a strict content-security policy, so a directly opened SVG is inert regardless.
The whitelist, exactly
| Root | Allowed extensions | Served? |
|---|---|---|
assets/ |
jpg/jpeg, png, webp, gif, svg, ico · woff/woff2, ttf, otf, eot · mp4, webm · pdf · css, js, json |
Yes, as static files — /assets/… is served by the web server, cheap and cacheable; the engine never touches it. |
data/ |
json only |
Yes, as static files — every entity is public at its own URL (/data/<type>/<id>.json, the file; .md beside it, the reading), crawlable, and the index (/data.json) lists them. Content is public by construction; what must not be public does not go in data/. |
theme/ |
php, css, js, svg, json |
No — shells are not pages. The router refuses /theme/*, the host refuses it first; the theme’s css/js live in assets/ to be served. |
guide/ |
md only — flat, lowercase names |
No — the site’s own knowledge for agents, read through the MCP only by keys that hold guide.read. |
A new type is a deliberate rule with its own content check, never a wildcard. One spelling per file: no .., no //, no /./, no segment starting with a dot, and a target that differs only in case from the file on disk is refused — the audit compares paths as strings, so an alias would slip past it. Caps: 10 MiB per asset, 1 MiB per data or theme write (both site-configurable); a zero-byte file is refused. Bytes are judged, not names: each binary type must open with its own magic bytes; every .json must parse.
SVG anywhere is read the way a browser reads it — start and end tags, attributes, entity-decoded — and refused on a <script> or <foreignObject> in any namespace, an event-handler attribute, javascript: or vbscript: anywhere, a data: scheme (other than an image) on href, src or the like, <!ENTITY, <?xml-stylesheet, <font color|face|size>, any HTML-only element name (meta, iframe, p, xmp, … — the parser would leave the icon and read what follows as page markup), and anything after the root’s </svg>. Under assets/icons/ a <style> block may carry only presentation rules on .class or #id selectors — fill, stroke, opacity and their kin; no element selectors, no at-rules, no url() except url(#id), no layout properties, and no string that holds a newline, /*, \ or < — because svg() inlines the icon and its CSS reaches the whole page. The door refuses it; svg() strips what came in another way.
Theme code is judged at the door as well: staging returns the audit’s verdict on includes, data references, strings and the CSP rules, and php -l over the file. Publishing adds the boot smoke of the project layer — see Keys and the MCP. A draft is inert until published.
Presentation values are content
Cards and heroes read colours from data — an ImageObject’s focus, surface and ink, or an entity’s presentation block — written by whoever may write content. A shell that echoes them into style= escapes them and validates them as colours.
Scripts
A script is a file in assets/js/, loaded with <script src>. A script in the header runs before main exists, so it waits for DOMContentLoaded; a script placed after its section may run directly. Sections that need page input are included from the shell — section() passes no variables. Bind events with addEventListener in that file, not with on*= attributes in the markup.
That is all a theme needs to know; the rest is what happens when a site turns on the nonce policy (SITE_CSP with '{nonce}' — see How the engine is put together). Under it the browser runs a file script as before, refuses every inline <script> that carries no nonce, and refuses every on*= handler — silently for the visitor, loudly in the console. You will not have to remember that: publishing a theme file with either of them then returns a warning that names the fix. An inline <script> that must stay inline carries nonce="<?= e(headers_nonce()) ?>"; the attribute is the only place the nonce goes (a cache hit rewrites exactly that attribute). A <script type="application/ld+json"> is data, not execution, and needs nothing.
Loading from outside
Under SITE_CSP every host a theme loads from must be allowed in the directive that matches the resource: script-src for a script, style-src for a stylesheet, connect-src for a fetch. Images and fonts over https: are already allowed by the skeleton policy. Two routes: add the host to SITE_CSP, or put the library in assets/ so it is 'self' and the policy stays tight — prefer the second. The console is the test: a blocked resource says so, a policy never fails quietly. Same-origin form posts need nothing — fetch('/intake') is 'self'.
The theme is trust
Templates are executable PHP, so the right to change them is separate from every content right, and publishing a template runs a syntax check first: a shell that does not parse is refused and the live site keeps the previous one. A read-only template right sees your source without being able to change it.
The skeleton grammar
Sites Braaf builds share a skeleton stylesheet and script. They live with the site, not the engine, so you may replace them; nothing in the engine assumes a class name.
| Topic | Grammar |
|---|---|
| Layout | main > section is a twelve-column grid with a bleed. Two axes, never aliased: where I stand via is-align-sm/md/rg/xl; how I divide via is-grid (subgrid). |
| Type | Skeleton containers get no font size, which keeps em pure. Everything is em; the fluid base tokens are the only knob, the type ladder fixed steps. |
| Placement | is-place-{top,middle,bottom} × {left,center,right} on a flex column gives a three-by-three raster; is-space-* reserves breathing room. |
| Interaction | Reveal-on-scroll via data-trigger with -mode (once or toggle), -stagger, -delay, -offset, -class, -target; observers shared per offset group after first paint. Slider affordance via data-slider on a horizontal scroller: clipped-edge classes and a sticky chevron, native scroll kept. Sticky stacks detect docking. Non-modal dialogs sync open state to body classes through an observer. |
| Image and colour | A text-shadow halo in the card colour plus a gradient overlay from the cluster side; decorative layers aria-hidden under the overlay. Bare anchors in copy: dashed underline in diluted ink, full on hover, diluted when visited — colour only, mixed opaque with the surface, never alpha. |