web surface is any browser without a shell. That covers a 360 px phone browser and a 1920 px desktop window alike, so a web page has to work at both ends. These helpers do the common parts in CSS, so the server render and the first frame already have the right layout.
Page
The page container: centered, capped at one of four widths, with a side gutter that grows with the window (16, 24, then 32 px).narrow is 680 px (reading, a form, a feed). default is 960 px (most pages). wide is 1200 px (grids, dashboards). full has no cap.The element drawn. Use
main when the page is the landmark itself.pageWidths exports the pixel values. The same widths are CSS variables (--cskn-page-narrow, --cskn-page-default, --cskn-page-wide), for a header that must line up with the page below it.
AppShell
One list of places, drawn three ways:- a bottom tab bar on a phone
- an icon rail from 768 px
- a sidebar from 1024 px
<main> landmark.
{ key, label, icon?, badge?, href?, tab? }. badge is a count, or true for a dot. With href the item is a real link: Cmd/Ctrl-click and middle-click open it in a new tab, and a plain click calls onSelect. tab: false keeps the item out of the phone tab bar, which shows the first five.What the icon rail shows instead of
brand, usually the logo alone. Without it the rail has no brand.Bottom of the sidebar: account, settings.
Labels for the skip link (default “Skip to content”) and the navigation landmark (default “Main”). Translate them.
AppShell is for the web surface. Inside the mobile shell use the stack navigator, and inside the desktop shell use DesktopWindow.useUrlRoute
Keeps the page your app shows in the address bar. Back and Forward walk through it, a refresh stays on it, and a copied link opens it. The app’s mount path (/<slug> on a user page) is handled for you.
Turns
{ path, segments, query } into a route. It must accept any path, including old or mistyped links: fall back to the home route rather than throwing.A path (and query) under the app’s mount. Don’t include the mount itself.
Cross-fade between pages with the browser’s View Transitions API on a push and on Back/Forward. Replacing the address never animates. It is skipped where the API is missing and under reduced motion.
The browser’s Back when your app pushed the current entry. Otherwise, for a page opened from a link or a refresh, it shows
fallback in place, so an in-app Back button never leaves your app.replace for choices your app makes, such as selecting the first item, moving on after a delete, or changing a filter.
A route often names data by id, such as /p/<id>. Keep a cache of the objects you already have, and fetch the rest when a link opens straight to one.
useDocumentTitle
Sets the browser tab’s title while the component is mounted, so tabs, history and bookmarks tell your pages apart.The page’s own name. A falsy value leaves the tab alone, for example while data loads.
useMediaKeys
The keys people expect from a media player in a browser, for as long as the component is mounted.
A key without a handler is left alone. Nothing fires while the user is typing, while a modifier key is held, or while an open dialog has the focus. Space on a button stays that button’s key.
Responsive chrome
Show and Hide take mode="css". Both branches are mounted, and a media query hides one, so the first frame is already right and resizing re-mounts nothing. Use it for layout chrome, and keep the default mode="js" for heavy subtrees. See Responsive.
Hover on hand-styled controls
Kit components have hover states. For a control you style yourself, add the classcskn-hoverable. It tints the control on hover with an inset shadow, which works even over an inline background.
Fonts and theme color
Load the fonts every page uses inindex.html, as <link rel="preconnect"> plus <link rel="stylesheet">. Don’t use a CSS @import: it waits for your own CSS before it even starts.
For a font only one page or surface needs, call loadFonts. It adds the preconnects, loads the stylesheet once per document, and adds display=swap when the URL has no display of its own.
UIProvider keeps <meta name="theme-color"> in step with your theme’s background, following light, dark and in-app theme switches. If index.html declares its own theme-color, the provider leaves it alone.