Repository navigation
🚧 [Do not merge] Shade for Ghost apps — milestone 1 experiments - #32111
Draft
peterzimon wants to merge 8 commits into
Draft
peterzimon wants to merge 8 commits into
peterzimon wants to merge 8 commits into
Conversation
ref https://linear.app/ghost/issue/DES-1586/ Shade's design rules live once, in its Storybook .mdx docs. Agents building Ghost apps outside the monorepo can't read those: the package shipped no docs, and page-header.d.ts pointed at an .mdx file that wasn't in it. The build now turns every .mdx under src/ into plain Markdown in docs/, with story canvases replaced by the story's code, so each published alpha carries the docs that match it. The generated files are never edited by hand. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ref https://linear.app/ghost/issue/DES-1585/ Trying a Shade change in an app outside the monorepo meant publishing an alpha. `pnpm pack:local <app-dir>` builds and packs Shade exactly as CI publishes it, stamps a local version, and installs it into the app with `--no-save`, so the app's package.json and lockfile stay as an outside developer's would. `--watch` runs the app's dev server and repeats this on every change, for a loop of a few seconds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Comment |
|
| Command | Status | Duration | Result |
|---|---|---|---|
nx run-many -t test:unit -p @tryghost/shade,@tr... |
✅ Succeeded | 7m 17s | View ↗ |
nx run @tryghost/admin:test:acceptance --shard=3/3 |
✅ Succeeded | 6m 41s | View ↗ |
nx run @tryghost/admin:test:acceptance --shard=2/3 |
✅ Succeeded | 6m 4s | View ↗ |
nx run @tryghost/admin:test:acceptance --shard=1/3 |
✅ Succeeded | 5m 59s | View ↗ |
nx run ghost-monorepo:lint:boundaries |
✅ Succeeded | 22s | View ↗ |
nx run-many -t lint -p ghost-monorepo,@tryghost... |
✅ Succeeded | 2m 51s | View ↗ |
nx run @tryghost/activitypub:test:acceptance --... |
✅ Succeeded | 47s | View ↗ |
nx run-many -t test:unit -p @internal/scripts,@... |
✅ Succeeded | 39s | View ↗ |
Additional runs (4) |
✅ Succeeded | ... | View ↗ |
💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗
☁️ Nx Cloud last updated this comment at 2026-10-22 11:52:56 UTC
ref https://linear.app/ghost/issue/DES-1587/ Ghost apps outside the monorepo will be built by agents that only have the npm package. Six Shade skills held design rules of their own, written for monorepo contributors, so rules lived in two places and none of them shipped. The rules now live once in the Storybook docs, which the package carries as Markdown, and each skill is a short guide that says when to apply which doc. The skills ship in the package's skills/ folder; the next commit links the monorepo's .agents/skills to those copies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…them ref https://linear.app/ghost/issue/DES-1587/ The six generic Shade skills now live in apps/shade/skills, so the monorepo links to them instead of keeping duplicates. The agent-skill checker skipped linked skills, so it now follows a link and fails if its target is missing. The skills link to the generated docs, which only exist after a build, so the doc-link checks build Shade's docs first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ref https://linear.app/ghost/issue/DES-1587/ Symlinking the six package skills into .agents/skills tripped up tools that don't follow links, such as the pre-commit backup and the skill checker. One small repository skill, shade-design, now triggers on UI work in Admin and points to the matching skill in apps/shade/skills, so agents in the monorepo still find them when they need them, without a second copy or any links. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #32111 +/- ##
==========================================
+ Coverage 85.10% 85.40% +0.30%
==========================================
Files 1392 1395 +3
Lines 52302 52371 +69
Branches 8994 9116 +122
==========================================
+ Hits 44511 44729 +218
+ Misses 6660 6557 -103
+ Partials 1131 1085 -46
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
ref https://linear.app/ghost/issue/DES-1588/ Agents building Ghost apps start in an empty folder with nothing but a brief. Setting Shade up in an app framed inside Admin took a hand-built reference app and two dozen snags to get right, and none of it was written down. A new doc page, "Using Shade in a Ghost app", holds that setup once. The shade-in-ghost-app skill ships in the package and walks it, and the shade-for-ghost-apps entry skill, installed from GitHub, installs Shade and points agents at the skills and docs inside node_modules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ref https://linear.app/ghost/issue/DES-1587/ Agents should read Shade's docs from one place. Shipping them inside the npm package meant a second copy next to the hosted Storybook we'll have later. Storybook now serves every .mdx doc as plain Markdown at /docs/<page>.md, with an llms.txt index, rebuilt as the sources change. The npm package goes back to shipping code only, and the repository tooling that only existed for the in-package docs is restored to what it was. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… as the front door ref https://linear.app/ghost/issue/DES-1588/ Skills linked to docs inside node_modules, which no longer ship there. Each skill now links to https://shade.ghost.org/docs/<page>.md and uses another address when the app's AGENTS.md names one, so a local Storybook stands in during development. The entry skill and the app skill merge into build-ghost-app-ui, installed with the rest in one `npx skills add`, and it tells agents to trust the installed package for what exists and the docs for how to use it. ghost-app-ui-dev-setup is an internal, manual-only skill for Ghost's team: in an empty folder it installs the skills from a local checkout, points them at the local Storybook, prepares the unpublished app SDK and adds light guardrails, so the app can then be built in a fresh chat the way an outside developer would. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Author
|
This exploration is now split into three stacked draft PRs for review:
This PR stays open as the record of the exploration and won't be merged. |
peterzimon
added a commit
that referenced
this pull request
Oct 27, 2026
ref https://linear.app/ghost/issue/DES-1588/ The first of three stacked PRs that get Shade ready for third-party Ghost apps. It's documentation only. The direction is in [Direction: docs, skills and testing for Ghost apps](https://linear.app/ghost/document/direction-docs-skills-and-testing-for-ghost-apps-9df789001cd3), and the exploration is on #32111, which stays open as the record. ## Why Third-party Ghost apps will be built with Shade, often by AI agents. Agents and outside developers can only follow Ghost's design rules if they're written down where they can read them. Until now: - many rules lived only inside agent skills in the monorepo; - the README mixed instructions for people *using* Shade with steps that only make sense inside the Ghost repo. Some were even wrong for apps: "don't import `styles.css`" is true for Admin's embedded apps, but an app in a frame must import it. This PR writes the rules once, in the docs everyone reads. It also gives each audience one clear place: - the README and Storybook for using Shade; - `CONTRIBUTING.md` for working on it. ## What changes - **Using Shade and working on Shade are separated.** - `README.md` (what npm shows) is rewritten for people *using* Shade: what it is, installing it in a standalone surface or app, the note that it's already set up inside Admin, and where the docs are. - The new `CONTRIBUTING.md` (not shipped to npm) holds everything about *working on* Shade: the Contributing and Layers pages, which leave Storybook, and the README's developer sections. - **Docs improvements.** Rules that lived only in agent skills now live in the Storybook docs: - the semantic token table and a Dark mode section; - the spacing scale, and which primitive to use when; - Imports, with embedded vs standalone setup; - "Composing a page". - **A new "Using Shade in a Ghost app" doc:** install, Tailwind, fonts, `ShadeApp`, theme, page frame, which template to start from, and which docs apply to apps. - **Corrections:** `DetailPage` exists, contrary to what the docs said, and two broken Storybook links are fixed. - Every link to the removed pages is fixed. No code changes, so it publishes a new Shade alpha with only the README changed.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Warning
Do not merge. This is an experiment branch for Shade as a platform design system — v0.1. Nothing here should reach
mainor npm until the approach is settled. Merging would publish a new@tryghost/shadealpha.ref https://linear.app/ghost/issue/DES-1586/
ref https://linear.app/ghost/issue/DES-1587/
ref https://linear.app/ghost/issue/DES-1588/
This branch gets Shade ready for third-party Ghost apps, which run as full pages in an iframe inside Admin. The goal: an AI agent given only Shade's skills builds app screens that look and behave like the rest of Admin. The direction is written up in Direction: docs, skills and testing for Ghost apps.
Where it stands (latest commits)
.mdxdoc is served as plain Markdown at/docs/<page>.md, with an/llms.txtindex, rebuilt as the sources change. Later this will be hosted atshade.ghost.org; locally it'shttp://localhost:6006.npx skills add TryGhost/Ghost/apps/shade/skills.build-ghost-app-uiis the front door: setup, the docs address, the order of trust (the installed package for what exists, the docs for how to use it, Ghost's source as reference only) and a self-check.AGENTS.mdcan point them at a local Storybook with aShade docs:line..mdxdocs. The skills hold none of their own. New docs include "Using Shade in a Ghost app", a token table, a Dark mode section, the spacing scale, Imports, and Composing a page.shade-designis a small repository skill that points monorepo agents at the Shade skills.ghost-app-ui-dev-setup(apps/shade/dev-skill/, internal, manual-only) sets up an empty folder for trying app UI development locally:pnpm pack:local <app-dir> [--watch]tries unpublished Shade code in an external app without publishing.Earlier commits on this branch shipped docs and skills inside the package; the latest two commits replace that approach.
🤖 Generated with Claude Code