Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Add coordinated workspace palettes in Appearance

deeb3a3030704ac
diff --git a/desktop/lib/main.dart b/desktop/lib/main.dart
index e5846c83f..1b436d246 100644
--- a/desktop/lib/main.dart
+++ b/desktop/lib/main.dart
@@ -58,6 +58,7 @@ class DesktopApp extends StatelessWidget {
}
Widget _app(AppearancePrefs prefs) {
+ grid.AppTheme.palette.value = prefs.palette;
// ⚠️ ORDER MATTERS, and it is why this is a statement rather than something
// tucked into the tree below: `buildAppTheme` reads `AppFont.sans` and
// `AppControl.*Scaled`, so the settings have to be on `AppFont` BEFORE the
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 2253a915d..434ac5ccc 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -87,6 +87,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
app.addListener(_recordNavigation);
FocusManager.instance.addListener(_restoreEmptyFocus);
_searchFocus.addListener(_searchFocusChanged);
+ grid.AppTheme.palette.addListener(_paletteChanged);
unawaited(_projects.load());
_spokenTasks = app.spokenTasks.listen(_openSpokenTask);
if (_native) {
@@ -117,6 +118,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
@override
void dispose() {
+ grid.AppTheme.palette.removeListener(_paletteChanged);
app.removeListener(_recordNavigation);
FocusManager.instance.removeListener(_restoreEmptyFocus);
_searchOverlay?.remove();
@@ -173,10 +175,16 @@ class _SwarmScreenState extends State<SwarmScreen> {
// output. Never-attached setup guides have no buffer to search.
bool get _canFindTerminal => app.focusedPane?.session != null;
+ void _paletteChanged() {
+ _searchOverlay?.markNeedsBuild();
+ if (_native) _syncNative();
+ }
+
void _syncNative() {
final payload = {
'enabled': _routeIsCurrent && !_dialogOpen && !_spokenPaletteOpen,
'activeId': app.activeSwarmId,
+ 'palette': grid.AppTheme.palette.value.nativeColors,
'canReopen': app.canReopenLastClosed,
'canFind': _canFindTerminal,
'canClosePane': app.focusedPane != null,
diff --git a/desktop/lib/settings/appearance/palette_section.dart b/desktop/lib/settings/appearance/palette_section.dart
new file mode 100644
index 000000000..ec14a4cea
--- /dev/null
+++ b/desktop/lib/settings/appearance/palette_section.dart
@@ -0,0 +1,246 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+
+import '../../shared/theme/app_theme.dart' as grid;
+import '../../shared/theme/appearance_prefs_store.dart';
+import '../../shared/theme/color_palette.dart';
+import '../../shared/widgets/section_heading.dart';
+
+class PaletteSection extends StatelessWidget {
+ const PaletteSection({super.key, this.store});
+ final AppearancePrefsStore? store;
+
+ @override
+ Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
+ final preferences = store ?? appearancePrefsStore;
+ return ValueListenableBuilder<AppearancePrefs>(
+ valueListenable: preferences,
+ builder: (context, prefs, _) => Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ const SectionHeading(
+ 'Color palette',
+ subtitle: 'A coordinated look for your tabs, search and agents. Changes apply instantly.',
+ ),
+ LayoutBuilder(
+ builder: (context, constraints) {
+ final columns = constraints.maxWidth >= 660
+ ? 3
+ : constraints.maxWidth >= 360
+ ? 2
+ : 1;
+ final width =
+ (constraints.maxWidth - 12 * (columns - 1)) / columns;
+ return Wrap(
+ spacing: 12,
+ runSpacing: 12,
+ children: [
+ for (final palette in HarnessPalette.values)
+ SizedBox(
+ width: width,
+ child: _PaletteChoice(
+ palette: palette,
+ selected: prefs.palette == palette,
+ onChoose: () =>
+ unawaited(preferences.setPalette(palette)),
+ ),
+ ),
+ ],
+ );
+ },
+ ),
+ const SizedBox(height: 24),
+ ],
+ ),
+ );
+ }
+}
+
+class _PaletteChoice extends StatelessWidget {
+ const _PaletteChoice({
+ required this.palette,
+ required this.selected,
+ required this.onChoose,
+ });
+ final HarnessPalette palette;
+ final bool selected;
+ final VoidCallback onChoose;
+
+ @override
+ Widget build(BuildContext context) => Semantics(
+ button: true,
+ selected: selected,
+ onTap: onChoose,
+ label: '${palette.label} palette. ${palette.description}',
+ child: ExcludeSemantics(
+ child: TextButton(
+ key: ValueKey('palette-${palette.name}'),
+ onPressed: onChoose,
+ style: ButtonStyle(
+ padding: const WidgetStatePropertyAll(EdgeInsets.all(8)),
+ backgroundColor: WidgetStatePropertyAll(palette.panel),
+ overlayColor: const WidgetStatePropertyAll(Colors.white10),
+ side: WidgetStateProperty.resolveWith(
+ (states) => BorderSide(
+ color: selected || states.contains(WidgetState.focused)
+ ? palette.accent
+ : Colors.white12,
+ width: selected || states.contains(WidgetState.focused) ? 1.5 : 1,
+ ),
+ ),
+ shape: WidgetStatePropertyAll(
+ RoundedRectangleBorder(borderRadius: BorderRadius.circular(10)),
+ ),
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ _WorkspacePreview(palette: palette),
+ const SizedBox(height: 8),
+ Row(
+ children: [
+ Expanded(
+ child: Text(
+ palette.label,
+ style: const TextStyle(
+ fontSize: 13,
+ color: Colors.white,
+ fontWeight: FontWeight.w500,
+ ),
+ ),
+ ),
+ SizedBox(
+ width: 16,
+ child: selected
+ ? Icon(Icons.check, size: 16, color: palette.accent)
+ : null,
+ ),
+ ],
+ ),
+ const SizedBox(height: 2),
+ Text(
+ palette.description,
+ style: const TextStyle(fontSize: 11, color: Colors.white70),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+}
+
+class _WorkspacePreview extends StatelessWidget {
+ const _WorkspacePreview({required this.palette});
+ final HarnessPalette palette;
+
+ @override
+ Widget build(BuildContext context) => ClipRRect(
+ borderRadius: BorderRadius.circular(4),
+ child: SizedBox(
+ height: 76,
+ child: ColoredBox(
+ color: palette.workspace,
+ child: Column(
+ children: [
+ ColoredBox(
+ color: palette.tabBar,
+ child: SizedBox(
+ height: 16,
+ child: Row(
+ children: [
+ const SizedBox(width: 6),
+ for (var i = 0; i < 3; i++)
+ Padding(
+ padding: const EdgeInsets.only(right: 3),
+ child: Container(
+ width: 3,
+ height: 3,
+ decoration: const BoxDecoration(
+ color: Colors.white38,
+ shape: BoxShape.circle,
+ ),
+ ),
+ ),
+ const SizedBox(width: 6),
+ Container(
+ width: 40,
+ height: 12,
+ margin: const EdgeInsets.only(top: 4),
+ color: palette.workspace,
+ ),
+ const Spacer(),
+ Container(
+ width: 28,
+ height: 6,
+ margin: const EdgeInsets.only(right: 6),
+ decoration: BoxDecoration(
+ color: palette.search,
+ borderRadius: BorderRadius.circular(3),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ Expanded(
+ child: Padding(
+ padding: const EdgeInsets.all(4),
+ child: Row(
+ children: [
+ for (var pane = 0; pane < 2; pane++) ...[
+ if (pane > 0) const SizedBox(width: 4),
+ Expanded(
+ child: Container(
+ padding: const EdgeInsets.all(6),
+ decoration: BoxDecoration(
+ color: palette.background,
+ borderRadius: BorderRadius.circular(3),
+ border: pane == 0
+ ? Border.all(
+ color: palette.accent.withValues(
+ alpha: 0.65,
+ ),
+ )
+ : null,
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Container(
+ width: 20,
+ height: 3,
+ color: palette.accent,
+ ),
+ const SizedBox(height: 6),
+ FractionallySizedBox(
+ widthFactor: 0.85,
+ child: Container(
+ height: 2,
+ color: Colors.white54,
+ ),
+ ),
+ const SizedBox(height: 4),
+ FractionallySizedBox(
+ widthFactor: 0.6,
+ child: Container(
+ height: 2,
+ color: Colors.white30,
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ ],
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+}
diff --git a/desktop/lib/settings/sections/appearance_section.dart b/desktop/lib/settings/sections/appearance_section.dart
index c403425a0..00f19f54b 100644
--- a/desktop/lib/settings/sections/appearance_section.dart
+++ b/desktop/lib/settings/sections/appearance_section.dart
@@ -3,15 +3,12 @@ import 'package:flutter/material.dart';
import '../../shared/theme/app_theme.dart' as grid;
import '../../shared/widgets/section_scaffold.dart';
import '../appearance/typography_section.dart';
+import '../appearance/palette_section.dart';
/// Settings ▸ Appearance: how the app looks on this Mac.
///
-/// ⚠️ The APP, not the terminal. Everything on this screen stops at the edge of
-/// a terminal pane: the pane renders a grid a remote program is drawing into, so
-/// it carries its own face and size in Settings ▸ Terminal, and the UI scale is
-/// held out of it at five separate seams — see `terminal_panel.dart`,
-/// `terminal_composer.dart`, `engine_identity.dart` and `terminal_section.dart`,
-/// with `test/terminal_ui_scale_isolation_test.dart` standing guard.
+/// Palettes coordinate the workspace and terminal defaults. UI typography stays
+/// separate from the agent terminal's font and size in Settings ▸ Terminal.
class AppearanceSection extends StatelessWidget {
const AppearanceSection({super.key});
@@ -20,11 +17,12 @@ class AppearanceSection extends StatelessWidget {
grid.AppTheme.watch(context);
return SectionScaffold(
title: 'Appearance',
- subtitle: 'How Harness looks on this Mac. Harness Desktop is dark-only.',
+ subtitle: 'Make your workspace feel like yours.',
child: SingleChildScrollView(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: const [
+ PaletteSection(),
TypographySection(),
// Room under the last card so a scrolled-to-bottom pane does not end
// flush against the window edge.
diff --git a/desktop/lib/shared/theme/app_theme.dart b/desktop/lib/shared/theme/app_theme.dart
index ebbcc5f9d..0e87232cd 100644
--- a/desktop/lib/shared/theme/app_theme.dart
+++ b/desktop/lib/shared/theme/app_theme.dart
@@ -2,6 +2,8 @@ import 'dart:io' show Platform;
import 'package:flutter/material.dart';
+import 'color_palette.dart';
+
/// The app's live brightness — the single source of truth the color tokens below
/// resolve against. Harness Desktop is dark-only: `_GridTokenScope` (in
/// `main.dart`) pins this to [Brightness.dark] once, at the top of the tree.
@@ -20,6 +22,7 @@ abstract final class AppTheme {
/// through the same [watch], since a widget that reads one token generally
/// reads both.
static final FontNotifier fonts = FontNotifier();
+ static final palette = ValueNotifier(HarnessPalette.graphite);
static bool get isDark => brightness.value == Brightness.dark;
@@ -81,6 +84,7 @@ abstract final class AppTheme {
static Brightness watch(BuildContext context) {
context.dependOnInheritedWidgetOfExactType<_BrightnessScope>();
context.dependOnInheritedWidgetOfExactType<_FontScope>();
+ context.dependOnInheritedWidgetOfExactType<_PaletteScope>();
return brightness.value;
}
}
@@ -158,7 +162,10 @@ class BrightnessScope extends StatelessWidget {
Widget build(BuildContext context) {
return _BrightnessScope(
notifier: AppTheme.brightness,
- child: _FontScope(notifier: AppTheme.fonts, child: child),
+ child: _FontScope(
+ notifier: AppTheme.fonts,
+ child: _PaletteScope(notifier: AppTheme.palette, child: child),
+ ),
);
}
}
@@ -171,17 +178,21 @@ class _FontScope extends InheritedNotifier<FontNotifier> {
const _FontScope({required super.notifier, required super.child});
}
+class _PaletteScope extends InheritedNotifier<ValueNotifier<HarnessPalette>> {
+ const _PaletteScope({required super.notifier, required super.child});
+}
+
/// The app's palette — a warm paper white with near-black ink in light, a deep
/// charcoal with off-white ink in dark (the design-system "Codex" direction).
/// Centralized so every pane reads the same surfaces/accents instead of re-typing
/// hex literals, and resolves per [AppTheme.brightness].
abstract final class AppPalette {
// Approved Swarms canvas and native tab-strip palette.
- static Color get swarmField => const Color(0xff463746);
- static Color get swarmTabBar => const Color(0xff332936);
- static Color get swarmAccent => const Color(0xffd8cce1);
+ static Color get swarmField => AppTheme.palette.value.workspace;
+ static Color get swarmTabBar => AppTheme.palette.value.tabBar;
+ static Color get swarmAccent => AppTheme.palette.value.accent;
// Shared with the native search field for a continuous input/results surface.
- static Color get swarmSearchSurface => const Color(0xff3d333f);
+ static Color get swarmSearchSurface => AppTheme.palette.value.search;
// the conversation / content area — pure white in light, like Codex.
//
@@ -192,19 +203,19 @@ abstract final class AppPalette {
// therefore carried by the rim and the shadow, not by the fill — §2's stack
// still holds, it just has less room to say it in.
static Color get windowBg =>
- AppTheme.pick(const Color(0xFFFFFFFF), const Color(0xFF181818));
+ AppTheme.pick(const Color(0xFFFFFFFF), AppTheme.palette.value.background);
// sidebar column — a barely-there cool grey (Codex keeps the rail almost white,
// set apart by a hairline, not a tone) / charcoal panel in dark.
static Color get panelBg =>
- AppTheme.pick(const Color(0xFFF9F9F8), const Color(0xFF141414));
+ AppTheme.pick(const Color(0xFFF9F9F8), AppTheme.palette.value.panel);
// input fills, quiet cards
static Color get cardBg =>
- AppTheme.pick(const Color(0xFFF3F3F2), const Color(0xFF1E1E1E));
+ AppTheme.pick(const Color(0xFFF3F3F2), AppTheme.palette.value.card);
static Color get cardBgHover =>
- AppTheme.pick(const Color(0xFFECECEA), const Color(0xFF252525));
+ AppTheme.pick(const Color(0xFFECECEA), AppTheme.palette.value.hover);
// A hairline separator. Light: a faint cool black; dark: a faint white — a
// black divider would vanish on charcoal.
@@ -263,7 +274,7 @@ abstract final class AppPalette {
/// it is the fill under white text in ~100 places, and lightening it there
/// would drop that text to ~3.1:1 — fixing the icon by breaking the buttons.
static Color get accentOnSurface =>
- AppTheme.pick(const Color(0xFF2F5BEA), const Color(0xFF6E8BFF));
+ AppTheme.pick(const Color(0xFF2F5BEA), AppTheme.palette.value.accent);
// avatar fill (white text on it); a touch brighter in dark for contrast.
static Color get accentMuted =>
@@ -895,17 +906,17 @@ abstract final class AppCard {
ThemeData buildAppTheme({Brightness brightness = Brightness.light}) {
final isDark = brightness == Brightness.dark;
final scheme = isDark
- ? const ColorScheme.dark(
+ ? ColorScheme.dark(
primary: AppPalette.accent,
onPrimary: Colors.white,
secondary: AppPalette.accent,
- surface: Color(0xFF181818),
- onSurface: Color(0xFFF5F5F5),
- onSurfaceVariant: Color(0xFFA8A8A2),
- surfaceContainerHighest: Color(0xFF1E1E1E),
- outline: Color(0x14FFFFFF),
- outlineVariant: Color(0x14FFFFFF),
- error: Color(0xFFF2544B),
+ surface: AppTheme.palette.value.background,
+ onSurface: const Color(0xFFF5F5F5),
+ onSurfaceVariant: const Color(0xFFA8A8A2),
+ surfaceContainerHighest: AppTheme.palette.value.card,
+ outline: const Color(0x14FFFFFF),
+ outlineVariant: const Color(0x14FFFFFF),
+ error: const Color(0xFFF2544B),
)
: const ColorScheme.light(
primary: AppPalette.accent,
@@ -934,7 +945,9 @@ ThemeData buildAppTheme({Brightness brightness = Brightness.light}) {
// both were `#1E1E1E`, which is [AppCard.base] — a content card's colour, one
// step *below* the block it was supposed to be.
final panelFill = isDark ? AppMenu.fillDark : AppMenu.fillLight;
- final dialogFill = isDark ? const Color(0xFF202020) : const Color(0xFFFFFFFF);
+ final dialogFill = isDark
+ ? AppTheme.palette.value.card
+ : const Color(0xFFFFFFFF);
final textTheme = _appTextTheme(scheme.onSurface, scheme.onSurfaceVariant);
return ThemeData(
diff --git a/desktop/lib/shared/theme/appearance_prefs_store.dart b/desktop/lib/shared/theme/appearance_prefs_store.dart
index 81c5b27cb..529b11b9a 100644
--- a/desktop/lib/shared/theme/appearance_prefs_store.dart
+++ b/desktop/lib/shared/theme/appearance_prefs_store.dart
@@ -3,10 +3,11 @@ import 'package:flutter/foundation.dart';
import '../../core/harness_file_store.dart';
import '../../core/local_key_value_store.dart';
import 'app_theme.dart';
+import 'color_palette.dart';
-/// How the app's own type is set on this Mac: which face, and how big.
+/// The app's coordinated palette and UI typography on this computer.
///
-/// Deliberately NOT the terminal's type. The terminal renders a grid a remote
+/// This does not change the terminal's type. The terminal renders a grid a remote
/// program draws into, so it keeps its own face and its own size in
/// [TerminalFontStore], reached from Settings ▸ Terminal — and the app's UI
/// scale is fenced out of it at five seams (see the notes in
@@ -14,7 +15,13 @@ import 'app_theme.dart';
/// in `test/terminal_ui_scale_isolation_test.dart`).
@immutable
class AppearancePrefs {
- const AppearancePrefs({this.uiFamily, this.uiSize = uiSizeDefault});
+ const AppearancePrefs({
+ this.uiFamily,
+ this.uiSize = uiSizeDefault,
+ this.palette = HarnessPalette.graphite,
+ });
+
+ final HarnessPalette palette;
/// The face the app's chrome is set in. `null` means the system font, which is
/// what [AppFont.sans] falls back to.
@@ -44,20 +51,23 @@ class AppearancePrefs {
AppearancePrefs copyWith({
String? uiFamily,
double? uiSize,
+ HarnessPalette? palette,
bool clearUiFamily = false,
}) => AppearancePrefs(
uiFamily: clearUiFamily ? null : (uiFamily ?? this.uiFamily),
uiSize: uiSize ?? this.uiSize,
+ palette: palette ?? this.palette,
);
@override
bool operator ==(Object other) =>
other is AppearancePrefs &&
other.uiFamily == uiFamily &&
- other.uiSize == uiSize;
+ other.uiSize == uiSize &&
+ other.palette == palette;
@override
- int get hashCode => Object.hash(uiFamily, uiSize);
+ int get hashCode => Object.hash(uiFamily, uiSize, palette);
}
/// The user's appearance choices, remembered across launches.
@@ -74,6 +84,8 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
static const _familyKey = 'app_ui_font_family';
static const _sizeKey = 'app_ui_font_size';
+ static const _paletteKey = 'app_color_palette';
+ Future<void>? _paletteSave;
final LocalKeyValueStore _storage;
@@ -86,15 +98,39 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
try {
final family = await _storage.read(_familyKey);
final size = await _storage.read(_sizeKey);
+ final palette = await _storage.read(_paletteKey);
value = AppearancePrefs(
uiFamily: _familyFrom(family),
uiSize: _sizeFrom(size),
+ palette: HarnessPalette.fromId(palette),
);
} catch (_) {
value = const AppearancePrefs();
}
}
+ /// Preview now, persist in order. Rapid choices coalesce while storage is
+ /// busy so an older write cannot replace the user's final selection.
+ Future<void> setPalette(HarnessPalette palette) {
+ if (value.palette == palette) return _paletteSave ?? Future.value();
+ value = value.copyWith(palette: palette);
+ return _paletteSave ??= _savePalette();
+ }
+
+ Future<void> _savePalette() async {
+ try {
+ while (true) {
+ final id = value.palette.name;
+ await _storage.write(_paletteKey, id);
+ if (value.palette.name == id) break;
+ }
+ } catch (_) {
+ // The chosen palette remains usable for this run if storage fails.
+ } finally {
+ _paletteSave = null;
+ }
+ }
+
/// Choose a face, or pass `null` for the system font.
Future<void> setUiFamily(String? family) async {
final next = _familyFrom(family);
@@ -130,9 +166,11 @@ class AppearancePrefsStore extends ValueNotifier<AppearancePrefs> {
/// Back to the shipped defaults.
Future<void> reset() async {
value = const AppearancePrefs();
+ await _paletteSave;
try {
await _storage.delete(_familyKey);
await _storage.delete(_sizeKey);
+ await _storage.delete(_paletteKey);
} catch (_) {
// See above.
}
diff --git a/desktop/lib/shared/theme/color_palette.dart b/desktop/lib/shared/theme/color_palette.dart
new file mode 100644
index 000000000..2a1bcf10b
--- /dev/null
+++ b/desktop/lib/shared/theme/color_palette.dart
@@ -0,0 +1,105 @@
+import 'package:flutter/painting.dart';
+
+/// Coordinated workspace colors. These feed the existing design-system tokens,
+/// native tabs/search, and terminal defaults; they do not change agent state.
+enum HarnessPalette {
+ graphite(
+ 'Graphite',
+ 'Neutral charcoal',
+ background: Color(0xff181818),
+ panel: Color(0xff141414),
+ card: Color(0xff1e1e1e),
+ hover: Color(0xff252525),
+ workspace: Color(0xff282828),
+ tabBar: Color(0xff1c1c1c),
+ search: Color(0xff2c2c2c),
+ accent: Color(0xffbdcbdc),
+ ),
+ dusk(
+ 'Dusk',
+ 'Soft plum',
+ background: Color(0xff181818),
+ panel: Color(0xff141414),
+ card: Color(0xff1e1e1e),
+ hover: Color(0xff252525),
+ workspace: Color(0xff463746),
+ tabBar: Color(0xff332936),
+ search: Color(0xff3d333f),
+ accent: Color(0xffd8cce1),
+ ),
+ midnight(
+ 'Midnight',
+ 'Deep indigo',
+ background: Color(0xff171b29),
+ panel: Color(0xff141722),
+ card: Color(0xff202638),
+ hover: Color(0xff2a3348),
+ workspace: Color(0xff252d43),
+ tabBar: Color(0xff1b2030),
+ search: Color(0xff262f46),
+ accent: Color(0xffb1c7f5),
+ ),
+ slate(
+ 'Slate',
+ 'Cool blue gray',
+ background: Color(0xff222a35),
+ panel: Color(0xff1b222c),
+ card: Color(0xff2c3543),
+ hover: Color(0xff374457),
+ workspace: Color(0xff354153),
+ tabBar: Color(0xff273140),
+ search: Color(0xff344154),
+ accent: Color(0xffbdd3e7),
+ ),
+ forest(
+ 'Forest',
+ 'Quiet evergreen',
+ background: Color(0xff18231e),
+ panel: Color(0xff141c18),
+ card: Color(0xff202c25),
+ hover: Color(0xff2a3a31),
+ workspace: Color(0xff2b3b31),
+ tabBar: Color(0xff1b2720),
+ search: Color(0xff293a31),
+ accent: Color(0xffb4d8be),
+ ),
+ ember(
+ 'Ember',
+ 'Warm earth',
+ background: Color(0xff26201c),
+ panel: Color(0xff1e1a17),
+ card: Color(0xff312923),
+ hover: Color(0xff3d342c),
+ workspace: Color(0xff3d322a),
+ tabBar: Color(0xff2b221d),
+ search: Color(0xff3c3129),
+ accent: Color(0xffe6c39e),
+ );
+
+ const HarnessPalette(
+ this.label,
+ this.description, {
+ required this.background,
+ required this.panel,
+ required this.card,
+ required this.hover,
+ required this.workspace,
+ required this.tabBar,
+ required this.search,
+ required this.accent,
+ });
+
+ final String label, description;
+ final Color background, panel, card, hover, workspace, tabBar, search, accent;
+ Color get foreground => const Color(0xfff5f5f5);
+
+ static HarnessPalette fromId(String? id) =>
+ values.where((palette) => palette.name == id).firstOrNull ?? graphite;
+
+ Map<String, int> get nativeColors => {
+ 'tabBar': tabBar.toARGB32(),
+ 'workspace': workspace.toARGB32(),
+ 'search': search.toARGB32(),
+ 'accent': accent.toARGB32(),
+ };
+}
diff --git a/desktop/lib/terminal/terminal_theme.dart b/desktop/lib/terminal/terminal_theme.dart
index f7df39b5d..f8098be3d 100644
--- a/desktop/lib/terminal/terminal_theme.dart
+++ b/desktop/lib/terminal/terminal_theme.dart
@@ -1,6 +1,41 @@
import 'package:flutter/material.dart';
import 'package:xterm/xterm.dart';
+import '../shared/theme/color_palette.dart';
+
+/// Cached per palette. Switching colors repaints the existing terminal view;
+/// it does not replace its controller, buffer, input connection or font.
+TerminalTheme terminalThemeFor(HarnessPalette palette) => _palettes.putIfAbsent(
+ palette,
+ () => TerminalTheme(
+ cursor: palette.accent,
+ selection: palette.accent.withValues(alpha: 0.3),
+ foreground: palette.foreground,
+ background: palette.background,
+ black: darkTerminalTheme.black,
+ red: darkTerminalTheme.red,
+ green: darkTerminalTheme.green,
+ yellow: darkTerminalTheme.yellow,
+ blue: darkTerminalTheme.blue,
+ magenta: darkTerminalTheme.magenta,
+ cyan: darkTerminalTheme.cyan,
+ white: darkTerminalTheme.white,
+ brightBlack: darkTerminalTheme.brightBlack,
+ brightRed: darkTerminalTheme.brightRed,
+ brightGreen: darkTerminalTheme.brightGreen,
+ brightYellow: darkTerminalTheme.brightYellow,
+ brightBlue: darkTerminalTheme.brightBlue,
+ brightMagenta: darkTerminalTheme.brightMagenta,
+ brightCyan: darkTerminalTheme.brightCyan,
+ brightWhite: darkTerminalTheme.brightWhite,
+ searchHitBackground: darkTerminalTheme.searchHitBackground,
+ searchHitBackgroundCurrent: darkTerminalTheme.searchHitBackgroundCurrent,
+ searchHitForeground: darkTerminalTheme.searchHitForeground,
+ ),
+);
+
+final _palettes = <HarnessPalette, TerminalTheme>{};
+
/// Harness owns the terminal's *default* appearance.
///
/// Terminal streams provide ANSI attributes, not the source application's
diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
index 8c22cfa2f..8b7c1d2d7 100644
--- a/desktop/lib/widgets/swarm_switcher.dart
+++ b/desktop/lib/widgets/swarm_switcher.dart
@@ -328,7 +328,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontSize: 11,
- color: Colors.white54,
+ color: Colors.white70,
),
),
onTap: search.canSubmit(row)
@@ -359,7 +359,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
: '↑↓ choose · Esc close',
maxLines: 1,
overflow: TextOverflow.ellipsis,
- style: const TextStyle(fontSize: 11, color: Colors.white54),
+ style: const TextStyle(fontSize: 11, color: Colors.white70),
),
),
),
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index d95c2a76f..276a1412e 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -1102,7 +1102,7 @@ class _TerminalPanelState extends State<TerminalPanel>
focusNode: _focusNode,
autofocus: widget.focused && !showComposer,
readOnly: widget.readOnly || !session.acceptsInput,
- theme: darkTerminalTheme,
+ theme: terminalThemeFor(grid.AppTheme.palette.value),
padding: const EdgeInsets.all(10),
textStyle: terminalFontStore.value,
// ⚠️ The terminal is NOT app chrome, and the user said so:
diff --git a/desktop/macos/Runner/SwarmTitlebar.swift b/desktop/macos/Runner/SwarmTitlebar.swift
index 2ff32cf26..7c53e6e05 100644
--- a/desktop/macos/Runner/SwarmTitlebar.swift
+++ b/desktop/macos/Runner/SwarmTitlebar.swift
@@ -47,6 +47,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
self.canCreateSwarm = (state["tabs"] as? [Any] ?? []).count < 24
self.updateHistory(state["history"] as? [[String: Any]] ?? [], closed: state["closedHistory"] as? [[String: Any]] ?? [])
self.strip.update(state)
+ self.window?.backgroundColor = self.strip.palette.tabBar
result(nil)
case "focusSearch":
self.strip.focusSearch(selectAll: (call.arguments as? [String: Any])?["selectAll"] as? Bool == true)
@@ -85,7 +86,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
window.titleVisibility = .hidden
window.titlebarAppearsTransparent = true
window.styleMask.remove(.fullSizeContentView)
- window.backgroundColor = NSColor(srgbRed: 0.20, green: 0.16, blue: 0.21, alpha: 1)
+ window.backgroundColor = strip.palette.tabBar
// AppKit fixes a right accessory's height to the title bar. A taller view
// alone is clipped. A compact unified toolbar gives the native traffic
// lights and the tab strip one 40-point row, without a second toolbar row.
@@ -543,10 +544,28 @@ private final class SwarmHistoryIcons {
}
private let swarmPasteboardType = NSPasteboard.PasteboardType("ai.autonomous.harness.v2.swarm")
-// Matches AppPalette.swarmField exactly, joining the tab to the terminal canvas.
-private let swarmSelectedTabColor = NSColor(srgbRed: 70.0 / 255, green: 55.0 / 255, blue: 70.0 / 255, alpha: 1)
-// Matches AppPalette.swarmSearchSurface so the input joins its results below.
-private let swarmSearchSurface = NSColor(srgbRed: 61.0 / 255, green: 51.0 / 255, blue: 63.0 / 255, alpha: 1)
+/// Dart's palette is authoritative. These defaults match Graphite before its
+/// first snapshot arrives; every window retains its own resolved colors.
+private struct SwarmNativePalette: Equatable {
+ let tabBar: NSColor
+ let workspace: NSColor
+ let search: NSColor
+ let accent: NSColor
+
+ init(_ values: [String: Any] = [:]) {
+ func color(_ name: String, _ fallback: UInt32) -> NSColor {
+ let supplied = values[name] as? Int64
+ let valid = supplied.map { $0 >= 0 && $0 <= Int64(UInt32.max) && ($0 >> 24) == 255 } ?? false
+ let argb = valid ? UInt32(supplied!) : fallback
+ return NSColor(srgbRed: CGFloat((argb >> 16) & 255) / 255,
+ green: CGFloat((argb >> 8) & 255) / 255, blue: CGFloat(argb & 255) / 255, alpha: 1)
+ }
+ tabBar = color("tabBar", 0xff1c1c1c)
+ workspace = color("workspace", 0xff282828)
+ search = color("search", 0xff2c2c2c)
+ accent = color("accent", 0xffbdcbdc)
+ }
+}
private final class SwarmSearchCell: NSSearchFieldCell {
override func select(withFrame rect: NSRect, in controlView: NSView, editor: NSText,
@@ -576,6 +595,7 @@ private final class SwarmSearchCell: NSSearchFieldCell {
/// AppKit owns editing, selection, paste and IME. Only result-navigation keys
/// leave the field editor; ordinary terminal input never passes through here.
private final class SwarmSearchField: NSSearchField {
+ var palette = SwarmNativePalette() { didSet { needsDisplay = true } }
var begin: (() -> Void)?
var command: ((String) -> Void)?
var searching = false { didSet { needsDisplay = true } }
@@ -649,7 +669,7 @@ private final class SwarmSearchField: NSSearchField {
}
override func draw(_ dirtyRect: NSRect) {
let shape = NSBezierPath(roundedRect: bounds, xRadius: searching ? 10 : 16, yRadius: searching ? 10 : 16)
- swarmSearchSurface.setFill()
+ palette.search.setFill()
shape.fill()
if searching {
// The strip continues the square bottom edge down to the result list.
@@ -674,6 +694,7 @@ private final class SwarmSearchField: NSSearchField {
}
private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
+ private(set) var palette = SwarmNativePalette()
var emit: ((String, Any?) -> Void)?
private let scroll = NSScrollView()
private let document = NSView()
@@ -697,7 +718,7 @@ private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
button.image = NSImage(systemSymbolName: symbol, accessibilityDescription: label)
button.symbolConfiguration = NSImage.SymbolConfiguration(pointSize: 13, weight: .regular)
button.isBordered = false
- button.contentTintColor = NSColor(srgbRed: 0.80, green: 0.75, blue: 0.83, alpha: 1)
+ button.contentTintColor = palette.accent
button.target = self
button.action = action
button.toolTip = label
@@ -717,6 +738,13 @@ private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
func update(_ state: [String: Any]) {
+ let nextPalette = SwarmNativePalette(state["palette"] as? [String: Any] ?? [:])
+ if nextPalette != palette {
+ palette = nextPalette
+ searchField.palette = palette
+ newButton.contentTintColor = palette.accent
+ needsDisplay = true
+ }
actionsEnabled = state["enabled"] as? Bool == true
let rows = state["tabs"] as? [[String: Any]] ?? []
activeId = state["activeId"] as? String ?? ""
@@ -727,6 +755,7 @@ private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
tabs = rows.compactMap { row in
guard let id = row["id"] as? String else { return nil }
let tab = previous[id] ?? SwarmTabButton(id: id)
+ tab.palette = palette
tab.name = row["name"] as? String ?? "New swarm"
tab.selected = id == activeId
tab.actionsEnabled = actionsEnabled
@@ -786,10 +815,10 @@ private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
override func draw(_ dirtyRect: NSRect) {
// The selected tab meets this edge; its bottom corners are shoulders,
// rather than the rounded bottom of a separate pill.
- swarmSelectedTabColor.setFill()
+ palette.workspace.setFill()
NSRect(x: 0, y: 0, width: bounds.width, height: 1).fill()
if searchField.searching {
- swarmSearchSurface.setFill()
+ palette.search.setFill()
NSRect(x: searchField.frame.minX, y: 0, width: searchField.frame.width,
height: searchField.frame.minY + 1).fill()
}
@@ -865,6 +894,9 @@ private final class SwarmTabStrip: NSView, NSSearchFieldDelegate {
}
private final class SwarmTabButton: NSView, NSDraggingSource, NSMenuItemValidation {
+ var palette = SwarmNativePalette() {
+ didSet { if palette != oldValue { needsDisplay = true } }
+ }
let swarmId: String
var name = "New swarm" { didSet { if name != oldValue { invalidateLabel(); updateAccessibility() } } }
var selected = false { didSet { if selected != oldValue { invalidateLabel(); updateAccessibility() } } }
@@ -966,7 +998,7 @@ private final class SwarmTabButton: NSView, NSDraggingSource, NSMenuItemValidati
shape.line(to: NSPoint(x: w - 8, y: 8))
shape.curve(to: NSPoint(x: w, y: 0), controlPoint1: NSPoint(x: w - 8, y: 3.6), controlPoint2: NSPoint(x: w - 4.4, y: 0))
shape.close()
- swarmSelectedTabColor.setFill()
+ palette.workspace.setFill()
shape.fill()
} else if hovered && actionsEnabled {
NSColor(white: 1, alpha: 0.05).setFill()
diff --git a/desktop/test/color_palette_test.dart b/desktop/test/color_palette_test.dart
new file mode 100644
index 000000000..f000228bc
--- /dev/null
+++ b/desktop/test/color_palette_test.dart
@@ -0,0 +1,184 @@
+import 'dart:async';
+import 'dart:ui' show SemanticsAction;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/local_key_value_store.dart';
+import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/settings/appearance/palette_section.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/shared/theme/appearance_prefs_store.dart';
+import 'package:harness/shared/theme/color_palette.dart';
+import 'package:harness/state/swarm_catalog.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/terminal/terminal_theme.dart';
+import 'package:xterm/xterm.dart';
+
+import 'swarm_screen_test.dart' show terminal;
+import 'swarm_state_test.dart' show createApp;
+
+class _Storage implements LocalKeyValueStore {
+ final values = <String, String>{};
+ Completer<void>? writeGate;
+ @override
+ Future<String?> read(String key) async => values[key];
+ @override
+ Future<void> delete(String key) async => values.remove(key);
+ @override
+ Future<void> write(String key, String value) async {
+ await writeGate?.future;
+ values[key] = value;
+ }
+}
+
+void main() {
+ tearDown(() => grid.AppTheme.palette.value = HarnessPalette.graphite);
+
+ test('rapid palette changes keep the last choice through relaunch', () async {
+ final storage = _Storage()..writeGate = Completer<void>();
+ final store = AppearancePrefsStore(storage: storage);
+ addTearDown(store.dispose);
+ final saved = store.setPalette(HarnessPalette.forest);
+ store.setPalette(HarnessPalette.ember);
+ expect(store.value.palette, HarnessPalette.ember);
+ storage.writeGate!.complete();
+ await saved;
+ final restored = AppearancePrefsStore(storage: storage);
+ addTearDown(restored.dispose);
+ await restored.load();
+ expect(restored.value.palette, HarnessPalette.ember);
+ await restored.reset();
+ expect(storage.values.containsKey('app_color_palette'), isFalse);
+ expect(restored.value.palette, HarnessPalette.graphite);
+ storage.values['app_color_palette'] = 'missing-preset';
+ await restored.load();
+ expect(restored.value.palette, HarnessPalette.graphite);
+ });
+
+ test('palette text is readable and terminal themes are cached', () {
+ double contrast(Color foreground, Color background) =>
+ (foreground.computeLuminance() + .05) /
+ (background.computeLuminance() + .05);
+ for (final palette in HarnessPalette.values) {
+ expect(
+ contrast(palette.foreground, palette.background),
+ greaterThanOrEqualTo(7),
+ reason: palette.name,
+ );
+ for (final background in [
+ palette.search,
+ palette.card,
+ palette.workspace,
+ ]) {
+ final secondary = Color.alphaBlend(Colors.white70, background);
+ expect(
+ contrast(secondary, background),
+ greaterThanOrEqualTo(4.5),
+ reason: palette.name,
+ );
+ }
+ expect(terminalThemeFor(palette), same(terminalThemeFor(palette)));
+ expect(terminalThemeFor(palette).background, palette.background);
+ expect(terminalThemeFor(palette).selection.a, lessThan(.5));
+ }
+ });
+
+ testWidgets(
+ 'palette choices fit narrow settings and support keyboard selection',
+ (tester) async {
+ final store = AppearancePrefsStore(storage: _Storage());
+ addTearDown(store.dispose);
+ final semantics = tester.ensureSemantics();
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: Scaffold(
+ body: SizedBox(
+ width: 340,
+ child: SingleChildScrollView(child: PaletteSection(store: store)),
+ ),
+ ),
+ ),
+ );
+ expect(tester.takeException(), isNull);
+ await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+ await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(store.value.palette, HarnessPalette.dusk);
+ await tester.ensureVisible(find.byKey(const ValueKey('palette-forest')));
+ expect(
+ tester
+ .getSemantics(find.bySemanticsLabel('Forest palette. Quiet evergreen'))
+ .getSemanticsData()
+ .hasAction(SemanticsAction.tap),
+ isTrue,
+ );
+ await tester.tap(find.byKey(const ValueKey('palette-forest')));
+ await tester.pump();
+ expect(store.value.palette, HarnessPalette.forest);
+ expect(tester.takeException(), isNull);
+ semantics.dispose();
+ },
+ );
+
+ testWidgets(
+ 'palette changes preserve the live terminal and update native colors',
+ (tester) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(1280, 800);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ addTearDown(tester.view.resetPhysicalSize);
+ const channel = MethodChannel('harness/swarm_tabs');
+ final updates = <Map>[];
+ tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, (
+ call,
+ ) async {
+ if (call.method == 'update') updates.add(call.arguments as Map);
+ return true;
+ });
+ addTearDown(
+ () => tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ channel,
+ null,
+ ),
+ );
+ final app = createApp();
+ final input = <TerminalBinaryFrame>[];
+ final session = terminal('a0', input)..terminal.write('Keep this output');
+ app.adoptSessionForTest(session);
+ final projects = SwarmProjectStore();
+ await tester.pumpWidget(
+ grid.BrightnessScope(
+ child: MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: SwarmScreen(
+ notifier: app,
+ nativeTabs: true,
+ projectStore: projects,
+ ),
+ ),
+ ),
+ );
+ await tester.pump();
+ final terminalState = tester.state(find.byType(TerminalView));
+ final before = tester.widget<TerminalView>(find.byType(TerminalView));
+ final hadFocus = before.focusNode!.hasFocus;
+ final pane = app.focusedPane;
+ grid.AppTheme.palette.value = HarnessPalette.midnight;
+ await tester.pump();
+ final after = tester.widget<TerminalView>(find.byType(TerminalView));
+ expect(tester.state(find.byType(TerminalView)), same(terminalState));
+ expect(after.terminal, same(before.terminal));
+ expect(app.focusedPane, same(pane));
+ expect(after.focusNode!.hasFocus, hadFocus);
+ expect(after.theme.background, HarnessPalette.midnight.background);
+ expect(updates.last['palette'], HarnessPalette.midnight.nativeColors);
+ expect(input, isEmpty);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ projects.dispose();
+ },
+ );
+}
diff --git a/desktop/tool/swarm_titlebar_checks.swift b/desktop/tool/swarm_titlebar_checks.swift
index 17cde575e..cb4843fd3 100644
--- a/desktop/tool/swarm_titlebar_checks.swift
+++ b/desktop/tool/swarm_titlebar_checks.swift
@@ -109,6 +109,14 @@ private extension SwarmTabStrip {
try checkTitlebar(events.filter { $0 == "searchBegin" }.count == 1, "Refocusing search keeps the same search session")
setSearchState(["query": "Workshop", "hint": "Search agents in Workshop…"])
try checkTitlebar(searchField.stringValue == "Workshop", "Group navigation updates the original editable input")
+ var themedState = state([["id": "swarm-0", "name": "Renamed tab"]], active: "swarm-0")
+ themedState["palette"] = ["workspace": Int64(0xff252d43), "search": Int64(0xff262f46)]
+ let oldField = searchField
+ update(themedState)
+ try checkTitlebar(searchField === oldField && searchField.stringValue == "Workshop" && searchField.searching,
+ "Palette changes preserve the open native search and typed query")
+ try checkTitlebar(tabs[0] === original && tabs[0].palette == palette && searchField.palette == palette,
+ "The existing native tab and search controls receive one coordinated palette")
closeSearch()
try checkTitlebar(searchField.stringValue.isEmpty && !searchField.searching, "Closing search clears and collapses its original input")
func key(_ characters: String, _ flags: NSEvent.ModifierFlags = []) -> NSEvent {
@@ -380,6 +388,16 @@ let titlebarCheckApp = NSApplication.shared
titlebarCheckApp.setActivationPolicy(.prohibited)
titlebarCheckApp.appearance = NSAppearance(named: .darkAqua)
do {
+ let paletteValues: [String: Any] = [
+ "tabBar": Int64(0xff1b2030), "workspace": Int64(0xff252d43),
+ "search": Int64(0xff262f46), "accent": Int64(0xffb1c7f5),
+ ]
+ let palette = SwarmNativePalette(paletteValues)
+ let searchColor = palette.search.usingColorSpace(.sRGB)!
+ try checkTitlebar(abs(searchColor.redComponent - 38.0 / 255) < 0.0001 && abs(searchColor.blueComponent - 70.0 / 255) < 0.0001,
+ "Native search uses the exact palette channels supplied by Flutter")
+ try checkTitlebar(SwarmNativePalette(["search": -1, "tabBar": "invalid"]) == SwarmNativePalette(),
+ "Malformed palette data retains readable native defaults")
let historyRow = SwarmHistoryEntry([
"id": "agent", "title": "Build a toy", "machineName": "MacBook Pro M2", "engine": "codex",
])!
diff --git a/docs/harness-v2-appearance-onboarding.md b/docs/harness-v2-appearance-onboarding.md
new file mode 100644
index 000000000..2c3e10177
--- /dev/null
+++ b/docs/harness-v2-appearance-onboarding.md
@@ -0,0 +1,35 @@
+# Appearance and first use
+
+Research and implementation notes, 2026-09-13. The product decisions below are Harness adaptations, not claims that the referenced tools endorse them.
+
+## Palette selection
+
+The useful common pattern is a named preset, a preview and an immediate result. Developers can personalize a workspace without first learning how its colors are configured.
+
+| Primary source | Observed behavior | Harness decision |
+| --- | --- | --- |
+| [iTerm2 color preferences](https://iterm2.com/documentation-preferences-profiles-colors.html) | Presets and individual colors belong to profiles; color schemes can be imported and exported, with separate light/dark colors available. | Put the palette in Appearance and make selection reversible. Keep palette and typography separate. |
+| [Ghostty themes](https://ghostty.org/docs/features/theme) | Named built-in themes, previews, custom theme files and light/dark pairs. | Offer a small, curated set first. One choice coordinates the app rather than asking users to configure each region. |
+| [Apple Terminal profiles](https://support.apple.com/guide/terminal/profiles-change-terminal-windows-trml107/mac) | Profiles collect window colors, background, font and cursor preferences. | Show a miniature workspace so a preset explains its effect before selection. |
+| [GNOME Terminal colors](https://help.gnome.org/gnome-terminal/app-colors.html) | Built-in, system and custom colors; changes apply and save automatically. ANSI palette colors and true-color output are distinct. | Apply immediately and persist. Keep explicit colors emitted by agents intact. |
+| [Superlogical](https://www.superlogical.com/) | Public material describes a product plan and beta signup. It does not establish a shipped theme chooser. | Do not infer a theme feature or copy an unverified interaction. |
+
+Implemented: six original dark presets in Settings → Appearance: **Graphite, Dusk, Midnight, Slate, Forest and Ember**. Graphite is the neutral default; Dusk preserves the earlier plum treatment. Preview cards show the tabs, search field, canvas and two agents. Mouse or keyboard selection updates Flutter tokens, retained terminal defaults and the native macOS titlebar. The preference loads before the first frame and rapid changes persist in order.
+
+The existing ANSI color ramp and explicit agent-emitted colors remain intact. A palette change does not replace terminal controllers, alter fonts, send input, attach sessions or modify an agent's configuration. Light palettes, imports and a color editor are future options, not disabled controls in this first version.
+
+Verification includes persistence/reload, keyboard operation, narrow layout, contrast, retained terminal identity and native titlebar/query identity. Primary text meets 7:1 on each terminal background; the tested secondary text meets 4.5:1 on the search, card and workspace surfaces. These checks cover Harness defaults, not arbitrary colors emitted by an agent.
+
+## Onboarding evidence and direction
+
+| Primary source | Observed behavior | Harness adaptation |
+| --- | --- | --- |
+| [Zed getting started](https://zed.dev/docs/getting-started) | An empty editor offers useful starting actions such as opening a folder or cloning a repository; the welcome screen gives way to work. | Make the empty workspace actionable and let it disappear as soon as an agent is visible. |
+| [VS Code getting started](https://code.visualstudio.com/docs/getstarted/overview) and [walkthroughs](https://code.visualstudio.com/docs/editing/getting-started/tips-and-tricks) | A short route to a first project, with optional walkthroughs and contextual learning. | Lead with the first agent. Teach grouping and shortcuts where the user can immediately use them. |
+| [Warp installation and setup](https://docs.warp.dev/getting-started/quickstart/installation-and-setup) | Current setup allows sign-in to be optional and can import an existing configuration. | Reuse an existing environment wherever possible. Evaluate Harness's actual authentication requirements before changing its sign-in boundary. |
+
+Current source audit: an unprepared computer reaches dependency setup before sign-in; an authenticated empty workspace leads with “Start a swarm,” generic search, New agent, machines and projects. This exposes several unfamiliar choices before the first useful session. Browser sign-in is a real requirement of the current CLI-backed authentication flow; it cannot simply be replaced with an embedded sign-in panel.
+
+The next implementation is a contextual first-workspace path: make the value and next action clear, reuse existing agents when available, make creating a first agent direct, and explain a swarm as agents working side by side. Keep returning users' ordinary New swarm screen fast. No mandatory tour, sample tasks submitted to real agents, or claimed conversion guarantee.
+
+First-use validation will use isolated state and stubbed machines/agents. Success means reaching an existing agent without an intermediate browsing step, or reaching a ready-to-create agent with the machine preselected and an obvious folder choice. A fresh-install dependency or provider sign-in may still take longer than a few seconds; those waits must be honest and actionable.
diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.md
index ccd74f7c6..fee0be10e 100644
--- a/docs/harness-v2-progress.md
+++ b/docs/harness-v2-progress.md
@@ -1,6 +1,14 @@
# Harness App V2 — development handoff
-Updated 2026-09-13 with Models, combined closed-work History and faster unified search. This is a working preview, not a release.
+Updated 2026-09-13 with coordinated palettes, Models, combined closed-work History and faster unified search. This is a working preview, not a release.
+
+## Active follow-up: appearance and first use
+
+- Added six coordinated palettes in Settings → Appearance: Graphite (neutral default), Dusk (the earlier plum), Midnight, Slate, Forest and Ember. Preview cards support mouse, keyboard and accessibility activation. Selection applies immediately, persists in order and loads before the first frame. Existing theme tokens feed Flutter surfaces, native tabs/search and retained terminal defaults. Agent-emitted colors and the existing ANSI ramp remain intact; controllers, buffers, focus, fonts and sessions are retained.
+- Verification: **1,118 Flutter tests passed, one existing skip; 295 AppKit checks passed** including hidden native window layout and retained search/tab identity through a palette change. Analyzer has no errors/warnings and the same 12 vendored infos. A focused four-test accessibility rerun passed after correcting the test's semantics-handle cleanup. Settings was rendered and visually inspected at `/private/tmp/harness-v2-palette-settings.png`; the Release build succeeded. Logs: `/private/tmp/harness-v2-palette-{full-tests,native,analyze,accessibility-tests,build}.log`.
+- Normally quit the verified preview PID 43778 and launched the rebuilt preview, **PID 56329** at the last check. CUA cannot currently obtain its window (`cgWindowNotFound`), although the process is running. Do not claim live palette-switch verification. Continue with isolated UI fixtures and re-observe before any later native interaction. No real-agent input was sent.
+- [Appearance and onboarding research](harness-v2-appearance-onboarding.md) records primary-source observations and product decisions. Onboarding is next: reduce first-workspace choices, make the product's value clear, offer an existing agent directly or a clear first-agent action, then explain grouping in context. Use isolated state rather than signing out the user's real account.
+- User authorizes autonomous decisions and frequent commits/pushes while away for eight hours. Keep the active goal running, preserve simple Command shortcuts and explicitly disabled Models placeholders. After onboarding, continue keymap runtime integration, commands in search, controlled resizing and optional cached preview, with performance and input correctness checks.
## Active follow-up: in-place New swarm search and account-based Models
@@ -14,7 +22,7 @@ Updated 2026-09-13 with Models, combined closed-work History and faster unified
- Verification so far: 1,114 full Flutter tests pass with one existing skip; analyzer has no errors/warnings (12 existing vendored infos); 288 native AppKit checks pass including hidden-window layout. Added direct-open/reuse tests, in-place geometry/cancellation/IME/native-field isolation tests, exact first-key agent focus tests, and display-identity tests. Logs: `/private/tmp/harness-v2-inline-models-{full-tests,analyze}.log`, `/private/tmp/harness-v2-inline-behavior-tests.log`, `/private/tmp/harness-v2-account-menu-native.log`. **Release rebuilt successfully** (`/private/tmp/harness-v2-inline-models-build.log`). Normally quit PID 511 and launched one preview, PID 31652 at last check. Live CUA visually verified an actual caret and results directly beneath the New swarm field, with the native titlebar field inactive. A query-entry attempt and temporary-tab cleanup attempt were declined by the CUA stale-state guard while the user changed workspaces; no query was sent. Live interaction was paused. One empty New swarm opened for review may still be present; re-observe before any cleanup, and never remove it if the user has added work. The user’s current layout differs from earlier snapshots and must be preserved. Models layout/alignment is verified by AppKit checks, not yet by a live menu screenshot.
- Concurrent changes from another user session are present in `app_state.dart`, `swarm_state_test.dart`, History serialization in `swarm_screen.dart`, History title layout/icon resolution in `SwarmTitlebar.swift`, and corresponding History/native tests. Preserve that work and stage this batch selectively; do not claim those edits as this session's implementation.
- **Keyboard correction is authoritative:** retain Cmd-H/J/K/L and Cmd-arrows for focus, Cmd-S for layout, Cmd-R for refresh, Cmd-B for Boss mode. The user explicitly rejected modifier-heavy navigation and a general-purpose-terminal product assumption. Rewrite the unused draft catalog before enabling remapping. The runtime patch was saved and removed from the working tree before this search follow-up: `/private/tmp/harness-v2-keyboard-wiring-before-inline-search.patch`. Do not apply it blindly: both search surfaces and the agreed defaults have changed.
-- [The revised keyboard plan](harness-v2-keyboard-system.md) and [prototype evidence](harness-v2-prototype-review.md) are current. Manual splits/resizing, optional lightweight search preview and commands in search are now explicitly approved; editor/diff handoff, structured output navigation and automation API are parked. The user is still actively reviewing product decisions; do not assume they are asleep.
+- [The revised keyboard plan](harness-v2-keyboard-system.md) and [prototype evidence](harness-v2-prototype-review.md) are current. Manual splits/resizing, optional lightweight search preview and commands in search are explicitly approved; editor/diff handoff, structured output navigation and automation API are parked. The latest direction above supersedes the earlier review pause.
## Previous batch: Models, closed agents and search performance