Rewrote Shade Storybook docs in conversational prose, added Terms section

[peterzimon]

Summary

Rewrites the Shade Storybook documentation pages so they read like prose written by a human, not bullet points generated by a machine. Adds a proper Terms section to the Architecture page that defines the words we throw around (tokens, primitives, components, recipes, layouts, features, app).

ref https://linear.app/tryghost/issue/DES-1343

What changed

Six docs rewritten:

• introduction.mdx — Welcome page. What Shade is, who it's for, getting set up.
• architecture.mdx — How the layered system works. New Terms section defining each layer with examples. Includes the file-system-vs-entrypoint mismatch (features/ on disk vs @tryghost/shade/patterns) that's been a quiet source of confusion.
• tokens.mdx — What tokens are, how they're defined, how to consume them.
• primitives-guide.mdx — Why primitives exist, when to reach for each, prop reference, migration examples.
• component-contracts.mdx — What you can rely on from a Shade component (rules and guarantees).
• contributing.mdx — Practical guide for adding to or changing Shade.

One doc left alone:

• migration-root-imports.mdx — Already a tight reference table; that's the right format for it.

Why

The previous docs read as defensive, robotic, and bullet-heavy. Workable as machine-readable reference, frustrating to learn from. Storybook is meant to be the source of truth for the design system, and humans need it as much as agents do.

The rewrites:

• Lead with prose, weave examples into the text instead of dropping them after definitions.
• Use a POV voice ("you", "we") so it reads like a colleague explaining the system.
• Keep bullet lists for genuinely list-like content (prop tables, the migration table, acceptance checklists). Drop them when they're just a list of sentences.
• Don't lose context — every rule, prop reference, and example from the old docs is preserved, just in a more readable shape.

Still useful for AI agents: the Terms section is now an explicit glossary an agent can ground its choices in, and the layer rules are stated plainly enough that "which layer does this belong in" has an answerable rule.

[coderabbitai]

Walkthrough

This pull request comprehensively revises the Shade design system documentation across six MDX files. The updates introduce a new layered mental model for understanding Shade's organization (Tokens → Primitives → Components → Recipes → Features), reorganize foundational guides with simplified narratives and practical examples, and establish clearer contributor workflows. Changes include reworked architecture documentation, refined component contract definitions with structured agent templates, updated contribution guidance with code examples for variants and static properties, refreshed introductory content targeting monorepo consumption, simplified primitives and tokens guides with improved prop documentation, and consolidated conventions. All changes are documentation-only with no alterations to exported public APIs or TypeScript signatures.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: rewriting Shade Storybook docs into conversational prose and adding a Terms section, which aligns with the primary focus of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description clearly explains the rationale for rewriting six Shade Storybook documentation pages from bullet-heavy format to conversational prose, defines the scope of changes, and articulates the reasoning behind the stylistic and structural improvements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DES-1343/shade-storybook-docs-rewrite

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/shade/src/docs/component-contracts.mdx`:
- Line 29: The wording incorrectly calls TrendBadge and MetricValue
"primitives"; update the text in the components/ui/ description to say they are
"smaller helpers" (or "smaller helpers like `TrendBadge` and `MetricValue`")
instead of "primitives" so it matches the Terms section that reserves
"primitives" for `Stack`, `Inline`, `Box`, `Container`, `Grid`, and `Text`; edit
the sentence referencing `TrendBadge` and `MetricValue` to use the corrected
phrase.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fd4dae47-2554-4961-ab9d-e6db4bfc1383

📥 Commits

Reviewing files that changed from the base of the PR and between 4b94747 and b1c2327.

📒 Files selected for processing (6)

• apps/shade/src/docs/architecture.mdx
• apps/shade/src/docs/component-contracts.mdx
• apps/shade/src/docs/contributing.mdx
• apps/shade/src/docs/introduction.mdx
• apps/shade/src/docs/primitives-guide.mdx
• apps/shade/src/docs/tokens.mdx

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Terminology conflict: TrendBadge and MetricValue are not "primitives" in Shade's vocabulary.

Line 29 labels TrendBadge and MetricValue as "primitives," but the architecture doc (and the Terms section you just wrote) defines primitives strictly as the six layout building blocks: Stack, Inline, Box, Container, Grid, Text. A reader coming from that page will be confused.

These are small helper components — a more accurate description would be "smaller helpers like TrendBadge and MetricValue."

✏️ Proposed fix

-Other things in `components/ui/` (recipes like `inputSurface`, smaller helpers, primitives like `TrendBadge` and `MetricValue`) follow the same spirit but don't yet have formal rule documents.
+Other things in `components/ui/` (recipes like `inputSurface`, smaller helpers like `TrendBadge` and `MetricValue`) follow the same spirit but don't yet have formal rule documents.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	Other things in `components/ui/` (recipes like `inputSurface`, smaller helpers, primitives like `TrendBadge` and `MetricValue`) follow the same spirit but don't yet have formal rule documents.
	Other things in `components/ui/` (recipes like `inputSurface`, smaller helpers like `TrendBadge` and `MetricValue`) follow the same spirit but don't yet have formal rule documents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/shade/src/docs/component-contracts.mdx` at line 29, The wording
incorrectly calls TrendBadge and MetricValue "primitives"; update the text in
the components/ui/ description to say they are "smaller helpers" (or "smaller
helpers like `TrendBadge` and `MetricValue`") instead of "primitives" so it
matches the Terms section that reserves "primitives" for `Stack`, `Inline`,
`Box`, `Container`, `Grid`, and `Text`; edit the sentence referencing
`TrendBadge` and `MetricValue` to use the corrected phrase.