Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): strengthen borders under contrast: high (#4529)

Ernestc857354033d6
diff --git a/.changeset/high-contrast-borders.md b/.changeset/high-contrast-borders.md
new file mode 100644
index 0000000000..eb90a3b085
--- /dev/null
+++ b/.changeset/high-contrast-borders.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] theme: `color.contrast: 'high'` now strengthens border tokens too — the emphasized border tone is pulled toward mid-scale (stronger against both light and dark surfaces) and the subtle hairline's alpha is doubled, so structural boundaries stay perceivable in high-contrast themes instead of only text/icons changing.
+@ernestt
diff --git a/packages/core/src/theme/expandColorScale.test.ts b/packages/core/src/theme/expandColorScale.test.ts
index 02254b490b..341e68edec 100644
--- a/packages/core/src/theme/expandColorScale.test.ts
+++ b/packages/core/src/theme/expandColorScale.test.ts
@@ -100,6 +100,20 @@ describe('expandColorScale', () => {
standard['--color-text-primary'],
);
});
+
+ it('contrast high strengthens both border tokens', () => {
+ const standard = expandColorScale({
+ accent: '#0064E0',
+ contrast: 'standard',
+ });
+ const high = expandColorScale({accent: '#0064E0', contrast: 'high'});
+ // Both the subtle hairline and the emphasized border shift under high
+ // contrast, so structural boundaries stay perceivable.
+ expect(high['--color-border']).not.toBe(standard['--color-border']);
+ expect(high['--color-border-emphasized']).not.toBe(
+ standard['--color-border-emphasized'],
+ );
+ });
});
describe('expandColorScale — neutral-only themes (#2279)', () => {
diff --git a/packages/core/src/theme/expandColorScale.ts b/packages/core/src/theme/expandColorScale.ts
index f6b996ac31..a584a2df11 100644
--- a/packages/core/src/theme/expandColorScale.ts
+++ b/packages/core/src/theme/expandColorScale.ts
@@ -71,7 +71,9 @@ export interface ColorScaleConfig {
neutralStyle?: 'warm' | 'cool' | 'neutral';
/**
- * Contrast level. Affects tone assignments for text and UI elements.
+ * Contrast level. `'high'` pulls text, icons, and borders toward stronger
+ * tones (and thickens the subtle border's alpha) so structural and textual
+ * boundaries stay perceivable.
* @default 'standard'
*/
contrast?: 'standard' | 'high';
@@ -190,17 +192,25 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
const textSecondaryLightTone = isHigh ? 20 : 30;
const textSecondaryDarkTone = isHigh ? 80 : 70;
+ // Borders track contrast the same way text does: high contrast pulls the
+ // emphasized border tone toward mid-scale (stronger against both the near-
+ // white light surface and the near-black dark surface) and thickens the
+ // otherwise-decorative subtle hairline by doubling its alpha, so structural
+ // boundaries stay perceivable for users who opt into high contrast.
+ const borderSubtleAlpha = isHigh ? 0.2 : 0.1;
+
// Emphasized borders outline form controls (CheckboxInput, Selector), so
// they are non-text UI boundaries under WCAG 1.4.11 and must reach 3:1
- // against the surface they sit on. The preferred tones (70 light /
- // 30 dark) land around 2.2:1 / 1.8:1, so bump the tone toward the
- // opposing extreme until the ratio passes. Text tones need no such loop:
- // their spacing guarantees >= 4.5:1 for any hue/chroma (see file header).
+ // against the surface they sit on. High contrast starts at a more
+ // aggressive tone (50 vs 70/30), guaranteeing a stronger result; standard
+ // contrast starts at 70/30 and walks toward mid-scale only as far as needed.
+ const borderEmphasizedStartLight = isHigh ? 50 : 70;
+ const borderEmphasizedStartDark = isHigh ? 50 : 30;
const borderEmphasized = ld(
ensureContrastTone(
seedHue,
neutralVariantChroma,
- 70,
+ borderEmphasizedStartLight,
-1,
N[99],
NON_TEXT_MIN_CONTRAST,
@@ -208,7 +218,7 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
ensureContrastTone(
seedHue,
neutralVariantChroma,
- 30,
+ borderEmphasizedStartDark,
1,
N[10],
NON_TEXT_MIN_CONTRAST,
@@ -276,8 +286,13 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
'--color-background-inverted': ld(N[10], N[99]),
// Border
- // Decorative hairline (~1.1:1 by design) — not a WCAG 1.4.11 boundary.
- '--color-border': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[95], 0.1)),
+ // Border
+ // Decorative hairline — not a WCAG 1.4.11 boundary. High contrast
+ // doubles the alpha so structural boundaries stay perceivable.
+ '--color-border': ld(
+ hexWithAlpha(N[10], borderSubtleAlpha),
+ hexWithAlpha(N[95], borderSubtleAlpha),
+ ),
'--color-border-emphasized': borderEmphasized,
// Effects