Minimal role token adoption

package.json

@@ -34,6 +34,10 @@
     "ci": "npm run test && npm run lint && npm run build && npx prettier --check src",
     "deploy": "website-deploy-aws",
     "panda": "panda codegen",
+    "dev:link-ui": "rm -rf node_modules/@microbit/ui && ln -s ../../../ui/packages/ui node_modules/@microbit/ui && rm -rf styled-system && npm run panda",
+    "dev:link-ui-patterns": "rm -rf node_modules/@microbit/ui-patterns && ln -s ../../../ui/packages/ui-patterns node_modules/@microbit/ui-patterns && rm -rf styled-system && npm run panda",
+    "dev:link-theme": "npm --prefix ../ml-trainer-microbit run build && mkdir -p node_modules/@microbit-foundation && rm -rf node_modules/@microbit-foundation/ml-trainer-microbit && ln -s ../../../ml-trainer-microbit node_modules/@microbit-foundation/ml-trainer-microbit && rm -rf styled-system && npm run panda",
+    "dev:unlink-theme": "rm -rf node_modules/@microbit-foundation/ml-trainer-microbit && rm -rf styled-system && npm run panda",
     "predev": "npm run panda",
     "dev": "cross-env VITE_VERSION=$npm_package_version vite",
     "dev:apps": "cross-env VITE_BUILD_MODE=apps VITE_VERSION=$npm_package_version vite --host",

src/compliance/NativeConsentDialog.tsx

@@ -57,6 +57,7 @@ export const NativeConsentDialog = ({
               <>
                 {" "}
                 <Link
+                  color="fg.link"
                   href={privacyPolicyLink}
                   target="_blank"
                   rel="noopener noreferrer"

src/components/AboutDialog.tsx

@@ -88,7 +88,7 @@ const AboutDialog = ({ isOpen, onClose, finalFocusRef }: AboutDialogProps) => {
               values={{
                 link: (chunks: ReactNode) => (
                   <Link
-                    color="brand.600"
+                    color="fg.link"
                     textDecoration="underline"
                     href="https://cctd.au.dk/"
                     target="_blank"

src/components/ActionBar/ActionBar.tsx

@@ -41,7 +41,7 @@ const ActionBar = ({
       as="header"
       gap={0}
       {...darkSurface}
-      bg="statusBarBg"
+      bg="surface.statusBar"
       css={{ "--inset-top": "env(safe-area-inset-top)" }}
       {...rest}
     >

src/components/BrokenFirmwareDialog.tsx

@@ -54,7 +54,7 @@ const BrokenFirmwareDialog = ({
               values={{
                 link: (chunks: ReactNode) => (
                   <Link
-                    color="brand.600"
+                    color="fg.link"
                     textDecoration="underline"
                     href="https://microbit.org/get-started/user-guide/firmware/"
                     target="_blank"
@@ -68,7 +68,7 @@ const BrokenFirmwareDialog = ({
           </Text>
           <Text w="100%">
             <Link
-              color="brand.600"
+              color="fg.link"
               textDecoration="underline"
               href={supportLinks.troubleshooting}
               target="_blank"

src/components/ConnectBatteryDialog.tsx

@@ -23,7 +23,7 @@ const ConnectBatteryDialog = ({ ...props }: ConnectBatteryDialogProps) => {
         <Text alignSelf="left" width="100%">
           <FormattedMessage id="connect-battery-subtitle" />
           <Link
-            color="brand.600"
+            color="fg.link"
             textDecoration="underline"
             href={supportLinks.wearable}
             target="_blank"

src/components/DownloadProgressDialog.tsx

@@ -140,11 +140,7 @@ const DownloadProgressDialog = ({
       </ModalBody>
       <ModalFooter css={{ justifyContent: "start" }}>
         {isNativePlatform() && tryAgain && isFindingDevice && (
-          <Button
-            variant="link"
-            css={{ color: "brand.600" }}
-            onPress={tryAgain}
-          >
+          <Button variant="link" css={{ color: "fg.link" }} onPress={tryAgain}>
             <FormattedMessage id="connect-native-change-pattern" />
           </Button>
         )}

src/components/ErrorHandlerErrorView.tsx

@@ -30,7 +30,7 @@ const ErrorHandlerErrorView = ({ error }: ErrorHandlerErrorViewProps) => {
             values={{
               link: (chunks: ReactNode) => (
                 <Link
-                  color="brand.600"
+                  color="fg.link"
                   textDecoration="underline"
                   href="https://support.microbit.org"
                   target="_blank"

src/components/IncompatibleEditorDevice.tsx

@@ -60,7 +60,7 @@ const IncompatibleEditorDevice = ({
                 values={{
                   link: (children) => (
                     <Link
-                      color="brand.600"
+                      color="fg.link"
                       textDecoration="underline"
                       href="https://support.microbit.org/support/solutions/articles/19000154234-which-version-of-micro-bit-do-i-have-"
                       target="_blank"
@@ -85,7 +85,7 @@ const IncompatibleEditorDevice = ({
                         <Button
                           variant="link"
                           css={{
-                            color: "brand.600",
+                            color: "fg.link",
                             textDecoration: "underline",
                           }}
                           onPress={() => saveHex(SaveType.Download)}

src/components/NotFound.tsx

@@ -19,7 +19,7 @@ const NotFound = ({ href }: NotFoundProps) => {
   return (
     <ErrorPage title={intl.formatMessage({ id: "not-found-title" })}>
       <Link
-        color="brand.600"
+        color="fg.link"
         textDecoration="underline"
         href={href ? href : createHomePageUrl()}
       >

src/components/UnsupportedMicrobitDialog.tsx

@@ -51,7 +51,7 @@ const UnsupportedMicrobitDialog = ({
               values={{
                 link: (chunks: ReactNode) => (
                   <Link
-                    color="brand.600"
+                    color="fg.link"
                     textDecoration="underline"
                     href="https://support.microbit.org/support/solutions/articles/19000119162"
                     target="_blank"
@@ -72,7 +72,7 @@ const UnsupportedMicrobitDialog = ({
                 values={{
                   link: (chunks: ReactNode) => (
                     <Link
-                      color="brand.600"
+                      color="fg.link"
                       textDecoration="underline"
                       href={supportLinks.bluetooth}
                       target="_blank"

src/deployment/default/panda-preset.test.ts

@@ -0,0 +1,54 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import {
+  droppedConditionTokens,
+  unknownSemanticTokens,
+} from "@microbit/ui/preset-lint";
+import { createRequire } from "node:module";
+import { describe, expect, it } from "vitest";
+import { appPreset } from "./panda-preset";
+
+// Panda accepts an unknown `semanticTokens` key silently — the override
+// never applies and nothing fails, so a rename in @microbit/ui would leave
+// this app on the library's colours with a green typecheck. See the
+// CSS-variable contract in @microbit/ui's README.
+
+it("app preset overrides only semantic tokens @microbit/ui defines", () => {
+  expect(unknownSemanticTokens(appPreset)).toEqual([]);
+});
+
+// A flat override of a { base, _onDark } token merges wholesale and
+// silently drops the dark-surface flip — the same failure, one door over.
+it("app preset keeps every condition the base preset's tokens carry", () => {
+  expect(droppedConditionTokens(appPreset)).toEqual([]);
+});
+
+// The private brand preset is optional — present only when linked
+// (`npm run dev:link-theme`) or installed in a brand build, exactly as
+// panda.config.ts treats it. Checked here rather than in its own repo so
+// that repo stays free of a dependency on this library, and because the
+// merge this guards against happens on this side.
+const require = createRequire(import.meta.url);
+let brandPreset: unknown;
+try {
+  brandPreset = (
+    require("@microbit-foundation/ml-trainer-microbit/panda-preset") as {
+      default: unknown;
+    }
+  ).default;
+} catch {
+  brandPreset = undefined;
+}
+
+describe.skipIf(!brandPreset)("private brand preset", () => {
+  it("overrides only semantic tokens @microbit/ui defines", () => {
+    expect(unknownSemanticTokens(brandPreset)).toEqual([]);
+  });
+
+  it("keeps every condition the base preset's tokens carry", () => {
+    expect(droppedConditionTokens(brandPreset)).toEqual([]);
+  });
+});

src/deployment/default/panda-preset.ts

@@ -271,7 +271,7 @@ export const appPreset = definePreset({
           // The native app's status-bar area (the ActionBar and the
           // full-screen dialog's safe-area gradient) follows the second
           // accent.
-          statusBarBg: { value: "{colors.brand2.500}" },
+          surface: { statusBar: { value: "{colors.brand2.500}" } },
         },
       },
       // This app's button vocabulary, merged into the core `button` recipe.
@@ -309,8 +309,8 @@ export const appPreset = definePreset({
               // pressed. Same tokens as `secondary` so the two can't drift.
               "secondary-disabled": {
                 borderWidth: "2px",
-                borderColor: "button.secondaryBorder",
-                color: "button.secondaryText",
+                borderColor: "button.secondary.border",
+                color: "button.secondary.fg",
                 bg: "transparent",
                 opacity: "0.4",
               },

src/pages/OpenSharedProjectPage.tsx

@@ -99,7 +99,7 @@ const OpenSharedProjectPage = () => {
                     values={{
                       link: (children: ReactNode) => (
                         <Link
-                          color="brand.600"
+                          color="fg.link"
                           textDecoration="underline"
                           href={`https://makecode.microbit.org/${encodeURIComponent(
                             shareId!