Stacks

Stacks is Stack Overflow's design system, the shared foundation of components, styles, and guidelines used across Stack Overflow's products. For usage instructions, see our usage guidelines.

Table of contents

• Contributing
• Local Development
  • Stacks Docs
  • Stacks Classic
  • Stacks Svelte
• Releasing Stacks
• License

Contributing

Please read through our contribution guidelines before getting started. The guide covers:

• Before you start: where to report bugs or request features
• Pull requests: how to set up and submit your work
• Merge requirements: required approvals and deployment rules that apply to everyone
• Code guidelines: formatting and style conventions

Local Development

This repo follows a monolithic structure and contains multiple packages split into npm workspaces. These can be found under the packages/ folder.

To get any of these Stacks workspaces working locally start out by installing all required dependencies:

npm i

Below are instructions on how to build and test each individual workspace. If you run into trouble, see Before you start in our contributing guide for how to reach us.

Stacks Docs

This workspace contains the Stacks documentation project that's hosted on: https://stackoverflow.design/

To contribute to Stacks documentation you can build locally via:

npm start

This command will pull up the local dev server at http://localhost:5173/. You can also view our building guidelines.

Stacks Classic

This workspace contains the css and js sources that define and power the Stacks design system.

Formatting

Format the source code with prettier by running:

npm run format -w packages/stacks-classic

Linting

Run all lint suites by running:

npm run lint -w packages/stacks-classic

Lint the styles (stylelint) by running:

npm run lint:css -w packages/stacks-classic

Lint the typescript source code (eslint) via running:

npm run lint:ts -w packages/stacks-classic

Lint the source code format (prettier) via running:

npm run lint:format -w packages/stacks-classic

Testing

Run all test suites by running:

npm run test -w packages/stacks-classic

Unit/Component Tests

Unit/Component tests are written with DOM Testing Library. Please follow the library's principles and documentation to write tests.

Stacks uses Web Test Runner and Playwright to run tests in a real browser context.

Execute the unit/component tests suite by running:

npm run test:unit -w packages/stacks-classic

or if you prefer watch mode run:

npm run test:unit:watch -w packages/stacks-classic

Visual Regression Tests

Prerequisites:

• git lfs (installation docs)
• docker (installation docs)
• pwsh (Installation docs)
• Run git config diff.lfs.textconv cat to make sure image diff works as expected (More info)

This Web Test Runner plugin is used to run visual regression tests. Visual regression tests end with this suffix *.visual.test.ts.

In CI, the visual regression suite runs only when a pull request or commit changes Stacks Classic styles, runtime code, visual tests or fixtures, baselines, direct dependency manifests, or visual test infrastructure. The required check still completes successfully without executing the suite for unrelated changes.

Execute the visual regression tests suite by running:

npm run test:visual -w packages/stacks-classic

After the first run, if there are failing snapshots, they end up overriding the baseline ones in the filesystem (e.g. /screenshots/<browser>/baseline/<name>.png). We do this for easier comparison of the diff directly in vscode and to make sure only the failing snapshots get regenerated (see this GH discussion that inspired the approach).

We also recommend to install this vscode extension for getting better diffs.

Less Tests

This is an experimental suite to test the generation of CSS from Less files. Less tests end with this suffix *.less.test.ts.

Execute the less tests suite by running:

npm run test:less -w packages/stacks-classic

Update the css snapshots via:

npm run test:less:update -w packages/stacks-classic

Stacks Svelte

This workspace contains a Svelte implementation of the Stacks Classic design system. Unlike the Stacks-Classic workspace which has its documentation defined in the separate Stacks-Docs workspace, this one defines its documentation site directly within its own workspace which can be reached via https://svelte.stackoverflow.design

We use storybook for local development. To start the storybook server run:

npm run storybook -w packages/stacks-svelte

The storybook server will reflect the changes you make to the components stories in real time. We use this addon to write stories directly in Svelte syntax. Stories need to have the *.stories.svelte extension to be picked up.

Formatting

npm run format -w packages/stacks-svelte

Linting

npm run lint -w packages/stacks-svelte

Testing

Stacks Svelte uses Web Test Runner and Playwright to run tests in a real browser context.

npm run test -w packages/stacks-svelte

or to run the tests in watch mode:

npm run test:watch -w packages/stacks-svelte

Releasing Stacks

This repo uses Semantic Versioning to distribute Stacks Classic and Stacks Docs via npm, and publishes release notes on Github.

We use changesets to automatize the steps necessary to publish to NPM, create GH releases and a changelog.

• Every time you do work that requires a new release to be published, add a changesets entry by running npx changeset and follow the instructions on screen. (changes that do not require a new release - e.g. changing a test file - don't need a changeset).
  • When opening a PR without a corresponding changeset the changesets-bot will remind you to do so. It generally makes sense to have one changeset for PR (if the PR changes do not require a new release to be published the bot message can be safely ignored)
• After CI succeeds on main, the release GitHub workflow creates or updates the chore(new-release) PR as pending changesets are merged.
• Prerelease mode and its npm tag are controlled by .changeset/pre.json, not by a separate release branch.
• When the chore(new-release) PR is merged, the workflow publishes the prepared package versions to npm and creates GitHub releases. Review the generated versions and changelogs before merging it.
• A changeset for a package listed in Changesets' ignore configuration remains tracked until that package is ready. When every pending changeset targets an ignored package, the release workflow temporarily excludes those files in its runner so changesets/action can publish any already-prepared package versions. If any actionable changeset exists, all files remain in place for normal release-PR generation.

The release github workflow only run if the CI workflow (running linter, formatter and tests) is successful: CI is blocking accidental releases.

Despite using changesets to communicate the intent of creating releases in a more explicit way, we still follow conventional commits standards for keeping our git history easily parseable by the human eye.

Docs are deployed directly from the current release flow; we no longer merge into a production branch to publish stackoverflow.design. Normal contribution PRs target main.

When changesets/action publishes a new version from main, the release workflow triggers the Netlify build hook stored in NETLIFY_DOCS_BUILD_HOOK_URL. The docs site's Netlify ignore rule skips automatic production builds from ordinary main commits while preserving deploy previews and branch deploys. To deploy the latest main docs without publishing packages, manually run the Deploy docs workflow from the main branch.

License

Code and documentation copyright 2017-2026 Stack Exchange, Inc and released under the MIT License.