Added Shade conventions skills for AI agents (#28960)

closes https://linear.app/ghost/issue/DES-1394/add-shade-skills

Adds 10 auto-triggering Claude Code skills under
`.agents/skills/shade-*` that encode Shade design system rules so AI
agents follow them at the moment of edit, without needing to discover
`apps/shade/AGENTS.md`.

**Tier 1 — broad triggers, fires often:**
- `shade-imports` — layer-specific subpaths, never root barrel
- `shade-tokens-not-hex` — semantic tokens only, with full inventory
- `shade-no-dark-variants` — don't write `dark:` for colour
- `shade-use-primitives` — `Stack`/`Inline`/`Box`/`Grid` over bare flex
divs
- `shade-component-decision` — layer decision flow + promotion checklist

**Tier 2 — narrow, high-payoff triggers:**
- `shade-new-component` — acceptance checklist for new Shade files
- `shade-shadcn-install` — `pnpm dlx shadcn` guardrails + post-install
cleanup
- `shade-page-templates` — `ListPage`/`PageHeader` skeleton + page-type
taxonomy
- `shade-input-surface-recipe` — `inputSurface()` composition
- `shade-dropdown-surface-contract` — `DropdownMenu`/`Select`/`Popover`
change together

Triggers are scoped to actual Shade-consuming apps (`shade`, `admin`,
`admin-x-settings`, `admin-x-framework`, `posts`, `stats`,
`activitypub`). Public apps (`portal`, `comments-ui`, `signup-form`,
`sodo-search`, `announcement-bar`) and the legacy
`admin-x-design-system` are excluded to avoid false positives.

`apps/shade/AGENTS.md` is also tightened:
- Fixed stale `ListPage` import (now `@tryghost/shade/page-templates`,
not `/patterns`)
- Removed `ListPage` from the Patterns examples row
- Documented `page-templates/` and `posts-stats/` as additional barrels

Author: peterzimon

.agents/skills/shade-component-decision/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: Shade component decision
+description: Decide which Shade layer (Token, Primitive, Component, Recipe, Pattern) a new piece of UI belongs in — and whether it should be added to Shade at all. Trigger when creating new files in apps/shade/src/components, or proposing to add a new Shade component.
+autoTrigger:
+  - fileEdit: "apps/shade/src/components/**/*.{ts,tsx}"
+---
+
+# Shade — pick the right layer (and decide whether to add to Shade at all)
+
+Before adding anything to Shade, walk the decision flow and the promotion checklist. The default is **keep code local first** — premature design system additions lock in the wrong API.
+
+## The five layers
+
+| Layer | Lives in | Examples |
+|---|---|---|
+| **Token** | `theme-variables.css`, `tailwind.theme.css` | `--background`, `--text-base`, `--radius-md` |
+| **Primitive** | `src/components/primitives/` | `Stack`, `Inline`, `Box`, `Grid`, `Container`, `Text` |
+| **Component** | `src/components/ui/` | `Button`, `Input`, `Dialog`, `Tabs`, `Card` |
+| **Recipe** | `src/components/ui/<name>.ts` (no JSX) | `inputSurface` |
+| **Pattern** | `src/components/patterns/` | `PageHeader`, `KpiCard`, `Filters`, `GhAreaChart` |
+
+Plus two additional barrels:
+
+- **`page-templates/`** (`@tryghost/shade/page-templates`) — top-level page wrappers (`ListPage` today). Composes Patterns + Components + Primitives. If you're building a new shape that wraps a whole admin page, this is where it goes. See `shade-page-templates`.
+- **`posts-stats/`** (`@tryghost/shade/posts-stats`) — transitional layer for components shared between `apps/posts` and `apps/stats` until those merge. Don't add to it unless the file is genuinely posts-or-stats-only and shared between both apps.
+
+## Decision flow (top-to-bottom, stop at first match)
+
+1. **Just a colour, size, radius, duration?** → **Token**. Add to `theme-variables.css` (semantic) or `tailwind.theme.css` (raw `@theme`).
+2. **Layout-only (spacing, alignment, structure)?** → **Primitive**. Reuse an existing one; only add a new one if the structural shape is genuinely novel.
+3. **Generic, accessible UI control with no Ghost-specific knowledge?** → **Component**. Reuse first; only add if it doesn't exist and the promotion checklist below passes.
+4. **The same chrome / focus / density rule shared across ≥ 2 components?** → **Recipe**. A class-string function (no JSX, no React) next to the components in `src/components/ui/`.
+5. **Knows about Ghost (KPIs, members, posts, newsletters, analytics)?** → **Pattern**.
+
+**Quick gut check: generic name → Component; Ghost-shaped name → Pattern.** `Button` is web-y; `KpiCard` is Ghost-y.
+
+## Allowed dependencies (one-way)
+
+Each layer can use anything **below** it. The reverse is forbidden.
+
+- A Button can't reach into a Pattern.
+- A Primitive can't import a Component.
+- A Recipe is pure CSS classes — no React, no JSX.
+
+## Promotion checklist — add to Shade only if ALL are true
+
+1. **Reused at least twice in different surfaces.** Actual second use, not "we might reuse this."
+2. **It's generic.** A `<MembersTable>` that's just `<Table>` with three preset columns belongs in the app, not Shade.
+3. **The shape has settled.** Slots and composition have been stable across both local copies for at least one iteration.
+4. **It has a generic name.** `PageHeader`, `KpiCard`, `PostShareModal` — not `MembersFilterBar` or `PostAnalyticsHero`.
+5. **The API is slots, not props.** 3–6 named subcomponents (`.Title`, `.Actions`, `.Body`) — not `<ListPage title="..." onAdd={...} columns={...} />`.
+6. **State stays with the consumer.** No `useQuery`, no routing, no app-context reads inside Shade.
+
+**Fail any of these? Keep it local.** Build it again somewhere else first, then promote.
+
+## Common misclassifications
+
+| Tempting | Actually | Why |
+|---|---|---|
+| Add a `variant="kpi"` to `Card` | New Pattern `KpiCard` | Product-specific shape, generic Component shouldn't know about it |
+| Add `<MembersFilterBar>` to patterns | Keep local in `apps/admin-x-settings` | Single-surface name |
+| Add a one-off class string as a recipe | Inline it in the one component | Recipes are for shared rules across ≥ 2 components |
+| Add a `useQuery`-driven `<MembersList>` to patterns | Keep local — patterns are state-free | Bring-your-own state |
+| Wrap a `<div className="flex gap-3">` as a new primitive | Use `Inline gap="md"` | Already covered |
+
+## When you've decided
+
+- New **Component** or **Pattern** → also see the `shade-new-component` skill for the file/story/state checklist.
+- New **Recipe** → no JSX, follow the `recipeClasses` + `recipe()` shape (see `apps/shade/src/components/ui/input-surface.ts`).
+- New **Token** → add to `apps/shade/theme-variables.css` (semantic + dark-mode override) or `apps/shade/tailwind.theme.css` (raw `@theme`). Never an ad-hoc CSS variable in a component file.
+
+## Source of truth
+
+Full rules: `apps/shade/AGENTS.md`. Human-facing: Storybook → Overview / Layers.

.agents/skills/shade-dropdown-surface-contract/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: Shade dropdown surface contract
+description: DropdownMenu, Select, and Popover share one visual recipe (bg-surface-elevated-2 + border-border/60 dark:border-border/30 + shadow-md). Change them together. Trigger when editing any of those three Shade files.
+autoTrigger:
+  - fileEdit: "apps/shade/src/components/ui/{dropdown-menu,select,popover}.tsx"
+---
+
+# Shade — dropdown surface contract
+
+`DropdownMenu`, `Select`, and `Popover` are the three Radix-backed floating menus that `Filters` and the rest of admin use. They share **one visual recipe**:
+
+```text
+bg-surface-elevated-2
+border border-border/60 dark:border-border/30
+shadow-md
+```
+
+Treat them as one component for any surface decision. **If you change the surface for one, change all three.**
+
+## Why this exists
+
+Floating menus open ON TOP of an already-elevated surface (sidebars, cards, top bars). They need to read as floating above their trigger. `--surface-elevated-2` is reserved for exactly this — popovers, dropdown content, and the sidebar user menu.
+
+In light mode the three surface tokens (`background` / `surface-elevated` / `surface-elevated-2`) flatten to near-white; the border + `shadow-md` carry elevation. In dark mode they're three distinct colours so layered surfaces stay legible without relying on borders alone.
+
+## The contract
+
+| Concern | Class |
+|---|---|
+| Background | `bg-surface-elevated-2` |
+| Border | `border border-border/60 dark:border-border/30` |
+| Shadow | `shadow-md` baseline. **`DropdownMenuContent` is the exception — it uses `shadow-lg`.** `DropdownMenuSubContent`, `SelectContent`, and `PopoverContent` all use `shadow-md`. |
+| Radius | `rounded-md` (component default) |
+| Animation | Standard Radix `data-[state=open]:` enter/exit set |
+
+The shadow split is intentional: the top-level `DropdownMenuContent` opens straight out of an unelevated trigger (a button on the page canvas) and needs the stronger drop. `DropdownMenuSubContent` already pops from inside a floating menu, so it uses the lighter `shadow-md` to avoid double-stacking elevation. `Select` and `Popover` also open from low-elevation triggers but their content sits closer to the trigger surface, so `shadow-md` is enough.
+
+The `dark:border-border/30` is a legitimate exception to the no-`dark:`-for-colour rule — it's an opacity modifier on an existing semantic token. See `shade-no-dark-variants`.
+
+## Changing the surface
+
+If a design change touches the floating-menu surface (background, border, shadow, elevation), edit **all three** files:
+
+- `apps/shade/src/components/ui/dropdown-menu.tsx` (`DropdownMenuContent` and `DropdownMenuSubContent`)
+- `apps/shade/src/components/ui/select.tsx` (`SelectContent`)
+- `apps/shade/src/components/ui/popover.tsx` (`PopoverContent`)
+
+If a fourth Radix-backed surface needs the same recipe, extract it as a `floatingSurface` recipe under `apps/shade/src/components/ui/`. Two consumers is too thin to justify a Recipe; three is the current count and just covered by mirroring.
+
+## Items inside the menu
+
+Hover state on menu items uses `--interactive-hover` (`bg-interactive-hover`) — the generic hover token. **Don't** use raw greys or apply ad-hoc opacity modifiers (`hover:bg-gray-900/30`). The interactive tokens already handle dark-mode translucency so they composite over the floating surface correctly.
+
+## Don't
+
+```tsx
+// BAD — changing dropdown surface but not Select / Popover
+// In dropdown-menu.tsx:
+'bg-surface-elevated border border-border/40 shadow-xl'  // <-- drifted from contract
+
+// BAD — raw greys for hover instead of the interactive token
+'hover:bg-gray-100 dark:hover:bg-gray-800'
+
+// BAD — surface-elevated (not -2) on a floating menu
+// loses the visual elevation above already-elevated triggers
+'bg-surface-elevated'
+```
+
+## Related skill
+
+Hover/active/selected state tokens (`--interactive-hover`, `--button-hover`, `--tab-hover`, `--table-row-hover`): see `shade-tokens-not-hex`.
+
+## Source of truth
+
+`apps/shade/AGENTS.md` (Tokens & dark mode → Dropdown surface contract). Storybook → Tokens / Tokens Guide.

.agents/skills/shade-imports/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: Shade imports
+description: Import Shade from layer-specific subpaths (primitives, components, patterns, page-templates, utils), never the root barrel. Trigger when editing TSX/TS in Shade-consuming apps.
+autoTrigger:
+  - fileEdit: "apps/{shade,admin,admin-x-settings,admin-x-framework,posts,stats,activitypub}/**/*.{ts,tsx}"
+---
+
+# Shade imports
+
+Always import Shade from its **layer-specific subpath**. Never from the root barrel `@tryghost/shade`.
+
+## Correct
+
+```ts
+import {Stack, Inline, Box, Grid, Container, Text} from '@tryghost/shade/primitives';
+import {Button, Input, Dialog} from '@tryghost/shade/components';
+import {PageHeader, KpiCard, Filters} from '@tryghost/shade/patterns';
+import {ListPage} from '@tryghost/shade/page-templates';
+import {PostShareModal} from '@tryghost/shade/posts-stats';
+import {cn, formatNumber} from '@tryghost/shade/utils';
+import {ShadeApp} from '@tryghost/shade/app';
+```
+
+**Note:** `ListPage` is in `@tryghost/shade/page-templates`, not `/patterns`. Page templates are top-level page wrappers; patterns are the building blocks they compose.
+
+## Incorrect
+
+```ts
+// BAD — root barrel
+import {Button, Stack} from '@tryghost/shade';
+
+// BAD — deep path into source
+import {Button} from '@tryghost/shade/src/components/ui/button';
+```
+
+## Inside Shade itself
+
+When editing files under `apps/shade/src/**`, use the `@/` alias for cross-file imports:
+
+```ts
+import {cn} from '@/lib/utils';
+import {inputSurface} from '@/components/ui/input-surface';
+```
+
+## Why
+
+Subpath imports make the layer (primitive/component/pattern) visible at the call site, which is the first piece of information a reader needs. The root barrel hides that and encourages cross-layer drift.

.agents/skills/shade-input-surface-recipe/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: Shade inputSurface recipe
+description: Use the inputSurface() recipe for form-control chrome (border, background, radius, focus ring, invalid state) — don't roll your own. Trigger when editing form-control-shaped files in Shade.
+autoTrigger:
+  - fileEdit: "apps/shade/src/components/ui/{input,textarea,input-group,select,combobox,multi-select-combobox,dropzone,calendar,command}.tsx"
+---
+
+# Shade — `inputSurface` recipe
+
+Form controls share one visual rule: border, background, radius, transition, focus ring, invalid state. That rule lives in **`inputSurface`** (`apps/shade/src/components/ui/input-surface.ts`) and is used by `Input`, `Textarea`, `InputGroup`, and the `Select` trigger. Don't duplicate the chrome — compose the recipe.
+
+```ts
+import {inputSurface, inputSurfaceClasses} from '@/components/ui/input-surface';
+import {cn} from '@/lib/utils';
+```
+
+## Two common modes
+
+### `inputSurface('self')` — directly on the focusable element
+
+Use on `<input>`, `<textarea>`, or any element that itself receives focus.
+
+```tsx
+<input
+    className={cn(
+        inputSurface('self'),
+        'flex h-9 w-full px-3 py-1 text-control placeholder:text-muted-foreground',
+        className
+    )}
+    {...props}
+/>
+```
+
+Covers: base chrome + `focus-visible:` ring + `aria-[invalid=true]` styling + `disabled:` opacity.
+
+### `inputSurface('within')` — on a wrapper containing a focusable child
+
+Use when the styled element is the wrapper (e.g. `InputGroup`) and focus state should react to **any** focusable descendant via `:has()`.
+
+```tsx
+<div className={cn(
+    inputSurface('within'),
+    'flex h-9 items-center gap-2 px-3',
+    className
+)}>
+    <Icon />
+    <input className="bg-transparent outline-hidden focus:outline-hidden" />
+</div>
+```
+
+Covers: base chrome + `has-[:focus-visible]:` ring + `has-[[aria-invalid=true]]:` styling. (No disabled atom — wrappers don't get a `disabled` HTML attribute.)
+
+## Edge case — only one specific child triggers focus state
+
+When `'within'` is too broad (e.g. a wrapper with multiple focusables but only one should drive chrome), compose atoms manually so Tailwind's JIT can statically detect the class string:
+
+```tsx
+import {inputSurfaceClasses} from '@/components/ui/input-surface';
+
+<div className={cn(
+    inputSurfaceClasses.base,
+    inputSurfaceClasses.invalidWithin,
+    // Literal class string — Tailwind needs to see it as text
+    'has-[[data-slot=control]:focus-visible]:border-focus-ring',
+    'has-[[data-slot=control]:focus-visible]:ring-2',
+    'has-[[data-slot=control]:focus-visible]:ring-focus-ring/25'
+)} />
+```
+
+Available atoms:
+
+- `inputSurfaceClasses.base` — border, background, radius, transition
+- `inputSurfaceClasses.focusSelf` — focus chrome for self mode
+- `inputSurfaceClasses.focusWithin` — focus chrome for within mode
+- `inputSurfaceClasses.invalidSelf` — `aria-[invalid=true]` styling on self
+- `inputSurfaceClasses.invalidWithin` — `aria-[invalid=true]` styling on a descendant
+- `inputSurfaceClasses.disabledSelf` — disabled styling for self mode
+
+## What the recipe owns vs. what you add
+
+| Recipe owns | You add |
+|---|---|
+| Border (`border-control-border`) | Height, padding |
+| Background (`bg-surface-elevated`, `dark:bg-transparent`) | Typography (`text-control`, `text-sm`) |
+| Radius (`rounded-md`) | Layout (`flex`, `items-center`) |
+| Transition (`transition-colors`) | Placeholder styling |
+| Focus ring (`focus-visible:ring-focus-ring/25`) | Component-specific tweaks |
+| Invalid state (`aria-[invalid=true]:border-destructive`) | Icons / slot positioning |
+| Disabled (`disabled:opacity-50`) — self only | — |
+
+## Don't
+
+```tsx
+// BAD — rolling your own focus chrome on a form control
+<input className="
+    rounded-md border border-input bg-background
+    focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring
+    aria-[invalid=true]:border-red-500
+    disabled:opacity-50
+" />
+
+// BAD — using inputSurface('within') on a self-focused element (over-broad)
+<input className={cn(inputSurface('within'), 'h-9')} />
+
+// BAD — non-literal class concatenation that Tailwind JIT can't see
+const dyn = `has-[[data-slot=control]:focus-visible]:${ringColor}`;
+```
+
+## Source of truth
+
+`apps/shade/src/components/ui/input-surface.ts` — the JSDoc on `inputSurface` is canonical. Human docs: Storybook → Recipes / inputSurface.