feat(docs): add Spectrum 2 documentation and MCP server

.changeset/README.md

@@ -6,3 +6,21 @@ find the full documentation for it [in our repository](https://github.com/change
 
 We have a quick list of common questions to get you started engaging with this project in
 [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+
+## Publishing a new package (first release)
+
+Releases use GitHub Actions with **OIDC** and **provenance**. npm trusted publishing expects the package to already exist for the repo’s OIDC identity. For a **new** package that has never been published:
+
+1. **Set the package to a placeholder version** (e.g. `0.0.0`) in its `package.json`, and add `publishConfig`, `repository`, and `files` so it’s publish-ready.
+
+2. **Publish the placeholder once** to create the package on npm (this establishes the package and links it for OIDC):
+   ```bash
+   cd tools/<package-dir>
+   npm login   # if your token is expired
+   npm publish --provenance=false
+   ```
+   Use your own npm auth for this one-time publish. **Provenance** only works in CI (GitHub Actions); locally you must pass `--provenance=false` or you’ll get “Automatic provenance generation not supported for provider: null”. After this, the package exists on npm and CI can publish future versions with OIDC and provenance.
+
+3. **Add a changeset** for the real first version (e.g. `1.0.0`), merge the release PR, and let the [Release workflow](.github/workflows/release.yml) run `pnpm release`. That publish will use OIDC and provenance.
+
+Do not skip the placeholder publish and go straight to a 1.0.0 changeset in CI if the package has never been published—CI may fail with permission or package-not-found errors.

.changeset/s2-docs-mcp-initial-release.md

@@ -0,0 +1,13 @@
+---
+"@adobe/s2-docs-mcp": major
+---
+
+Initial release of S2 Docs MCP server and Spectrum 2 documentation.
+
+This adds comprehensive Spectrum 2 documentation to the monorepo:
+- **102 markdown pages** with YAML frontmatter scraped from s2.spectrum.corp.adobe.com
+- **MCP server** (`@adobe/s2-docs-mcp`) providing AI assistants with structured access to
+  S2 component docs via tools: list-s2-components, get-s2-component, search-s2-docs,
+  find-s2-component-by-use-case, get-s2-stats
+- **Transform scripts** (`tools/s2-docs-transformer`) for maintaining frontmatter and scraping
+  workflow

.lintstagedrc.js

@@ -8,14 +8,19 @@ export default {
     if (processableFiles.length === 0) return [];
     // Use -o flag (no path) to write back to same file
     return processableFiles.map(
-      (file) => `remark ${file} --use remark-gfm --use remark-github -o`,
+      (file) =>
+        `remark ${file} --use remark-frontmatter --use remark-gfm --use remark-github -o`,
     );
   },
   "!**/pnpm-lock.yaml": [],
   "!**/package-lock.json": [],
   "!**/yarn.lock": [],
   ".changeset/*.md": (files) => {
-    // Only run changeset linter on changeset files
-    return files.map((file) => `pnpm changeset-lint check-file ${file}`);
+    // Only run changeset linter on actual changeset files, not README.md
+    const changesetFiles = files.filter((file) => !file.endsWith("README.md"));
+    if (changesetFiles.length === 0) return [];
+    return changesetFiles.map(
+      (file) => `pnpm changeset-lint check-file ${file}`,
+    );
   },
 };

README.md

@@ -27,6 +27,7 @@ Packages in this monorepo:
 * [Spectrum S2 Tokens Viewer](docs/s2-tokens-viewer/) an enhanced token viewer with component usage analysis for Spectrum 2 tokens.
 * [Spectrum Tokens Docs](docs/site/) a static site to show the component options API and other token data.
 * [Release Timeline Visualization](docs/release-timeline/) interactive charts showing release frequency and development activity patterns. Published as a [static site](https://opensource.adobe.com/spectrum-design-data/release-timeline/).
+* [Spectrum 2 Documentation](docs/s2-docs/) comprehensive component guides and design principles from s2.spectrum.corp.adobe.com.
 
 ## Development Tools
 
@@ -39,6 +40,7 @@ Packages in this monorepo:
 * [Transform Tokens JSON](tools/transform-tokens-json/) utilities for merging and transforming token data between formats.
 * [Token Manifest Builder](tools/token-manifest-builder/) generates manifest files for token distribution.
 * [Spectrum Design Data MCP](tools/spectrum-design-data-mcp/) Model Context Protocol server providing AI assistants with structured access to Spectrum design system data.
+* [S2 Docs MCP](tools/s2-docs-mcp/) MCP server providing AI assistants with access to Spectrum 2 component documentation and design guidelines.
 
 ## Setup monorepo locally
 

docs/s2-docs/INDEX.md

@@ -0,0 +1,166 @@
+# Spectrum 2 Documentation - Index
+
+> Complete offline archive. Last full update: 2026-02-12
+> Source: <https://s2.spectrum.corp.adobe.com/>
+> Part of the [Spectrum Design Data](https://github.com/adobe/spectrum-design-data) monorepo.
+
+**Total pages: 100**
+
+## Fundamentals (3)
+
+* [Home](fundamentals/home.md)
+* [Introduction](fundamentals/introduction.md)
+* [Principles](fundamentals/principles.md)
+
+## Designing with Spectrum 2 (25)
+
+### Core Concepts
+
+* [Attention hierarchy](designing/attention-hierarchy.md)
+
+### Color (3)
+
+* [Grays](designing/grays.md)
+* [Colors](designing/colors.md)
+* [Background layers](designing/background-layers.md)
+
+### Typography (2)
+
+* [Fundamentals](designing/typography-fundamentals.md)
+* [Fonts](designing/fonts.md)
+
+### Layout & Styling
+
+* [Object styles](designing/object-styles.md)
+* [Spacing](designing/spacing.md)
+* [States](designing/states.md)
+* [Containers](designing/containers.md)
+
+### App Frame (10)
+
+* [S2 App Frame](designing/s2-app-frame.md)
+* [Overview](designing/app-frame-overview.md)
+* [Header](designing/app-frame-header.md)
+* [Side navigation](designing/app-frame-side-navigation.md)
+* [Content area](designing/app-frame-content-area.md)
+* [Creating bluelines](designing/app-frame-creating-bluelines.md)
+* [Browsing context: Content area](designing/s2-app-frame-content-area-browsing-context.md)
+* [Browsing context: Creating bluelines](designing/s2-app-frame-creating-bluelines-browsing-context.md)
+* [Browsing context: Header](designing/s2-app-frame-header-browsing-context.md)
+* [Browsing context: Side navigation](designing/s2-app-frame-side-navigation-browsing-context.md)
+
+### Visual Elements
+
+* [Brand](designing/brand.md)
+* [Icons: Fundamentals](designing/icon-fundamentals.md)
+* [Icons: Using icons](designing/using-icons.md)
+* [Illustrations](designing/illustrations.md)
+* [Motion](designing/motion.md)
+
+## Developing with Spectrum 2 (1)
+
+* [Developer overview](developing/developer-overview.md)
+
+## Support (2)
+
+* [FAQs](support/faqs.md)
+* [Resources](support/resources.md)
+
+## Components (69)
+
+### Actions (9)
+
+* [Action bar](components/actions/action-bar.md)
+* [Action button](components/actions/action-button.md)
+* [Action group](components/actions/action-group.md)
+* [Button](components/actions/button.md)
+* [Button group](components/actions/button-group.md)
+* [Close button](components/actions/close-button.md)
+* [Link](components/actions/link.md)
+* [List view](components/actions/list-view.md)
+* [Menu](components/actions/menu.md)
+
+### Containers (5)
+
+* [Cards](components/containers/cards.md)
+* [Divider](components/containers/divider.md)
+* [Popover](components/containers/popover.md)
+* [Standard panel](components/containers/standard-panel.md)
+* [Table](components/containers/table.md)
+
+### Feedback (11)
+
+* [Alert banner](components/feedback/alert-banner.md)
+* [Alert dialog](components/feedback/alert-dialog.md)
+* [Coach indicator](components/feedback/coach-indicator.md)
+* [Coach mark](components/feedback/coach-mark.md)
+* [Contextual help](components/feedback/contextual-help.md)
+* [Illustrated message](components/feedback/illustrated-message.md)
+* [In-line alert](components/feedback/in-line-alert.md)
+* [Standard dialog](components/feedback/standard-dialog.md)
+* [Takeover dialog](components/feedback/takeover-dialog.md)
+* [Toast](components/feedback/toast.md)
+* [Tooltip](components/feedback/tooltip.md)
+
+### Inputs (31)
+
+* [Calendar](components/inputs/calendar.md)
+* [Checkbox](components/inputs/checkbox.md)
+* [Checkbox group](components/inputs/checkbox-group.md)
+* [Color area](components/inputs/color-area.md)
+* [Color handle](components/inputs/color-handle.md)
+* [Color handle and loupe](components/inputs/color-handle-and-loupe.md)
+* [Color slider](components/inputs/color-slider.md)
+* [Color wheel](components/inputs/color-wheel.md)
+* [Combo box](components/inputs/combo-box.md)
+* [Date picker](components/inputs/date-picker.md)
+* [Drop zone](components/inputs/drop-zone.md)
+* [Field label](components/inputs/field-label.md)
+* [Help text](components/inputs/help-text.md)
+* [Number field](components/inputs/number-field.md)
+* [Picker](components/inputs/picker.md)
+* [Radio button](components/inputs/radio-button.md)
+* [Radio group](components/inputs/radio-group.md)
+* [Rating](components/inputs/rating.md)
+* [Search field](components/inputs/search-field.md)
+* [Segmented control](components/inputs/segmented-control.md)
+* [Select box](components/inputs/select-box.md)
+* [Slider](components/inputs/slider.md)
+* [Swatch](components/inputs/swatch.md)
+* [Swatch group](components/inputs/swatch-group.md)
+* [Switch](components/inputs/switch.md)
+* [Tag](components/inputs/tag.md)
+* [Tag field](components/inputs/tag-field.md)
+* [Tag group](components/inputs/tag-group.md)
+* [Text area](components/inputs/text-area.md)
+* [Text field](components/inputs/text-field.md)
+* [Thumbnail](components/inputs/thumbnail.md)
+
+### Navigation (5)
+
+* [Accordion](components/navigation/accordion.md)
+* [Breadcrumbs](components/navigation/breadcrumbs.md)
+* [Side navigation](components/navigation/side-navigation.md)
+* [Tabs](components/navigation/tabs.md)
+* [Tree view](components/navigation/tree-view.md)
+
+### Status (8)
+
+* [Avatar](components/status/avatar.md)
+* [Avatar group](components/status/avatar-group.md)
+* [Badge](components/status/badge.md)
+* [Meter](components/status/meter.md)
+* [Progress bar](components/status/progress-bar.md)
+* [Progress circle](components/status/progress-circle.md)
+* [Status light](components/status/status-light.md)
+* [Steplist](components/status/steplist.md)
+
+***
+
+## Notes
+
+* All documentation is fully offline and accessible without VPN/authentication
+* Content is current as of last update (2026-02-12); new pages may have placeholder content until scraped
+* Some pages contain links to internal Adobe resources that still require authentication
+* Screenshots and diagrams are referenced but not included in the markdown files
+* For MCP setup and integration, see this project's [README](README.md).

docs/s2-docs/README.md

@@ -0,0 +1,85 @@
+# Spectrum 2 Documentation
+
+Scraped documentation from Adobe's Spectrum 2 design system.
+
+## Overview
+
+This project contains 102 pages of S2 documentation with YAML frontmatter, including component guides, design principles, and development resources.
+
+## Structure
+
+* `components/` - 69 component docs (actions, containers, feedback, inputs, navigation, status)
+* `designing/` - 25 design guidelines (color, typography, app frame, etc.)
+* `fundamentals/` - 3 core pages (home, introduction, principles)
+* `developing/` - 1 developer overview
+* `support/` - 4 support pages (FAQs, contact, resources, quarterly recap)
+
+## Using with AI / Cursor
+
+You can give AI assistants access to this documentation in several ways:
+
+### MCP (recommended)
+
+Enable the **S2 Docs MCP** server so the AI can query docs via tools (search, get component, list by category). See [MCP Server Integration](#mcp-server-integration) below.
+
+### Cursor [**@Files**](https://github.com/Files) & Folders
+
+In Cursor chat, use **[**@Files**](https://github.com/Files) & Folders** and reference the `docs/s2-docs` folder (or a subfolder like `docs/s2-docs/components/actions`) to attach markdown files as context. The AI can then read the component guides and design guidelines directly.
+
+### Cursor [**@Docs**](https://github.com/Docs)
+
+If this documentation is published at a URL (e.g. GitHub Pages), you can add it to Cursor’s [@Docs](https://cursor.com/docs/context/mentions#docs): type **[**@Docs**](https://github.com/Docs)** in chat → **Add new doc** → paste the URL. Cursor will index the site for use in chat. Manage added docs under **Cursor Settings → Indexing & Docs**.
+
+## MCP Server Integration
+
+AI tools can query this documentation via the S2 Docs MCP server.
+
+### Setup
+
+```bash
+# Install MCP server
+cd ~/Spectrum/spectrum-design-data/tools/s2-docs-mcp
+pnpm install
+
+# Configure in .cursor/mcp.json
+{
+  "mcpServers": {
+    "s2-docs": {
+      "command": "node",
+      "args": [
+        "/Users/YOUR_USERNAME/Spectrum/spectrum-design-data/tools/s2-docs-mcp/src/cli.js"
+      ]
+    }
+  }
+}
+```
+
+### Available Tools
+
+* `list-s2-components` - Browse components by category
+* `get-s2-component` - Get full component documentation
+* `search-s2-docs` - Search across all docs
+* `find-s2-component-by-use-case` - Find components by use case
+* `get-s2-stats` - Documentation coverage statistics
+
+See [tools/s2-docs-mcp](../../tools/s2-docs-mcp/README.md) for details.
+
+## Maintenance
+
+**Updating documentation:**
+
+```bash
+# Re-run transform scripts to update frontmatter
+cd ../../tools/s2-docs-transformer
+pnpm run process-all
+
+# Regenerate component index
+cd ../s2-docs-mcp
+node src/batch-scraper.js index
+```
+
+**Scraping new content:** See the [s2-docs-transformer README](../../tools/s2-docs-transformer/README.md) for scraping and transformation tools.
+
+## License
+
+Apache-2.0 © Adobe