Skip to main content
Styles

Border

Draft

A constrained set of width and color tokens that define element edges, separate content areas, and communicate interactivity.

thin / default1px
medium / strong2px
thick4px

Common alternative names

Stroke, outline, rule, divider, separator

Principles​

Borders are structural, not decorative​

Borders should communicate meaning — grouping related content, separating distinct regions, or indicating interactivity. Avoid using borders purely for visual embellishment. Every border should serve a clear purpose in the layout.

Use the minimum weight that works​

Start with the default (thin) border weight. Only reach for stronger weights when you need to convey emphasis or create a clear visual hierarchy. Heavier borders draw attention, so use them sparingly to preserve their impact.

Pair width and color intentionally​

A border's weight and color work together to set its visual prominence. A thin border in a subtle color recedes into the background, while a thick border in a strong color demands attention. Match the combination to the element's importance in the hierarchy.

Anatomy​

Arch UI borders are defined by two properties, each controlled by tokens:

WidthThe thickness of the border line. Controlled by --border-width-* tokens. Ranges from 0px (none) to 4px (thick).
ColorThe colour of the border line. Controlled by --color-border-* tokens. Adapts automatically between light and dark themes.

Border style is always solid in Arch UI. We do not provide tokens for dashed or dotted borders because they introduce visual noise and have inconsistent rendering across browsers.

Usage​

Separating content regions​

Use --border-width-default with --color-border-default to create subtle dividers between content areas — for example, between list items, table rows, or sidebar and main content.

Defining container boundaries​

Use --border-width-default with --color-border-subtle for card and container outlines. The subtle color keeps the border from competing with the content inside.

Communicating emphasis​

Use --border-width-strong with --color-border-strong when a border needs to stand out — for example, an active tab indicator, a selected state, or a section header underline.

Focus indicators​

Every interactive element must have a visible focus ring. Use --color-border-focus for focus outlines to ensure accessibility compliance.

Feedback states​

Use semantic border color tokens to communicate validation states:

StateTokenWhen to use
Danger--color-border-dangerValidation errors, destructive action boundaries
Success--color-border-successConfirmed inputs, success states
Warning--color-border-warningCaution indicators, partial validation
border: var(--border-width-default) solid var(--color-border-default);
✓ Do

Use border tokens for all border widths and colours. Tokens adapt to themes automatically and keep the system consistent.

border: 1px solid #e5e5e5;
✕ Don't

Hardcode pixel values or hex colours for borders. Raw values break theming and drift from the design system over time.

border-width: var(--border-width-default);
✓ Do

Default to --border-width-default (1px) for most UI borders. Only escalate to strong or thick when the design requires emphasis.

border-width: var(--border-width-thick);
✕ Don't

Use thick borders (4px) as a default container boundary. Heavy borders create visual clutter and reduce the prominence of intentional emphasis.