From 62c55defb1cf9d26d2b34ed1b6875eaf66b72bbd Mon Sep 17 00:00:00 2001 From: Sal Date: Fri, 12 Sep 2025 08:54:09 -0400 Subject: [PATCH 1/3] add readme's for each package --- packages/stacks-classic/README.md | 91 +++++++++++++++++++++++++++++++ packages/stacks-docs/README.md | 15 +++++ 2 files changed, 106 insertions(+) create mode 100644 packages/stacks-classic/README.md create mode 100644 packages/stacks-docs/README.md diff --git a/packages/stacks-classic/README.md b/packages/stacks-classic/README.md new file mode 100644 index 0000000000..eb62361f47 --- /dev/null +++ b/packages/stacks-classic/README.md @@ -0,0 +1,91 @@ +# Stacks Classic + +This workspace contains the css and js sources that define and power the Stacks design system. + +Format the source code with prettier by running: +```sh +npm run format -w packages/stacks-classic +``` + +## Linting + +Run all lint suites by running: +```sh +npm run lint -w packages/stacks-classic +``` +Lint the styles (stylelint) by running: +```sh +npm run lint:css -w packages/stacks-classic +``` +Lint the typescript source code (eslint) via running: +```sh +npm run lint:ts -w packages/stacks-classic +``` +Lint the source code format (prettier) via running: +```sh +npm run lint:format -w packages/stacks-classic +``` + +## Testing + +Run all test suites by running: +```sh +npm run test -w packages/stacks-classic +``` + +### Unit/Component Tests + +Unit/Component tests are written with [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro). +Please follow the library’s principles and documentation to write tests. + +Stacks uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context. + +Execute the unit/component tests suite by running: +```sh +npm run test:unit -w packages/stacks-classic +``` +or if you prefer watch mode run: +```sh +npm run test:unit:watch -w packages/stacks-classic +``` + +### Visual Regression Tests + +**Prerequisites:** +- `git lfs` ([installation docs](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) +- `docker` ([installation docs](https://docs.docker.com/engine/install/)) +- `pwsh` ([Installation docs](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)) +- Run `git config diff.lfs.textconv cat` to make sure image diff works as expected ([More info](https://github.com/microsoft/vscode/issues/86611#issuecomment-875894108)) + +This [Web Test Runner plugin](https://www.npmjs.com/package/@web/test-runner-visual-regression) is used to run visual regression tests. +Visual regression tests end with this suffix `*.visual.test.ts`. + +Execute the visual regression tests suite by running: +```sh +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//baseline/.png`). +We do this for easier comparison of the dif directly in vscode and to make sure only the failing snapshots get regenerated (see [this GH discussion](https://github.com/modernweb-dev/web/discussions/427#discussioncomment-3543771) that inspired the approach). + +We also recommend to install [this vscode extension](https://marketplace.visualstudio.com/items?itemName=RayWiis.png-image-diff) 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: +```sh +npm run test:less -w packages/stacks-classic +``` + +Update the css snapshots via: +```sh +npm run test:less:update -w packages/stacks-classic +``` + +# Release management +Refer to the main [README.md](../../README.md) for details on how releases are currently managed. + +# Bugs and feature requests +Have a bug or feature request? First search existing or closed issues to make sure the issue hasn’t been noted yet. If not, review our [issue guidelines](../../CONTRIBUTING.md#open-an-issue) for submitting [a bug report](../../CONTRIBUTING.md#reporting-bugs) or [feature request](../../CONTRIBUTING.md#feature-requests). \ No newline at end of file diff --git a/packages/stacks-docs/README.md b/packages/stacks-docs/README.md new file mode 100644 index 0000000000..ebdc8addd8 --- /dev/null +++ b/packages/stacks-docs/README.md @@ -0,0 +1,15 @@ +# 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: +```sh +npm start +``` +This command will pull up the local dev server at http://localhost:8080. You can also view our [building guidelines](https://stackoverflow.design/product/develop/building). + +# Release management +Refer to the main [README.md](../../README.md) for details on how releases are currently managed. + +# Bugs and feature requests +Have a bug or feature request? First search existing or closed issues to make sure the issue hasn’t been noted yet. If not, review our [issue guidelines](../../CONTRIBUTING.md#open-an-issue) for submitting [a bug report](../../CONTRIBUTING.md#reporting-bugs) or [feature request](../../CONTRIBUTING.md#feature-requests). \ No newline at end of file From 3e89037dca3002b6d055eb09488bfc18d6ac962b Mon Sep 17 00:00:00 2001 From: Sal Date: Fri, 12 Sep 2025 08:57:38 -0400 Subject: [PATCH 2/3] Create six-buckets-grab.md --- .changeset/six-buckets-grab.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/six-buckets-grab.md diff --git a/.changeset/six-buckets-grab.md b/.changeset/six-buckets-grab.md new file mode 100644 index 0000000000..e355e59da3 --- /dev/null +++ b/.changeset/six-buckets-grab.md @@ -0,0 +1,6 @@ +--- +"@stackoverflow/stacks": patch +"@stackoverflow/stacks-docs": patch +--- + +chore(docs): add readme for each workspace From 18724f823e62241ddfa724f1aa0fdcc8ace8159b Mon Sep 17 00:00:00 2001 From: Sal Date: Fri, 12 Sep 2025 09:39:20 -0400 Subject: [PATCH 3/3] adjust stacks classic readme a bit --- packages/stacks-classic/README.md | 97 +++++-------------------------- 1 file changed, 15 insertions(+), 82 deletions(-) diff --git a/packages/stacks-classic/README.md b/packages/stacks-classic/README.md index eb62361f47..2a394db5ae 100644 --- a/packages/stacks-classic/README.md +++ b/packages/stacks-classic/README.md @@ -1,91 +1,24 @@ -# Stacks Classic +# Stacks -This workspace contains the css and js sources that define and power the Stacks design system. +[![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url] -Format the source code with prettier by running: -```sh -npm run format -w packages/stacks-classic -``` +Stacks is Stack Overflow’s design system. It includes the resources needed to create consistent, predictable interfaces and workflows that conform to Stack Overflow’s principles, design language, and best practices. -## Linting +Our documentation is built with Stacks itself, using its [immutable, atomic classes](http://johnpolacek.com/rethinking/) and components. -Run all lint suites by running: -```sh -npm run lint -w packages/stacks-classic -``` -Lint the styles (stylelint) by running: -```sh -npm run lint:css -w packages/stacks-classic -``` -Lint the typescript source code (eslint) via running: -```sh -npm run lint:ts -w packages/stacks-classic -``` -Lint the source code format (prettier) via running: -```sh -npm run lint:format -w packages/stacks-classic -``` +The [Stacks website](https://stackoverflow.design/) documents: -## Testing +## Product +- Semantic and accessible component markup +- Cross-browser compatible Less / CSS +- An [icon library](https://github.com/StackExchange/Stacks-Icons) -Run all test suites by running: -```sh -npm run test -w packages/stacks-classic -``` +## Email +- Email templates & components -### Unit/Component Tests +# Using Stacks +Using Stacks is outlined in our [usage guidelines](https://stackoverflow.design/product/develop/using-stacks). -Unit/Component tests are written with [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro). -Please follow the library’s principles and documentation to write tests. +## Migrating from v1 to v2 -Stacks uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context. - -Execute the unit/component tests suite by running: -```sh -npm run test:unit -w packages/stacks-classic -``` -or if you prefer watch mode run: -```sh -npm run test:unit:watch -w packages/stacks-classic -``` - -### Visual Regression Tests - -**Prerequisites:** -- `git lfs` ([installation docs](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) -- `docker` ([installation docs](https://docs.docker.com/engine/install/)) -- `pwsh` ([Installation docs](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.3)) -- Run `git config diff.lfs.textconv cat` to make sure image diff works as expected ([More info](https://github.com/microsoft/vscode/issues/86611#issuecomment-875894108)) - -This [Web Test Runner plugin](https://www.npmjs.com/package/@web/test-runner-visual-regression) is used to run visual regression tests. -Visual regression tests end with this suffix `*.visual.test.ts`. - -Execute the visual regression tests suite by running: -```sh -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//baseline/.png`). -We do this for easier comparison of the dif directly in vscode and to make sure only the failing snapshots get regenerated (see [this GH discussion](https://github.com/modernweb-dev/web/discussions/427#discussioncomment-3543771) that inspired the approach). - -We also recommend to install [this vscode extension](https://marketplace.visualstudio.com/items?itemName=RayWiis.png-image-diff) 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: -```sh -npm run test:less -w packages/stacks-classic -``` - -Update the css snapshots via: -```sh -npm run test:less:update -w packages/stacks-classic -``` - -# Release management -Refer to the main [README.md](../../README.md) for details on how releases are currently managed. - -# Bugs and feature requests -Have a bug or feature request? First search existing or closed issues to make sure the issue hasn’t been noted yet. If not, review our [issue guidelines](../../CONTRIBUTING.md#open-an-issue) for submitting [a bug report](../../CONTRIBUTING.md#reporting-bugs) or [feature request](../../CONTRIBUTING.md#feature-requests). \ No newline at end of file +To migrate from Stacks v1 to v2, see our [migration guide](/MIGRATION_GUIDE.md). \ No newline at end of file