{"canonical_url":"https://engineer.company/glossary/stylesheet/","content_markdown":"# Stylesheet\n\n## What it is\n\nA stylesheet, spelled style sheet in the specifications and often just called\nthe CSS file, is one collection of CSS rules that a browser fetches, parses and\napplies to a document as a single unit.\n\nA page can receive stylesheets in four ways. A `link` element with\n`rel=\"stylesheet\"` points at a separate file. A `style` element carries rules\ninside the HTML itself. An `@import` rule at the top of one stylesheet pulls in\nanother. And a script can build one with `new CSSStyleSheet()` and attach it to\na document or a shadow root through `adoptedStyleSheets`. The first two look\nlike this in the head of a page:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"/css/site.css\" /\u003e\n\u003clink rel=\"stylesheet\" href=\"/css/print.css\" media=\"print\" /\u003e\n\u003cstyle\u003e\n    .banner {\n        border-block-end: 2px solid;\n    }\n\u003c/style\u003e\n```\n\nThe author's sheets are not the only ones in play. Every browser ships a default\nstylesheet, which is why an unstyled heading still comes out large and bold, and\na reader can add a user stylesheet of their own; the cascade weighs the three\norigins against each other. The `style` attribute on one element is a different\nthing: declarations with no selector, belonging to that element and to no sheet.\n\nOnce loaded, a stylesheet becomes a `CSSStyleSheet` object in the CSS Object\nModel, the specification this term's definition comes from. The object records\nthe element that owns the sheet, the media it applies to, its title, whether it\nis disabled, and its list of rules, and `document.styleSheets` lists a page's\nsheets in order. One flag exists for privacy: a sheet fetched from another\norigin without CORS is not origin-clean, and a script that asks for its rules\ngets a security error instead.\n\nThe `media` attribute limits a sheet to an environment. A sheet marked\n`media=\"print\"` is still downloaded, but the browser waits only for sheets whose\nmedia matches, so a print sheet does not hold up the screen.\n\n## Why it matters\n\nA stylesheet decides what a browser has to fetch before it shows anything. The\nHTML standard treats an enabled stylesheet link found by the parser before the\nbody exists as render-blocking when its media matches, so the first paint\nnormally waits until that file has arrived and been parsed, instead of drawing the page unstyled and redrawing it in front\nof the reader. Its size, its host and the round trips needed to discover it all\nsit between a click and the first thing a reader sees.\n\nThe number of files is the first decision. One bundle shared by every page is\nfetched once and then served from the cache; a stylesheet per page sends less up\nfront and more as a reader moves around. Rules inlined in a `style` element cost\nno extra request, but they travel again with every page, because they cannot be\ncached apart from the document that carries them. Each `@import` adds a discovery\nstep: the browser learns the imported address as it reads the importing sheet,\nand fetching an uncached import can add another network round trip.\n\nCaching is the second. A stylesheet cached for a year makes every later page\nfaster, but a change then has to reach readers holding the old copy. The usual\nanswer is a fingerprinted file name, with a hash of the content inside the name,\nso a changed file is a new address and an old one can stay cached for as long as\nanyone likes, while the HTML pointing at it is kept short-lived.\n\nTrust is the third. A stylesheet decides what is visible and where; it can hide\na warning, restyle a button, or request images from any address its rules name.\nLoading one from a third party hands that power to the third party, along with a\nhost the page cannot render without. Subresource Integrity lets the page state a\ncryptographic hash for the file, and the browser refuses any file whose bytes\ndiffer.\n\n## What it looks like in practice\n\nThe site's July 2026 stylesheet rework shows how far one inlined asset can tip\nthe balance. At 87 KB the bundle was, for a document site with no framework, most of a\npage's weight spent before any content arrived, and two thirds of the largest\nstylesheet turned out to be one base64-encoded font: about 56 KB of text\nencoding about 42 KB of font. It had been inlined for a first-paint benefit that\na preloaded external file gets anyway, and every page paid for it whether the\nweight was needed or not. Taking it out took that file from 84 KB to 28 and\n[the whole bundle from 87 KB to 31 KB](/portfolio/cut-the-stylesheet-bundle-from-87-kb-to-31-kb/),\nwith the font weights preloaded instead. Base64 writes every three bytes as four\ncharacters, so a binary file inlined into a stylesheet always weighs about a\nthird more than the file served on its own.\n\nPaper is a medium a stylesheet has to serve too. The site's case studies are\nwhat someone prints and takes into a meeting. In the August 2026 implementation,\n[one 637-line stylesheet](/portfolio/built-a-637-line-print-stylesheet/)\nwith a single page rule and one print block made them print on unknown paper in\nboth colour themes. The page rule sets a margin and deliberately no paper size,\nand a measure of about seventy-two characters keeps a landscape sheet from\nrunning a line to about a hundred and ten. Four engine behaviours are written\ndown as traps, each having caused a real defect: viewport units measured\nagainst the page box by one engine but against the window by another, which\ncropped a third of every line; fixed-position elements that paint on every\nsheet; a palette defaulting to white text for the dark theme, which printed four\nsection labels white on white; and a flex or grid box that paged media cannot\nsplit, which produced a blank first sheet. The accompanying six-part check covered six paper\nand orientation combinations, both colour-scheme preferences and the real page\ncount, and it was that check which noticed when a stray comment terminator made\nthe CSS linter swallow a whole rule and pass clean twice.\n\nThe site's [security page](/security/) lists Subresource Integrity on the\nstylesheet: the bundle is fingerprinted and hashed at build time, so a reader's\nbrowser can verify that it arrived unmodified. The same page asks the reader to\ncount the hosts in the browser's network panel and gives the answer as one, the\nsite's own.\n\n## Where it goes wrong\n\nA stylesheet the browser learns about late delays its use. A link at the end of\nthe body or a sheet injected by a script can arrive after the first paint, so\nraw text jumps into a layout, or a finished layout shifts. A chain of `@import`\nrules in a render-blocking sheet can instead prolong the wait for the first\npaint. An import chain looks harmless in the source:\n\n```css\n/* site.css: the browser finds base.css only after this file arrives */\n@import url(\"base.css\");\n@import url(\"theme.css\");\n```\n\nPut stylesheet links in the head and flatten imports into the bundle at build\ntime.\n\nA deploy can pair new markup with old rules. Readers whose cache holds the\nprevious stylesheet get HTML expecting classes the old file has never heard of,\nand their layout breaks until the cache expires, while anyone testing with a\nfresh cache sees a working site. The cause is a stylesheet name that never\nchanges combined with a long cache lifetime, and a fingerprinted name removes\nit.\n\nA stylesheet served with the wrong content type is ignored. The HTML standard\napplies a linked stylesheet only when it arrives as `text/css`, with one\nexception for a same-origin file on a page in quirks mode. A server that labels\n`.css` files as `text/plain`, or answers a missing file with an HTML page and a\nsuccess status, leaves the page unstyled while the network panel shows a request\nthat apparently worked. Check the header on the deployed file.\n\nAn integrity hash goes stale when the file changes after hashing: a hand edit on\nthe server, a CDN that minifies on the way through, or a build that hashes\nbefore its last rewrite. The browser treats the mismatch as a network error and\nrenders without the sheet. On another origin, integrity also needs CORS: a\n`crossorigin` attribute on the link and a matching header from the server.\nCompute the hash in the step that writes the final file.\n\nA framework stylesheet on a public CDN used to be justified by readers already\nhaving it cached from other sites. The Fetch standard partitions the HTTP cache\nby top-level site, so each site's copy is fetched and stored separately, and\nwhat remains is a second host on the critical path under someone else's control.\nServing the file from the site's own host costs the same bytes without the extra\nconnection.\n\n## Further reading\n\n- [CSS Object Model (CSSOM)](https://www.w3.org/TR/cssom-1/#css-style-sheet) —\n  what a style sheet is inside the browser, and the interface scripts use to\n  read and change it.\n- [HTML Standard: Links](https://html.spec.whatwg.org/multipage/links.html) —\n  the `stylesheet` link type, the content-type rule and when a stylesheet blocks\n  rendering.\n- [Subresource Integrity](https://www.w3.org/TR/SRI/) — the `integrity`\n  attribute and what the browser does with a file that fails the check.\n- [Fetch Standard: HTTP cache partitions](https://fetch.spec.whatwg.org/#http-cache-partitions)\n  — how the cache is keyed by top-level site.\n- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css-page-3/) — the\n  `@page` rule and page margins a print stylesheet works with.\n- [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/) — print,\n  screen, colour-scheme preferences and the other conditions a `media` attribute\n  can test.\n\n\u003chttps://engineer.company/glossary/stylesheet/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How a stylesheet reaches a page, why the browser waits for it before it paints anything, and the ways a stale, mislabelled or tampered file breaks a site.","formats":{"gemtext":"https://engineer.company/glossary/stylesheet/index.gmi","gopher":"https://engineer.company/glossary/stylesheet/gophermap","html":"https://engineer.company/glossary/stylesheet/","json":"https://engineer.company/glossary/stylesheet/index.json","markdown":"https://engineer.company/glossary/stylesheet/index.md","pdf":"https://engineer.company/glossary/stylesheet/index.pdf"},"kind":"page","language":"en","title":"What is a stylesheet?","url":"https://engineer.company/glossary/stylesheet/","version":1}