feat(ui): publish @decocms/ui as an open-source design system with Storybook and Claude Code skill (#5867)

* feat(ui): make @decocms/ui a publishable open-source package

- Rename @deco/ui -> @decocms/ui (npm scope owned by decocms)
- Move Studio-domain code out of the design system: github url helpers
  and the sound engine now live in apps/web; delete dead
  llm-model-selector and models-binding-provider (no consumers)
- Rewrite internal self-package imports to relative paths
- Publishing metadata: MIT license, repository, files, publishConfig,
  sideEffects; react/react-dom/react-hook-form/sonner become
  peerDependencies; drop unused date-fns
- Add tsc dist build (ESM + d.ts). Dual exports: extension-suffixed
  subpaths resolve to TS source (monorepo DX), extensionless subpaths
  resolve to compiled dist (external consumers)
- components.json: rsc false (SPA library)

* feat(ui): add Storybook 10 with stories for every component

- Storybook 10 (react-vite) in packages/ui: docs, a11y, and theme addons;
  light/dark toggle via the design system's .dark class; Tailwind v4
  through @tailwindcss/vite
- Stories for all 67 components, co-located as src/components/*.stories.tsx
  (excluded from the npm tarball and the dist build)
- Design System foundation pages: Welcome (install + principles), Colors
  (semantic token reference), Typography (families, weights, scale)
- bun run --cwd=packages/ui storybook to develop, build-storybook for the
  static site

* feat(ui): npm publish workflow, Storybook Pages deploy, and Claude Code skill

- publish-ui-npm.yaml: auto-publish @decocms/ui on version change
  (mirrors the bindings publish flow, OIDC provenance)
- deploy-storybook.yml: build and deploy the Storybook to GitHub Pages
  on pushes to main touching packages/ui
- Claude Code plugin marketplace at the repo root with a decocms-ui
  plugin; its skill teaches agents to install and use the design system
  (tokens, imports, component inventory, conventions)

* fix(ui): deploy Storybook to Cloudflare Pages instead of GitHub Pages

decocms-ui.pages.dev reads as the design system's own home; the GitHub
Pages URL would be pinned under the studio repo path. Reuses the CF
credentials already used by deploy-docs.

* feat(ui): attach designsystem.decocms.com to the Storybook Pages project

Adds an idempotent workflow step that attaches the custom domain via the
Cloudflare API (wrangler has no pages-domain command) and makes it the
canonical docs URL in the skill, plugin metadata, and release notes.

* refactor(ui): deploy Storybook as Cloudflare Worker static assets

Replaces the Pages project + curl domain step with a declarative
wrangler.jsonc: assets-only Worker with designsystem.decocms.com as a
custom_domain route. Validated with wrangler deploy --dry-run.

* fix(ui): delete dead code surfaced by knip after the sound/github move

Inside packages/ui these files had no knip entry config, so their
reachability was never analyzed; moving them into apps/web exposed them.
Removes the three unreferenced sound assets and the uncalled
fetchGitHubReadme, and narrows sound-engine helpers to module-private.

Author: viktormarinho

.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "decocms",
+  "owner": {
+    "name": "decocms",
+    "url": "https://github.com/decocms"
+  },
+  "plugins": [
+    {
+      "name": "decocms-ui",
+      "source": "./packages/ui",
+      "description": "Build UI with the decocms product design system (@decocms/ui): install, tokens, components, and conventions.",
+      "author": { "name": "decocms" },
+      "homepage": "https://designsystem.decocms.com/"
+    }
+  ]
+}

.github/workflows/deploy-storybook.yml

@@ -0,0 +1,29 @@
+name: Deploy Storybook
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "packages/ui/**"
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun and install dependencies
+        uses: ./.github/actions/setup-bun
+
+      - name: Build Storybook
+        run: bun run build-storybook
+        working-directory: packages/ui
+
+      - name: Deploy to Cloudflare Workers (static assets)
+        run: bunx wrangler deploy
+        working-directory: packages/ui
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

.github/workflows/publish-ui-npm.yaml

@@ -0,0 +1,82 @@
+name: Publish @decocms/ui
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "packages/ui/**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js for npm registry
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Setup Bun and install dependencies
+        uses: ./.github/actions/setup-bun
+
+      - name: Check if version changed
+        id: version-check
+        run: |
+          # Get the current version from package.json
+          CURRENT_VERSION=$(bun -e "console.log(require('./package.json').version)")
+
+          # Check if this specific version already exists in npm
+          # This works for both stable and prerelease versions (unlike checking 'latest' tag)
+          if npm view @decocms/ui@$CURRENT_VERSION version >/dev/null 2>&1; then
+            echo "version-changed=false" >> $GITHUB_OUTPUT
+            echo "⏭️ Version $CURRENT_VERSION already published, skipping publish"
+          else
+            echo "version-changed=true" >> $GITHUB_OUTPUT
+            echo "✅ Version $CURRENT_VERSION not found in npm, will publish"
+          fi
+
+          echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+          # Check if this is a prerelease version (contains a hyphen)
+          if [[ "$CURRENT_VERSION" == *-* ]]; then
+            echo "npm-tag=next" >> $GITHUB_OUTPUT
+            echo "📦 Prerelease version detected, will publish with tag 'next'"
+          else
+            echo "npm-tag=latest" >> $GITHUB_OUTPUT
+            echo "📦 Stable version detected, will publish with tag 'latest'"
+          fi
+        working-directory: packages/ui
+
+      - name: Publish to npm
+        if: steps.version-check.outputs.version-changed == 'true'
+        run: npm publish --access public --tag ${{ steps.version-check.outputs.npm-tag }} --provenance
+        working-directory: packages/ui
+
+      - name: Create Release
+        if: steps.version-check.outputs.version-changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "ui-v${{ steps.version-check.outputs.current-version }}" \
+            --title "@decocms/ui v${{ steps.version-check.outputs.current-version }}" \
+            --notes "## Changes
+
+          Automated release of the @decocms/ui design system.
+
+          ### Installation
+          \`\`\`bash
+          bun add @decocms/ui react react-dom
+          \`\`\`
+
+          ### Docs
+          https://designsystem.decocms.com/"

.gitignore

@@ -124,3 +124,6 @@ deploy/helm/sandbox-env/charts/
 # (nats, opentelemetry-collector) as .tgz under charts/. They stay tracked
 # because the chart pins specific versions and offline installs depend on
 # them being present.
+
+# Storybook static build
+storybook-static

apps/web/README.md

@@ -73,7 +73,7 @@ bun run build:studio
 providers; `src/index.web.tsx` is the browser entry that renders it (the Tauri
 desktop build has its own entry, `src/index.native.tsx`). Route components load
 lazily, TanStack Query manages remote state, and shared UI primitives come from
-`@deco/ui`.
+`@decocms/ui`.
 
 ```text
 TanStack Router
@@ -147,7 +147,7 @@ Do not change it to `bun --bun vite dev`: the proxy depends on Node's
   isomorphic contracts in explicit `@decocms/shared/*` exports.
 - Keep React hooks, contexts, and other browser runtime code in `apps/web`,
   including `src/sdk`; do not move them into the shared package.
-- Consume design-system primitives from `@deco/ui` and use design tokens rather
+- Consume design-system primitives from `@decocms/ui` and use design tokens rather
   than raw palette values.
 - Route every user-facing string through `useT()`. Add matching English and
   Brazilian Portuguese dictionary entries.

apps/web/ct/playwright/index.css

@@ -2,7 +2,7 @@
 
 /*
  * Tailwind v4 auto-scans the project root but EXCLUDES node_modules — and
- * @deco/ui (where Switch, Button, Select, etc. live) is a workspace package
+ * @decocms/ui (where Switch, Button, Select, etc. live) is a workspace package
  * resolved through node_modules. Without scanning it, sizing utilities like the
  * Switch's `h-[1.15rem] w-8` are never generated, so icon-only buttons collapse
  * to 0x0 and Playwright treats them as hidden. Point @source at the real UI

apps/web/ct/playwright/index.tsx

@@ -1,6 +1,6 @@
 import { beforeMount } from "@playwright/experimental-ct-react/hooks";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { TooltipProvider } from "@deco/ui/components/tooltip.tsx";
+import { TooltipProvider } from "@decocms/ui/components/tooltip.tsx";
 import "./index.css";
 
 // One client per page load; retries off so failed (stubbed) queries settle fast.

apps/web/index.css

@@ -1,4 +1,4 @@
-@import "@deco/ui/styles/global.css";
+@import "@decocms/ui/styles/global.css";
 @import "@daveyplate/better-auth-ui/css";
 
 @theme {

apps/web/package.json

@@ -21,7 +21,7 @@
     "@ai-sdk/react": "^3.0.210",
     "@better-auth/sso": "1.4.1",
     "@daveyplate/better-auth-ui": "^3.2.7",
-    "@deco/ui": "workspace:*",
+    "@decocms/ui": "workspace:*",
     "@decocms/bindings": "workspace:*",
     "@decocms/mcp-utils": "workspace:*",
     "@decocms/sandbox": "workspace:*",

apps/web/playwright-ct.config.ts

@@ -71,7 +71,7 @@ export default defineConfig({
           },
           // General `@/* -> src/*` alias. MUST come after the stub aliases
           // above so Vite (first-match-wins) resolves those first. Matches
-          // only `@/`-prefixed ids, so `@deco/ui`, `@tanstack/*` etc. are
+          // only `@/`-prefixed ids, so `@decocms/ui`, `@tanstack/*` etc. are
           // untouched.
           { find: "@/", replacement: `${path.join(here, "src")}/` },
         ],