feat(admin): Saddle Violet, a flat rail, and a Dashboard that leads with a sentence (#153) (#154)

* feat(admin): put the admin UI on the Saddle Violet palette

Replaces the monochrome accent (#171717) with the brand palette, as
consumer-side --pp-* overrides in Saddle's own stylesheet. Nothing in
node_modules or the library is touched; the DS defines its tokens inside
:where(), which has zero specificity, so a plain class selector wins
without !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 the whole palette follows: every color has a bright value for
FILLS and a darker same-hue value for TEXT. This is not a stylistic
choice — three of the four given hexes cannot carry text at all (lime
1.98:1 on white, cyan 2.43, coral 3.67), and the DS derives
--pp-tone-text from --pp-tone for status, so a lime --pp-success would
have meant lime badge text at 1.9:1: materially worse than what ships
today. The readable partners go back at the tone layer, the same seam
the accent tone already uses.

Lime, cyan and amber each move one step down their own ramp for the
MARK tier too. A status dot or a 2px lane rail has to clear 3:1 on a
white card to be seen, and at the -500 step they are at 1.98 and 2.43 —
invisible. Coral already clears it and is used exactly as given. The
Permissions lane rails take the readable step for the same reason: a
2px hairline at 1.9:1 is not there at all.

Warning stays amber rather than folding into coral. Saddle says two
different things with those: amber is "powerful, asks first" (the
Remove lane, the shield chip, the write-tier pill) and red is "blocked
or failed" (a denied call, a connection error). They need opposite
reactions from the reader.

Also here, because they are all color decisions in the same block:

- Neutrals warmed onto #FBFBFA / #111111. The ramp is the only lever
  needed — no DS component reads --pp-n-* directly, all eleven feed ten
  semantic aliases — and the lightness steps are unchanged, so no
  hierarchy moves. Muted text goes 4.40 -> 4.50, clearing AA.
- --pp-focus set explicitly. It is a separate literal that no accent
  file touches, so Saddle has been shipping a monochrome accent with a
  WordPress-blue focus ring this whole time.
- Radii tightened to 3/4/6px and elevation flattened, to sit closer to
  wp-admin's own register while staying a hair softer. Pills untouched.
- .pp-code--dark's ground pinned to near-black. It reads --pp-code-bg
  from --pp-action but hard-codes its border, muted and body colors, so
  a violet action token would have left 35 CodeBlock/Snippet instances
  violet-backed with muted text at 2.26:1.
- The brand mark is recolored through the nav lockup, never in the SVG:
  editing the file would break the `black` sentinel that core's
  svg-painter needs to repaint the wp-admin menu icon.

Four token references were already broken and would have stayed broken
through any re-brand: --pp-fg-muted, --pp-fg and --pp-fg-subtle do not
exist in @plugpress/ui 0.12.0, and --s-accent was referenced by the
Cookbook recipe bar but defined nowhere in the repo.

Refs #153

* 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

* docs: session log for the admin re-brand and UX pass

Refs #153

Author: ifahimreza

STATUS.md

@@ -1,4 +1,25 @@
 ## Last session
+2026-08-25, later (**the admin UI re-branded on Saddle Violet, the rail flattened, and the Dashboard rewritten to lead with a sentence**) — Issue [#153](https://github.com/plugpressco/saddle/issues/153), PR [#154](https://github.com/plugpressco/saddle/pull/154); companion Pro PR [saddle-pro#78](https://github.com/plugpressco/saddle-pro/pull/78). **637 tests** (was 643 — the 6 are the Cookbook's), 0 lint errors both languages.
+
+**The palette, and the rule that shaped all of it.** Fahim's brand palette went in as consumer-side `--pp-*` overrides in Saddle's own stylesheet — never the library, and no `!important` needed because the DS defines its tokens inside `:where()`. The load-bearing finding: **three of the four accent hexes cannot carry text.** On white, violet is 5.84:1 but lime is **1.98**, cyan **2.43**, coral **3.67** — and the DS derives `--pp-tone-text` from `--pp-tone` for status, so a lime `--pp-success` would have meant lime badge text at 1.9:1, *worse than what ships today*. So every color has a bright value for fills and a darker same-hue value for text, with the readable partners put back at the tone layer. Lime, cyan and amber each moved **one step down their own ramp** for the mark tier too, because a status dot or a 2px rail needs 3:1 to be seen at all. Warning stayed amber rather than folding into coral: Saddle uses amber for "powerful, asks first" and red for "blocked or failed", and the Permissions screen needs both.
+
+**Two latent things surfaced on the way.** `--pp-focus` is a separate literal that no accent file touches, so Saddle had been shipping a monochrome accent with a **WordPress-blue focus ring** since the DS migration. And `.pp-code--dark` reads its background from `--pp-action` while hard-coding its border, muted and body colors — so a violet action token would have left 35 `CodeBlock`/`Snippet` instances violet-backed with muted text at 2.26:1. Pinned back to near-black in one line; the upstream fix belongs in `plugpress-ui`.
+
+**Four token references were already broken** and would have stayed broken through any re-brand: `--pp-fg-muted`, `--pp-fg` and `--pp-fg-subtle` don't exist in v0.12.0, and `--s-accent` was referenced by the Cookbook recipe bar and defined nowhere.
+
+**The UX pass, in Fahim's words:** *"no group in sidebar… simple name"*, *"dashboard make overview cleaner page"*, *"remove cookbook"*, *"make like apple company ux"*. The rail is one flat list — a pure data change, since `AppNav` takes a mixed array of items and groups. Two things fell out and were cleaned rather than left half-done: `TopBar`'s group breadcrumb had nothing left to resolve, and the footer was 28 lines of raw `<button>`s re-implementing the DS's own nav-item markup when the DS supports footer groups natively (`footer: true`), which brings `aria-current` and the collapsed-rail tooltips with it. Labels: **Guidance → Instructions**, **Connections → Apps**; routing keys untouched, so every `#hash` still resolves — verified in the browser.
+
+**The Dashboard now opens with `levelFor( tier ).one`** — "Your AI can create and edit content. Deleting always asks you first." It had four equal tiles of three different kinds, paraphrasing that sentence down to one word, plus a `Connection` tile that read `—` on most installs while a real problem already had its own callout. Counts are one quiet line; the tile grid is gone.
+
+**The Cookbook is deleted** — screen, CSS, REST route, PHP class, 6 tests. Verified not agent-facing first: `Saddle_Cookbook` had exactly three references and zero hits across abilities, system context, context bundle, skills, playbooks and the MCP transport. Its `saddle_cookbook_recipes` filter goes with it (no consumer, Pro checked).
+
+**Pro's License moved off the sidebar into Settings** — one PR in `saddle-pro`, none needed in free. The component was already a single `<Card>` wrapped in a `PageHeader`. The part that would have broken silently: `url()` deep-linked to `#license`, which routed only because `license` was a registered *tab* id, so the Plugins-row link and the update notice would have landed on a dead hash. Now `#settings`, test moved with it.
+
+**Also:** the `LEVELS` strings in `api.js` were raw English, never wrapped in `__()` — including the sentence now used as the Dashboard headline. `DESIGN-ALIGNMENT.md`'s 2026-07-04 monochrome DECIDED replaced (kept below as history) with the palette, the 85/15 rule, the fill/text split and the recorded deviation from the DS's near-black-buttons rule.
+
+**Next up:** Fahim reviews #154 and saddle-pro#78. Both are red on CI for #145 alone. `main` still at `1.0.0-rc8`; nothing self-hosted may be published from this tree without a bump.
+
+## Previous session
 2026-08-25 (**WordPress.org review round 2 — they were right about `get-media`, and it was five abilities wider; fixed, swept, verified on a live install, `.org` zip rebuilt**) — Issue [#148](https://github.com/plugpressco/saddle/issues/148), PR [#149](https://github.com/plugpressco/saddle/pull/149) **ready, deliberately not merged**. **643 tests** (was 612), 0 lint errors. Plugin Check against the built zip: **0 errors**.
 
 **Their finding, and why it was bigger than the line they cited.** The reviewer flagged `saddle/get-media` for checking only the generic `read` capability. Correct — and the reason it matters generalizes: read-tier abilities pass `$cap = 'read'`, which **every logged-in user holds including a Subscriber**, any logged-in user can mint a core Application Password, and the MCP route requires only `is_user_logged_in()`. So the permission callback proved the caller was signed in and nothing more, across the whole read surface. The write side has guarded against exactly this since day one (`authorize_write()`, rule 4 of the wp-security-rules skill); the read side had the same idea implemented **three times** and applied to half the abilities. Six gaps: `get-media`, `get-post`/`get-page`, `list-post-revisions`, `list-posts`/`list-pages`, `search-content`, `list-media`.

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');