Prepared Docs

Overview

Separator draws a visual rule between regions when whitespace alone does not communicate grouping—common between toolbars and content, settings sections, or toggle groups. Prefer increasing gap first; add separators when density or tinted backgrounds require explicit edges.

When to use

Neighboring regions share a background hue and would blur without a line.
Toolbars or headers need a crisp boundary above scrolling bodies.
Design specs call for a rule between two labeled sections inside one card.

When not to use

Spacing suffices—use FlexBox/Grid gap to avoid visual noise (Carbon-style restraint).
ToggleGroupItem already includes separators—do not double rules.
Purely decorative lines that do not clarify structure—remove them.

Variants

SeparatorColor tokens (Alt, Alt2) should be chosen for contrast on tinted panels; test in both themes.

Anatomy

Full-bleed or inset line per layout; orientation horizontal or vertical depending on parent flex direction.

Content guidelines

Separators carry no copy; nearby headings carry semantics.

Behavior and states

Separators are non-interactive and should not steal focus.

Best practices

Do align separator width with content grid padding—avoid random shorter rules without intent.
Do use tokens, not raw colors.
Don’t stack multiple parallel separators—signals a layout problem.
Don’t use separators to fix overcrowding—edit content or spacing first.

Accessibility

Expose separator role semantics per implementation so assistive tech ignores decorative lines appropriately.
Ensure separators do not imply clickable regions.

Toolbar for action clusters above content.
Toggle group for built-in separators.
Box for layout containers using borders instead of rules when appropriate.

Scrollable / Accessibility

Separator / API and Development

Overview

When to use

Neighboring regions share a background hue and would blur without a line.
Toolbars or headers need a crisp boundary above scrolling bodies.
Design specs call for a rule between two labeled sections inside one card.

When not to use

Spacing suffices—use FlexBox/Grid gap to avoid visual noise (Carbon-style restraint).
ToggleGroupItem already includes separators—do not double rules.
Purely decorative lines that do not clarify structure—remove them.

Variants

SeparatorColor tokens (Alt, Alt2) should be chosen for contrast on tinted panels; test in both themes.

Anatomy

Full-bleed or inset line per layout; orientation horizontal or vertical depending on parent flex direction.

Content guidelines

Separators carry no copy; nearby headings carry semantics.

Behavior and states

Separators are non-interactive and should not steal focus.

Best practices

Do align separator width with content grid padding—avoid random shorter rules without intent.
Do use tokens, not raw colors.
Don’t stack multiple parallel separators—signals a layout problem.
Don’t use separators to fix overcrowding—edit content or spacing first.

Accessibility

Expose separator role semantics per implementation so assistive tech ignores decorative lines appropriately.
Ensure separators do not imply clickable regions.

Toolbar for action clusters above content.
Toggle group for built-in separators.
Box for layout containers using borders instead of rules when appropriate.

Scrollable / Accessibility

Separator / API and Development