Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/api-migrations.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,30 @@
# LUI API migration guide

### Foreground accent ink compatibility

`primary` and `accent` in a foreground slot retain their accent ink color;
they are not remapped to `primary-foreground` or `accent-foreground`. This
restores pre-ADR-0007 heading and icon contrast, including Android light
themes where `onPrimary` is white. Theme overrides for `primary` and `accent`
continue to select that ink on native backends. Explicit `*-foreground` values remain available
for content painted on a corresponding filled control.

Container and surface tokens such as `surface`, `card`, `secondary` and
`muted` still resolve to their ink counterparts in foreground slots. For
example, keep `text ~foreground:"primary" ~value:"General" []` for an
accent-colored heading, and use `~background:"primary"` with
`~foreground:"primary-foreground"` for text on a primary fill. Background
and border resolution is unchanged on all backends.

Web separates accent ink from its neutral accent fill: `foreground:"accent"`
uses `--lui-accent-ink` (`#1d4ed8` in light mode, `#93c5fd` in dark mode,
including system dark mode). These defaults meet 4.5:1 contrast against
background, secondary and accent fills. The fill tokens are unchanged;
`foreground:"primary"` still uses primary ink. Web themes can customize
`--lui-accent-ink` on their `[data-kb-theme]` scope independently of
`--lui-accent`. For example, use `--lui-accent-ink: #1d4ed8` for blue text
while keeping a pale neutral accent fill.

### Dynamic platform tweak attachment order

Anchorless dynamic segments now reconcile child edges from descendants to
Expand Down Expand Up @@ -616,7 +641,8 @@ that need fixed line spacing can supply an explicit `line_height` metric.
Existing colors, custom colors, theme overrides, and legacy aliases such as
`title2` and `mono` remain available. Newly admitted colors reuse existing
platform surfaces and accents rather than introducing a new palette.
Foreground slots resolve container tokens through their corresponding ink
Foreground slots resolve container tokens (excluding the accent ink names
`primary` and `accent`) through their corresponding ink
token: for example `~foreground:"secondary"` uses `secondary-foreground`, not
the pale secondary background. Explicit `*-foreground` theme overrides win.
Apple keeps its adaptive secondary style only when the corresponding
Expand Down
5 changes: 2 additions & 3 deletions platform/android/lui/src/main/kotlin/dev/lui/LuiTheme.kt
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ fun luiHexColor(name: String): Color? {
/** Resolves a semantic color name against the inherited token table then
* the Material 3 scheme, mirroring the Flutter `_color` mapping so both
* mobile hosts agree. [foreground] picks the "on-*" variant for pair
* tokens like `accent`/`secondary`/`warning`/`success`/`error`. */
* tokens like `secondary`/`warning`/`success`/`error`. */
@Composable
fun luiThemeColor(name: String?, foreground: Boolean = false): Color? {
if (name == null || (foreground && name.isBlank())) return null
Expand All @@ -100,8 +100,7 @@ internal val LocalLuiInheritedForeground = compositionLocalOf<Color?> { null }
internal val luiForegroundTokens = mapOf(
"background" to "foreground", "surface" to "foreground",
"surface-raised" to "foreground", "card" to "card-foreground",
"primary" to "primary-foreground", "secondary" to "secondary-foreground",
"accent" to "accent-foreground", "muted" to "muted-foreground",
"secondary" to "secondary-foreground", "muted" to "muted-foreground",
"destructive" to "destructive-foreground", "warning" to "warning-foreground",
"success" to "success-foreground", "info" to "info-foreground",
"glass" to "foreground", "bar" to "foreground",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,29 @@ class LuiDesignTokensTest {
}
assertEquals(scheme.onSecondaryContainer, resolveLuiThemeColor("secondary", true, emptyMap(), scheme))
assertEquals(scheme.secondaryContainer, resolveLuiThemeColor("secondary", false, emptyMap(), scheme))
assertEquals(scheme.onSecondaryContainer, resolveLuiThemeColor("accent", true, emptyMap(), scheme))
assertEquals(scheme.primary, resolveLuiThemeColor("accent", true, emptyMap(), scheme))
assertEquals(scheme.onPrimary, resolveLuiThemeColor("accent-foreground", true, emptyMap(), scheme))
assertEquals(Color.Red, resolveLuiThemeColor("secondary", true, mapOf("secondary-foreground" to Color.Red), scheme))
assertEquals(Color.Transparent, resolveLuiThemeColor("transparent", false, emptyMap(), scheme))
assertEquals(Color.Transparent, resolveLuiThemeColor("unknown", false, emptyMap(), scheme))
}
}

@Test fun accentInkIsNotReplacedByContainerContentColors() {
for (scheme in listOf(LuiThemeDefaults.lightScheme(), LuiThemeDefaults.darkScheme())) {
assertEquals(scheme.primary, resolveLuiThemeColor("primary", true, emptyMap(), scheme))
assertEquals(scheme.primary, resolveLuiThemeColor("accent", true, emptyMap(), scheme))
assertEquals(scheme.primary, resolveLuiThemeColor("primary", false, emptyMap(), scheme))
assertEquals(scheme.secondaryContainer, resolveLuiThemeColor("accent", false, emptyMap(), scheme))
val tokens = mapOf("primary" to Color.Red, "primary-foreground" to Color.White,
"accent" to Color.Blue, "accent-foreground" to Color.Yellow)
assertEquals(Color.Red, resolveLuiThemeColor("primary", true, tokens, scheme))
assertEquals(Color.Blue, resolveLuiThemeColor("accent", true, tokens, scheme))
assertEquals(Color.White, resolveLuiThemeColor("primary-foreground", true, tokens, scheme))
assertEquals(Color.Yellow, resolveLuiThemeColor("accent-foreground", true, tokens, scheme))
}
}

@Test fun singleLineIsAnExactClassToken() {
assertTrue(LuiTypography.singleLine("caption single-line semibold"))
assertFalse(LuiTypography.singleLine(null))
Expand Down
3 changes: 1 addition & 2 deletions platform/apple/Sources/LUIAppleBackend/LUIThemePolicy.swift
Original file line number Diff line number Diff line change
Expand Up @@ -358,8 +358,7 @@ enum LUIThemeColorResolver {
static let foregroundTokens = [
"background": "foreground", "surface": "foreground",
"surface-raised": "foreground", "card": "card-foreground",
"primary": "primary-foreground", "secondary": "secondary-foreground",
"accent": "accent-foreground", "muted": "muted-foreground",
"secondary": "secondary-foreground", "muted": "muted-foreground",
"destructive": "destructive-foreground", "success": "success-foreground",
"warning": "warning-foreground", "info": "info-foreground",
"glass": "foreground", "bar": "foreground",
Expand Down
3 changes: 1 addition & 2 deletions platform/native/lui_paint/lui_paint.ml
Original file line number Diff line number Diff line change
Expand Up @@ -578,8 +578,7 @@ let pbool store id name =
let foreground_tokens =
[ "background", "foreground"; "surface", "surface-foreground";
"surface-raised", "surface-raised-foreground"; "card", "card-foreground";
"primary", "primary-foreground"; "secondary", "secondary-foreground";
"accent", "accent-foreground"; "muted", "muted-foreground";
"secondary", "secondary-foreground"; "muted", "muted-foreground";
"destructive", "destructive-foreground"; "warning", "warning-foreground";
"success", "success-foreground"; "info", "info-foreground";
"glass", "foreground"; "bar", "foreground" ]
Expand Down
13 changes: 12 additions & 1 deletion platform/native/test/lui_native_test.ml
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,16 @@ let test_blur_weight () =

(* ---------- store→paint pipeline ---------- *)

let test_foreground_tokens () =
List.iter (fun token ->
check string "accent ink and explicit ink tokens stay unchanged" token
(Lui_paint.foreground_token token))
["primary"; "accent"; "primary-foreground"; "accent-foreground"; "#123456"];
check string "surface colors still select their ink" "surface-foreground"
(Lui_paint.foreground_token "surface");
check string "secondary containers still select their ink" "secondary-foreground"
(Lui_paint.foreground_token "secondary")

let test_pipeline () =
let t = Lui_store.create () in
Lui_store.apply_batch t
Expand Down Expand Up @@ -142,4 +152,5 @@ let () =
test_case "backdrop" `Quick test_backdrop_of;
test_case "blur weight" `Quick test_blur_weight ]);
("pipeline",
[ test_case "store→paint" `Quick test_pipeline ]) ]
[ test_case "foreground tokens" `Quick test_foreground_tokens;
test_case "store→paint" `Quick test_pipeline ]) ]
6 changes: 3 additions & 3 deletions platform/web/melange/core/lui_web_util.ml
Original file line number Diff line number Diff line change
Expand Up @@ -524,8 +524,7 @@ let semantic_color_names =
let foreground_tokens =
[ "background", "foreground"; "surface", "surface-foreground";
"surface-raised", "surface-raised-foreground"; "card", "card-foreground";
"primary", "primary-foreground"; "secondary", "secondary-foreground";
"accent", "accent-foreground"; "muted", "muted-foreground";
"secondary", "secondary-foreground"; "muted", "muted-foreground";
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
"destructive", "destructive-foreground"; "warning", "warning-foreground";
"success", "success-foreground"; "info", "info-foreground";
"glass", "glass-foreground"; "bar", "bar-foreground" ]
Expand All @@ -535,7 +534,8 @@ let radius_tokens = [ "none", 0; "sm", 4; "md", 6; "lg", 8; "xl", 12; "full", 99

let web_color_value ?(foreground = false) color =
let color = if foreground then Option.value ~default:color (List.assoc_opt color foreground_tokens) else color in
if color = "transparent" then "transparent"
if foreground && color = "accent" then "var(--color-accent-ink)"
else if color = "transparent" then "transparent"
(* Material names (Apple glass/bar surfaces) have no CSS equivalent;
approximate with a translucent theme surface. *)
else if color = "glass" || color = "glass-container" || color = "bar" then
Expand Down
4 changes: 4 additions & 0 deletions platform/web/src/lui.css
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
}

:root, .dark, [data-kb-theme] {
--color-accent-ink: var(--lui-accent-ink);
--lui-surface: var(--lui-secondary);
--lui-surface-raised: var(--lui-card);
--lui-muted: var(--lui-secondary);
Expand Down Expand Up @@ -69,6 +70,7 @@
--lui-secondary: oklch(0.97 0 0);
--lui-secondary-foreground: oklch(0.205 0 0);
--lui-accent: oklch(0.97 0 0);
--lui-accent-ink: #1d4ed8;
--lui-accent-foreground: oklch(0.205 0 0);
--lui-muted-foreground: oklch(0.556 0 0);
--lui-destructive: oklch(0.577 0.245 27.325);
Expand Down Expand Up @@ -98,6 +100,7 @@
--lui-secondary: oklch(0.269 0 0);
--lui-secondary-foreground: oklch(0.985 0 0);
--lui-accent: oklch(0.269 0 0);
--lui-accent-ink: #93c5fd;
--lui-accent-foreground: oklch(0.985 0 0);
--lui-muted-foreground: oklch(0.708 0 0);
--lui-destructive: oklch(0.396 0.141 25.723);
Expand Down Expand Up @@ -127,6 +130,7 @@
--lui-secondary: oklch(0.269 0 0);
--lui-secondary-foreground: oklch(0.985 0 0);
--lui-accent: oklch(0.269 0 0);
--lui-accent-ink: #93c5fd;
--lui-accent-foreground: oklch(0.985 0 0);
--lui-muted-foreground: oklch(0.708 0 0);
--lui-destructive: oklch(0.396 0.141 25.723);
Expand Down
45 changes: 45 additions & 0 deletions platform/web/test/design-tokens.test.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import assert from 'node:assert/strict';
import {readFileSync} from 'node:fs';
import test from 'node:test';
import {chromium} from 'playwright';

const build = process.env.LUI_TEST_BUILD_DIR ?? '_build';
const Util = await import(new URL(`../../../${build}/default/examples/components/web/lui-components-web/node_modules/lui.web.dom/core/lui_web_util.js`, import.meta.url));
Expand All @@ -14,11 +15,55 @@ test('canonical colors resolve as CSS values and container foregrounds resolve a
assert.equal(Util.web_color_value(true, 'secondary'), 'var(--color-secondary-foreground)');
assert.equal(Util.web_color_value(undefined, 'secondary'), 'var(--color-secondary)');
assert.equal(Util.web_color_value(true, 'surface'), 'var(--color-surface-foreground)');
for (const color of ['primary', 'primary-foreground', 'accent-foreground']) {
assert.equal(Util.web_color_value(true, color), `var(--color-${color})`);
}
assert.equal(Util.web_color_value(true, 'accent'), 'var(--color-accent-ink)');
assert.equal(Util.web_color_value(false, 'accent'), 'var(--color-accent)');
assert.equal(Util.web_color_value(true, '#123456'), '#123456');
assert.equal(Util.web_color_value(undefined, ''), '');
assert.equal(Util.web_color_value(undefined, 'custom-token'), 'custom-token');
});

test('accent ink contrasts with unchanged background, secondary and accent fills', async () => {
const browser = await chromium.launch({headless: true});
try {
const page = await browser.newPage();
const css = readFileSync(new URL('../dist/lui.css', import.meta.url), 'utf8');
for (const mode of ['light', 'dark', 'system']) {
await page.emulateMedia({colorScheme: mode === 'light' ? 'light' : 'dark'});
await page.setContent(`<style>${css}</style><section data-kb-theme="${mode}"></section>`);
const results = await page.evaluate(ink => {
const scope = document.querySelector('section');
const canvas = document.createElement('canvas').getContext('2d', {willReadFrequently: true});
const luminance = color => {
canvas.fillStyle = color;
canvas.fillRect(0, 0, 1, 1);
return [...canvas.getImageData(0, 0, 1, 1).data].slice(0, 3)
.map(value => value / 255)
.map(value => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4)
.reduce((sum, value, index) => sum + value * [0.2126, 0.7152, 0.0722][index], 0);
};
return ['background', 'secondary', 'accent'].map(fill => {
scope.style.color = ink;
scope.style.backgroundColor = `var(--color-${fill})`;
const style = getComputedStyle(scope);
const a = luminance(style.color), b = luminance(style.backgroundColor);
return {fill, background: style.backgroundColor,
contrast: (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)};
});
}, Util.web_color_value(true, 'accent'));
assert.equal(results[1].background, results[2].background, 'accent fill stays secondary');
for (const {fill, contrast} of results) {
console.log(`${mode} accent ink on ${fill}: ${contrast.toFixed(2)}:1`);
assert.ok(contrast >= 4.5, `${mode} ${fill}: ${contrast}`);
}
}
} finally {
await browser.close();
}
});

test('built CSS retains semantic typography and single-line truncation', () => {
const css = readFileSync(new URL('../dist/lui.css', import.meta.url), 'utf8');
for (const name of [...vocabulary.textRoles, ...vocabulary.textModifiers]) {
Expand Down
5 changes: 4 additions & 1 deletion tooling/test/design-token-parity.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ test('every canonical color resolves in each backend and both native palettes',
});

test('container colors have admitted foreground counterparts rather than raw fills', () => {
const nonContainers = new Set(['foreground', 'muted-foreground', 'border', 'input', 'ring', 'transparent']);
const nonContainers = new Set(['primary', 'accent', 'foreground', 'muted-foreground', 'border', 'input', 'ring', 'transparent']);
const containers = vocabulary.colors.filter(name => !nonContainers.has(name));
const tables = {
Web: [between(web, 'let foreground_tokens =', 'let space_tokens'), /"([^"]+)",\s*"([^"]+)"/g],
Expand All @@ -52,6 +52,9 @@ test('container colors have admitted foreground counterparts rather than raw fil
};
for (const [backend, [source, pattern]] of Object.entries(tables)) {
const pairs = new Map([...source.matchAll(pattern)].map(m => [m[1], m[2]]));
for (const name of ['primary', 'accent']) {
assert.equal(pairs.get(name), undefined, `${backend} keeps ${name} as accent ink`);
}
const admitted = colorTables[backend === 'Native' ? 'NativeLight' : backend];
for (const name of containers) {
const target = pairs.get(name);
Expand Down
Loading