A desktop operating system as a website: windows with working chrome, icons as navigation, a taskbar that tracks what is open beside a plain text index of every window, a wallpaper system under all of it, and a real keyboard model underneath. This is a shell archetype, not just a visual register. The register a shell wears is swappable; what this repo actually packages is the OS. PostHog's current desktop-metaphor era is the defining commercial exemplar, and the longer site-as-OS lineage of portfolio desktops and browser-OS art projects is the root the whole idea descends from. The exemplar is also a working proof of this collection's central claim about shells: its production CSS runs skin and wallpaper as independent attribute axes on the body, register and surface composed separately, which is the shells and registers thesis deployed at company scale. This repo adopts that slot and that mechanism; every scene shipped here is original work. The retro-95 look most people picture first is one costume the tokens could reach; the shipped register is a modern-clean desktop, warm light ground and crisp chrome, closer to what PostHog proved a business can ship.
The screenshot above is demo/index.html, a fictional team workspace called Davenport whose pages are windows: about, features, pricing and docs are programs on its desktop. That is the honesty test for a shell demo: a workspace product is itself a desk, so a site arranged as a desktop is describing the product, not wearing a gimmick.
Open it live, or clone the repo and open the file. There is no build step, no framework, no node_modules, and no server to start.
The demo declares no color of its own. It links tokens/tokens.css, components/components.css, shell/shell.css and shell/shell.js and reads every value from the first of those, so it stays honest about what the theme actually produces.
There is a second page worth opening: components/index.html renders the five in-window components with the markup to copy, on an ordinary page, which is its own point: the components do not need the shell.
A visual style is a set of coordinates, not a mood. This theme sits at one point in the creative direction framework, which sets brand direction on four axes. Here is where it lands and what each choice pays for.
| Axis | Position | What the position buys |
|---|---|---|
| Tone register | Playful | The shell is the joke: a site that answers "where is pricing" with a window called Pricing. It lands in the first five seconds or not at all. |
| Aesthetic philosophy | Polished Standard | The chrome runs on the best-known pattern library in computing. Nobody needs a window explained to them, which is what frees the metaphor to be fun instead of homework. |
| Audience relationship | Peer | The desktop goes unexplained. Icons get names, not a tutorial; the reader has used a computer before and the interface assumes it. |
| Sensory ambition | Considered | One animation, one accent, one sticky note. The craft is visible mostly in what the shell declines to do. |
Those four position names are the exact strings the framework uses. If you want the long version of any of them, the links go to the position page.
One of those four strains, and it is worth naming rather than hiding. A whole-site device metaphor is the loudest sensory gesture in this collection, and a fair reading pushes it toward Resonant. It stays at Considered because the metaphor here is structure rather than atmosphere: no wallpaper photograph, no boot sequence, no simulated crunch of a hard drive. Reduced motion collapses the one animation, JavaScript off removes the shell entirely, and the content survives both. Resonant work wants the reader to feel something staged for them; this wants a grin of recognition, and then it gets out of the way.
Clone once, then pick the path that matches what you came for. A shell theme has two different things worth taking, so the two grabs are stated separately.
git clone --depth 1 https://github.com/rampstackco/desktop-os-themeGrab the shell. Four files: the tokens, the in-window components, the chrome, the behavior. Your content goes in os-window articles, your navigation in os-icon anchors; the demo is the reference markup.
<link rel="stylesheet" href="/styles/tokens/tokens.css" />
<link rel="stylesheet" href="/styles/components/components.css" />
<link rel="stylesheet" href="/styles/shell/shell.css" />
<script src="/styles/shell/shell.js" defer></script>Grab the register only. Skip the shell/ directory entirely and you have a warm modern-clean theme for ordinary pages: tokens plus five components, no windows anywhere. This is the grab where this repo behaves exactly like the register themes in the collection.
<link rel="stylesheet" href="/styles/tokens/tokens.css" />
<link rel="stylesheet" href="/styles/components/components.css" />Tailwind v4. One import. theme.css pulls in tokens.css and maps it onto Tailwind's theme namespaces, so you get bg-os-accent, shadow-os-window, rounded-os, h-os-taskbar. The shell files are plain CSS and JS either way; the adapter covers the tokens.
@import "tailwindcss";
@import "./styles/tokens/theme.css";Tailwind v3. Load the tokens in your stylesheet, then register the preset.
@import "./styles/tokens/tokens.css";
@tailwind base;
@tailwind components;
@tailwind utilities;// tailwind.config.js
module.exports = {
presets: [require("./styles/tokens/preset.js")],
content: ["./src/**/*.{html,js,jsx,ts,tsx}"],
};The demo is a plain document that a script upgrades, not an app with a fallback. With JavaScript disabled it reads top to bottom: a masthead, the icon nav as a row of anchor links, every window as a titled card in reading order, the taskbar's shortcut strip as a footer nav that jumps to each one. This is verified by loading the page with scripts off, not assumed. The mechanism is one class: shell.js puts os-live on the root element as its first act, and every OS behavior in shell.css is scoped under it. The close and minimize buttons do not exist in the markup at all; the script injects them, because a control that does nothing must not exist.
shell.js is one file of vanilla JavaScript with zero dependencies, annotated section by section, small enough to read over coffee. It is the whole shell.
A fake operating system that strands a keyboard user is a failed build, so the keyboard model is the part of this theme that got the most engineering:
- The icons are not the only way through. The taskbar carries a shortcut strip: six plain text links, one per window, complete and identical whether or not the script runs. An icon rail is a navigation surface a reader has to recognise as one first, and the reader who does not recognise it needs an ordinary set of links, not a better-drawn icon. This is WCAG 2.4.5 Multiple Ways on purpose rather than by luck, and it is class decision 44. The strip is a fixed index; the list of open windows beside it is the part that tracks state, and the two are drawn differently so nobody has to guess which is which.
- Every icon, shortcut, control, taskbar entry and the launcher is keyboard-reachable with a visible focus ring drawn from the accent.
- The full Tab cycle was walked and recorded with the welcome window open: skip link, six icons, two window controls, the window's scroll region, two in-content links, six shortcuts, the open window's taskbar entry, the wallpaper switcher, wrap. Twenty stops. No focus trap anywhere; closed windows leave the tab order by leaving the render tree.
- Escape closes the topmost visible openable: the launcher panel if it is open, otherwise the front window. One key, one rule.
- Focus is managed at the three moments it can be lost. Opening a window moves focus into it. Closing one returns focus to the element that opened it. Minimizing one moves focus to the window's taskbar entry, because that is where the window went.
- Close is never a dead end: behind the last window is always the desktop with its icons.
- Windows carry
role="dialog"with a real label, and noaria-modal, because nothing is modal and nothing traps. The scroll region is focusable so a keyboard user can scroll a long window. All of this ARIA is added by the script at enhance time, so the no-JS document never claims semantics it cannot honor. prefers-reduced-motioncollapses the one animation to instant through the tokens, not through a bolted-on override.
tokens/tokens.css is the single source of truth. Every literal value in the theme appears there exactly once; theme.css and preset.js hold no values of their own and point back at it with var(). The file is annotated by framework axis, contrast ratios in the comments are measured, and the shell geometry (title bar height, cascade offset, taskbar height) is a token group like any other, which is what keeps a re-skin a one-file edit.
shell/shell.css and shell/shell.js draw the OS from those tokens. The window manager is deliberately small: multiple windows, cascade placement, raise on click, honest close and minimize, and nothing else. No drag, no resize, no maximize. One excellent window beats a buggy window manager, and every one of those three deletions is where site-as-OS builds historically go to die.
The desktop ground is a wallpaper slot, not a color. Two variants ship: the quiet field (a soft top light under the dot grid, drawn by plain CSS, which is what the no-JS document and prefers-contrast: more both get) and the scene, a desk flatlay in Davenport's own language, coffee ring and ruled paper and pencil, drawn as inline SVG so it reads the tokens like everything else. A taskbar button switches them; the switch is one data-wallpaper attribute on the body, all styling attribute-scoped in shell.css, and the script only toggles the attribute. The wallpaper's paint set is restricted by rule to the light tokens, so the worst text-over-wallpaper pairing on the desktop measures 9.88:1 and no variant needs a scrim; the numbers are in the shell.css comment. Re-skin the tokens and the wallpaper re-skins with the OS, which CUSTOMIZE.md shows in a captured image.
CUSTOMIZE.md documents retheming as axis moves rather than as a color picker. Its first worked move re-skins the whole shell to a dark developer register in ten measured tokens, which is the shells and registers thesis demonstrated rather than asserted.
Consuming this from a Claude skill. The design-standards skill asks for a project's design tokens as a required input and offers to define a working set when none exist. Point it at tokens/tokens.css instead. The file covers every category the skill asks for, in the order it asks, and the contrast ratios are already in the comments.
terminal-ui-theme is a register: a dark phosphor surface any site can wear. This repo is a shell: a structure a site lives inside, which happens to ship wearing a modern-clean register and can wear others, including one much like terminal-ui's. If you want your ordinary page to look like a terminal, go there. If you want your site to be a machine with windows, you are in the right repo.
This repo is the pilot of a five-repo class. All five ship the same anatomy: a top-level shell/ directory, one root enhancement class, ARIA and controls injected at enhance time, shell geometry as a token group, and a ground axis on the body. They differ in the machine.
- retro-desktop-theme is this shell at the other temperature. The same window manager, the same enhancement contract, the same wallpaper mechanism, wearing 1995: beveled silver chrome on a teal ground, a Programs menu, an era-correct three-step window open. Neither repo is the other's fallback. Pick this one if the desktop is the point, pick that one if the era is the point, and CUSTOMIZE.md shows the road between them in both directions so you can see what you would be trading.
- phone-launcher-theme is one app at a time. Its native state is 390 and the desktop is a presented device on a stage, which is the opposite direction of travel from this repo's transform. This one gives you a window pile you can cascade, minimize and raise. If your content is a column somebody reads on a phone, go there.
- game-console-ui-theme is a board you drive from across the room. Rows of tiles as the whole navigation surface, arrow-key spatial navigation, type sized for ten feet, a dark ground. If the reader is holding a remote rather than a mouse, go there.
- vivaocean-theme is the showcase strain, and the answer to what a shell looks like when the ground is the point. One window held in an animated seascape, a rail down each side, and a nine-page site underneath in which every page is a real static document. Where this repo spends its craft on a window manager, that one spends it on a ground that never stops moving and still clears AA over every frame. Go there if the atmosphere is the product.
The class-decision log for all five lives here: docs/class-decisions.md. Forty-six numbered decisions with the repository and pull request that filed each one, plus the determinism toolkit, the states-by-viewports rule a new shell verifies against, and the guarantee-layer record showing how all five shells satisfy decision 44 — now audited per state as well as per repository, which is decision 46 and which found three states where the guarantee is not on the screen.
MIT. See LICENSE. Use it commercially, fork it, rename the tokens, ship it. No attribution required.
Issues and pull requests are welcome here. For questions, ideas, and anything conversational, use the discussions on the claude-skills repo, which is where all discussion for these repos lives.