feat: Unified Community Marketplace — themes + compositions in one repo

## Summary

A unified community marketplace for themes, compositions, and templates — managed as a single monorepo with paired XDS versioning. Internally, this evolves `xds-common` into the marketplace. Externally, it's a separate community repo.

This ties into the docsite Marketplace tab and the broader XDS ecosystem vision.

## Motivation

Themes, compositions, and templates are community-contributed artifacts that all share the same maintenance problem: staying compatible with XDS core across versions. Managing them separately multiplies that burden. A single marketplace with one CI pipeline, one upgrade command, and one release cycle solves it once.

### Why not separate packages?

Individual contributors maintaining their own npm packages don't keep up with breaking changes. Themes silently degrade — buttons revert to default blue, token overrides stop applying — and nobody notices until it's embarrassing. A collectively-maintained marketplace with automated upgrades prevents this.

### Why one marketplace, not separate theme/composition repos?

Same maintenance problem, same solution. One `xds upgrade` run, one CI pipeline, one release. Compositions and themes also pair naturally — a dashboard layout might look best with a specific theme. Having them together makes those connections visible.

## Three-Tier Distribution Model

| Tier | Where it lives | Who maintains it | Versioning |
|------|---------------|-----------------|------------|
| **Core** | XDS OSS monorepo (`packages/themes/`) | XDS team | Lockstep with `@xds/core` |
| **Marketplace** | Unified marketplace repo (internally: `xds-common` in internal monorepo) | XDS team runs upgrades; contributors own their directories | Lockstep with `@xds/core` |
| **Independent** | Author's own repo/package | Author | Author's own cadence; `xds upgrade` CLI available |

**The incentive:** contribute to the marketplace and get free maintenance (codemods, validation, releases handled for you), or go independent and handle it yourself.

## Internal Strategy: Evolving `xds-common`

`XDS Common` already exists in internal monorepo as a internal libs that wraps XDS with Meta-specific components. It:
- Lives where internal consumers already are (internal source path apps)
- Has `@xds/core` as a peer dependency
- Gets updated as part of the XDS publish process

Instead of creating a new internal repo, evolve `xds-common` into the internal marketplace. Brand themes (WhatsApp, Meta, Instagram), shared compositions, and Meta-specific templates all live here. Internal teams PR contributions in; the XDS upgrade process keeps everything compatible.

## Structure

Each theme/composition is its own package because dependencies vary — a WhatsApp theme might need Material icons while an Instagram theme needs its own icon set. You shouldn't have to download all icon libraries just because you want one theme.

```
marketplace/
themes/
whatsapp/
src/index.ts # defineTheme call
package.json # declares icon/font peer deps
instagram/
...
compositions/
dashboard-layout/
src/index.tsx # component composition
package.json
settings-page/
...
templates/
admin-panel/
...
```

All packages versioned in lockstep. Separate npm publishes so consumers install only what they need.

## Automated Upgrade Flow

When XDS core ships a new version:

1. `xds upgrade` runs in the marketplace repo — bumps deps + runs codemods across all themes/compositions
2. Validation pipeline runs on everything (token checks, contrast, build)
3. If everything passes → PR is merge-ready (or auto-merged in CI)
4. If something breaks → PR shows exactly which contributions need manual attention from their codeowners
5. Merge → publish all marketplace packages at the new version

This is the same `xds upgrade` command that independent publishers use on their own repos. The only difference is who runs it.

## CI Validation on Contributions

PRs into the marketplace automatically run:

- **Token validation** — all overridden tokens exist in the XDS token registry (no typos, no deprecated names)
- **Build check** — `xds theme build` succeeds for themes; standard build for compositions
- **Contrast checks** — reported as warnings, not blocking (per #918 brand accuracy philosophy — respect the brand team's intent)
- **Component rendering** — themes render in Storybook/Sandbox to catch visual breakage
- **Composition rendering** — compositions render with default + marketplace themes

Most PRs should be merge-ready before a human reviews. Human review focuses on quality and brand accuracy, not boilerplate.

## Contributor Model

- Theme/composition authors are **codeowners** of their directory
- They can iterate freely (fix colors, add component overrides, update compositions)
- Governance gates on: does it build, does it pass validation, does it not break other contributions
- Standard `CONTRIBUTING.md` + directory scaffold so every contribution follows the same structure

## Docsite Integration

The Marketplace tab on the docsite surfaces everything from this repo:
- Browse themes with live previews (rendered in Sandbox)
- Browse compositions with examples
- Browse templates with screenshots
- Filter by category, brand, style
- Install instructions per package

## Scaling Mechanisms

| Mechanism | What it does |
|-----------|-------------|
| **Automated compatibility PRs** | CI opens upgrade PRs when core ships; humans review and merge |
| **Contribution scaffold** | `CONTRIBUTING.md` + standard directory structure reduces review friction |
| **Storybook/Sandbox dogfooding** | Every theme and composition renders automatically in the showcase — visual breakage is obvious |
| **Codeowner model** | Contributors own their directory; XDS team owns infra and cross-cutting upgrades |
| **`xds upgrade` integration** | Same CLI command works for marketplace, independent packages, and consumer apps |

## Relationship to #918 (Brand Theming)

This issue covers the **distribution and maintenance** layer. #918 covers the **creation, validation, and governance** layer. They're complementary:

- #918's validation pipeline (contrast checks, component visual audit, quality tiers) runs as CI in this marketplace
- #918's semantic mapping framework (token conflict detection) becomes part of `defineTheme` validation
- #918's brand accuracy philosophy (inform, don't block) governs the CI gates here
- #918's theme creation methods are agent workflows, not marketplace infrastructure

## Open Questions

- Should the OSS marketplace repo live under `facebookexperimental` or a new org?
- What's the minimum quality bar for accepting a contribution? (builds + validates? quality review? brand owner sign-off for brand themes?)
- How do we handle compositions that pair well with specific themes? (documentation? metadata? Sandbox previews with specific themes?)
- Should templates (page-level scaffolds) live here too, or stay in the CLI?
- What's the migration path for existing themes? (WhatsApp theme currently in the main repo as a PR — does it move to marketplace, or stay in core?)

## Related

- #918 — Brand theming: creation, distribution, governance
- #792 — CSS cascade ordering for theming priority
- #278 — XDSDashboardLayout (composition candidate)

*— Navi, on behalf of @cixzhang*