Fundamentals

Layout

Content has a maximum width, cards and tiles sit in a kern-grid, and breakpoints are measured on the container, not on the window.

Tokens

Widths for the page and the sidebar, and three breakpoints. Custom properties do not work in @media or @container conditions, so the breakpoint values are written literally there; the tokens are for documentation and for JavaScript (getComputedStyle(document.documentElement).getPropertyValue('--breakpoint-md')).

Token	Value
`--content-max`	`1280px`
`--content-wide`	`1600px`
`--sidebar-width`	`240px`
`--breakpoint-sm`	`640px`
`--breakpoint-md`	`960px`
`--breakpoint-lg`	`1280px`

Breakpoints

Kern components switch by the room they really have: kern-grid is a size container, and its columns and the spans of kern-grid-item change at 640, 960 and 1280 px of grid width. A grid in a sidebar, a drawer or half a page therefore behaves like on a small screen, without any extra configuration. Use the same values for your own container queries.

.panel { container-type: inline-size; } @container (min-width: 640px) { .panel .fields { grid-template-columns: 1fr 1fr; } }

Grid

kern-grid has two modes:

Auto (default): as many columns of at least min as fit, e.g. for key figures or device cards. No breakpoints needed.
Columns: columns="12" with kern-grid-item span="12" span-md="8" for layouts like list and details side by side.

<kern-grid min="220px"> <kern-stat label="Devices online" value="36"></kern-stat> <kern-stat label="Updates" value="3"></kern-stat> </kern-grid> <kern-grid columns="12"> <kern-grid-item span="12" span-md="8"><kern-card heading="Devices">…</kern-card></kern-grid-item> <kern-grid-item span="12" span-md="4"><kern-card heading="Details">…</kern-card></kern-grid-item> </kern-grid>

Gaps come from the spacing scale (gap="sm|md|lg"); inside a card, use kern-grid too, not nested cards.

App shell

kern-app-shell is the frame around the pages: a topbar that stays at the top, the content with --content-max and page padding, and an optional footer. With a sidebar slot it adds a side navigation that stands on the left from 960 px and becomes a drawer below, opened by the menu button of kern-topbar. A skip link and the landmarks header, nav and main come with it.

<kern-app-shell> <kern-topbar slot="topbar" app-name="Shelly Manager"></kern-topbar> <div slot="sidebar">…</div>  <kern-page-header heading="Devices"></kern-page-header> <kern-grid min="240px">…</kern-grid> </kern-app-shell>

Unlike the grid, the shell decides by its own width with a breakpoint property (default 960), because the side navigation is about the whole window, not one container.

Build the side navigation from kern-list variant="nav": one list per group with a heading, links as kern-list-item href with an icon in start and a counter as kern-badge mono in meta. current marks the open page (aria-current="page").

Routing: the links are real hrefs, so the navigation works without JavaScript. In a single-page app, listen for kernNavigate (it bubbles) and call preventDefault() to route yourself; detail.href is the target.
New tabs stay with the browser: kernNavigate only fires for a plain left click. Ctrl/Cmd, Shift or middle click and links with target open as the browser does.
Drawer: below the breakpoint the navigation is a drawer; a link click closes it and moves focus to the main content, also when your router took over.
Current page: after routing, move current to the new item.
Focus: after a navigation without page load, call focusMain() on the shell, so keyboard and screen reader users continue in the new content instead of in the navigation. While the drawer is open it waits until the drawer has closed.

document.addEventListener('kernNavigate', (e) => { e.preventDefault(); router.go(e.detail.href); if (e.target.localName === 'kern-list-item') { for (const el of document.querySelectorAll('kern-list-item[current]')) el.current = false; e.target.current = true; } document.querySelector('kern-app-shell').focusMain(); });