Focus Utility

Some people use keyboards or other devices to navigate through a page by jumping from one interactive element to the next. Focus states let users know which element they’re currently on and is ready to be interacted with.

The focus outline utility provides a dual-ring focus indicator that maintains visibility across both light and dark themes. It automatically handles focus states using modern CSS selectors and follows WCAG accessibility guidelines.

For more information on focus and wider accessiblity guidelines, refer to our Accessiblity Guidelines.

Usage in Code

CSS

@import '@cosmos/foundation/src/utils/focus/index.css';

<button class="cosmos-focus">Button</button>

SCSS

@import '@cosmos/foundation/src/utils';

.my-interactive-element {
  @include cosmos-focus();
}

Less

@import '@cosmos/foundation/src/utils';

.my-interactive-element {
  .cosmos-focus();
}

Stylus

@import '@cosmos/foundation/src/utils'

.my-interactive-element
  cosmos-focus()

Customization

All implementations accept the same parameters with these defaults:

Parameter	Default	Description
radius	cosmos-radius-medium	Border radius of the focus ring
width	cosmos-border-medium	Width of the focus ring
offset	2px	Gap between element and focus ring
offset-x	2px	Horizontal offset override
offset-y	2px	Vertical offset override
accent-primary	cosmos-color-accent-focus	Inner focus ring color
accent-secondary	cosmos-color-surface-solid-light-lighter	Outer focus ring color

Example with custom parameters:

.my-interactive-element {
  @include cosmos-focus(
    $radius: $cosmos-radius-large,
    $width: $cosmos-border-thin,
    $offset: 4px, // setting the same value for offset-x + offset-y
    $offset-x: 4px, // override default offset value
    $offset-y: 4px, // override default offset value
    $accent-primary: $cosmos-color-accent-positive,
    $accent-secondary: $cosmos-color-surface-solid-dark-lighter
  );
}

Best Practices

✅ Do:

Apply to all interactive elements (buttons, links, form controls)

Ensure focus indicators have sufficient contrast ratio (minimum 3:1 against adjacent colors per WCAG 2.1 AA)

Use consistent parameters across your project to maintain visual coherence

❌ Don't:

Apply to purely decorative elements without interactive functionality

Customize accent colors unless required for specific accessibility needs (e.g., meeting higher contrast requirements)

Usage in Design

Focus is provided by the Cosmos Foundation and can be accessed via the Asset panel. Follow the steps below to properly apply a focus to focusable UI elements in Design.

Bring an instance of Focus into your design file.

Align Focus to the element with an additional 4px to height and width.

If nesting the focus in an auto-layout frame, position Focus absolute and center align with element.

Change the radius property of the Focus to match the element.

Rename the object or group containing the element and Focus as ‘focused-[element]’ for example 'focused-cosmos-button'.