build: restructure repo as pnpm workspace monorepo (#262)

Author: nathanyoung

.github/workflows/chromatic.yml

@@ -19,12 +19,15 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Build design tokens
+        run: pnpm build-tokens
       - name: Run Chromatic
         uses: chromaui/action@latest
         with:
           projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
           onlyChanged: true # Required option to enable TurboSnap
+          workingDir: packages/components

.github/workflows/pull-request.yml

@@ -17,9 +17,6 @@ permissions:
   contents: 'read'
   packages: 'read'
   repository-projects: 'read'
-env:
-  GH_PACKAGES_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
 jobs:
   lint-js:
@@ -32,10 +29,8 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
-      - name: Set up .npmrc
-        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Lint
@@ -50,10 +45,8 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
-      - name: Set up .npmrc
-        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Build
@@ -68,7 +61,7 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -84,7 +77,7 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -103,12 +96,15 @@ jobs:
           version: 10.20.0
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.19'
+          node-version: '22'
           cache: pnpm
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Build design tokens
+        run: pnpm build-tokens
       - name: Run Chromatic
         uses: chromaui/action@latest
         with:
           projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
           onlyChanged: true # Required option to enable TurboSnap
+          workingDir: packages/components

.github/workflows/semantic-release.yml

@@ -2,6 +2,11 @@ name: Release
 
 on:
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to publish (e.g. v7.8.0). Defaults to the committed package versions.'
+        required: false
+        type: string
   release:
     types: [published]
 
@@ -11,7 +16,7 @@ permissions:
 
 jobs:
   release:
-    name: Release Package
+    name: Release Packages
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -29,16 +34,35 @@ jobs:
       - name: install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Both packages release in lockstep: the git tag is the single source
+      # of truth for the version. Setting versions before publish also makes
+      # pnpm rewrite the workspace:^ dependency to ^<version>.
+      - name: set package versions from release tag
+        run: |
+          TAG="${{ github.event.release.tag_name || inputs.tag }}"
+          if [[ -n "$TAG" ]]; then
+            VERSION="${TAG#v}"
+            echo "Setting all package versions to $VERSION"
+            pnpm -r exec npm pkg set version="$VERSION"
+          else
+            echo "No tag available; publishing with committed package versions"
+          fi
+
       - name: test
         run: pnpm test
 
       - name: build
         run: pnpm build
 
+      # pnpm (not npm) must do the publishing: only pnpm rewrites the
+      # workspace:^ protocol to a real semver range in the published
+      # manifests. -r publishes in dependency order (design-tokens first)
+      # and skips the private workspace root. --no-git-checks is required
+      # because release events check out a detached tag.
       - name: Publish
         run: |
           if [[ "${{ github.event.release.prerelease }}" == "true" ]]; then
-            npm publish --ignore-scripts --tag beta --access public
+            pnpm publish -r --access public --tag beta --no-git-checks --ignore-scripts
           else
-            npm publish --ignore-scripts --access public
+            pnpm publish -r --access public --no-git-checks --ignore-scripts
           fi

.gitignore

@@ -5,13 +5,11 @@ node_modules
 dist
 
 # testing
-/coverage
+coverage
 
 # production
-/coverage
-/dist
-/build
-/storybook-static
+build
+storybook-static
 
 # IDEs
 .vscode

.releaserc

@@ -1,9 +1,6 @@
 {
   "branches": ["main", { "name": "beta", "prerelease": true }],
   "plugins": [
-    "@semantic-release/npm",
-    "@semantic-release/github",
-    "@semantic-release/release-notes-generator",
     ["@semantic-release/commit-analyzer", {
       "preset": "angular",
       "releaseRules": [
@@ -17,6 +14,15 @@
         { "type": "feat", "release": "minor" },
         { "type": "fix", "release": "patch" }
       ]
-    }]
+    }],
+    "@semantic-release/release-notes-generator",
+    ["@semantic-release/exec", {
+      "prepareCmd": "pnpm -r exec npm pkg set version=${nextRelease.version}"
+    }],
+    ["@semantic-release/git", {
+      "assets": ["packages/components/package.json", "packages/design-tokens/package.json"],
+      "message": "chore(release): ${nextRelease.version} [skip ci]"
+    }],
+    "@semantic-release/github"
   ]
 }

.storybook/main.ts

@@ -1,15 +1,23 @@
 # AGENTS.md
 
+## Repository layout
+
+- This is a pnpm workspace monorepo with two published packages:
+  - `packages/components` — `@hyphen/hyphen-components`, the React component library.
+  - `packages/design-tokens` — `@hyphen/hyphen-design-tokens`, the design token source (token JSON in `tokens/`, icon/logo SVGs in `assets/`) and its Style Dictionary build.
+- Components consume the tokens package via a `workspace:^` dependency; the tokens `build/` output must exist before component tests or Storybook run. The root scripts handle this ordering — prefer them over per-package scripts.
+- Both packages share one version and are published together by the Release workflow (version comes from the GitHub release tag).
+
 ## Testing instructions
 
 - Find the CI plan in the .github/workflows folder.
-- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
+- From the repo root you can just call `pnpm test` (it builds the design tokens first, then runs every package's tests). The commit should pass all tests before you merge.
 - Fix any test or type errors until the whole suite is green.
 - Add or update tests for the code you change, even if nobody asked.
 
 ## PR instructions
 
-- Always run `pnpm lint` and `pnpm test` before committing.
+- Always run `pnpm lint` and `pnpm test` from the repo root before committing.
 
 ## Code Review Checklist
 

AGENTS.md

@@ -1,70 +1,56 @@
 <p align="center">
-  <a href="https://hyphen.ai" rel="noopener" target="_blank"><img width="150" src="public/images/logo.png" alt="Hyphen logo"></a></p>
+  <a href="https://hyphen.ai" rel="noopener" target="_blank"><img width="150" src="packages/components/public/images/logo.png" alt="Hyphen logo"></a></p>
 </p>
 
-<h1 align="center" style="border-bottom: none;">Hyphen Component Library</h1>
+<h1 align="center" style="border-bottom: none;">Hyphen Design System</h1>
 <h3 align="center">
 
-  A [React](https://reactjs.org/) component library to power all Hyphen UI
+  The monorepo for Hyphen's design system packages
 
 </h3>
 
-## Quick Start
+## Packages
 
-### 1. Install
+| Package | Description |
+| --- | --- |
+| [`@hyphen/hyphen-components`](packages/components) | A [React](https://reactjs.org/) component library to power all Hyphen UI |
+| [`@hyphen/hyphen-design-tokens`](packages/design-tokens) | Design tokens (color, spacing, typography, icons, logos) that power all Hyphen UIs |
 
-`pnpm add @hyphen/hyphen-components`
-
-### 2. Import Global CSS
+Both packages are versioned and released together: one GitHub release
+publishes both to npm with the same version.
 
-```jsx
-import '@hyphen/hyphen-components/dist/css/utilities.css'; // Utility classes -- REQUIRED
-import '@hyphen/hyphen-components/dist/css/variables.css'; // CSS Variables -- REQUIRED
-import '@hyphen/hyphen-components/dist/css/index.css'; // Component CSS -- REQUIRED
-import '@hyphen/hyphen-components/dist/css/fonts.css'; // Included Font files -- OPTIONAL BUT ENCOURAGED
-```
+## Quick Start (consumers)
 
-We recommend importing our global reset in order to maintain a consistent
-look of all components across applications.
+`pnpm add @hyphen/hyphen-components`
 
-```jsx
-import '@hyphen/hyphen-components/dist/css/reset.css' // A Basic CSS Reset -- OPTIONAL BUT ENCOURAGED.
-```
+See the [components README](packages/components/README.md) for usage,
+global CSS imports, and documentation links.
 
-### 3. Usage
+Design tokens can also be consumed directly on other platforms:
+`pnpm add @hyphen/hyphen-design-tokens` — see the
+[design tokens README](packages/design-tokens/README.md).
 
-```jsx
-import React from 'react';
-import ReactDOM from 'react-dom';
-import { Box } from '@hyphen/hyphen-components';
+## Development
 
-function App() {
-  return <Box>Hello World</Box>;
-}
+This is a [pnpm workspace](https://pnpm.io/workspaces). All commands run
+from the repo root:
 
-ReactDOM.render(<App />, document.querySelector('#app'));
+```sh
+pnpm install          # install all workspace dependencies
+pnpm build            # build design tokens, then components
+pnpm test             # build tokens, then run all test suites
+pnpm lint             # lint all packages
+pnpm storybook        # run the component Storybook locally
 ```
 
-## Documentation
-
-[SEE FULL DOCS HERE](https://ux.hyphen.ai)
-
-## Contributing
-
-Issues and PRs welcome! See [HERE](./CONTRIBUTING.md) for our Contribution Guide.
-
-## Raising an Issue
-
-When raising an issue:
-
-* Make sure the issue hasn't been raised yet.
-* Tag issue accordingly using your best judgement. Do NOT create new tags. If you feel a new one is needed, raise it in your issue.
-* If your issue is a bug, include **screenshots** or animated GIFs in your issue whenever needed (if issue is visual in nature).
-* If your issue is a bug, include steps to reproduce, or link to reproducible issue, e.g.: Code Sandbox or similar. Please also provide any additional details including device, OS, browser, browser version etc.
-
-[Issues can be raised here](https://github.com/hyphen/hyphen-components/issues).
+Changing a color, icon, or any other token is now a normal PR to this
+repo: edit the sources in `packages/design-tokens` (token JSON in
+`tokens/`, icon SVGs in `assets/icons`) and the same PR can update the
+components that use them.
 
-## License
+## Releasing
 
-This project is licensed under the terms of the
-[MIT license](./LICENSE).
+Releases are automated with [semantic-release](https://github.com/semantic-release/semantic-release)
+from conventional commit messages. When a GitHub release is published,
+the Release workflow stamps the tag's version into both packages and
+publishes them to npm in dependency order.