webship-js 2.0.2 → 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +109 -0
  9. package/CLAUDE.md +317 -0
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/generate-reports.js +181 -9
  14. package/buildspec.yml +56 -0
  15. package/cloudbuild.yaml +49 -0
  16. package/codefresh.yml +77 -0
  17. package/cucumber.js +48 -5
  18. package/docs/00-quick-start.md +102 -0
  19. package/docs/01-getting-started.md +102 -0
  20. package/docs/02-bbr-smart-waits.md +77 -0
  21. package/docs/03-selector-registry.md +95 -0
  22. package/docs/04-step-reference.md +799 -0
  23. package/docs/05-web-first-assertions.md +91 -0
  24. package/docs/06-network-and-dialogs.md +83 -0
  25. package/docs/07-auth-state.md +75 -0
  26. package/docs/08-clock-mocking.md +59 -0
  27. package/docs/09-api-testing.md +114 -0
  28. package/docs/10-accessibility.md +167 -0
  29. package/docs/11-debugging.md +129 -0
  30. package/docs/12-ai-agent-guide.md +338 -0
  31. package/docs/13-faq.md +236 -0
  32. package/docs/14-recipes-cookbook.md +255 -0
  33. package/docs/15-tag-conventions.md +76 -0
  34. package/docs/16-ci-cd.md +879 -0
  35. package/docs/README.md +113 -0
  36. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  37. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  38. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  39. package/docs/advanced-screenshots.md +52 -0
  40. package/docs/advanced-selectors.md +18 -0
  41. package/docs/api-step-definitions.md +45 -0
  42. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  43. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  44. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  45. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  46. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  47. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  48. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  49. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  50. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  51. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  52. package/docs/diffy-step-definitions.md +21 -0
  53. package/docs/global-settings.md +295 -0
  54. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  55. package/docs/install-webship-js.md +35 -0
  56. package/docs/overview.md +41 -0
  57. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  58. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  59. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  60. package/docs/step-definitions/then-i-should-be.md +56 -0
  61. package/docs/step-definitions/then-i-should-see.md +62 -0
  62. package/docs/step-definitions/then-item-checkbox.md +54 -0
  63. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  64. package/docs/step-definitions/then-item-should-contain.md +67 -0
  65. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  66. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  67. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  68. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  69. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  70. package/docs/step-definitions/when-i-click-link.md +51 -0
  71. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  72. package/docs/step-definitions/when-i-fill.md +59 -0
  73. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  74. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  75. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  76. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  77. package/docs/step-definitions/when-i-press-button.md +58 -0
  78. package/docs/step-definitions/when-i-reload-page.md +51 -0
  79. package/docs/step-definitions/when-i-scroll.md +73 -0
  80. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  81. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  82. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  83. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  84. package/docs/step-definitions/when-i-wait.md +62 -0
  85. package/docs/step-definitions.md +50 -0
  86. package/examples/a11y.html +31 -0
  87. package/examples/cookies.html +10 -0
  88. package/examples/date.html +12 -0
  89. package/examples/element.html +11 -0
  90. package/examples/field.html +24 -0
  91. package/examples/keyboard.html +11 -0
  92. package/examples/links.html +9 -0
  93. package/examples/modal.html +14 -0
  94. package/examples/path.html +3 -0
  95. package/examples/table.html +13 -0
  96. package/examples/video-demo.html +43 -0
  97. package/package.json +10 -3
  98. package/playwright.config.ts +3 -2
  99. package/tests/features/a11y.feature +39 -0
  100. package/tests/features/cookie.feature +13 -0
  101. package/tests/features/date.feature +11 -0
  102. package/tests/features/element.feature +16 -0
  103. package/tests/features/field.feature +25 -0
  104. package/tests/features/keyboard.feature +10 -0
  105. package/tests/features/link.feature +11 -0
  106. package/tests/features/modal-advanced-example.feature +1 -1
  107. package/tests/features/modal.feature +11 -0
  108. package/tests/features/path.feature +16 -0
  109. package/tests/features/response.feature +8 -0
  110. package/tests/features/responsive.feature +10 -0
  111. package/tests/features/table.feature +18 -0
  112. package/tests/features/video.feature +18 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +7 -1
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/step-definitions/a11y.steps.js +800 -0
  142. package/tests/step-definitions/action.steps.js +167 -0
  143. package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
  144. package/tests/step-definitions/assertion.steps.js +352 -0
  145. package/tests/step-definitions/auth.steps.js +126 -0
  146. package/tests/step-definitions/clock.steps.js +128 -0
  147. package/tests/step-definitions/cookie.steps.js +216 -0
  148. package/tests/step-definitions/debug.steps.js +39 -0
  149. package/tests/step-definitions/dialog.steps.js +193 -0
  150. package/tests/step-definitions/element.steps.js +356 -0
  151. package/tests/step-definitions/field.steps.js +653 -0
  152. package/tests/step-definitions/file-download.steps.js +211 -0
  153. package/tests/step-definitions/form.steps.js +333 -0
  154. package/tests/step-definitions/iframe.steps.js +228 -0
  155. package/tests/step-definitions/input.steps.js +202 -0
  156. package/tests/step-definitions/javascript.steps.js +232 -0
  157. package/tests/step-definitions/keyboard.steps.js +112 -0
  158. package/tests/step-definitions/link.steps.js +142 -0
  159. package/tests/step-definitions/metatag.steps.js +91 -0
  160. package/tests/step-definitions/modal.steps.js +244 -0
  161. package/tests/step-definitions/navigation.steps.js +218 -0
  162. package/tests/step-definitions/network.steps.js +280 -0
  163. package/tests/step-definitions/path.steps.js +141 -0
  164. package/tests/step-definitions/response.steps.js +98 -0
  165. package/tests/step-definitions/responsive.steps.js +125 -0
  166. package/tests/step-definitions/rest.steps.js +111 -0
  167. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  168. package/tests/step-definitions/scroll.steps.js +189 -0
  169. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
  170. package/tests/step-definitions/storage.steps.js +194 -0
  171. package/tests/step-definitions/table.steps.js +181 -0
  172. package/tests/step-definitions/video.steps.js +178 -0
  173. package/tests/step-definitions/wait.steps.js +400 -0
  174. package/tests/step-definitions/web-first.steps.js +298 -0
  175. package/tests/step-definitions/webship.js +741 -1477
  176. package/tests/step-definitions/xml.steps.js +411 -0
  177. package/tests/step-definitions/yaml.steps.js +913 -0
  178. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  179. package/tsconfig.json +19 -3
  180. package/videos/README.md +32 -0
  181. package/.travis-ci.yml +0 -16
@@ -0,0 +1,102 @@
1
+ # Getting Started
2
+
3
+ Webship-js is an automated functional testing harness built on Playwright + Cucumber-js. You write feature files in plain Gherkin; webship-js handles the browser, smart waits, screenshots, reports, and CMS-aware selectors out of the box.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install webship-js --save-dev
9
+ ```
10
+
11
+ The post-install script copies a starter `cucumber.js`, `playwright.config.ts`, and `tests/` skeleton into your project on first install.
12
+
13
+ ## Project layout
14
+
15
+ ```
16
+ your-project/
17
+ ├── cucumber.js # Profiles + worldParameters
18
+ ├── playwright.config.ts # Browser launch + context options
19
+ └── tests/
20
+ ├── features/ # *.feature files (Gherkin)
21
+ ├── selectors/ # CMS / framework selector JSON
22
+ └── step-definitions/ # *.js or *.ts (loaded automatically)
23
+ ```
24
+
25
+ ## TypeScript and JavaScript together
26
+
27
+ Step definitions can be plain JavaScript (`.js`) or TypeScript (`.ts`) — mix freely in the same project. The default `cucumber.js` registers the [`tsx`](https://tsx.is) require hook, so `.ts` files run with zero build step:
28
+
29
+ ```js
30
+ // cucumber.js (default)
31
+ requireModule: ['tsx/cjs'],
32
+ require: ['tests/step-definitions/**/*.{js,ts}'],
33
+ ```
34
+
35
+ Add a TypeScript step alongside JS ones:
36
+
37
+ ```ts
38
+ // tests/step-definitions/custom.steps.ts
39
+ import { Then } from '@cucumber/cucumber';
40
+ import assert from 'node:assert';
41
+
42
+ Then(/^(I |we )*see a TypeScript step$/, async function (this: { page: import('playwright').Page }) {
43
+ assert.ok(this.page);
44
+ });
45
+ ```
46
+
47
+ Pure-JS shops can drop both `requireModule` and the `.ts` half of the glob.
48
+
49
+ ## Run the suite
50
+
51
+ ```bash
52
+ # Default — full pretty output, optional auto-screenshots on failure.
53
+ npm test
54
+
55
+ # Fast run — no slow-mo.
56
+ npm run test:fast
57
+
58
+ # Watch the browser interactively.
59
+ npm run test:headed
60
+
61
+ # Pick a single browser.
62
+ BROWSER=firefox npm test
63
+ BROWSER=webkit npm test
64
+
65
+ # Parallel + retry (CLI flags — no separate profile needed).
66
+ npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky
67
+ ```
68
+
69
+ ## Environment variables
70
+
71
+ | Variable | Default | Effect |
72
+ | --- | --- | --- |
73
+ | `LAUNCH_URL` | `http://localhost:8080` | Base URL for `Given I am on "/path"` |
74
+ | `BROWSER` | `chromium` | `chromium` / `firefox` / `webkit` |
75
+ | `HEADLESS` | `true` | Set to `false` for headed mode |
76
+ | `SLOW_MO` | `300` headed: `800` | Per-action delay (ms); set `0` for fast runs |
77
+ | `WEBSHIP_AUTO_SETTLE` | on | Set to `off` to disable auto edge-wait after actions |
78
+
79
+ ## First feature file
80
+
81
+ ```gherkin
82
+ Feature: Smoke
83
+
84
+ Scenario: Homepage loads
85
+ Given I am on the homepage
86
+ Then the page should declare a language
87
+ And the page should have exactly one h1
88
+ And there should be no JavaScript errors
89
+ ```
90
+
91
+ ## Next reading
92
+
93
+ - [BBR smart waits](02-bbr-smart-waits.md) — why we never `sleep N seconds`.
94
+ - [Selector registry](03-selector-registry.md) — named selectors + CMS presets.
95
+ - [Step reference](04-step-reference.md) — every built-in step, by topic.
96
+ - [Web-first assertions](05-web-first-assertions.md) — auto-retrying matchers.
97
+ - [Networking & dialogs](06-network-and-dialogs.md) — mocks, routes, alerts.
98
+ - [Auth state](07-auth-state.md) — save / restore login.
99
+ - [Clock mocking](08-clock-mocking.md) — control time.
100
+ - [API testing](09-api-testing.md) — direct HTTP from BDD.
101
+ - [Accessibility](10-accessibility.md) — POUR smoke checks.
102
+ - [Debugging](11-debugging.md) — screenshots, headed mode, traces.
@@ -0,0 +1,77 @@
1
+ # BBR Smart Waits
2
+
3
+ Webship-js follows a **Behavior-Based Robotics** philosophy: **react to the environment, not the clock.** A test never sleeps for a fixed N seconds. Instead, every wait step returns as soon as the page is at the **edge** of activity — DOM ready, no in-flight network, no pending timers, no live mutations.
4
+
5
+ ## What gets tracked
6
+
7
+ Webship-js installs a small init script in every browser context. It exposes four signals:
8
+
9
+ | Signal | Counter / time | Source |
10
+ | --- | --- | --- |
11
+ | Fetch / XHR in flight | `window.__webshipAjaxCount` | wraps `window.fetch` and `XMLHttpRequest.send` |
12
+ | Pending `setTimeout` | `window.__webshipPendingTimers` | wraps `window.setTimeout` / `clearTimeout` |
13
+ | Last DOM mutation | `window.__webshipLastMutation` | `MutationObserver` on `<html>` |
14
+ | Network idle | (Playwright internal) | `page.waitForLoadState('networkidle')` |
15
+
16
+ `smartSettle(page, budget)` polls all four atomically and returns when:
17
+
18
+ ```
19
+ __webshipAjaxCount === 0
20
+ && __webshipPendingTimers === 0
21
+ && (Date.now() - __webshipLastMutation) >= 250 ms
22
+ ```
23
+
24
+ …or when `budget` elapses, whichever comes first. Each phase is best-effort, so a slow network does not stall the others.
25
+
26
+ ## Step phrasings
27
+
28
+ ```gherkin
29
+ # Bounded smart wait (returns early on idle).
30
+ When I wait 5 seconds
31
+ When I wait max of 5 seconds
32
+ When I wait for 3 seconds for AJAX to finish
33
+
34
+ # Pure edge waits.
35
+ When I wait until the page is loaded
36
+ When I wait for AJAX to finish
37
+ When I wait until pending timers settle
38
+ When I wait until the network is idle
39
+
40
+ # Targeted edge waits.
41
+ When I wait for "#dashboard" to appear
42
+ When I wait for "#loading" to disappear
43
+ When I wait for the text "Welcome" to appear
44
+ When I wait until the URL contains "/dashboard"
45
+ When I wait until the page title contains "Dashboard"
46
+ When I wait until 5 elements match ".product-card"
47
+ When I wait until at least 3 elements match ".item"
48
+
49
+ # Modal-specific.
50
+ When I wait for the modal to appear
51
+ When I wait for the modal to disappear
52
+
53
+ # Body + DOMContentLoaded only (cheaper than full smart settle).
54
+ When I wait until the page is interactive
55
+
56
+ # Polling text assertion — re-runs the matcher until the deadline.
57
+ Then eventually I should see "Done"
58
+ Then eventually I should see "Done" within 10 seconds
59
+ ```
60
+
61
+ ## Auto-settle after actions
62
+
63
+ After every state-changing step (click, press, fill, submit, select, check, uncheck, choose, attach, reload, navigate), webship-js silently runs `smartSettle(page, 1500)`. Tests do not need an explicit wait between an action and its follow-up assertion in the typical case. Disable per-run with `WEBSHIP_AUTO_SETTLE=off`.
64
+
65
+ ## What this kills
66
+
67
+ - **Sleep-driven testing** — `wait 3s` no longer means "sleep three seconds." It means "wait up to three seconds for the page to become quiet."
68
+ - **`networkidle` blind spots** — animations and `setTimeout`-driven UI changes that did not trigger a network request still register on the DOM-mutation and timer-pending signals.
69
+ - **Race-condition flake** — a click followed by an assertion that runs before the DOM finishes updating is now caught by the auto-settle hook.
70
+
71
+ ## When to override
72
+
73
+ You generally don't. A few legitimate cases:
74
+
75
+ - **Real animation** with a known duration (`wait 3 seconds` is fine — smart wait will exit early but the budget is still honored).
76
+ - **Polling backend** that mutates without fetch/XHR (e.g. raw WebSocket pushes). Use a targeted edge wait: `wait for the text "..." to appear`.
77
+ - **Off-by-design UI** that runs an `setInterval` heartbeat. The pending-timer counter only tracks `setTimeout`, so heartbeats do not block `smartSettle`.
@@ -0,0 +1,95 @@
1
+ # Selector Registry
2
+
3
+ Long, brittle CSS strings poison feature files. Webship-js solves this with a **named selector registry**: register a CSS or XPath string once, refer to it by a friendly name in every step.
4
+
5
+ ## Three ways to register
6
+
7
+ ### 1. Inline (one selector at a time)
8
+
9
+ ```gherkin
10
+ Scenario: Add to cart
11
+ Given I am on "/products/101"
12
+ When I add "buy button" selector for ".product__buy button[type=submit]" css selector
13
+ And I click "buy button" by attr
14
+ ```
15
+
16
+ ### 2. Bulk (Gherkin data table)
17
+
18
+ ```gherkin
19
+ Scenario: Layout assertions
20
+ Given I define css selectors:
21
+ | header | header.site |
22
+ | nav | nav[role="navigation"] |
23
+ | main | main |
24
+ | footer | footer |
25
+ Then "main" should be visible
26
+ ```
27
+
28
+ ### 3. JSON file (project-wide preset)
29
+
30
+ ```js
31
+ // cucumber.js
32
+ worldParameters: {
33
+ selectors: {
34
+ filesPath: './tests/selectors/',
35
+ files: ['cms-drupal-cms-gin.json'],
36
+ }
37
+ }
38
+ ```
39
+
40
+ Every scenario starts with a fresh registry. Later entries with the same name override earlier ones (last wins).
41
+
42
+ ## Built-in CMS / framework presets
43
+
44
+ Webship-js ships ready-made selector packs:
45
+
46
+ ```
47
+ tests/selectors/
48
+ ├── _canonical-keys.json # Index of canonical keys + naming rules
49
+ ├── back-end-selectors.json # Generic admin layout
50
+ ├── front-end-selectors.json # Generic public layout
51
+ ├── cms-drupal-cms-gin.json # Drupal CMS (Gin admin theme)
52
+ ├── cms-drupal-core-claro.json # Drupal Core (Claro admin theme)
53
+ ├── cms-generic-admin.json # Pattern-matching generic CMS admin
54
+ ├── cms-ghost-admin.json # Ghost
55
+ ├── cms-joomla-admin.json # Joomla
56
+ ├── cms-magento2-admin.json # Magento 2
57
+ ├── cms-prestashop-admin.json # PrestaShop
58
+ ├── cms-shopify-admin.json # Shopify Polaris admin
59
+ ├── cms-strapi-admin.json # Strapi
60
+ ├── cms-typo3-admin.json # TYPO3
61
+ ├── cms-contentful-admin.json # Contentful
62
+ ├── cms-craft-admin.json # Craft CMS
63
+ ├── cms-wordpress-admin.json # WordPress
64
+ ├── cms-woocommerce-front.json # WooCommerce storefront
65
+ ├── framework-ant-design.json # Ant Design
66
+ ├── framework-bootstrap.json # Bootstrap
67
+ ├── framework-bulma.json # Bulma
68
+ ├── framework-chakra.json # Chakra UI
69
+ ├── framework-foundation.json # Foundation
70
+ ├── framework-material-ui.json # MUI
71
+ ├── framework-shadcn.json # shadcn / Radix
72
+ ├── framework-tailwind.json # Tailwind common patterns
73
+ └── framework-vuetify.json # Vuetify
74
+ ```
75
+
76
+ ## Canonical key set
77
+
78
+ To keep tests portable, every preset exposes the same core names. See `tests/selectors/_canonical-keys.json` for the full list. Highlights:
79
+
80
+ - **Layout** — `main nav`, `main nav item`, `sidebar`, `header bar`, `main content`, `page title`, `breadcrumb`, `user menu`
81
+ - **Modal** — `modal`, `modal overlay`, `modal title`, `modal body`, `modal footer`, `modal close`
82
+ - **Buttons** — `primary button`, `secondary button`, `danger button`, `save button`, `cancel button`, `delete button`
83
+ - **Notices** — `notice success`, `notice error`, `notice warning`, `notice info`, `toast`
84
+ - **Forms** — `form`, `form item`, `form label`, `form input`, `form select`, `form textarea`, `form actions`
85
+ - **Tables** — `data table`, `table header`, `table row`, `table first row`, `table row cell`
86
+ - **Tabs** — `tabs`, `tab item`, `active tab`, `tab content`
87
+ - **Search** — `search input`
88
+ - **Pagination** — `pagination`
89
+
90
+ ## Naming rules
91
+
92
+ - Lowercase words separated by single spaces (`primary button`, not `primary-button`).
93
+ - Modifier first (`active tab`, `danger button`, `first list item`).
94
+ - Synonyms collapse to canonical names (`alert success` / `notification success` / `callout success` → `notice success`).
95
+ - `data table` for HTML tables; `data list` for `ul`/`ol` collections.