Layout and responsive

01Overview

Three small sets of tokens. Breakpoints decide when a layout rearranges, the z scale decides which surface wins when two overlap, and the focus ring makes the keyboard position visible on every surface.

02Tokens

Generated from @nuton/tokens. Code-only tokens live in Git only and never as Figma variables; a check fails if a name exists in both places.

Breakpoints

Content widths

Layers (z-index)

Focus ring

03Usage

Load @nuton/tokens/tokens.css once. Use the CSS variables for layers and focus, and the breakpoint values through Tailwind or JavaScript, because a media query can't read a CSS variable.

/* Layers: choose by role, never by number. */
.lesson-header { position: sticky; inset-block-start: 0; z-index: var(--nu-z-sticky); }
.tutor-sheet   { position: fixed; z-index: var(--nu-z-overlay); }

/* Focus: outline (not box-shadow) so it survives forced-colours mode. */
.lesson-card:focus-visible {
  outline: var(--nu-focus-ring-width) solid var(--nu-focus-ring-color);
  outline-offset: var(--nu-focus-ring-offset);
}

/* Breakpoints: var() doesn't work in @media. Copy the value from
   --nu-breakpoint-lg (1024px) and name the token beside it. */
@media (min-width: 1024px) { /* --nu-breakpoint-lg */
  .lesson { grid-template-columns: 16rem minmax(0, 1fr) 22rem; }
}

/* app.css */
@import 'tailwindcss';
@import '@nuton/tokens/tokens.css';
@import '@nuton/tokens/tailwind-v4.css'; /* sets --breakpoint-sm … 2xl */

// Breakpoint variants: sm: md: lg: xl: 2xl:
<div className="grid lg:grid-cols-[16rem_minmax(0,1fr)_22rem]">…</div>

// Focus colour: outline-focus-ring-color / ring-focus-ring-color
<a className="focus-visible:outline-focus-ring-color">…</a>

// The v4 theme has no z-index names. Reference the variable:
<header className="sticky top-0 z-(--nu-z-sticky)">…</header>

// tailwind.config.js
module.exports = { presets: [require('@nuton/tokens/tailwind-v3-preset')] }

// Screens: sm md lg xl 2xl
// z-index: z-base z-raised z-sticky z-overlay z-modal z-popover z-toast z-tooltip
<header className="sticky top-0 z-sticky">…</header>
<div className="fixed inset-0 z-overlay bg-overlay-gray" />

// Focus colour: outline-focus-ring-color / ring-focus-ring-color
<a className="focus-visible:outline-focus-ring-color">…</a>

import { tokens } from '@nuton/tokens'

// '1024px', read from the token, never retyped.
const wide = window.matchMedia(`(min-width: ${tokens['breakpoint-lg'].value})`)
wide.addEventListener('change', (e) => setTutorAsSheet(!e.matches))

• Write mobile first: the base styles are the narrow layout, and each breakpoint adds to it with min-width.
• Components that live inside panels (the tutor, a sidebar) respond to their container with container queries, not to the window. A tutor panel is narrow on a wide screen.
• Pick a layer by what the surface is: sticky, overlay, modal, popover, toast, tooltip. Never write z-index: 9999 or bump a number to win a fight; fix the stacking context instead.
• Use logical properties (inset-inline-start, padding-inline) so layouts can mirror for right-to-left languages later.
• Leave focus on .nu-* components alone. They draw their own indicator; the focus-ring tokens are for your own interactive elements.

Tailwind v4 also gets bg-overlay-gray and the other colours from tailwind-v4.css; there are no Tailwind names for the focus-ring width and offset in either version, so use the CSS variables.

04In use

Structured lesson (D23)

From lg up, the lesson shows contents, lesson and tutor side by side. Narrower, the tutor becomes an overlay sheet and the contents a drawer, both on --nu-z-overlay. D23 approves this collapse; the exact switch point (around md–lg) is validated per layout. This site switches its own sidebar to a drawer at lg.

const wide = useMediaQuery(`(min-width: ${tokens['breakpoint-lg'].value})`)

return wide ? (
  <div className="lesson">            {/* three columns */}
    <nav aria-label="Lesson contents"><LessonContents /></nav>
    <article><Lesson /></article>
    <aside aria-label="Tutor"><TutorPanel /></aside>
  </div>
) : (
  <>
    <Button appearance="ghost" leadingIcon={<RiBookOpenLine />} aria-expanded={drawer} onClick={openDrawer}>Contents</Button>
    <Button appearance="stroke" leadingIcon={<RiQuestionAnswerLine />} aria-expanded={sheet} onClick={openSheet}>Ask tutor</Button>
    <article><Lesson /></article>
    {drawer && <Drawer label="Lesson contents"><LessonContents /></Drawer>}  {/* z-index: var(--nu-z-overlay) */}
    {sheet && <Sheet label="Tutor"><TutorPanel /></Sheet>}                   {/* z-index: var(--nu-z-overlay) */}
  </>
)

The width is simulated with the toggle so the demo works on any screen. Opening a panel moves focus to its Close button; Escape or Close returns focus to the button that opened it. The frame uses isolation: isolate, so its overlay layers stay inside it.

Layering

Search opens the CommandMenu: its scrim sits on --nu-z-overlay (40) and the dialog on --nu-z-modal (50), both above this site's sticky header (--nu-z-sticky, 20). The menu uses --nu-z-popover (60).

<Button appearance="stroke" leadingIcon={<RiSearch2Line />} onClick={() => setOpen(true)}>Search lessons</Button>
<DropdownMenu>                         {/* content: z-index var(--nu-z-popover) */}
  <DropdownMenuTrigger asChild>
    <Button appearance="ghost" iconOnly aria-label="Lesson actions"><RiMore2Line /></Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuItem leading={<RiEditLine />}>Rename</DropdownMenuItem>
    …
  </DropdownMenuContent>
</DropdownMenu>

<CommandMenu open={open} onOpenChange={setOpen} label="Search lessons"> {/* scrim: overlay, dialog: modal */}
  <CommandMenuGroup heading="Biology 101">
    <CommandMenuItem leading={<RiBookOpenLine />}>Photosynthesis</CommandMenuItem>
  </CommandMenuGroup>
</CommandMenu>

Focus

05Accessibility

Layout decides whether content survives zoom and narrow screens, and whether the keyboard position can be seen.

You must: never hide content at small widths that people need (move it into a drawer or sheet instead); keep focus order matching the visual order after a layout rearranges; never remove an outline without a visible replacement.

06Guidelines and related

Do and don't

Related

• SpacingThe space inside layouts: padding and gaps.
• ElevationShadows for surfaces that sit on higher layers, and focus effects.
• Dropdown and selectMenus and the command menu, on the popover and modal layers.
• ButtonThe focus effect today and the C5 proposal.