Focus Utility
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'.