Elevation

01Overview

Nuton is a flat, light interface. Most surfaces sit on the page with a 1px Stroke/Soft-200 border; a shadow says that something floats above the content, such as a menu, a popover or the command search. The higher the surface, the softer and wider its shadow.

Regular shadows: one soft layer

Custom shadows: layered, with a hairline ring

Regular shadows are a single soft drop. Custom shadows stack several drops with a 1px ring and an inner bottom edge, so a surface reads as raised even without a border. Today components use the regular set; the custom set has no component yet.

02Tokens

Every value below is generated from @nuton/tokens. Shadows are Figma effect styles under components/; the group prefix is dropped in the name (custom-shadows/large becomes --nu-shadow-custom-shadows-large).

Regular shadows

Custom shadows

Focus effects

Component shadows

Overlays

03Usage

/* A floating panel: border + shadow, like the Nuton menus */
.lesson-popover {
  border: 1px solid var(--nu-stroke-soft-200);
  border-radius: var(--nu-radius-16);
  background: var(--nu-bg-white);
  box-shadow: var(--nu-shadow-regular-shadow-medium);
}

/* The dimmed page behind a modal */
.lesson-dialog__overlay {
  position: fixed;
  inset: 0;
  background: var(--nu-overlay-gray);
  z-index: var(--nu-z-overlay);
}

/* app.css */
@import "tailwindcss";
@import "@nuton/tokens/tokens.css";
@import "@nuton/tokens/tailwind-v4.css";

<div className="rounded-16 border border-stroke-soft-200 bg-bg-white shadow-regular-shadow-medium">…</div>
<div className="fixed inset-0 bg-overlay-gray" />

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

<div className="rounded-16 border border-stroke-soft-200 bg-bg-white shadow-regular-shadow-medium">…</div>
<div className="fixed inset-0 z-overlay bg-overlay-gray" />

Every shadow is a shadow-* utility in both Tailwind outputs (for example shadow-custom-shadows-tooltip, shadow-toggle-switch). Overlays are colours: bg-overlay-gray, bg-overlay-slate. The v3 preset also has z-overlay; the v4 theme has no z-index utilities, so use var(--nu-z-overlay) there.

Choosing a token

• Resting controls (text areas, digit inputs, key icons, avatar groups): regular-shadow-x-small, always with a border.
• Floating panels (dropdown menus, combobox lists, command search): regular-shadow-medium with a 1px Stroke/Soft-200 border.
• Tiny marks on busy backgrounds (chart legend dots, status badges): regular-shadow-small (interim).
• Focus: the buttons/*-focus effect that matches the control's intent (important for neutral, primary, error). Don't use a focus effect for elevation.
• Behind a modal: overlay-gray, the one in use. overlay-slate is a cooler alternative with no documented use yet.

04In use

Real @nuton/ui components, each reading its shadow from a token.

Floating menu

Open the menu. The panel uses regular-shadow-medium and a border; the switch thumb uses toggle-switch.

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button appearance="stroke" size="sm" trailingIcon={<RiArrowDownSLine />}>Lesson actions</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="start">
    <DropdownMenuItem leading={<RiEditLine />} onSelect={edit}>Edit lesson</DropdownMenuItem>
    <DropdownMenuItem leading={<RiShareLine />} onSelect={share}>Share with space</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuSwitchItem leading={<RiBellLine />} checked={notify} onCheckedChange={setNotify}>
      Notify students
    </DropdownMenuSwitchItem>
  </DropdownMenuContent>
</DropdownMenu>

Overlay behind a modal

Open the search. overlay-gray dims the page and the panel floats on regular-shadow-medium. Press Escape to close; focus returns to the button.

<Button appearance="stroke" size="sm" leadingIcon={<RiSearch2Line />} onClick={() => setOpen(true)}>
  Search lessons
</Button>
<CommandMenu open={open} onOpenChange={setOpen} label="Search Nuton" placeholder="Search lessons and spaces…">
  <CommandMenuEmpty>No results</CommandMenuEmpty>
  <CommandMenuGroup heading="Actions">
    <CommandMenuItem leading={<RiAddLine />} onSelect={createLesson}>Create lesson</CommandMenuItem>
  </CommandMenuGroup>
  <CommandMenuGroup heading="Lessons">
    <CommandMenuItem leading={<RiBookOpenLine />} onSelect={openLesson}>Photosynthesis</CommandMenuItem>
    <CommandMenuItem leading={<RiFolderLine />} description="12 lessons" onSelect={openSpace}>Biology 101</CommandMenuItem>
  </CommandMenuGroup>
</CommandMenu>

Resting fields and focus

The text area rests on regular-shadow-x-small. Tab into either field to see the buttons/important-focus effect.

<Field label="Lesson title">
  <Input size="sm" defaultValue="Photosynthesis" />
</Field>
<Field label="Summary" hint="Shown on the lesson card.">
  <Textarea rows={3} defaultValue="How plants turn light into energy." />
</Field>

Focus effects by intent

Tab through the buttons. Each intent has its own focus effect: important (neutral), primary and error.

<Button appearance="stroke">Save draft</Button>
<Button intent="primary" appearance="stroke">Invite students</Button>
<Button intent="error" appearance="stroke">Remove lesson</Button>

Small surfaces

<KeyIcon icon={<RiBookOpenLine />} label="Lessons" />        // regular-shadow-x-small
<ChartLegend color="blue">Completed</ChartLegend>            // regular-shadow-small (interim)
<ChartLegend color="orange">In progress</ChartLegend>
<SwitchIndicator checked />                                 // toggle-switch

Where components use each token

05Accessibility

You must: pair a floating surface's shadow with a border; keep the component's focus effect (don't remove it with box-shadow: none); manage focus in anything shown on an overlay.

06Guidelines and related

Do and don't

Related

• ColourStroke and background colours that pair with shadows.
• RadiusCorner radii for the surfaces shadows lift.
• Layout and responsiveZ-index layers for overlays and modals.
• Dropdown and selectMenus and the command search on regular-shadow-medium.
• ButtonFocus effects by intent.
• Inputs and fieldsResting x-small shadow and focus.