feat(admin): one flat rail, a Dashboard that leads with a sentence

The UX half of the re-brand. Four rules, now recorded in
DESIGN-ALIGNMENT.md, and every change below traces to one of them: one
idea per screen; content over chrome; say nothing rather than say
nothing; plain, task-first names.

**The rail is one flat list.** The three labelled sections were three
more things to read before you could read the thing you came for, and
seven items is not a wall. This is a pure data change — AppNav takes a
mixed array of items and groups, so only what the useMemo returns
changed; the JSX did not.

Two things fell out of it and are cleaned up here rather than left
half-done. TopBar's "group · title" breadcrumb had nothing left to
resolve, so the lookup goes and it shows the title. And the footer was
28 lines of raw <button>s re-implementing the DS's own nav-item markup
by hand; the DS supports footer groups natively (`footer: true` puts a
group in .pp-nav__bottom), which brings aria-current and the
collapsed-rail tooltips with it instead of us maintaining them.

Two labels now say what you do there: Guidance -> Instructions,
Connections -> Apps. Routing keys are untouched, so every #hash link,
the ALIASES map and Pro's routing keep working.

**The Dashboard leads with a sentence.** It opened with four equal tiles
of three different kinds — two counts, a setting and a health state —
which reads as a metrics dashboard for a question that is not a metric.
The answer to "what can my AI do right now" was already written, in
levelFor(tier).one, and the tiles were paraphrasing it down to one word.
So that sentence is the page now, the counts are one quiet line under
it, and the Connection tile is gone: it said "—" on most installs while
a real problem already had its own callout with an explanation and a
fix, so it spent a quarter of the page saying nothing. When there are no
apps the count is dropped too — the callout directly below already says
it.

The LEVELS strings in api.js were raw English, never wrapped in __() —
including the sentence this design just promoted to the page headline.
Fixed, which is most of the 10 new msgids.

**The Cookbook is removed** — tab, screen, CSS, REST route, PHP class
and its 6 tests. Verified not agent-facing first: Saddle_Cookbook is
referenced in exactly three places (itself, its test, one admin REST
callback) and has zero hits across includes/abilities, the system
context, the context bundle, skills, playbooks and the MCP transport.
Not to be confused with Saddle_Recipes, the section recipes behind
saddle/list-section-recipes — different system, untouched.

637 tests (was 643; the 6 are the cookbook's), 0 lint errors.

Refs #153

Author: ifahimreza

admin/DESIGN-ALIGNMENT.md

@@ -1,48 +1,126 @@
 # Saddle — Design Alignment
 
-> **DECIDED (2026-07-10, Fahim):** the admin UI is fully migrated to
-> **`@plugpress/ui` v0.3.0** — the shared PlugPress design system — which is
-> exactly the "shared component package" outcome the original research called
-> for. Import primitives directly from `@plugpress/ui`; the old
-> `admin/src/ui.jsx` compat shim is deleted. The system is **light-only**
-> (dark mode was removed from the DS in v0.2.0 — the dark-theme and
-> `s-palette-*` mentions below are historical). The 2026-07-04 monochrome
-> identity **stands**, now expressed through `tokens/accents/saddle.css`
-> (a fully monochrome accent) on top of the shared `--pp-*` tokens;
-> `style.scss` keeps only product-specific pieces (setup shell, permissions
-> lanes/chips, activity timeline, wizard flourishes) aliased to those tokens.
-> The brand mark is **single-sourced** from `assets/brand/mark.svg` — React's
-> `<BrandMark />` (SVGR import) and the PHP admin-menu icon
-> (`class-saddle-settings.php`, `file_get_contents` + recolor) both read that
-> one file; edit the SVG once to rebrand every surface.
-> Don't re-litigate any of this in future sessions.
+> **DECIDED (2026-08-25, Fahim):** Saddle has a brand palette, built on
+> **Saddle Violet `#6D3BF5`**. This **supersedes the 2026-07-04 monochrome
+> decision** kept below for history. The register is unchanged — calm, restrained,
+> Vercel/Geist — but the one accent is now violet instead of near-black.
+> **Roughly 85% of the interface stays black, white and gray; violet is the
+> remaining 15%.** Don't re-litigate this; do hold the line on the 85/15.
+
+## The palette
+
+| Role | Name | Hex |
+|---|---|---|
+| Primary brand | Saddle Violet | `#6D3BF5` |
+| Hover / active | Deep Violet | `#5121C7` |
+| Soft background | Lavender Mist | `#F1ECFF` |
+| Main text | Near Black | `#111111` |
+| Page background | Warm White | `#FBFBFA` |
+| Success / read-only | Lime | `#84CC16` |
+| Activity / info | Cyan | `#06B6D4` |
+| Warning / gated | Amber | — |
+| Destructive / blocked | Coral | `#F43F5E` |
+
+It lives in `admin/src/style.scss` as consumer-side `--pp-*` overrides. **Never in
+`@plugpress/ui`** — the library is off-limits from a plugin task, and the DS
+defines its tokens inside `:where()` (zero specificity), so a plain class selector
+wins with no `!important`. Both `.pp-app` and the body class are targeted, because
+portaled overlays render outside `.pp-app` and would otherwise lose every token.
+
+## The rule that governs every color
+
+**Every color has a bright value for FILLS and a darker same-hue value for TEXT.**
+This is not a preference. Measured on white: violet is 5.84:1, but lime is 1.98,
+cyan 2.43 and coral 3.67 — none of them can carry a label. The DS mandates the
+same split for the accent (`--pp-accent` paints surfaces at 3:1;
+`--pp-accent-text` paints links and labels at 4.5:1, measured against the *tint*,
+not just white).
+
+Three consequences worth knowing before you touch a status color:
+
+- **A mark needs 3:1 too.** A status dot, a 2px lane rail or a thin ring is a
+  graphical object, so lime and cyan are each used **one step down their ramp**
+  (`#65A30D`, `#0891B2`) — at the `-500` step they are invisible on a white card.
+  Coral already clears it and is used exactly as given.
+- **The DS collapses `--pp-tone-text` into `--pp-tone`** for status tones, so the
+  readable partners are put back at the tone layer — the same seam the accent tone
+  already uses.
+- **Warning and destructive are two different signals.** Amber means "powerful,
+  asks first" (the Remove lane, the shield chip, the write-tier pill); coral means
+  "blocked or failed" (a denied call, a connection error). They need opposite
+  reactions from the reader — don't fold them together.
+
+## Where violet is allowed to land
+
+**Yes:** primary buttons · links · focus rings · the active nav row · the brand
+mark · the Cookbook-style accent bars · `tone="accent"` fills · selection states.
+
+**No:** card backgrounds, page bands, table headers, every icon, borders at large,
+section headings. If a screen has more than a few violet elements, remove some
+rather than softening the violet.
+
+**One deliberate deviation from the DS guide, recorded so it isn't "fixed" back:**
+the guide says *"Primary buttons are near-black (`--pp-action`), never the accent
+color."* Saddle's are violet. The cost was that `.pp-code--dark` reads
+`--pp-code-bg` from `--pp-action` while hard-coding its border, muted and body
+colors, so `--pp-code-bg` is pinned back to near-black in `style.scss`. Code panels
+are deliberately **not** the button color.
+
+## The UX register
+
+Four rules the admin is held to. A change that doesn't trace to one of these
+doesn't belong.
+
+1. **One idea per screen.** Lead with the thing the user came to find out, in a
+   sentence. Supporting facts go quiet underneath. The Dashboard is the worked
+   example: it opens with `levelFor( tier ).one` and nothing competes with it.
+2. **Content over chrome.** Structure comes from type, spacing and hairlines, not
+   from more panels. Radii are 3/4/6px and elevation is flat — close to wp-admin's
+   own square register, a hair softer.
+3. **Say nothing rather than say nothing.** A tile reading `—` is worse than no
+   tile. The Dashboard's old "Connection" tile is why this rule is written down.
+4. **Plain, task-first names.** Labels say what you do there. The sidebar is one
+   flat list with no group headings — seven items is not a wall.
 
 ## Constraints that still apply
 
-- UI primitives come from `@plugpress/ui` only — no `@wordpress/components`,
-  no Tailwind, no styled-components, no second UI kit.
+- UI primitives come from `@plugpress/ui` only — no `@wordpress/components`, no
+  Tailwind, no styled-components, no second UI kit.
 - The Settings page must remain a single mounted React root (`#saddle-root`).
-- Don't regress accessibility: labels, focus rings, `role`/`aria-*` semantics,
-  and `prefers-reduced-motion` support must survive any restyling.
+- Don't regress accessibility: labels, focus rings, `role`/`aria-*` semantics and
+  `prefers-reduced-motion` must survive any restyling. Every text pair in the
+  palette clears AA; muted text actually improved (4.40 → 4.50).
 - Light-only: never add a theme toggle.
-- Portaled DS overlays (dialogs, dropdowns, toasts) read tokens from the
-  `pp-scope` class on `<body>` (added via `admin_body_class`) — keep it.
-- Stylesheet order: the DS bundle (`index.css` → handle `saddle-admin-ds`)
-  loads before Saddle's own `style-index.css` so product rules win.
+- Portaled DS overlays read tokens from `pp-scope` on `<body>` (via
+  `admin_body_class`) — keep it.
+- Stylesheet order: the DS bundle (`index.css` → `saddle-admin-ds`) loads before
+  Saddle's `style-index.css` so product rules win.
+- **The brand mark is recolored through CSS `color`, never by editing
+  `assets/brand/mark.svg`.** `class-saddle-settings.php` does
+  `str_replace( 'currentColor', 'black', … )`, and that `black` is a sentinel
+  core's `svg-painter.js` needs to repaint the wp-admin menu icon per the user's
+  admin color scheme. The menu icon is deliberately left alone.
 
 ---
 
 ## History
 
-> **DECIDED (2026-07-04, Fahim):** the monochrome identity is intentional,
-> not a placeholder. Saddle keeps its own near-black/white, OpenAI/Apple-register
-> look — one restrained accent reserved for status/safety. The earlier
-> "align to inbees/outbees" directive below is SUPERSEDED; kept for history.
+> **SUPERSEDED (2026-07-04, Fahim):** the monochrome identity is intentional, not
+> a placeholder. Saddle keeps its own near-black/white, OpenAI/Apple-register
+> look — one restrained accent reserved for status/safety.
+>
+> Still true in spirit: the restraint, the single accent, the register. What
+> changed on 2026-08-25 is only which color the accent is.
+
+> **DECIDED (2026-07-10, Fahim):** the admin UI is fully migrated to
+> `@plugpress/ui` — the shared PlugPress design system. Import primitives directly
+> from `@plugpress/ui`; the old `admin/src/ui.jsx` compat shim is deleted. The
+> system is light-only (dark mode was removed from the DS in v0.2.0).
 
-### The former rule (superseded)
+### The former rule (superseded 2026-07-04)
 
-Do **not** invent a visual design from memory or taste. Saddle has to read as
-"the same workspace" as the rest of the PlugPress portfolio (inbees/outbees).
-That means pulling real values, not approximating them — and if a shared
-PlugPress design-system package exists, consume it rather than re-implementing
-it. (That package now exists: `@plugpress/ui`. It happened.)
+Do **not** invent a visual design from memory or taste. Saddle has to read as "the
+same workspace" as the rest of the PlugPress portfolio (inbees/outbees). That means
+pulling real values, not approximating them — and if a shared PlugPress
+design-system package exists, consume it rather than re-implementing it. (That
+package now exists: `@plugpress/ui`. It happened.)

admin/build/index.asset.php

@@ -1 +1 @@
-<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-element', 'wp-hooks', 'wp-i18n'), 'version' => '1e6978e822c8398099c0');
+<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-element', 'wp-hooks', 'wp-i18n'), 'version' => '768b5d174835e661c422');

admin/build/index.js

@@ -40,7 +40,6 @@ import {
 	PlugIcon,
 	ActivityIcon,
 	SettingsIcon,
-	SparklesIcon,
 } from '@plugpress/ui';
 import { __, sprintf, _n } from '@wordpress/i18n';
 import { api, levelFor } from './api';
@@ -50,7 +49,6 @@ import Dashboard from './components/Dashboard';
 import Permissions from './components/Permissions';
 import Guidance from './components/Guidance';
 import Memory from './components/Memory';
-import Cookbook from './components/Cookbook';
 import Apps from './components/ConnectedClients';
 import Integrations from './components/Integrations';
 import Activity from './components/Activity';
@@ -65,25 +63,20 @@ const TABS = [
 		title: __( 'Dashboard', 'saddle' ),
 		icon: <DashboardIcon />,
 	},
-	{
-		name: 'cookbook',
-		title: __( 'Cookbook', 'saddle' ),
-		icon: <SparklesIcon />,
-	},
 	{
 		name: 'permissions',
 		title: __( 'Permissions', 'saddle' ),
 		icon: <ShieldIcon />,
 	},
 	{
 		name: 'guidance',
-		title: __( 'Guidance', 'saddle' ),
+		title: __( 'Instructions', 'saddle' ),
 		icon: <BookOpenIcon />,
 	},
 	{ name: 'memory', title: __( 'Memory', 'saddle' ), icon: <InboxIcon /> },
 	{
 		name: 'connect',
-		title: __( 'Connections', 'saddle' ),
+		title: __( 'Apps', 'saddle' ),
 		icon: <LinkIcon />,
 	},
 	{
@@ -103,22 +96,18 @@ const TABS = [
 	},
 ];
 
-// Sidebar grouping — labeled sections so eight items don't read as a flat
-// wall. Names reference TABS (routing stays keyed by name); Settings lives in
-// the rail footer.
-const NAV_GROUPS = [
-	{ key: 'top', label: '', items: [ 'dashboard', 'cookbook' ] },
-	{
-		key: 'ai',
-		label: __( 'Your AI', 'saddle' ),
-		items: [ 'permissions', 'guidance', 'memory' ],
-	},
-	{
-		key: 'connect',
-		label: __( 'Connect', 'saddle' ),
-		items: [ 'connect', 'integrations' ],
-	},
-	{ key: 'monitor', label: __( 'Monitor', 'saddle' ), items: [ 'activity' ] },
+// The rail, in order. One flat list rather than labeled sections: seven items
+// is not a wall, and the headings were three more things to read before you
+// could read the thing you came for. Names reference TABS (routing stays keyed
+// by name); Settings sits in the rail footer.
+const NAV_MAIN = [
+	'dashboard',
+	'permissions',
+	'guidance',
+	'memory',
+	'connect',
+	'integrations',
+	'activity',
 ];
 const NAV_FOOTER = [ 'settings' ];
 
@@ -159,13 +148,11 @@ const DOT_TONES = {
 	paused: 'neutral',
 };
 
-// The slim sticky bar above the content column: page context on the left
-// (nav group · page title), the always-visible safety-status pill on the
-// right. The pill is a real button — it jumps to Settings, where the
-// controls it reflects live.
+// The slim sticky bar above the content column: the page title on the left,
+// the always-visible safety-status pill on the right. The pill is a real
+// button — it jumps to Settings, where the controls it reflects live.
 function TopBar( { tab, tier, paused, onNavigate, notices } ) {
 	const t = TABS.find( ( x ) => x.name === tab );
-	const group = NAV_GROUPS.find( ( g ) => g.items.includes( tab ) );
 	const level = levelFor( tier );
 	let tone = level.key === 'read' ? 'safe' : 'active';
 	if ( paused ) {
@@ -174,16 +161,6 @@ function TopBar( { tab, tier, paused, onNavigate, notices } ) {
 	return (
 		<header className="saddle-topbar">
 			<div className="saddle-topbar__context">
-				{ !! group?.label && (
-					<>
-						<span className="saddle-topbar__group">
-							{ group.label }
-						</span>
-						<span className="saddle-topbar__sep" aria-hidden="true">
-							·
-						</span>
-					</>
-				) }
 				<span className="saddle-topbar__title">{ t?.title }</span>
 			</div>
 			<div className="saddle-topbar__right">
@@ -310,7 +287,7 @@ export default function App() {
 	// every addon bundle registered its filters at script evaluation.
 	const extTabs = useMemo( collectTabs, [] );
 	const extNames = useMemo( () => extTabs.map( ( t ) => t.id ), [ extTabs ] );
-	const { navItems, navFooter } = useMemo( () => {
+	const navItems = useMemo( () => {
 		const allTabs = [
 			...TABS,
 			...extTabs.map( ( t ) => ( {
@@ -319,24 +296,31 @@ export default function App() {
 				icon: <t.Icon />,
 			} ) ),
 		];
-		return {
-			navItems: NAV_GROUPS.map( ( g ) => ( {
-				heading: g.label || undefined,
-				items: [
-					...g.items,
-					...extTabs
-						.filter( ( t ) => t.group === g.key )
-						.map( ( t ) => t.id ),
-				].map( ( name ) => navItem( name, allTabs ) ),
-			} ) ),
+		// A contributed tab joins the main list unless it asked for the footer.
+		// The groups it used to be able to name are gone, so anything that is
+		// not explicitly 'footer' lands in the one list rather than nowhere.
+		const extMain = extTabs
+			.filter( ( t ) => t.group !== 'footer' )
+			.map( ( t ) => t.id );
+		const extFooter = extTabs
+			.filter( ( t ) => t.group === 'footer' )
+			.map( ( t ) => t.id );
+
+		return [
+			...[ ...NAV_MAIN, ...extMain ].map( ( name ) =>
+				navItem( name, allTabs )
+			),
+			// A real DS group rather than hand-rolled buttons in the `footer`
+			// slot: `footer: true` is what puts it in .pp-nav__bottom, and it
+			// brings aria-current and the collapsed-rail tooltips with it.
 			// Extension footer entries sit above Settings, which stays last.
-			navFooter: [
-				...extTabs
-					.filter( ( t ) => t.group === 'footer' )
-					.map( ( t ) => t.id ),
-				...NAV_FOOTER,
-			].map( ( name ) => navItem( name, allTabs ) ),
-		};
+			{
+				footer: true,
+				items: [ ...extFooter, ...NAV_FOOTER ].map( ( name ) =>
+					navItem( name, allTabs )
+				),
+			},
+		];
 	}, [ extTabs ] );
 	const [ tab, setTabState ] = useState( () => tabFromHash( extNames ) );
 	const [ wizardOpen, setWizardOpen ] = useState( false );
@@ -544,42 +528,12 @@ export default function App() {
 									<span>{ __( 'Saddle', 'saddle' ) }</span>
 								</>
 							}
-							items={ navItems }
-							value={ tab }
-							onChange={ setTab }
 							// Navigation only. Docs, Rate Saddle and the version
 							// stamp all live in Settings → About; repeating them
 							// here made a five-item footer out of a two-item one.
-							footer={
-								<>
-									{ navFooter.map( ( item ) => (
-										<button
-											key={ item.value }
-											type="button"
-											className="pp-nav__item"
-											aria-current={
-												tab === item.value
-													? 'page'
-													: undefined
-											}
-											title={ item.label }
-											onClick={ () =>
-												setTab( item.value )
-											}
-										>
-											<span
-												className="pp-nav__icon"
-												aria-hidden="true"
-											>
-												{ item.icon }
-											</span>
-											<span className="pp-nav__label">
-												{ item.label }
-											</span>
-										</button>
-									) ) }
-								</>
-							}
+							items={ navItems }
+							value={ tab }
+							onChange={ setTab }
 						/>
 					}
 				>
@@ -639,9 +593,6 @@ export default function App() {
 										onCapsChanged={ loadCaps }
 									/>
 								) }
-								{ tab === 'cookbook' && (
-									<Cookbook onNavigate={ setTab } />
-								) }
 								{ tab === 'guidance' && <Guidance /> }
 								{ tab === 'memory' && <Memory /> }
 								{ tab === 'activity' && <Activity /> }