Modal

A Modal is a focused container that appears above the page to display essential, interruptive, or task-related content without navigating away from the current view. It temporarily disables interaction with the underlying interface and requires the user to complete an action before returning to the previous context.

When to use it (and when not to)

Use when:

The user must take an action before continuing (e.g. confirm, acknowledge, complete a task).
You need to display content that requires full focus without distractions.
The interaction must not be missed (e.g. legal notices, blocking states).

Avoid when:

The information is optional, lightweight, or can be shown inline or via a Popover/Tooltip.
The interruption breaks the user flow unnecessarily.
A non-blocking alternative (sheet, inline block, banner) would provide a smoother experience.

Quick summary of accessibility & consistency

The Modal must trap focus until it is closed (keyboard and assistive technologies).
Focus must move to the Modal container on open, and return to the triggering element on close.
Provide a clear and visible close action.
Ensure all content inside the Modal is reachable and announced in a logical order.
Maintain consistent spacing, elevation, and layout across breakpoints.
On mobile, Modals are replaced by a Bottom Sheet to ensure touch accessibility and ergonomic interactions.

Properties

Anatomy : Full Screen

Modal

Background color:

color-background-neutral-default#ffffff

Button-Main

Depends on: Button-Main

Has icon left: false

Has border: false

Has icon right: true

Type: Tertiary

Size: LG

State: Rested

Mode: On Base

Slot

Depends on: slot

Anatomy : With Image

Modal

Background color:

color-background-neutral-default#ffffff

Image (aspect ratio)

Depends on: aspect ratio

Play Button: true

Type: Placeholder

Content

Slot

Depends on: slot

Button-Main (Tertiary)

Depends on: Button-Main

Has icon left: true

Has border: true

Has icon right: true

Type: Tertiary

Size: LG

State: Rested

Mode: On Base

Button-Main (Secondary)

Depends on: Button-Main

Has border: true

Has icon left: true

Has icon right: true

Type: Secondary

Size: LG

State: Rested

Mode: On Base

Button-Main (Primary)

Depends on: Button-Main

Has border: true

Has icon left: true

Has icon right: true

Type: Primary

Size: LG

State: Rested

Mode: On Base

Link Button

Has Icon: true

Button-Main (Close)

Has icon left: false

Has border: false

Has icon right: true

Type: Tertiary

Size: LG

State: Rested

Mode: On Base

Anatomy : Without Image

Modal

Background color:

color-background-neutral-default#ffffff

Content

Button-Main (Close)

Depends on: Button-Main

Has icon left: false

Has border: false

Has icon right: true

Type: Tertiary

Size: LG

State: Rested

Mode: On Base

Slot

Depends on: slot

Button-Main (Tertiary)

Depends on: Button-Main

Has icon left: true

Has border: true

Has icon right: true

Type: Tertiary

Size: LG

State: Rested

Mode: On Base

Button-Main (Secondary)

Depends on: Button-Main

Has border: true

Has icon left: true

Has icon right: true

Type: Secondary

Size: LG

State: Rested

Mode: On Base

Button-Main (Primary)

Depends on: Button-Main

Has border: true

Has icon left: true

Has icon right: true

Type: Primary

Size: LG

State: Rested

Mode: On Base

Horizontal Actions

Link Button

Has Icon: true

Behaviour

The Modal is built using a small set of structural elements. All buttons inside the Modal — including the Close Button and all action buttons — inherit their behaviour and specifications from the Button Main component.

Close Button (mandatory) — Always required to ensure a reliable, accessible way to dismiss the Modal. Uses the Button Main component (LG size with the “Close” icon). Optional behaviours such as dismissing by tapping outside the Modal are not defined at component level and must not replace the Close Button.
Image (optional, 16:9 or 9:16) — An optional image can be placed at the top of the Modal. Recommended ratio: 16:9 or 9:16, sourced from the Image component to maintain consistency and responsive behaviour. Optional short text may be placed over the image when required by the content. For more details, refer to the Image component.
Content Slot (mandatory) — The content slot is flexible and can hold different types of content such as text, images or simple forms. It does not impose its own copy rules. Any element placed inside the slot must follow the guidelines of its own component (for example Button Main, Link, Image or Form elements). The modal only provides the container and overall behaviour.
Action Area — All action buttons inside the Modal (Primary, Secondary, Tertiary, Link) use the Button or Link Button components. Only the layout changes depending on viewport:
- Horizontal Actions (Desktop & Tablet) — Buttons appear side-by-side following Button spacing and hierarchy rules. Supports any combination of Primary, Secondary, Tertiary and Link buttons. Refer to the Button and Link Button documentation for behaviour, states, and accessibility.
- Vertical Actions (Desktop, Tablet & Mobile) — Buttons are stacked vertically to ensure optimal tap targets on smaller screens. Automatically used in Mobile viewports. May also be used on larger viewports when clarity or long labels require it.
Link (optional) — A Link Button may be used as a secondary or tertiary action. Follows all behaviour, spacing, and accessibility rules defined in the Link Button component.
Backdrop (mandatory) — The Modal appears above a semi-transparent Backdrop that blocks interaction with underlying content and ensures focus isolation. For tokens (colour, opacity, elevation) refer to the Backdrop component documentation.

Transitions

The Modal uses a light fade-in/out animation to provide a smooth appearance and reduce abrupt visual changes.

Default transition: transition: opacity .5s ease-out;

Modes

The Modal supports Toyota and Lexus brand modes. The structural layout, behaviour, and spacing remain identical — only brand-specific tokens (colours, typography) are applied through the design token system.

Composition

Layout & Spacing : Desktop, Full Screen

Modal

Direction: Horizontal

Alignment: Top right

Vertical resizing: Fixed

Horizontal resizing: Fixed

Content

Direction: Vertical

Alignment: Top right

Vertical resizing: Fill

Horizontal resizing: Fill

Item spacing: 24

Padding: 40

Styling

Colors

Name	Applied as	Applied to
`color-background-neutral-default`	Background color	Modal
`color-background-neutral-default`	Background color	Modal
`color-surface-dim-neutral-default`	Background color	Backdrop
`color-surface-dim-neutral-default`	Background color	Backdrop
`color-foreground-contrast-emphasis`	Text color	Title
`color-foreground-contrast-emphasis`	Text color	Title

Text Styles

Name	Applied as	Applied to
Lorem Ipsum `typography-title-7`	Text style	Title
Lorem Ipsum `typography-title-7`	Text style	Title

Accessibility

General

The Modal must trap focus while it is open, keeping keyboard and assistive technology users inside the dialog.
Focus must return to the trigger once the Modal is closed.
The first focusable element should be the Close Button.
The Modal must announce itself to screen readers as a dialog using the correct accessibility attributes (for example role="dialog" and aria-modal="true").
Content inside the slot must follow the accessibility rules of each component placed inside it.

Focus Order

The Modal follows a consistent focus-trap pattern across all devices:

Desktop & Portable Devices (keyboard navigation)

Initial focus moves to the first interactive element: the Close button (always present). This ensures a predictable and accessible starting point regardless of the content inserted in the slot.
Tab / Shift+Tab cycle through all interactive elements inside the Modal in this order:
1. Close button
2. Interactive elements inside the content slot (if any)
3. Action buttons (horizontal or vertical set — optional)
4. Link (optional)
Focus cannot escape the Modal until it is closed.
When closing, focus returns to the element that triggered the Modal.

Mobile & Tablet (touch + assistive tech)

Mobile users do not navigate with a physical Tab key, but assistive technologies (VoiceOver, TalkBack, Switch Control) follow the same logical focus sequence defined for desktop.
The focus-trap still applies:
- Screen readers move through the elements in the same order: Close → Slot content → Action buttons (optional) → Link (optional).
- Users cannot reach content outside the Modal until it is closed.

Universal rule — Closing the Modal always returns accessibility focus to the element that opened it.

Usage

Do

Guidance on how to use a component.

Use a Modal when the user must focus on a single task or piece of information.
Always keep the Close Button visible and accessible.

Don’t

Guidance on what to avoid when using a component.

Avoid using a Modal for long or complex content. If the content becomes too long, consider using a dedicated page instead.
Do not stack multiple Modals.

Responsive Behaviour

The Modal adapts to each viewport to ensure usability and accessibility:

Desktop & Tablet — The component appears as a centred dialog with a backdrop.
Mobile — The same Modal automatically adopts a bottom-sheet layout (sliding up from the bottom). This layout improves touch interaction, keeps key actions reachable, and follows mobile accessibility conventions.

Both views share the same structure, slot, close button behaviour, and action sets. Only the layout changes.