coentrify 0.0.2 → 0.1.1

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 (262) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +2 -1
  3. package/bin/coentrify.js +83 -12
  4. package/package.json +3 -2
  5. package/src/changelog/0.0.1.md +259 -0
  6. package/src/changelog/0.0.2.md +219 -0
  7. package/src/changelog/0.0.3.md +81 -0
  8. package/src/changelog/0.0.4.md +198 -0
  9. package/src/changelog/0.0.5.md +160 -0
  10. package/src/changelog/0.0.6.md +282 -0
  11. package/src/changelog/0.0.7.md +113 -0
  12. package/src/changelog/0.0.8.md +212 -0
  13. package/src/changelog/0.1.0.md +9 -0
  14. package/src/changelog/0.1.1.md +27 -0
  15. package/src/changelog/overview.md +14 -0
  16. package/src/coentrify-json.md +74 -0
  17. package/src/commands.md +50 -0
  18. package/src/glossary.md +132 -0
  19. package/src/how-it-works.md +51 -0
  20. package/src/onboarding.md +141 -0
  21. package/src/origin.md +19 -0
  22. package/src/philosophy.md +99 -0
  23. package/src/proof.md +596 -0
  24. package/src/readme.md +76 -0
  25. package/src/recommendations.md +107 -0
  26. package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
  27. package/src/standards/ai/overview.md +6 -0
  28. package/src/standards/ai/prompt-small-models-differently.md +21 -0
  29. package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
  30. package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
  31. package/src/standards/angular/no-any-in-templates.md +25 -0
  32. package/src/standards/angular/no-inline-templates.md +14 -0
  33. package/src/standards/angular/one-component-per-folder-flat.md +12 -0
  34. package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
  35. package/src/standards/angular/overview.md +16 -0
  36. package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
  37. package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
  38. package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
  39. package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
  40. package/src/standards/angular/ui-copy-in-template.md +26 -0
  41. package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
  42. package/src/standards/architecture/adopt-configure-override.md +25 -0
  43. package/src/standards/architecture/app-shield.md +57 -0
  44. package/src/standards/architecture/converge-only-once-proven.md +22 -0
  45. package/src/standards/architecture/folder-concerns.md +28 -0
  46. package/src/standards/architecture/overview.md +11 -0
  47. package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
  48. package/src/standards/architecture/separation-before-layer-standards.md +17 -0
  49. package/src/standards/architecture/unique-where-it-counts.md +19 -0
  50. package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
  51. package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
  52. package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
  53. package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
  54. package/src/standards/behavior/always-make-no-mistakes.md +45 -0
  55. package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
  56. package/src/standards/behavior/always-work-from-a-plan.md +29 -0
  57. package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
  58. package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
  59. package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
  60. package/src/standards/behavior/communication-boundary.md +18 -0
  61. package/src/standards/behavior/dev-tiers.md +25 -0
  62. package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
  63. package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
  64. package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
  65. package/src/standards/behavior/feature-workflow.md +31 -0
  66. package/src/standards/behavior/file-a-change-with-coentrify.md +25 -0
  67. package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
  68. package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
  69. package/src/standards/behavior/general-working-rules.md +37 -0
  70. package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
  71. package/src/standards/behavior/normal-dashes.md +15 -0
  72. package/src/standards/behavior/note-issues.md +26 -0
  73. package/src/standards/behavior/overview.md +46 -0
  74. package/src/standards/behavior/own-ports-own-processes.md +37 -0
  75. package/src/standards/behavior/project-lifecycle.md +21 -0
  76. package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
  77. package/src/standards/behavior/prose-style.md +24 -0
  78. package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
  79. package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
  80. package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
  81. package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
  82. package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
  83. package/src/standards/behavior/standards-maintenance.md +65 -0
  84. package/src/standards/behavior/standards-over-skills.md +17 -0
  85. package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
  86. package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
  87. package/src/standards/behavior/the-quality-of-the-question.md +17 -0
  88. package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
  89. package/src/standards/behavior/understand-the-need.md +69 -0
  90. package/src/standards/behavior/use-us-english-everywhere.md +17 -0
  91. package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
  92. package/src/standards/behavior/verify-control-before-rename.md +11 -0
  93. package/src/standards/code/code-principles.md +32 -0
  94. package/src/standards/code/escape-hatch-comments.md +20 -0
  95. package/src/standards/code/name-by-concept-not-copy.md +20 -0
  96. package/src/standards/code/no-abbreviated-names.md +20 -0
  97. package/src/standards/code/no-describe-what-comments.md +26 -0
  98. package/src/standards/code/overview.md +10 -0
  99. package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
  100. package/src/standards/commits/commits.md +44 -0
  101. package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
  102. package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
  103. package/src/standards/commits/overview.md +8 -0
  104. package/src/standards/commits/verify-staging-before-committing.md +29 -0
  105. package/src/standards/docs/application-template.md +89 -0
  106. package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
  107. package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
  108. package/src/standards/docs/docs-folder-structure.md +38 -0
  109. package/src/standards/docs/docs-state-knowledge.md +23 -0
  110. package/src/standards/docs/documentation-philosophy.md +62 -0
  111. package/src/standards/docs/feature-spec-template.md +89 -0
  112. package/src/standards/docs/feature-template.md +62 -0
  113. package/src/standards/docs/file-names.md +20 -0
  114. package/src/standards/docs/glossary.md +18 -0
  115. package/src/standards/docs/library-feedback.md +20 -0
  116. package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
  117. package/src/standards/docs/overview.md +20 -0
  118. package/src/standards/docs/ui-vocabulary.md +31 -0
  119. package/src/standards/docs/workspace-levels.md +24 -0
  120. package/src/standards/docs/workspace-suite.md +24 -0
  121. package/src/standards/docs/workspace-template.md +41 -0
  122. package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
  123. package/src/standards/e2e/e2e-mock-contract.md +20 -0
  124. package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
  125. package/src/standards/e2e/e2e-test-conventions.md +61 -0
  126. package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
  127. package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
  128. package/src/standards/e2e/overview.md +14 -0
  129. package/src/standards/e2e/per-feature-overview-test.md +30 -0
  130. package/src/standards/e2e/real-input-for-frame-races.md +25 -0
  131. package/src/standards/e2e/substring-locator-collisions.md +23 -0
  132. package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
  133. package/src/standards/electron/electron-packaging-and-suite.md +22 -0
  134. package/src/standards/electron/electron-shell-shape.md +21 -0
  135. package/src/standards/electron/overview.md +6 -0
  136. package/src/standards/gamedev/2d-visual-design.md +22 -0
  137. package/src/standards/gamedev/budget-exceptions.json +6 -0
  138. package/src/standards/gamedev/captures-and-reels.md +39 -0
  139. package/src/standards/gamedev/devbox.md +21 -0
  140. package/src/standards/gamedev/game-design-laws-experience.md +68 -0
  141. package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
  142. package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
  143. package/src/standards/gamedev/game-design-laws-progress.md +64 -0
  144. package/src/standards/gamedev/game-design-laws-quality.md +30 -0
  145. package/src/standards/gamedev/game-design-laws-story.md +45 -0
  146. package/src/standards/gamedev/game-design-laws-ui.md +52 -0
  147. package/src/standards/gamedev/game-design-laws-world.md +38 -0
  148. package/src/standards/gamedev/game-design-laws.md +114 -0
  149. package/src/standards/gamedev/game-phases-concept.md +29 -0
  150. package/src/standards/gamedev/game-phases-design.md +39 -0
  151. package/src/standards/gamedev/game-phases-development.md +30 -0
  152. package/src/standards/gamedev/game-phases-live.md +19 -0
  153. package/src/standards/gamedev/game-phases.md +52 -0
  154. package/src/standards/gamedev/game-work-workflow.md +47 -0
  155. package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
  156. package/src/standards/gamedev/incremental-pacing.md +22 -0
  157. package/src/standards/gamedev/launch-strategy.md +50 -0
  158. package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
  159. package/src/standards/gamedev/overview.md +29 -0
  160. package/src/standards/gamedev/own-icons.md +19 -0
  161. package/src/standards/gamedev/silent-runs.md +26 -0
  162. package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
  163. package/src/standards/overview.md +43 -0
  164. package/src/standards/records/activity-log.md +33 -0
  165. package/src/standards/records/changelog-per-version.md +43 -0
  166. package/src/standards/records/healing-log.md +23 -0
  167. package/src/standards/records/overview.md +10 -0
  168. package/src/standards/records/playtest-files.md +38 -0
  169. package/src/standards/records/request-log.md +30 -0
  170. package/src/standards/records/user-test-files.md +21 -0
  171. package/src/standards/reporting/change-report.md +43 -0
  172. package/src/standards/reporting/overview.md +6 -0
  173. package/src/standards/reporting/reels-and-video-proof.md +32 -0
  174. package/src/standards/scripts/no-npx-in-scripts.md +20 -0
  175. package/src/standards/scripts/npm-script-naming.md +43 -0
  176. package/src/standards/scripts/overview.md +7 -0
  177. package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
  178. package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
  179. package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
  180. package/src/standards/security/never-access-the-keychain.md +16 -0
  181. package/src/standards/security/overview.md +7 -0
  182. package/src/standards/simple-workflow/bugs-template.md +38 -0
  183. package/src/standards/simple-workflow/overview.md +12 -0
  184. package/src/standards/simple-workflow/plan-template.md +50 -0
  185. package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
  186. package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
  187. package/src/standards/simple-workflow/roadmap-template.md +41 -0
  188. package/src/standards/simple-workflow/technical-debt-template.md +44 -0
  189. package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
  190. package/src/standards/simple-workflow/todo-template.md +31 -0
  191. package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
  192. package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
  193. package/src/standards/tests/gestures-in-tests.md +35 -0
  194. package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
  195. package/src/standards/tests/implementation-agnostic-locators.md +18 -0
  196. package/src/standards/tests/overview.md +13 -0
  197. package/src/standards/tests/realistic-test-data-variance.md +24 -0
  198. package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
  199. package/src/standards/tests/test-design.md +47 -0
  200. package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
  201. package/src/standards/tickets-workflow/agent-roles.md +54 -0
  202. package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
  203. package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
  204. package/src/standards/tickets-workflow/overview.md +15 -0
  205. package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
  206. package/src/standards/tickets-workflow/the-builder.md +28 -0
  207. package/src/standards/tickets-workflow/the-conductor.md +44 -0
  208. package/src/standards/tickets-workflow/the-done-part.md +23 -0
  209. package/src/standards/tickets-workflow/ticket-template.md +96 -0
  210. package/src/standards/tickets-workflow/work-item-names.md +30 -0
  211. package/src/standards/tickets-workflow/work-tracking.md +177 -0
  212. package/src/standards/tickets-workflow/work-workflow.md +123 -0
  213. package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
  214. package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
  215. package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
  216. package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
  217. package/src/standards/tooling/develop-against-mocks.md +19 -0
  218. package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
  219. package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
  220. package/src/standards/tooling/node-versions.md +24 -0
  221. package/src/standards/tooling/overview.md +17 -0
  222. package/src/standards/tooling/parallel-agents.md +45 -0
  223. package/src/standards/tooling/playwright-parallel-runs.md +30 -0
  224. package/src/standards/tooling/playwright-video-recording.md +32 -0
  225. package/src/standards/tooling/read-before-you-truncate.md +19 -0
  226. package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
  227. package/src/standards/tooling/vitepress-wiki.md +38 -0
  228. package/src/standards/typescript/always-add-explicit-types.md +32 -0
  229. package/src/standards/typescript/barrel-imports.md +21 -0
  230. package/src/standards/typescript/no-magic-values.md +52 -0
  231. package/src/standards/typescript/one-artifact-per-file.md +19 -0
  232. package/src/standards/typescript/overview.md +8 -0
  233. package/src/standards/ui/communicate-state.md +21 -0
  234. package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
  235. package/src/standards/ui/overview.md +16 -0
  236. package/src/standards/ui/pixel-perfect-design-check.md +22 -0
  237. package/src/standards/ui/ui-component-design.md +34 -0
  238. package/src/standards/ui/ui-components-first.md +25 -0
  239. package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
  240. package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
  241. package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
  242. package/src/standards/ui/ui-styleguide.md +30 -0
  243. package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
  244. package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
  245. package/src/standards/ui/walk-the-users-journey.md +29 -0
  246. package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
  247. package/src/standards/web/dark-mode-through-tokens.md +19 -0
  248. package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
  249. package/src/standards/web/overview.md +9 -0
  250. package/src/standards/web/scss-shared-partial-imports.md +16 -0
  251. package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
  252. package/src/standards.md +66 -0
  253. package/src/tools/overview.md +22 -0
  254. package/src/tools/scripts/coentrify-update.py +242 -0
  255. package/src/tools/scripts/unlink-missing-standards.py +138 -0
  256. package/src/tools/specs/changelog-append.md +15 -0
  257. package/src/tools/specs/coentrify-json-check.md +21 -0
  258. package/src/tools/specs/commit-gate.md +32 -0
  259. package/src/tools/specs/healing-append.md +15 -0
  260. package/src/tools/specs/landing.md +29 -0
  261. package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
  262. package/src/tools/specs/reload-core-rules.md +20 -0
@@ -0,0 +1,24 @@
1
+ # Node Versions
2
+
3
+ Use a Node.js major that is in Long-Term Support.
4
+
5
+ ## Why
6
+
7
+ Production runs on a stable release with long-term support.
8
+
9
+ ## How To Apply
10
+
11
+ Through Node 26 only even majors reach LTS. From Node 27 on, every major does, in the October after its April release.
12
+
13
+ When picking a Node version, pin an LTS major in every place Node is pinned:
14
+
15
+ - `.nvmrc` / `.node-version`.
16
+ - `engines.node` in `package.json`.
17
+ - `@types/node` and other Node-related type packages.
18
+ - CI workflow `setup-node` versions.
19
+ - Docker base images (`node:22-alpine`, etc.).
20
+
21
+ ## Related
22
+
23
+ - [Pre-Empt Recurring Code-Review Nits](../code/pre-empt-recurring-code-review-nits.md)
24
+ - [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
@@ -0,0 +1,17 @@
1
+ # Overview
2
+
3
+ The Tooling standards: development tools.
4
+
5
+ - [Browser Captures Go To Disk](browser-captures-go-to-disk.md) - base64 captures go to disk through a script, never by hand
6
+ - [Check Where A Pane Click Landed](check-where-a-pane-click-landed.md) - check where a pane click landed before calling a control broken
7
+ - [Defer Tooling Until The Cost Shows Up](defer-tooling-until-the-cost-shows-up.md) - add heavy tooling only once its absence costs something
8
+ - [Develop Against Mocks](develop-against-mocks.md) - develop against a committed, toggleable mock layer
9
+ - [Hygiene Tests Run On Their Own Runner](hygiene-tests-run-on-their-own-runner.md) - hygiene checks run as plain vitest specs on their own runner
10
+ - [Lightweight Test Reporting Only](lightweight-test-reporting-only.md) - reporting shows only whether the suite is green
11
+ - [Node Versions](node-versions.md) - a Node major in Long-Term Support
12
+ - [Parallel Agents](parallel-agents.md) - a git worktree, an e2e port and a scratchpad per agent. Reset to main first, commit then rebase, builders on the cheaper model, a story lands whole through the project's merge script, clean up only after git cherry
13
+ - [Playwright Parallel Runs](playwright-parallel-runs.md) - one worker per agent run, and a full suite as one background command, in two halves only past its limit
14
+ - [Playwright Video Recording](playwright-video-recording.md) - video options per file, and variants share one flow function
15
+ - [Read Before You Truncate](read-before-you-truncate.md) - read a file into a variable before opening it for write
16
+ - [Start Playwright On A Clean Port](start-playwright-on-a-clean-port.md) - lsof the e2e port before a run, since reuseExistingServer takes anything
17
+ - [VitePress Wiki](vitepress-wiki.md) - the docs wiki on its own port, open at session start
@@ -0,0 +1,45 @@
1
+ # Parallel Agents
2
+
3
+ Each agent works in a git worktree and on ports of its own, and every landing goes through the project's scripts.
4
+
5
+ ## Why
6
+
7
+ Agents that work at the same time should not conflict.
8
+
9
+ ## Worktrees
10
+
11
+ - Each agent works in a git worktree of its own, with the main tree's node modules linked, its own e2e port by argument, its own scratchpad folder for logs and captures, and a second port of its own for any second run.
12
+ - No Electron is launched from a worktree without the shell's own ignored node modules copied in.
13
+ - Every brief starts with `git reset --hard main` on the new branch, before any code is read: the worktree branches from origin's main, which lags the local one.
14
+ - A check against old code goes through a scratch branch of its own.
15
+ - Agents commit per item and rebase onto main right after each commit, so main's latest is under the next item. A rebase refuses a dirty tree and git stash is shared by every worktree, so the commit comes first.
16
+ - Builders run on the cheaper model.
17
+
18
+ ## Watching Agents
19
+
20
+ - An agent with no commit for about half an hour gets a look: its uncommitted files, its suite logs, its servers. A builder polishing a detail or rerunning suites then is stopped and told to close from what it has. A long run of several suites with finished items sitting uncommitted is stopped and split into one commit per item with the touched suite only.
21
+ - Whatever watches for agent commits lists every agent branch by pattern and never marks waiting commits as seen when it restarts. After any restart, list what waits with `git cherry` and land it.
22
+
23
+ ## Landing
24
+
25
+ - A story lands on main whole, once its tickets are done, and again after rework: the simplified release workflow. Its branch goes through the project's merge script, in a command of its own, never beside anything else. The merge commit carries the story's id ([Commits](../commits/commits.md#ticket-prefix)).
26
+ - The main checks go through the project's main checks script with the checks named as npm scripts, such as the hygiene, types, unit and wiki checks and the development build. A docs landing names hygiene and the wiki at least.
27
+ - A docs commit outside a landing goes through the project's docs commit script, hygiene among its checks, which commits only when every check exits 0.
28
+ - After any `git merge --abort`, `git cherry main <branch>` runs before a landing is reported.
29
+ - Before its story merges, the builder rebases the branch onto main and runs the main checks green, the development build's warnings read. The merge script refuses a branch that main has moved past.
30
+ - A landing that changes the app's shell, its routes, how screens load or what boots first gets the whole browser suite in its builder's worktree before it merges.
31
+ - A docs commit that adds spec cases lands together with the commit tagging their tests.
32
+
33
+ ## Cleanup
34
+
35
+ - A builder's branch and worktree go when its story is done: at its verdict, or at its last landing when none is due. Another agent's worktree goes after its final report, never at a landing.
36
+ - A branch is deleted only after `git cherry main <branch>` was read for it and every `+` traced to a landing, never by a wider pattern than the branches checked.
37
+
38
+ ## Related
39
+
40
+ - [The Builder](../tickets-workflow/the-builder.md)
41
+ - [Agent Roles](../tickets-workflow/agent-roles.md)
42
+ - [The Conductor](../tickets-workflow/the-conductor.md)
43
+ - [Playwright Parallel Runs](playwright-parallel-runs.md)
44
+ - [Own Ports, Own Processes](../behavior/own-ports-own-processes.md)
45
+ - [Start Playwright On A Clean Port](start-playwright-on-a-clean-port.md)
@@ -0,0 +1,30 @@
1
+ # Playwright Parallel Runs
2
+
3
+ Playwright runs share the machine lightly, and end in a result that can be trusted.
4
+
5
+ ## Why
6
+
7
+ Runs on a shared machine should not get in each other's way, and each should end in a result that can be trusted.
8
+
9
+ ## On A Shared Machine
10
+
11
+ - Every agent's Playwright run uses `--workers=1` and only the touched spec. No more agents run suites at once than the machine carries without lag. Agents on default workers overload the machine and lag the director's typing.
12
+ - When the machine is loaded, the agents on debt pause first.
13
+ - An agent never adds load of its own making, busy loops or CPU burners, to reproduce or steady a flaky case ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)).
14
+
15
+ ## A Full Suite
16
+
17
+ A full browser suite runs as one background command with a time limit above the suite's length, gated on its exit code. A killed run proves nothing.
18
+
19
+ Where a suite outlasts the longest a background command may run, split it in two:
20
+
21
+ - Two halves, on two ports, in two background commands at once, each under the limit and each gated on its own exit code.
22
+ - Each half gets its own output folder (`--output`) and its own html report folder (`PLAYWRIGHT_HTML_OUTPUT_DIR`). Two runs sharing Playwright's artifact folder delete each other's traces.
23
+ - The halves share one build: the first half's web server builds, and the second half gets a static server of its own on that output, started once the build is up. Two web servers building into the same folder at once collide.
24
+ - Never point a half at the other half's server, which stops when that half ends.
25
+ - A case that fails under that load and passes alone is a flaky case ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)).
26
+
27
+ ## Related
28
+
29
+ - [Start Playwright On A Clean Port](start-playwright-on-a-clean-port.md)
30
+ - [Gate Commits On Exit Codes](../commits/gate-commits-on-exit-codes.md)
@@ -0,0 +1,32 @@
1
+ # Playwright Video Recording
2
+
3
+ A Playwright recording sets its video options per file, and its variants share one flow.
4
+
5
+ ## Why
6
+
7
+ A recording is proof, so it has to come out sharp and whole.
8
+
9
+ ## Video Options Are Per File
10
+
11
+ `test.use({ video: { mode, size } })` cannot live inside a `test.describe` block. Playwright rejects it with "Cannot use({ video }) in a describe group, because it forces a new worker". A spec file is its own worker scope, so the option works at the top of a file only.
12
+
13
+ - The default `video.size` is the viewport scaled to fit 800x800, which downscales mobile-shaped footage noticeably.
14
+ - When footage must be 1:1 sharp at several viewports, split the spec into one file per viewport (e.g. `*.mobile.spec.ts`), each with its own `test.use`, sharing one `deviceOptions(size)` helper that bundles viewport and video size.
15
+ - When sharp framing doesn't matter, leave `video.size` unset. The scaling is proportional, just not native. Never for a reel, which keeps the viewport's size ([Reels And Video Proof](../reporting/reels-and-video-proof.md)).
16
+
17
+ ## Variants Of One Take
18
+
19
+ To record the same take under another condition (dark mode, another viewport, a locale):
20
+
21
+ - Extract the take into a shared async function that takes the page, and call it from both tests rather than copy-pasting. Re-run the formatter afterward, since extraction reflows indentation.
22
+ - Give the variant a distinct tag suffix (`@<feature-id>-overview-dark`) wherever output files are named after the tag, or the variant overwrites the original recording.
23
+ - Force the theme before the first navigation with `page.emulateMedia({ colorScheme: 'dark' })`, so the whole take records in it and it survives a mid-flow reload.
24
+
25
+ ## Pitfalls
26
+
27
+ - Never kill a recording run mid-build and rerun it at once: `reuseExistingServer` picks up the half-built server, whose lazy chunks aren't built yet, and navigation lands on a `chrome-error://` page ([Start Playwright On A Clean Port](start-playwright-on-a-clean-port.md)). A clean run without recording is the fast way to prove the flow first.
28
+ - An overlay that renders subtitles or labels into the DOM collides with substring locators ([Substring Locator Collisions](../e2e/substring-locator-collisions.md)).
29
+
30
+ ## Related
31
+
32
+ - [Reels And Video Proof](../reporting/reels-and-video-proof.md)
@@ -0,0 +1,19 @@
1
+ # Read Before You Truncate
2
+
3
+ A scripted in-place edit reads the whole file into a variable, runs its checks and replacements, and only then opens the file for writing.
4
+
5
+ ## Why
6
+
7
+ A file survives a scripted edit, uncommitted work included.
8
+
9
+ ## How To Apply
10
+
11
+ - Python: `s = open(p).read()`, assert, transform, then `with open(p, 'w') as f: f.write(new)`.
12
+ - Never redirect a command's output onto a file the same command reads.
13
+ - A file with uncommitted work that isn't yours: snapshot it to the scratchpad before the first scripted edit.
14
+ - A new file written from a heredoc (`cat > f <<EOF`) clobbers a file of the same name without a word: run `set -o noclobber` first, or `ls` the target names, so a clash fails loud.
15
+ - `open(p,'w').write(fix(open(p).read()))` opens for writing first, which empties the file: the read sees nothing, the assert fails, and the file stays empty, taking its uncommitted work with it.
16
+
17
+ ## Related
18
+
19
+ - [Review Changes Before Reporting Done](../behavior/review-changes-before-reporting-done.md)
@@ -0,0 +1,22 @@
1
+ # Start Playwright On A Clean Port
2
+
3
+ Before a Playwright run, the e2e port is clean: a lingering server of yours is killed, since `reuseExistingServer` takes whatever already listens there.
4
+
5
+ ## Why
6
+
7
+ Every run starts clean, so it shows the code as it stands.
8
+
9
+ ## How To Apply
10
+
11
+ - Point the e2e config's `webServer` URL and `BASE_URL` at the port the run gets as an argument, such as `npm run e2e -- --port=41738`, and at the project's own fixed port without one ([Own Ports, Own Processes](../behavior/own-ports-own-processes.md)). Never an exported variable, which outlives the command.
12
+ - Before a capture, a probe or a suite that must show the latest code, run `lsof -nP -i :<port>` and kill a listener that is yours, told by the marker in its command line.
13
+ - The check gates the start:
14
+ - A listener of yours found means kill it and look again before `start:e2e` runs, never start beside it.
15
+ - A listener that is not yours means another port.
16
+ - An "up" from a curl proves nothing while it stands.
17
+ - Stopping a `start:e2e` mid-build does not stop it: its preview can still come up later on the port, so look for the port's listener instead of the npm process.
18
+ - What listens there can be the director's own app, another project's server, or a stale watcher of this one that does not always rebuild. The tell is a capture of the old state, a snapshot of a different page, or role and locator queries that time out with no error.
19
+
20
+ ## Related
21
+
22
+ - [Playwright Video Recording](playwright-video-recording.md)
@@ -0,0 +1,38 @@
1
+ # VitePress Wiki
2
+
3
+ The project docs are served as a VitePress wiki on a fixed non-default port, started by one npm script and open from the first minute of a session. The sidebar is generated from the docs folder, the pages hot reload, every image opens in a lightbox, and the wiki builds in the pre-push hook so a broken page never lands.
4
+
5
+ ## Why
6
+
7
+ The director reviews the docs, changelogs, captures and reels in the wiki while the agent works.
8
+
9
+ ## Setup
10
+
11
+ - The sidebar mirrors the docs folder tree ([Docs Folder Structure](../docs/docs-folder-structure.md)), generated, with no page listed by hand.
12
+ - The root pages stand on top in the order they read, any other root page after them, so a new page never goes missing.
13
+ - Every folder is a collapsed group. The known folders come in a set order, any other folder after them.
14
+ - A sidebar group is never a page itself, since a group that links cannot be closed by clicking it again. Its overview is the first item inside the dropdown.
15
+ - A page's title is its H1, and a spec nests collapsed under its feature.
16
+ - The record groups run newest first: the log, the activity, the playtests, the user tests and the changelog. The activity and log groups are titled Activity Log and Request Log.
17
+ - A new or deleted page is picked up in place: once the changes settle, the sidebar is rebuilt and the open pages reload. The server never restarts for it, since a burst of new pages would restart it over and over.
18
+ - The wiki has one config file, `.vitepress/config`, and a session never creates a second one.
19
+ - The watcher ignores the build output and the cache.
20
+ - Every image in a page enlarges on a click to the full window width, so the director judges a capture at full size, never shrunk to the text column. The arrow keys walk the page's images, Escape or a click closes it, a counter shows the position, and the hidden state has its own display rule.
21
+ - Local search, last updated dates and clean URLs are on.
22
+ - The dev server sends `Cache-Control: no-store`, so the director never reviews a stale image.
23
+ - Videos sit in the public folder and embed with a plain video tag.
24
+ - A bare word in angle brackets in a page, `<name>`, reads as an html tag and fails the build. It goes in code marks.
25
+ - A hosts-file domain is a stopgap not worth keeping.
26
+ - The URL with the port is the bookmark.
27
+
28
+ ## How To Apply
29
+
30
+ - Set the wiki up on day one with the docs skeleton, before any feature.
31
+ - At session start, run the wiki when the project has one and hand over its URL. It keeps running after the session when the director asked for it ([Own Ports, Own Processes](../behavior/own-ports-own-processes.md)).
32
+ - Keep the config generic, with no hand-kept page lists.
33
+ - A full wiki cleanup check against the product as it is is filed as work at each version's close: stale names, drifted references, duplicated facts, the reconstructed history checked against the changelogs.
34
+ - Verify a theme change on a fresh navigation, with a page at rest and one with the feature in use, by what is painted ([Hidden Attribute Loses To Display](../web/hidden-attribute-loses-to-display.md)). A hot reload replaces a page's images without the lightbox listeners, so a stale page reads as a broken lightbox.
35
+
36
+ ## Related
37
+
38
+ - [Changelog Per Version](../records/changelog-per-version.md)
@@ -0,0 +1,32 @@
1
+ # Always Add Explicit Types
2
+
3
+ Annotate every binding - `const`, `let`, function parameters, function return types - even when TypeScript can infer them. Inference is for the compiler, not the reader.
4
+
5
+ ## Why
6
+
7
+ Strict typing leaves no room for side effects or unforeseen paths.
8
+
9
+ ## Examples
10
+
11
+ ```ts
12
+ const value: User = getUser();
13
+ let count: number = 0;
14
+ function load(id: string): User { ... }
15
+ const handler: (event: Event) => void = (event) => { ... };
16
+ ```
17
+
18
+ ## Linter
19
+
20
+ If a linter rule forbids explicit annotations on inferrable bindings, change the rule, not the code.
21
+
22
+ ## Exceptions
23
+
24
+ - Loop variables in a typed iterable (`for (const user of users)`).
25
+ - Destructured parameters where each field's type is pinned by the parent type.
26
+ - The parameters and return of a function assigned to a binding that carries its full function type.
27
+ - An `as const` object: its literal type is the point ([No Magic Values](no-magic-values.md)).
28
+
29
+ ## Related
30
+
31
+ - [No Magic Values](no-magic-values.md)
32
+ - [Pre-Empt Recurring Code-Review Nits](../code/pre-empt-recurring-code-review-nits.md)
@@ -0,0 +1,21 @@
1
+ # Barrel Imports
2
+
3
+ Within a lib, import a symbol through its folder's barrel index, not the deep file path - `from '../constants'`, not `from '../constants/sort-order.const'`. The IDE surfaces the barrel import as a quick-fix hint. Take it.
4
+
5
+ ## Why
6
+
7
+ An import path stays the same when a file moves.
8
+
9
+ ## How To Apply
10
+
11
+ - Import another folder's symbol through that folder's barrel. A file in the same folder is imported directly, never through its own folder's barrel.
12
+ - Scope is imports within a lib. This does not override the [App-Shield](../architecture/app-shield.md) rule against static imports across lazy-loaded edges, nor the narrow-alias exception of the [E2E Mock Contract](../e2e/e2e-mock-contract.md).
13
+ - Enforce it with a lint rule that flags deep-path imports ([Pre-Empt Recurring Code-Review Nits](../code/pre-empt-recurring-code-review-nits.md)).
14
+ - Barrel imports are shorter, and group well.
15
+ - A lint rule flags import cycles, such as `import/no-cycle`.
16
+
17
+ ## Related
18
+
19
+ - [One Artifact Per File](one-artifact-per-file.md)
20
+ - [App-Shield](../architecture/app-shield.md)
21
+ - [E2E Mock Contract](../e2e/e2e-mock-contract.md)
@@ -0,0 +1,52 @@
1
+ # No Magic Values
2
+
3
+ No magic strings or numbers in code. Any literal that is used more than once, or that *could* be used elsewhere, must be hoisted into a named constant. Applies to numbers too - `APP_BOOT_TIMEOUT` over `15_000` inline, even at a single call site, because the name carries the meaning.
4
+
5
+ ## Why
6
+
7
+ A name carries the meaning a literal cannot.
8
+
9
+ ## How To Apply
10
+
11
+ - A test names the same constant, so an e2e spec stays in sync with the scenario keys it targets.
12
+ - A constant is reused, edited in one place, and found by the IDE at every call site.
13
+
14
+ ## TypeScript Pattern
15
+
16
+ For sets of related string values, use the `as const` and `Enum<T>` pattern. Do **not** use the TypeScript `enum` keyword for new code - it generates runtime output, blocks pure type imports, and has type/value collision that makes it painful to import. The pattern keeps what an `enum` offers: autocomplete, and an exhaustive switch through the union type.
17
+
18
+ ```ts
19
+ // constants/<name>.const.ts
20
+ export const SortOrder = {
21
+ Ascending: 'asc',
22
+ Descending: 'desc',
23
+ } as const;
24
+
25
+ // types/<name>.type.ts
26
+ export type SortOrderType = Enum<typeof SortOrder>;
27
+ ```
28
+
29
+ `Enum<T>` is the generic `type Enum<T> = T[keyof T]`. Define it once, in config or core, for every layer but ui. ui stays free of the workspace, so it can be picked up and used elsewhere, and keeps its own copy in its `generics/` under a name of its own, such as `EnumOption<T>`. Which layer holds the shared one is the project's call.
30
+
31
+ For a single scalar constant (not a set), annotate its plain type, never `as const` or `Readonly<T>`, which protect nothing on a primitive - e.g. `export const BOT_USER_EMAIL: string = '...';` or `const DEFAULT_LIMIT: number = 50;`. Protection goes where it is needed: `as const` is reserved for the object that backs a union via `Enum<T>`.
32
+
33
+ ## Folder Layout
34
+
35
+ - `constants/` for `*.const.ts`.
36
+ - `types/` for `*.type.ts`.
37
+ - `generics/` for type-only utilities like `Enum<T>`.
38
+ - Each folder has its own `index.ts` re-exporting siblings. The lib's top-level `index.ts` re-exports each subfolder.
39
+
40
+ ## Exceptions
41
+
42
+ HTML template binding into a typed component input, where the literal is validated at compile time:
43
+
44
+ ```html
45
+ <some-button variant="cta"> <!-- fine, `variant` is typed -->
46
+ ```
47
+
48
+ This is fine *because* `<some-button>` defines its accepted variants with the `as const` and `Enum<T>` pattern and binds `variant` to that type. The component itself is **not** exempt - it must own its variant const, never an inline string union or hardcoded list.
49
+
50
+ ## Related
51
+
52
+ - [App-Shield](../architecture/app-shield.md)
@@ -0,0 +1,19 @@
1
+ # One Artifact Per File
2
+
3
+ Each exported artifact - a type, a class, an interface, each half of the `as const` and `Enum<T>` pattern - should live in its own file named after it, under the matching folder (`*.type.ts` in `types/`, `*.const.ts` in `constants/`). Never bundle several artifacts into one file. A folder's file list then is the list of artifacts: a navigable index layer.
4
+
5
+ ## Why
6
+
7
+ A read stays on the one artifact it needs.
8
+
9
+ ## How To Apply
10
+
11
+ - Split any bundle (wire-type god-files are the usual offender) into one file per artifact.
12
+ - Re-export siblings from the folder barrel so consumers still import from one place.
13
+ - The one exception is the mock contract's single `.const.ts` ([E2E Mock Contract](../e2e/e2e-mock-contract.md)).
14
+
15
+ ## Related
16
+
17
+ - [Barrel Imports](barrel-imports.md)
18
+ - [No Magic Values](no-magic-values.md)
19
+ - [Folder Concerns](../architecture/folder-concerns.md)
@@ -0,0 +1,8 @@
1
+ # Overview
2
+
3
+ The TypeScript standards: rules for TypeScript.
4
+
5
+ - [Always Add Explicit Types](always-add-explicit-types.md) - annotate every binding and return type
6
+ - [Barrel Imports](barrel-imports.md) - import another folder's symbols through its barrel, and a same-folder file directly
7
+ - [No Magic Values](no-magic-values.md) - hoist literals into consts, and use the `as const` and `Enum<T>` pattern, never `enum`
8
+ - [One Artifact Per File](one-artifact-per-file.md) - one type, const or class per file
@@ -0,0 +1,21 @@
1
+ # Communicate State
2
+
3
+ Every state the user cares about - loading, empty, error, success, disabled/locked - must be visibly communicated. Never leave a state silent, and never let one state masquerade as another (an error rendered as "no results", a load in progress rendered as empty).
4
+
5
+ ## Why
6
+
7
+ The user always knows what the system is doing.
8
+
9
+ ## How To Apply
10
+
11
+ - Model async data as explicit states (loading / loaded / empty / error) instead of a single value with an empty fallback. Each gets its own affordance: skeleton or spinner, empty state, error callout, success toast.
12
+ - Disabled or locked controls signal why they are inert.
13
+ - Use an existing design-system component for the feedback (callout, toast, empty state) per [UI Components First](ui-components-first.md).
14
+ - Visibility of system status is the first usability heuristic.
15
+ - A failed fetch that falls back to an empty list tells the user there is nothing, when the truth is that it could not load.
16
+
17
+ ## Related
18
+
19
+ - [Validation Errors Fire On Submit](validation-errors-fire-on-submit.md)
20
+ - [UI Component Design](ui-component-design.md)
21
+ - [UI Copy In Template](../angular/ui-copy-in-template.md)
@@ -0,0 +1,26 @@
1
+ # Never Obscure Information The User Needs
2
+
3
+ Information the user acts on must reach the screen intact. Collapsing distinct states into one, or presenting choices the user can't tell apart, obscures information: a high-severity correctness problem, never a cosmetic one, and never taken lightly.
4
+
5
+ ## Why
6
+
7
+ The user acts on information that is whole and true.
8
+
9
+ ## How To Apply
10
+
11
+ - A presentation map (mapper or view-model) that sends several distinct source values to one target is suspect. Confirm each collapse is equivalent. One that drops a state the user must see is a high-priority bug and a sweep across the other mappers.
12
+ - Cover every source enum value in mapper tests and assert distinct, faithful outputs.
13
+ - A control whose options share a label for distinct entities is an ambiguous choice: add a disambiguator (such as a location suffix) and flag it explicitly as ambiguous or missing information.
14
+ - When unsure, preserve the distinction over a tidier display.
15
+
16
+ ## Examples
17
+
18
+ - A mapper that folds a distinct status into another, expired shown as pending, makes the user act on the wrong urgency.
19
+ - A filter that lists same-named entities by name alone hands the user a choice that cannot be made correctly.
20
+
21
+ ## Related
22
+
23
+ - [Communicate State](communicate-state.md)
24
+ - [Realistic Test Data Variance](../tests/realistic-test-data-variance.md)
25
+ - [Test Design](../tests/test-design.md)
26
+ - [Note Issues](../behavior/note-issues.md)
@@ -0,0 +1,16 @@
1
+ # Overview
2
+
3
+ The UI standards: components and styling.
4
+
5
+ - [Communicate State](communicate-state.md) - every state is visible, never let error look like empty
6
+ - [Never Obscure Information The User Needs](never-obscure-information-the-user-needs.md) - never collapse distinct states or offer ambiguous choices
7
+ - [Pixel-Perfect Design Check](pixel-perfect-design-check.md) - compare app and design side by side at the widths that matter
8
+ - [UI Component Design](ui-component-design.md) - shared ui is pure: inputs, slots, strict BEM
9
+ - [UI Components First](ui-components-first.md) - use existing design-system and shared UI components, and add one rather than roll custom
10
+ - [UI Layout Via Slot Composition](ui-layout-via-slot-composition.md) - layout through generic slots, not config props
11
+ - [UI Library Is Domain-Agnostic](ui-library-is-domain-agnostic.md) - ui stays domain-agnostic, and domain maps live in the app layer
12
+ - [UI Refactor: Preserve, Don't Redesign](ui-refactor-preserve-dont-redesign.md) - a ui extraction looks exactly as before, and differences become variants
13
+ - [UI Styleguide](ui-styleguide.md) - every workspace with a ui layer gets a styleguide with variants and a testbox
14
+ - [UI Variants By Function, Not By Color](ui-variants-by-function-not-by-color.md) - variant inputs are named by function, not color
15
+ - [Validation Errors Fire On Submit](validation-errors-fire-on-submit.md) - submit reveals validation errors from any gesture
16
+ - [Walk The User's Journey](walk-the-users-journey.md) - design and check every screen as the user's journey: who, experiencing what, wanting what, the next question at each step. Show what means something to the user
@@ -0,0 +1,22 @@
1
+ # Pixel-Perfect Design Check
2
+
3
+ When building or reviewing UI against a design, compare the rendered pixels to the design directly. A "looks about right" glance is not enough where the design is the contract.
4
+
5
+ ## Why
6
+
7
+ Where the design is the contract, the build honors it to the pixel.
8
+
9
+ ## How To Apply
10
+
11
+ - Capture the design (Figma screenshot) and the running app at the same view, and compare them side by side: colors, padding, spacing, type, alignment.
12
+ - Check at the resolutions that matter - the breakpoints the view targets - since responsive rules change layout (e.g. callouts hidden at narrow widths, so verify at a width where they show).
13
+ - Where the view is meant to match the design it must match, or the difference must be explainable. Flag every unexplained inconsistency.
14
+ - Treat this as part of verification, alongside the functional checks.
15
+ - Drift in color, padding, spacing and alignment is invisible to type checks, lint and unit tests. It shows only in the rendered output, where a side-by-side comparison makes it obvious and a prose review walks past it.
16
+
17
+ ## Related
18
+
19
+ - [Always Verify Before Reporting Done](../behavior/always-verify-before-reporting-done.md)
20
+ - [Review Changes Before Reporting Done](../behavior/review-changes-before-reporting-done.md)
21
+ - [Always Use Design Tokens For Colors](../web/always-use-design-tokens-for-colors.md)
22
+ - [Note Issues](../behavior/note-issues.md)
@@ -0,0 +1,34 @@
1
+ # UI Component Design
2
+
3
+ Shared UI components encapsulate UI behavior and presentation. They hold no app-specific data, render no app-controlled behavior and expose clear extension points for the consumer.
4
+
5
+ ## Why
6
+
7
+ Components stay reusable, and all of them behave in a similar, expected way.
8
+
9
+ ## Pure UI
10
+
11
+ UI components own no app-specific assets (logos, illustrations), copy (including translation strings and their defaults), env values, or interactive controls the page should own (a logout button, a dialog's confirm button). Everything app-specific flows in from the consumer.
12
+
13
+ A component that pairs a UI shell with a purpose is the classic trap: a confirm dialog is a dialog (pure UI) plus a confirm action (app behavior). Keep the shell pure: the dialog renders its chrome and reserves an actions or footer slot, and the consumer projects its own buttons and owns what they do. Baking the purpose in (confirm and cancel inputs plus output emitters) drags app logic into the ui layer and makes the component less flexible.
14
+
15
+ ## Prefer Content Projection, Strongly
16
+
17
+ Default to content projection. Before adding any input, for data, composition or state, check whether the variation can be expressed by what the consumer projects. It almost always can. The component reserves space and styles it, and the consumer fills it. The component never renders a button on the page's behalf, even when it has a matching output.
18
+
19
+ Slots name regions, by the names and rules in [UI Layout Via Slot Composition](ui-layout-via-slot-composition.md).
20
+
21
+ ## Inputs As Fallback
22
+
23
+ When projection can't model the variation (a boolean that only changes styling, like `isDisabled`), use a typed input. Nothing app-specific is imported inside the shared lib. The component owns the visual treatment of each input value, and the consumer decides when each applies.
24
+
25
+ ## Styling Uses Strict BEM
26
+
27
+ Component CSS follows strict BEM: `block`, `block__element`, `block--modifier`, `block__element--modifier`. Each component owns only its own block: never reach into another component's BEM tree, style descendants by tag or let selectors cascade across components.
28
+
29
+ A feature's style applies to the feature alone: elements outside it, a media player or an action bar, keep their own look.
30
+
31
+ ## Related
32
+
33
+ - [Prefer Content Projection Over Props (Angular)](../angular/prefer-content-projection-over-props-angular.md)
34
+ - [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
@@ -0,0 +1,25 @@
1
+ # UI Components First
2
+
3
+ UI primitives (buttons, icons, callouts, tooltips, dialogs, toasts, inputs, layout chrome) come from existing components - either the project's design-system package or the workspace's shared UI library composed on top. Don't roll custom SVGs, native buttons, or bespoke styling for anything covered by an existing component.
4
+
5
+ ## Why
6
+
7
+ The UI stays one coherent system.
8
+
9
+ ## How To Apply
10
+
11
+ - Reach for an existing component first. Verify icon and component names against the package before using.
12
+ - A missing component composed from existing primitives, such as a card with a header and a list, is added to the workspace's shared UI library without asking.
13
+ - Arranging ui components into a page stays in the app layer.
14
+ - UI primitives stay in the UI library.
15
+ - A missing primitive that belongs in the design system itself, such as a new base control or icon, goes to the director, since it is a request to the design system's owners ([Library Feedback](../docs/library-feedback.md)). It is never inlined as a custom one.
16
+ - An existing component brings theming and accessibility with it.
17
+ - Everything through the UI layer gives the design system a clear pressure point when something is missing.
18
+
19
+ ## Related
20
+
21
+ - [No Inline Templates](../angular/no-inline-templates.md)
22
+ - [One Component Per Folder, Flat](../angular/one-component-per-folder-flat.md)
23
+ - [Prefer Content Projection Over Props (Angular)](../angular/prefer-content-projection-over-props-angular.md)
24
+ - [UI Component Design](ui-component-design.md)
25
+ - [UI Variants By Function, Not By Color](ui-variants-by-function-not-by-color.md)
@@ -0,0 +1,33 @@
1
+ # UI Layout Via Slot Composition
2
+
3
+ Layout in the shared `ui` library is slot composition through content projection. A layout or container component exposes a few generic slots (such as header, body, footer), owns only how those regions sit, and never takes a columns template, grid-config prop or preset.
4
+
5
+ ## Why
6
+
7
+ A layout component stays generic and reusable.
8
+
9
+ ## Slot Rules
10
+
11
+ - The body is the default slot, `<ng-content />`, except in the rare component where a default makes no sense (symmetric regions, such as left and right), which has two named slots and no default.
12
+ - Named slots use an attribute selector, `<ng-content select="[slot=top]" />`, filled by the consumer as `<x slot="top">`.
13
+ - Two or more slots are usually one default (the body) plus a couple of named ones (`header`, `actions`, `footer`).
14
+
15
+ ## How To Apply
16
+
17
+ - A responsive grid flows by the space available, instead of a fixed set of columns.
18
+ - Finer structure is the next layer down: a region that needs columns or sections gets a section or grid component projected into its slot, so the container never grows options for every shape.
19
+ - A slot names a region of the component, the place where content sits. Some reusable ones:
20
+ - `header`, `footer` - a pair of regions above and below the body, the header holding a title, badges or tabs.
21
+ - `title`, `description` - the regions for the consumer's text and whatever sits with it. The component owns their layout and typography, the consumer the content.
22
+ - `actions` - the region for the buttons the consumer owns (save, cancel, close).
23
+ - `top`, `bottom` - the other pair above and below the body. Which pair fits depends on the component.
24
+ - Whatever sits in a region goes into its slot: a chip after a card's title text, or a tooltip on it, is projected into the title slot along with the text.
25
+ - A slot never names a kind of content (`chip`, `badge`, `tooltip`, `button`): a region holds whatever the consumer puts there.
26
+ - Reuse an existing container (page, page content, card, section) before adding a new one. The routing may already provide one, so the cleanest layout is sometimes no new container at all.
27
+
28
+ ## Related
29
+
30
+ - [UI Component Design](ui-component-design.md)
31
+ - [Prefer Content Projection Over Props (Angular)](../angular/prefer-content-projection-over-props-angular.md)
32
+ - [UI Library Is Domain-Agnostic](ui-library-is-domain-agnostic.md)
33
+ - [UI Refactor: Preserve, Don't Redesign](ui-refactor-preserve-dont-redesign.md)
@@ -0,0 +1,20 @@
1
+ # UI Library Is Domain-Agnostic
2
+
3
+ The shared `ui` library must stand on its own, extractable as-is into another app in a different domain. A ui component therefore knows nothing about the domain: it takes generic presentation primitives (a `severity` or `tone`, an `icon` name, a `label`, a generic `variant`) as inputs and renders them, and never maps a domain value to a presentation value.
4
+
5
+ ## Why
6
+
7
+ The library can drop into an unrelated app unchanged.
8
+
9
+ ## How To Apply
10
+
11
+ - The consumer in the app layer owns the domain-to-presentation map, such as a record status to a badge `tone`, and passes the resolved `tone` in.
12
+ - `data`, the data layer of [App-Shield](../architecture/app-shield.md), holds no such map either: it stays design-system-free and imports no design-system package.
13
+ - A duplicated map consolidates into one shared feature module instead of moving to ui.
14
+ - A component whose name or inputs encode a domain concept (an order status badge, a table with fixed domain columns) does not belong in ui. Generic primitives (badge, table, chart) do.
15
+
16
+ ## Related
17
+
18
+ - [UI Variants By Function, Not By Color](ui-variants-by-function-not-by-color.md)
19
+ - [App-Shield](../architecture/app-shield.md)
20
+ - [UI Component Design](ui-component-design.md)
@@ -0,0 +1,25 @@
1
+ # UI Refactor: Preserve, Don't Redesign
2
+
3
+ Extracting feature markup into shared `ui` primitives, or consolidating duplicated styles, is a refactor: the rendered result must look exactly as before. Where two consumers had different styling, preserve both as named variants on the primitive, and never silently normalize them to one "consistent" treatment.
4
+
5
+ ## Why
6
+
7
+ Design decisions stay with the director.
8
+
9
+ ## How To Apply
10
+
11
+ - Before extracting, diff the old per-consumer values (color, font scale and weight, spacing, border and fill). Every difference becomes a variant input with a functional name (`size`, `tone`, `variant`), defaulting to the most common case. The other consumers opt in.
12
+ - Verify fidelity by comparing computed styles in preview against the originals. "Looks close" is not enough.
13
+ - Every value comes from the design system's tokens for color, spacing, typography and radius, such as `color.$text-*`. A missing token is added as [Always Use Design Tokens For Colors](../web/always-use-design-tokens-for-colors.md) says. A layout value that is no design token, such as a 320px scroll cap, is hardcoded as a justified escape hatch with a note. The same bar holds for `ViewEncapsulation.None` and casts.
14
+ - A consistency improvement (normalizing incidental drift) is a separate, opt-in change: propose it on its own instead of bundling it into the refactor.
15
+
16
+ ## Examples
17
+
18
+ - A consolidation can quietly change the visuals: a brand-colored count goes gray, compact details grow, a panel's padding shifts.
19
+
20
+ ## Related
21
+
22
+ - [General Working Rules](../behavior/general-working-rules.md)
23
+ - [UI Variants By Function, Not By Color](ui-variants-by-function-not-by-color.md)
24
+ - [UI Library Is Domain-Agnostic](ui-library-is-domain-agnostic.md)
25
+ - [Escape Hatch Comments](../code/escape-hatch-comments.md)