@wazir-dev/cli 1.0.0

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 (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
@@ -0,0 +1,623 @@
1
+ # User Mental Models — Design Psychology Expertise Module
2
+
3
+ > A design psychologist specializing in user mental models ensures that digital products align with how users think, predict, and interpret system behavior. The scope spans cognitive science foundations (schema theory, conceptual models, affordances), practical design rules for matching user expectations, measurement techniques for detecting mental model violations, ethical boundaries around deceptive patterns, and platform-specific model differences across devices and demographics. Core references: Don Norman's *The Design of Everyday Things* (1988, revised 2013), Jakob Nielsen and the Nielsen Norman Group (NNG), and Jon Yablonski's *Laws of UX*.
4
+
5
+ ---
6
+
7
+ ## 1. The Science of Mental Models
8
+
9
+ ### 1.1 What Is a Mental Model?
10
+
11
+ A mental model is an internal representation of how a user believes a system works. It is not a perfect mirror of reality — it is a simplified, sometimes incorrect, working theory that the user builds from experience, observation, analogy, and instruction. Users do not need to understand the actual implementation of a system; they need a model accurate enough to predict what will happen when they take an action.
12
+
13
+ Don Norman distinguishes three aspects of mental models in *The Design of Everyday Things*:
14
+
15
+ 1. **Design Model** — The conceptualization the designer holds. It is the intended logic of how the system should work.
16
+ 2. **System Image** — Everything the user can perceive about the system: its interface, documentation, error messages, physical form. This is the only channel through which the design model reaches the user.
17
+ 3. **User's Model** — The mental model the user constructs from interacting with the system image. If the system image clearly communicates the design model, the user's model will approximate it. If the system image is ambiguous, the user's model will diverge, causing errors and frustration.
18
+
19
+ The designer's job is to ensure the system image accurately and clearly conveys the design model so the user's mental model converges toward it.
20
+
21
+ ### 1.2 Conceptual Models vs. Implementation Models
22
+
23
+ These two terms describe the opposite ends of a spectrum:
24
+
25
+ **Conceptual Model (User-Facing)**
26
+ The simplified, user-oriented explanation of how a system works. It uses metaphors, analogies, and visible structure to make the system comprehensible. Example: a "shopping cart" on an e-commerce site is a conceptual model — it maps to a familiar physical-world concept so users know they can add items, review them, remove them, and proceed to payment.
27
+
28
+ **Implementation Model (System-Facing)**
29
+ The actual technical architecture of how the system operates internally. Example: the shopping cart is actually a session-scoped data structure in a database, referenced by a cookie, with inventory reservation logic and price-calculation pipelines. Users never need to know this.
30
+
31
+ The gulf between these two models determines usability:
32
+ - When the interface exposes the implementation model (e.g., showing database IDs, using technical jargon, requiring users to understand system internals), usability suffers.
33
+ - When the interface presents a clear conceptual model that hides implementation complexity, usability improves.
34
+
35
+ Alan Cooper's *About Face* calls this the "principle of least astonishment" — the interface should behave in a way that matches the user's conceptual model, never surprising them with implementation-level behavior.
36
+
37
+ ### 1.3 Don Norman's Gulfs: Execution and Evaluation
38
+
39
+ Norman identified two fundamental gaps that determine how usable a system is:
40
+
41
+ **Gulf of Execution**
42
+ The gap between what the user wants to do and what the system allows them to do (or makes visible as possible). A wide gulf of execution means the user cannot figure out how to accomplish their goal. Example: a user wants to bold text in a word processor but there is no visible button, no menu item labeled "Bold," and Ctrl+B does nothing — the gulf of execution is enormous.
43
+
44
+ **Gulf of Evaluation**
45
+ The gap between the system's actual state and the user's ability to perceive and interpret that state. A wide gulf of evaluation means the user cannot tell whether their action succeeded. Example: a user submits a form but receives no confirmation message, no visual change, no redirect — they cannot evaluate whether the submission worked.
46
+
47
+ Good design bridges both gulfs through:
48
+ - **Clear affordances and signifiers** (bridging execution)
49
+ - **Immediate, interpretable feedback** (bridging evaluation)
50
+ - **A transparent conceptual model** that connects the two
51
+
52
+ ### 1.4 Schema Theory and User Cognition
53
+
54
+ Schema theory, introduced by Frederic Bartlett (1932) and expanded by Jean Piaget, describes how humans organize knowledge into cognitive frameworks called *schemas*. A schema is a structured cluster of pre-organized knowledge about a concept, event, or situation.
55
+
56
+ **How schemas apply to interface design:**
57
+
58
+ - **Recognition over recall**: Users recognize familiar patterns faster than they recall unfamiliar ones. A magnifying glass icon activates the "search" schema instantly; a novel icon requires learning.
59
+ - **Assimilation**: When a new interface element fits an existing schema, users absorb it effortlessly. A toggle switch that looks like a physical light switch activates the on/off schema.
60
+ - **Accommodation**: When a new element contradicts existing schemas, users must restructure their mental model. This is cognitively expensive and error-prone. A toggle switch that works in reverse (left = on) forces accommodation.
61
+ - **Schema activation**: Contextual cues trigger relevant schemas. Seeing a credit card form activates the "payment" schema, priming users to expect fields for card number, expiration, and CVV. If the form asks for a social security number instead, the activated schema is violated.
62
+
63
+ **Implications for designers:**
64
+ - Leverage existing schemas whenever possible (use established patterns)
65
+ - Signal schema shifts explicitly (e.g., "This works differently than you might expect...")
66
+ - Never violate an activated schema without clear warning and justification
67
+ - Group related elements to activate a single coherent schema rather than forcing users to juggle multiple competing frameworks
68
+
69
+ ### 1.5 Affordances and Signifiers
70
+
71
+ Don Norman refined these concepts across multiple editions of his work:
72
+
73
+ **Affordance**
74
+ The relationship between an object and an agent that determines how the object can be used. A flat surface affords pushing. A handle affords pulling. A button affords pressing. Affordances exist whether or not the user perceives them.
75
+
76
+ **Signifier**
77
+ A perceivable cue that communicates what actions are possible. A signifier makes an affordance visible. A raised, beveled button with a shadow is a signifier that says "I can be pressed." A flat, uniform rectangle with no visual differentiation has no signifier — even if it is technically clickable.
78
+
79
+ Norman introduced the term "signifier" in the 2013 revised edition because the term "affordance" had been widely misused in the design community. He clarified:
80
+ - Affordances define what actions are possible
81
+ - Signifiers indicate where the action should take place
82
+ - Designers cannot control affordances (they are properties of the world), but they can control signifiers
83
+
84
+ **Common signifier failures in digital design:**
85
+ | Failure | Example | Mental Model Impact |
86
+ |---|---|---|
87
+ | Missing signifier | Text that is actually a link but has no underline, no color change, no hover effect | User never discovers the action is possible |
88
+ | False signifier | Blue underlined text that is not a link | User attempts action and fails, losing trust |
89
+ | Ambiguous signifier | An icon that could mean "settings," "tools," or "preferences" | User must guess, increasing error rate |
90
+ | Conflicting signifier | A red button labeled "Continue" | Color schema says "stop/danger" but label says "proceed" |
91
+
92
+ ### 1.6 Jakob's Law: Users Spend Most of Their Time on Other Sites
93
+
94
+ Jakob Nielsen formulated this law based on decades of usability research at NNG:
95
+
96
+ > "Users spend most of their time on other sites. This means that users prefer your site to work the same way as all the other sites they already know."
97
+
98
+ This is the single most important implication of mental models for digital product design. Users do not arrive at your product with a blank slate. They arrive with mental models built from hundreds of other products. Their expectations about how navigation works, where the search bar lives, what a hamburger icon means, how checkout flows proceed — all of this is pre-loaded.
99
+
100
+ **Jakob's Law does not mean:**
101
+ - Every site must look identical
102
+ - Innovation is forbidden
103
+ - Visual design cannot be distinctive
104
+
105
+ **Jakob's Law does mean:**
106
+ - Core interaction patterns should follow established conventions
107
+ - Deviations from convention must earn their keep through measurably superior usability
108
+ - The burden of proof is on the designer who breaks a convention, not on the user who expects it
109
+
110
+ ### 1.7 Learned Conventions and Transfer Effects
111
+
112
+ **Learned Conventions**
113
+ Through repeated exposure, users internalize interaction patterns as "how things work." These become automatic behaviors — users execute them without conscious thought:
114
+
115
+ - Clicking a logo navigates to the homepage
116
+ - Pulling down on a mobile feed refreshes content
117
+ - Swiping left on a list item reveals delete/archive actions
118
+ - Ctrl/Cmd+Z undoes the last action
119
+ - The close button (X) is in the top-right corner of a dialog
120
+ - A shopping cart icon in the header shows items and links to checkout
121
+
122
+ These conventions form through years of consistent exposure across platforms. They become nearly as automatic as physical motor skills.
123
+
124
+ **Positive Transfer**
125
+ When a user's prior experience with one system helps them use a new system. Positive transfer accelerates learning and reduces errors.
126
+ - A user who knows Gmail can quickly learn Outlook because the conceptual model (inbox, compose, send, reply, folders/labels) transfers directly.
127
+ - A user familiar with pinch-to-zoom on one app expects it everywhere on touch devices.
128
+
129
+ **Negative Transfer**
130
+ When prior experience interferes with using a new system because the new system contradicts established patterns. Negative transfer causes errors, frustration, and abandonment.
131
+ - An app that uses swipe-right to delete (when users have learned swipe-left to delete from other apps) causes negative transfer.
132
+ - A form where Tab moves to the submit button instead of the next field breaks the form-navigation schema.
133
+ - Software that uses Ctrl+S to "share" instead of "save" hijacks a deeply ingrained convention.
134
+
135
+ **Key research finding (Smashing Magazine, 2012):** Users who encounter unfamiliar interaction patterns show a measurable increase in task abandonment rates. Even minor deviations from learned conventions — if they go unnoticed by the user — can cause persistent errors because the user's trained behavior masks the new pattern and inhibits learning.
136
+
137
+ ---
138
+
139
+ ## 2. Design Implications: 15 Rules for Mental Model Alignment
140
+
141
+ Each rule follows the structure: Principle, Rule, Concrete Example.
142
+
143
+ ### Rule 1: Follow Established Navigation Patterns
144
+
145
+ **Principle:** Users have a deeply ingrained schema for website navigation based on thousands of prior interactions. Primary navigation belongs at the top (horizontal) or left (vertical). Mobile navigation uses bottom tab bars or hamburger menus.
146
+
147
+ **Rule:** Place primary navigation in the location users expect for your platform. Do not invent novel navigation placement unless user testing proves it outperforms the standard.
148
+
149
+ **Example:** A SaaS dashboard that places its main navigation in the bottom-right corner as a floating radial menu. Users spend 40% longer finding basic features compared to a standard left sidebar. The "innovative" navigation is abandoned in the next sprint.
150
+
151
+ ### Rule 2: Use Universally Recognized Icons
152
+
153
+ **Principle:** Certain icons have achieved near-universal recognition through decades of consistent usage. Deviating from these established icon-meaning pairs forces users into a recall task instead of a recognition task, increasing cognitive load.
154
+
155
+ **Rule:** Use standard icons for standard functions. Always pair ambiguous icons with text labels. Never repurpose a widely recognized icon for a different function.
156
+
157
+ **Example:** The magnifying glass means "search." The gear/cog means "settings." The house means "home." The envelope means "email/messages." A product that uses a magnifying glass icon to mean "zoom" (not search) violates the dominant schema and confuses users.
158
+
159
+ ### Rule 3: Match Expectations from Comparable Products
160
+
161
+ **Principle:** Jakob's Law — users bring mental models from competitor products and similar applications in the same domain. An e-commerce site is compared to Amazon and Shopify stores. A project management tool is compared to Trello, Asana, and Jira.
162
+
163
+ **Rule:** Study the dominant products in your category. Identify shared conventions (layout, terminology, flow structure). Adopt these conventions as your baseline, then differentiate through content, quality, and secondary interactions.
164
+
165
+ **Example:** A new email client that puts "Compose" at the bottom-right of the screen (matching Gmail, Outlook, and Apple Mail) versus one that hides "Compose" inside a three-dot overflow menu. The former aligns with mental models; the latter forces users to hunt for the primary action.
166
+
167
+ ### Rule 4: Maintain Internal Consistency
168
+
169
+ **Principle:** Beyond matching external conventions, a product must be consistent with itself. If tapping a card in one section opens a detail view, tapping a card in another section should not open an edit dialog. Internal inconsistency creates competing mental models within the same product.
170
+
171
+ **Rule:** Establish an internal interaction pattern vocabulary (documented in a design system) and enforce it across every screen. Same component, same behavior, every time.
172
+
173
+ **Example:** A dashboard where clicking a metric card on the "Overview" page opens a chart, but clicking a metric card on the "Analytics" page opens a filter panel. Users learn the first pattern and carry the wrong expectation to the second.
174
+
175
+ ### Rule 5: Provide Clear Signifiers for All Interactive Elements
176
+
177
+ **Principle:** Norman's signifier concept — users must be able to perceive what is clickable, tappable, draggable, or scrollable without guessing. The trend toward flat design has stripped away many traditional signifiers (shadows, bevels, underlines), often at the cost of discoverability.
178
+
179
+ **Rule:** Every interactive element must have at least one perceivable signifier: color differentiation, underline, cursor change on hover, elevation/shadow, or explicit labeling. Test with the "screenshot test" — if a static screenshot does not reveal what is interactive, the signifiers are insufficient.
180
+
181
+ **Example:** Ghost buttons (transparent background, thin border) on a white background. Users in testing often fail to identify them as buttons. Adding a subtle fill color or increasing border weight restores the signifier.
182
+
183
+ ### Rule 6: Use Metaphors Users Already Understand
184
+
185
+ **Principle:** Interface metaphors leverage users' existing knowledge of the physical world or other digital experiences. The desktop metaphor (files, folders, trash can), the shopping cart metaphor, the notebook metaphor — these succeed because users already have rich schemas for the source domain.
186
+
187
+ **Rule:** Choose metaphors that accurately map to the system's behavior. Extend metaphors only where the extension is intuitive. Abandon metaphors where they mislead (if "deleting" from the "trash" actually means permanent deletion, the recoverability implied by a physical trash can is misleading).
188
+
189
+ **Example:** Apple's original Notes app used a skeuomorphic yellow legal pad. The metaphor worked: users understood they could write, tear off (delete), and the content was casual/personal. When Notes gained features like folders, sharing, and collaboration, the legal-pad metaphor broke down — legal pads do not have those affordances — and Apple rightly moved to a more abstract design.
190
+
191
+ ### Rule 7: Avoid Innovation for Innovation's Sake
192
+
193
+ **Principle:** Novel interactions must deliver measurable value to justify the learning cost they impose. The dopamine hit users get from recognizing familiar patterns (schema confirmation) is replaced by cognitive friction when patterns are unfamiliar.
194
+
195
+ **Rule:** Before introducing a non-standard interaction, answer: "What does this do better than the established pattern, and is the improvement large enough to justify the relearning cost?" If the answer is unclear, use the established pattern.
196
+
197
+ **Example:** A banking app that replaces the standard number pad for amount entry with a slider. The slider is "innovative" but imprecise for financial transactions. Users cannot enter exact amounts efficiently. The standard number pad, while unremarkable, is faster and more accurate.
198
+
199
+ ### Rule 8: Preserve Spatial Consistency Across States
200
+
201
+ **Principle:** Users build spatial mental models of where elements live on a page. Moving elements between states (loading, empty, populated, error) breaks spatial memory and forces users to re-scan.
202
+
203
+ **Rule:** Keep key elements (navigation, primary actions, search) in fixed positions across all application states. Content areas can change; chrome and controls should not.
204
+
205
+ **Example:** A form where the "Submit" button jumps from the bottom-right to the center when validation errors appear, because the error messages push the layout. Users who have already located the button must search for it again.
206
+
207
+ ### Rule 9: Use Progressive Disclosure for Complexity
208
+
209
+ **Principle:** Users' initial mental models of a system are simple. Presenting all functionality at once overwhelms the model-building process. Progressive disclosure matches the pace of information delivery to the pace of model construction.
210
+
211
+ **Rule:** Show essential features and controls by default. Reveal advanced options through deliberate user action (expandable sections, "Advanced" links, secondary menus). Label the disclosure triggers clearly so users know more options exist.
212
+
213
+ **Example:** A search interface that shows a simple search bar by default, with an "Advanced Filters" link that expands to reveal date ranges, categories, and boolean operators. New users are not overwhelmed; power users can access full functionality.
214
+
215
+ ### Rule 10: Make System State Visible and Interpretable
216
+
217
+ **Principle:** Norman's gulf of evaluation — users must be able to determine the current state of the system. When system state is hidden, users' mental models drift from reality, leading to errors.
218
+
219
+ **Rule:** Provide continuous, real-time feedback on system state. Use progress indicators for processes, status badges for objects, and explicit state labels for modes. Never leave the user wondering "Did it work?" or "What mode am I in?"
220
+
221
+ **Example:** A file upload component that shows no progress bar, no percentage, and no indication of success or failure. Users click "Upload" repeatedly because they cannot evaluate whether the first click worked. Adding a progress bar and a success checkmark eliminates the confusion.
222
+
223
+ ### Rule 11: Match Terminology to User Language
224
+
225
+ **Principle:** Users have mental models for domain vocabulary. Technical jargon, internal codenames, and implementation-level terms break these models. Nielsen's heuristic: "Match between system and the real world."
226
+
227
+ **Rule:** Use the same terminology your users use. Conduct card sorting or user interviews to discover natural-language labels. If your system calls something a "workspace" but users call it a "project," use "project."
228
+
229
+ **Example:** A CMS that labels its content organization feature "Taxonomies." Content creators and marketers (the primary users) do not use this word. They expect "Categories" or "Tags." Changing the label to "Categories & Tags" aligns with user vocabulary and eliminates support tickets.
230
+
231
+ ### Rule 12: Provide Undo and Reversibility
232
+
233
+ **Principle:** When users can reverse actions, they explore more confidently because their mental model includes a safety net. Without undo, users hesitate, fearing permanent consequences.
234
+
235
+ **Rule:** Make destructive actions reversible wherever possible. For truly irreversible actions, require explicit confirmation with clear language about consequences. Design the undo mechanism to match the user's model of undoing (Ctrl+Z, "Undo" toast notification, trash/archive with restore).
236
+
237
+ **Example:** Gmail's "Undo Send" toast that appears for 5-30 seconds after sending an email. It matches the mental model of "I just realized I made a mistake" and provides a brief window of reversibility. Contrast with an email system where "Send" is immediate and permanent — users send test emails to themselves first, adding friction.
238
+
239
+ ### Rule 13: Handle Errors in Terms of User Goals
240
+
241
+ **Principle:** Error messages written from the system's perspective ("Error 500: Internal Server Error," "NullPointerException at line 247") expose the implementation model. Users' mental models operate at the goal level: they want to complete a task, not debug code.
242
+
243
+ **Rule:** Write error messages that (1) say what happened in user terms, (2) explain why, and (3) tell the user what to do next. Never expose stack traces, error codes, or system internals in the primary interface.
244
+
245
+ **Example:** Instead of "422 Unprocessable Entity," display: "We could not save your changes because the email address format is not valid. Please check the email field and try again." The user's mental model is "I'm trying to save my profile," not "I'm sending a PATCH request to an API endpoint."
246
+
247
+ ### Rule 14: Respect Platform-Specific Conventions
248
+
249
+ **Principle:** Users build separate mental models for each platform. iOS users expect tab bars at the bottom, swipe-to-go-back gestures, and action sheets sliding up from the bottom. Android users expect a top app bar, a floating action button (FAB), and Material Design motion patterns.
250
+
251
+ **Rule:** Follow the human interface guidelines for each platform (Apple HIG, Material Design 3). Do not impose one platform's conventions on another. If building cross-platform, adapt navigation and interaction patterns per platform, not just visual styling.
252
+
253
+ **Example:** An Android app that uses iOS-style bottom sheets for every confirmation dialog instead of Material Design's AlertDialog. Android users find the bottom sheets unfamiliar for simple yes/no confirmations, slowing their response time.
254
+
255
+ ### Rule 15: Signal Mode Changes Explicitly
256
+
257
+ **Principle:** Modes are states where the same action produces different results (e.g., "edit mode" vs. "view mode," "selection mode" vs. "navigation mode"). If users do not realize they have entered a mode, their mental model of what actions will do is wrong.
258
+
259
+ **Rule:** Make mode changes visually obvious. Use distinct color schemes, prominent labels ("Editing"), or structural changes to signal the mode. Provide a clear, obvious way to exit the mode.
260
+
261
+ **Example:** A photo editor where tapping "Select" enters selection mode, but the only visual difference is a barely visible blue tint on the toolbar. Users tap on photos expecting to open them (navigation mode behavior) but instead select them (selection mode behavior). A prominent "X items selected" banner with a "Cancel" button makes the mode unmistakable.
262
+
263
+ ---
264
+
265
+ ## 3. Measurement: Detecting Mental Model Violations
266
+
267
+ ### 3.1 First-Click Testing
268
+
269
+ **What it measures:** Whether users' initial instinct for where to click/tap aligns with the correct action path. First-click accuracy is the strongest single predictor of task success — users who click correctly on the first try complete tasks successfully 87% of the time, versus 46% for those who click incorrectly first (UIE research).
270
+
271
+ **How to run it:**
272
+ 1. Present a static screenshot or wireframe of the interface
273
+ 2. Give participants a task: "Where would you click to change your password?"
274
+ 3. Record the coordinates of their first click
275
+ 4. Aggregate click data into a heatmap
276
+
277
+ **Mental model signals:**
278
+ - Clustered clicks on the correct target = mental model alignment
279
+ - Scattered clicks across the interface = no clear mental model for this task
280
+ - Clustered clicks on the wrong target = systematic mental model mismatch (the most actionable finding — users share a consistent but incorrect model)
281
+
282
+ **Tools:** Optimal Workshop Chalkmark, Maze, UsabilityHub (Lyssna), Figma prototype click tracking.
283
+
284
+ ### 3.2 Card Sorting
285
+
286
+ **What it measures:** How users mentally categorize and group information. Card sorting reveals users' internal taxonomy — their mental model of information architecture.
287
+
288
+ **Types:**
289
+ - **Open card sort**: Users group labeled cards into categories they create and name themselves. Best for generative research when building a new IA.
290
+ - **Closed card sort**: Users sort cards into pre-defined categories. Best for evaluating whether a proposed IA matches user expectations.
291
+ - **Hybrid card sort**: Users sort into pre-defined categories but can also create new ones.
292
+
293
+ **Mental model signals:**
294
+ - High agreement across participants on groupings = strong shared mental model
295
+ - A card consistently placed in "wrong" category = label or concept mismatch
296
+ - A card that participants place in multiple different categories = ambiguous concept that needs clearer labeling or restructuring
297
+ - Category names users create (in open sorts) that differ from your labels = terminology mismatch
298
+
299
+ **Tools:** Optimal Workshop OptimalSort, UXtweak, UserZoom, Maze.
300
+
301
+ ### 3.3 Tree Testing
302
+
303
+ **What it measures:** Whether users can find information within a proposed navigation hierarchy. Tree testing strips away visual design to test the information architecture in isolation.
304
+
305
+ **How to run it:**
306
+ 1. Build a text-only hierarchy of your navigation structure
307
+ 2. Give participants tasks: "Find the page where you would update your billing address"
308
+ 3. Participants click through the text tree to find the answer
309
+ 4. Measure success rate, directness (did they backtrack?), and time to completion
310
+
311
+ **Mental model signals:**
312
+ - High success + high directness = IA matches mental models
313
+ - High success + low directness = users find it eventually but the path is not intuitive (the IA is "findable but not guessable")
314
+ - Low success on specific tasks = fundamental category mismatch for that content
315
+ - Users consistently choosing the same wrong first branch = that category label activates the wrong schema
316
+
317
+ **Tools:** Optimal Workshop Treejack, UXtweak Tree Testing, Maze.
318
+
319
+ ### 3.4 User Confusion Signals in Usability Testing
320
+
321
+ During moderated or unmoderated usability testing, the following observable behaviors indicate mental model violations:
322
+
323
+ | Signal | What It Indicates | Example |
324
+ |---|---|---|
325
+ | **Rage clicks** | User believes an element is interactive but it does not respond | Clicking a card header that looks like a link but is plain text |
326
+ | **Back-button confusion** | User's spatial model does not match navigation structure | Opening a full-screen overlay, pressing Back, and being taken to the previous page instead of closing the overlay |
327
+ | **Repeated scanning** | User is searching for an element they expect to exist in a specific location | Eyes darting to the top-right corner looking for "Log Out" that is buried in a dropdown |
328
+ | **Verbal expressions** | User narrates confusion during think-aloud protocol | "I thought this would..." / "Why did it..." / "Where is the..." |
329
+ | **Wrong-tool errors** | User uses the wrong feature because it resembles the correct one | Using a global search when they needed a page-level filter, because both have search-bar signifiers |
330
+ | **Premature task abandonment** | User gives up before completing the task | "I can't figure out how to do this" — strongest signal of model failure |
331
+ | **Excessive help-seeking** | User looks for documentation, tooltips, or asks the moderator | Indicates the interface is not self-explanatory for this task |
332
+
333
+ ### 3.5 Expectation Mapping
334
+
335
+ **What it measures:** The gap between what users expect to happen and what actually happens, measured systematically.
336
+
337
+ **How to run it:**
338
+ 1. Before showing the interface, ask users: "What would you expect to see on a [type] page?" or "How would you expect [task] to work?"
339
+ 2. Document their predictions (expected layout, expected steps, expected terminology)
340
+ 3. Have them use the actual interface
341
+ 4. After the task, ask: "Was anything different from what you expected?"
342
+ 5. Map expectations against reality to find systematic gaps
343
+
344
+ **Mental model signals:**
345
+ - Expectations that match reality = model alignment (no action needed)
346
+ - Expectations that differ from reality but users adapt quickly = minor gap (monitor but not urgent)
347
+ - Expectations that differ from reality and cause errors = critical gap (redesign needed)
348
+ - Expectations that are consistent across many users but differ from the design = the design is wrong, not the users
349
+
350
+ ### 3.6 Quantitative Metrics for Model Alignment
351
+
352
+ Beyond qualitative methods, these metrics indicate mental model alignment at scale:
353
+
354
+ - **Task success rate**: Percentage of users who complete a task without assistance. Below 78% (industry benchmark per MeasuringU) indicates potential model mismatch.
355
+ - **Time on task**: Significantly longer than expected completion time suggests users are struggling with an unfamiliar model.
356
+ - **Error rate**: Frequency of incorrect actions per task. Systematic errors (many users making the same mistake) indicate a shared incorrect mental model.
357
+ - **Navigation path efficiency**: Actual clicks divided by optimal clicks. A ratio above 2.0 suggests users' mental model of the IA does not match the actual structure.
358
+ - **SUS (System Usability Scale) score**: Below 68 (the average) correlates with usability issues often rooted in model mismatches.
359
+ - **First-click accuracy**: As noted above, correlates strongly with overall task success.
360
+
361
+ ---
362
+
363
+ ## 4. Dark Patterns Warning: Exploiting Mental Models
364
+
365
+ Dark patterns (also called "deceptive patterns") deliberately exploit users' mental models and learned conventions to manipulate behavior in ways that benefit the business at the user's expense. The FTC has formally defined dark patterns as "design practices that trick or manipulate users into making choices they would not otherwise have made and that may cause harm."
366
+
367
+ ### 4.1 How Dark Patterns Exploit Mental Models
368
+
369
+ Dark patterns work because users rely on mental models — they act on autopilot based on learned conventions. Deceptive patterns weaponize this trust:
370
+
371
+ **Schema Hijacking**
372
+ The pattern mimics a familiar, trusted interaction but redirects the outcome. Users' learned behavior (e.g., "the prominent button is the correct next step") is used against them.
373
+
374
+ **Autopilot Exploitation**
375
+ Users process familiar interfaces with System 1 thinking (fast, automatic, heuristic-based). Dark patterns are designed to pass System 1 inspection while hiding their true intent from System 2 (slow, deliberate) analysis.
376
+
377
+ **Convention Violation for Profit**
378
+ Breaking a convention strategically so that the "mistake" users make benefits the company. Moving the "Decline" button to where "Accept" usually is.
379
+
380
+ ### 4.2 Taxonomy of Mental-Model-Based Dark Patterns
381
+
382
+ **Bait and Switch**
383
+ Users expect one outcome based on established patterns but receive a different one. A dialog asks "Do you want to update Windows?" with a close (X) button. Clicking X — which users' mental model says means "dismiss/cancel" — instead initiates the update. Microsoft deployed this exact pattern in 2016, generating widespread backlash.
384
+
385
+ **Misdirection**
386
+ Using visual hierarchy and design conventions to draw attention toward a desired action and away from the alternative. Subscription cancellation pages where "Keep my subscription" is a large, brightly colored button and "Cancel subscription" is a small, gray text link below the fold. This exploits the learned convention that the primary CTA is the action the user wants.
387
+
388
+ **Confirmshaming**
389
+ Framing the decline option in emotionally manipulative language to exploit the mental model that buttons describe neutral actions. "No thanks, I don't want to save money" instead of simply "Decline" or "No thanks." This exploits the user's expectation of neutral, descriptive button labels.
390
+
391
+ **Roach Motel (Easy In, Hard Out)**
392
+ Making sign-up follow the standard, friction-free mental model (one-click, minimal steps) while making cancellation deviate from all conventions (multi-page flow, phone call required, hidden link). Amazon's Prime cancellation flow was the subject of a $25 billion FTC action in 2025.
393
+
394
+ **Trick Questions**
395
+ Using double negatives or confusing phrasing in checkboxes: "Uncheck this box if you prefer not to not receive emails." This exploits the user's mental model that checkboxes use straightforward affirmative language ("Check to receive emails").
396
+
397
+ **Disguised Ads**
398
+ Making advertisements visually identical to content or navigation elements. "Download" buttons on software sites that are actually ads. This hijacks the signifier schema — users interpret any element styled as a button with relevant text as a genuine interface control.
399
+
400
+ **Forced Continuity**
401
+ Free trial flows that match the user's mental model for "free" (no commitment) but silently store payment information and begin charging when the trial expires, with no warning and no easy cancellation path.
402
+
403
+ **Hidden Costs**
404
+ Displaying a price throughout the shopping flow, then adding fees (service charges, handling fees, "convenience" fees) only at the final checkout step, after the user has invested effort. This exploits the sunk-cost mental model — users are less likely to abandon after investing time.
405
+
406
+ ### 4.3 Ethical Boundaries
407
+
408
+ The ethical line is clear: **designs that rely on users misunderstanding what will happen are deceptive, regardless of intent.**
409
+
410
+ **Regulatory landscape (as of 2026):**
411
+ - The FTC Act, Section 5 prohibits unfair or deceptive practices, explicitly encompassing dark patterns
412
+ - California Privacy Rights Act (CPRA), Colorado Privacy Act (CPA), and Connecticut Data Privacy Act exclude consent obtained through dark patterns from valid consent
413
+ - The EU's Digital Services Act (DSA) prohibits dark patterns that distort users' ability to make free and informed decisions
414
+ - The FTC's 2022 report, *Bringing Dark Patterns to Light*, established enforcement precedents
415
+
416
+ **Design ethics principles:**
417
+ 1. Never use design conventions to misdirect users toward actions they did not intend
418
+ 2. Present options with equal visual weight when the choice is genuinely the user's
419
+ 3. Make cancellation, opt-out, and unsubscribe flows as easy as sign-up and opt-in
420
+ 4. Label buttons and actions with neutral, accurate descriptions of what will happen
421
+ 5. Disclose all costs, commitments, and consequences before asking for user action
422
+
423
+ ---
424
+
425
+ ## 5. Platform-Specific Mental Model Considerations
426
+
427
+ ### 5.1 Mobile vs. Desktop Mental Models
428
+
429
+ Users carry fundamentally different expectations and interaction models depending on the device:
430
+
431
+ | Dimension | Desktop Mental Model | Mobile Mental Model |
432
+ |---|---|---|
433
+ | **Input method** | Precise cursor, keyboard shortcuts, right-click context menus | Touch (imprecise), gestures (swipe, pinch, long-press), on-screen keyboard |
434
+ | **Navigation** | Tabs, sidebars, breadcrumbs, URL bar | Bottom tab bars, hamburger menus, swipe gestures, back button/gesture |
435
+ | **Content density** | Users expect information-dense layouts with multiple columns | Users expect focused, single-column, scrollable content |
436
+ | **Task scope** | Deep, complex tasks (spreadsheets, document editing, multi-step workflows) | Quick, focused tasks (checking notifications, sending a message, looking up an address) |
437
+ | **Performance expectation** | Pages should load within 5 seconds | Pages should load within 3 seconds (Google research) |
438
+ | **Session behavior** | Longer sessions, multiple tabs open, alt-tab switching | Short, frequent sessions, single-app focus, interrupted by notifications |
439
+
440
+ **Critical design implications:**
441
+ - Do not simply shrink a desktop interface for mobile. Users' mental models for what a mobile experience should be are distinct.
442
+ - Mobile users expect gesture-based shortcuts (pull-to-refresh, swipe-to-dismiss) that have no desktop equivalent.
443
+ - Desktop users expect hover states, tooltips, and right-click menus that have no touch equivalent.
444
+ - Responsive design must adapt interaction models, not just layout.
445
+
446
+ ### 5.2 Web vs. Native App Expectations
447
+
448
+ Users maintain separate mental models for "a website I visit in a browser" and "an app I installed on my device":
449
+
450
+ **Web Mental Model:**
451
+ - Content is transient — I might not return to this exact page
452
+ - I navigate with the browser's back button and can see the URL
453
+ - I expect pages to load (network-dependent)
454
+ - I do not expect offline access
455
+ - I expect consistent cross-platform behavior (same site on any device)
456
+ - I am cautious about permissions (notifications, location, camera)
457
+
458
+ **Native App Mental Model:**
459
+ - The app is persistent — it retains my data and state
460
+ - I navigate with in-app controls and platform gestures
461
+ - I expect instant, fluid transitions (no page loads)
462
+ - I expect some offline functionality
463
+ - I expect the app to follow my platform's design language (HIG or Material Design)
464
+ - I am more willing to grant permissions (I chose to install this)
465
+
466
+ **Hybrid app danger zone:**
467
+ Apps built with web technologies (React Native, Flutter, Capacitor) that do not adopt native conventions create a mental model uncanny valley. The app "feels wrong" without users being able to articulate why. Common violations:
468
+ - Using web-style navigation (breadcrumbs, browser-like back arrows) inside a native app
469
+ - Page transitions that feel like browser loads instead of native animations
470
+ - Inputs that do not use the platform's native keyboard, date picker, or action sheets
471
+ - Ignoring platform-specific gestures (swipe-to-go-back on iOS, hardware back on Android)
472
+
473
+ ### 5.3 iOS vs. Android Mental Models
474
+
475
+ Despite convergence in recent years, users of each platform carry distinct mental models:
476
+
477
+ **iOS Users Expect:**
478
+ - Bottom tab bar for primary navigation (up to 5 tabs)
479
+ - Swipe from left edge to go back
480
+ - Action sheets and share sheets sliding up from the bottom
481
+ - Title in the center of the navigation bar
482
+ - Pull-to-refresh on scrollable content
483
+ - Smooth, physics-based animations (spring dynamics)
484
+ - System-level haptic feedback for confirmations
485
+
486
+ **Android Users Expect:**
487
+ - Top app bar with hamburger menu or back arrow
488
+ - Floating Action Button (FAB) for the primary action
489
+ - Navigation drawer sliding in from the left
490
+ - Title aligned left in the app bar
491
+ - Material Design motion (emphasis on meaningful transitions)
492
+ - Bottom navigation bar (Material Design 3) for 3-5 primary destinations
493
+ - Hardware/gesture back button that is universally available
494
+
495
+ **Cross-platform pitfall:** Applying iOS patterns on Android (or vice versa) triggers negative transfer. Android users presented with an iOS-style tab bar at the bottom may expect it to behave like Android's bottom navigation (which has slightly different interaction rules around re-selection and scroll-to-top behavior).
496
+
497
+ ### 5.4 Generational Differences in Mental Models
498
+
499
+ Different age cohorts have formed mental models based on different foundational technologies:
500
+
501
+ **Digital Natives (Born After ~1995)**
502
+ - Touchscreen-first mental model: expect swipe, pinch, tap as primary interactions
503
+ - Social media paradigm: expect feeds, likes, comments, sharing as core patterns
504
+ - Expect instant feedback and real-time updates
505
+ - Comfortable with ephemeral content (Stories, disappearing messages)
506
+ - Strong gesture vocabulary — rarely need explicit button signifiers for common actions
507
+ - Expect personalization and algorithmic curation
508
+
509
+ **Digital Immigrants (Born ~1965-1995)**
510
+ - Desktop-first mental model: mouse, keyboard, file system hierarchy
511
+ - Email and web paradigm: expect links, pages, folders as organizational metaphors
512
+ - Comfortable with both desktop and mobile but learned desktop patterns first
513
+ - Expect explicit navigation (menus, breadcrumbs) over gesture-based discovery
514
+ - Prefer persistent content over ephemeral
515
+ - Accept some learning curve for new tools
516
+
517
+ **Late Adopters (Born Before ~1965)**
518
+ - Physical-world mental models dominate: expect digital interfaces to map to physical analogies
519
+ - Prefer explicit, labeled buttons over icons alone
520
+ - May not have internalized gesture conventions (long-press, swipe)
521
+ - Higher anxiety about irreversible actions — need stronger confirmation dialogs and undo capabilities
522
+ - Expect linear, step-by-step flows rather than non-linear exploration
523
+ - Struggle with flat design that lacks clear signifiers (need stronger visual hierarchy)
524
+
525
+ **Design implication:** Know your audience. A productivity tool for enterprise users (30-55 age range) should not rely on gesture-only interactions. A social app for Gen Z should not force desktop-era interaction patterns. Universal accessibility requires accommodating the widest range of mental models through progressive enhancement: clear signifiers for those who need them, gesture shortcuts for those who expect them.
526
+
527
+ ### 5.5 Cultural Mental Model Differences
528
+
529
+ Mental models are also shaped by cultural context:
530
+
531
+ - **Reading direction**: LTR vs. RTL cultures have mirrored spatial expectations for progress, navigation flow, and visual hierarchy
532
+ - **Color meaning**: Red means "danger" or "stop" in Western cultures but means "luck" and "prosperity" in Chinese culture. Green means "go" in the West but may signal different concepts elsewhere.
533
+ - **Icon interpretation**: A mailbox icon may not resonate in cultures where physical mailboxes are not common. A floppy disk as a "save" icon is meaningless to users who have never seen one (increasingly common across all cultures).
534
+ - **Form expectations**: Name fields — Western users expect "First Name / Last Name" but many cultures use a single name, family-name-first ordering, or have naming conventions that do not fit this schema.
535
+ - **Trust signals**: What signals credibility varies by culture — certain color schemes, certifications, or social proof mechanisms carry different weight.
536
+
537
+ ---
538
+
539
+ ## 6. Quick Reference Checklist
540
+
541
+ Use this checklist during design reviews to verify mental model alignment:
542
+
543
+ ### Information Architecture
544
+ - [ ] Navigation placement follows platform conventions (top/left for desktop, bottom tabs for mobile)
545
+ - [ ] Labels use user language, not internal jargon (validated via card sort or user interviews)
546
+ - [ ] Content groupings match how users mentally categorize the information (validated via card sort)
547
+ - [ ] Key content is findable within 3 clicks/taps from the entry point (validated via tree test)
548
+
549
+ ### Interaction Patterns
550
+ - [ ] All interactive elements have clear signifiers (pass the screenshot test)
551
+ - [ ] Standard icons are used for standard functions (search, settings, home, back, close, share)
552
+ - [ ] Ambiguous icons include text labels
553
+ - [ ] Core flows match competitor/industry conventions (Jakob's Law compliance)
554
+ - [ ] Internal patterns are consistent — same component, same behavior, everywhere
555
+ - [ ] Destructive actions are reversible (undo) or require explicit confirmation
556
+ - [ ] Mode changes are visually obvious with clear exit mechanisms
557
+
558
+ ### Feedback & System State
559
+ - [ ] Every user action produces visible feedback within 100ms
560
+ - [ ] System state is always visible (loading, empty, error, success states designed)
561
+ - [ ] Progress indicators are used for operations longer than 1 second
562
+ - [ ] Error messages use user-goal language, not system/technical language
563
+ - [ ] Success confirmations are explicit (not just absence of error)
564
+
565
+ ### Platform Compliance
566
+ - [ ] Mobile: touch targets meet minimum size (44x44pt iOS / 48x48dp Android)
567
+ - [ ] Mobile: gesture interactions follow platform conventions (swipe-back, pull-to-refresh)
568
+ - [ ] iOS: follows Apple Human Interface Guidelines for navigation, typography, and controls
569
+ - [ ] Android: follows Material Design 3 guidelines for components, motion, and layout
570
+ - [ ] Desktop: supports keyboard navigation and standard shortcuts (Ctrl+Z, Ctrl+S, Tab)
571
+ - [ ] Web: browser back button behavior is predictable and correct
572
+
573
+ ### Accessibility & Inclusivity
574
+ - [ ] Design does not rely solely on gestures that may not be in all users' mental models
575
+ - [ ] Icons paired with text labels for users who may not share the icon's cultural meaning
576
+ - [ ] Color alone does not convey meaning (accommodates colorblind users' mental models)
577
+ - [ ] Form fields use expected patterns (email fields show email keyboard, phone fields show number pad)
578
+ - [ ] Help and documentation are available but not required for primary tasks
579
+
580
+ ### Dark Pattern Avoidance
581
+ - [ ] Opt-out is as easy as opt-in
582
+ - [ ] Cancellation flow has the same friction level as sign-up flow
583
+ - [ ] Button labels accurately describe what will happen (no confirmshaming)
584
+ - [ ] All costs and commitments are disclosed before the action point
585
+ - [ ] Primary and secondary actions have appropriate (not manipulative) visual weight
586
+ - [ ] No learned conventions are exploited to misdirect users
587
+
588
+ ### Research & Validation
589
+ - [ ] First-click test conducted on key task entry points
590
+ - [ ] Card sort conducted for information architecture decisions
591
+ - [ ] Tree test conducted on proposed navigation structure
592
+ - [ ] Usability test includes observation for confusion signals (rage clicks, verbal frustration, premature abandonment)
593
+ - [ ] Expectation mapping conducted for novel or non-standard interactions
594
+ - [ ] Task success rate, time on task, and error rate tracked for critical flows
595
+
596
+ ---
597
+
598
+ ## 7. Key References
599
+
600
+ ### Books
601
+ - **Norman, Don.** *The Design of Everyday Things* (1988, revised 2013). The foundational text on affordances, signifiers, conceptual models, and the gulfs of execution and evaluation.
602
+ - **Norman, Don.** *Emotional Design: Why We Love (or Hate) Everyday Things* (2004). Extends mental model theory into emotional responses to design.
603
+ - **Nielsen, Jakob.** *Usability Engineering* (1993). Establishes usability heuristics and the research-driven approach to matching user expectations.
604
+ - **Cooper, Alan.** *About Face: The Essentials of Interaction Design* (4th ed., 2014). Implementation models vs. user mental models, persona-driven design.
605
+ - **Yablonski, Jon.** *Laws of UX* (2020). Codifies Jakob's Law and other psychology-based design laws with practical examples.
606
+ - **Johnson, Jeff.** *Designing with the Mind in Mind* (3rd ed., 2020). Cognitive psychology principles applied directly to UI design.
607
+ - **Krug, Steve.** *Don't Make Me Think* (3rd ed., 2014). The practical implications of users' expectation-driven, scan-and-click behavior.
608
+
609
+ ### Articles & Research
610
+ - **Nielsen Norman Group.** "Mental Models and User Experience Design." Defines mental models in the UX context and explains their impact on design decisions. (nngroup.com/articles/mental-models/)
611
+ - **Nielsen Norman Group.** "Jakob's Law of Internet User Experience." The original articulation of why users expect consistency across sites. (nngroup.com/articles/end-of-web-design/)
612
+ - **Nielsen Norman Group.** "The Two UX Gulfs: Evaluation and Execution." Detailed treatment of Norman's gulf framework. (nngroup.com/articles/two-ux-gulfs-evaluation-execution/)
613
+ - **Nielsen Norman Group.** "Card Sorting: Uncover Users' Mental Models." Methodology guide for card sorting research. (nngroup.com/articles/card-sorting-definition/)
614
+ - **Nielsen Norman Group.** "Deceptive Patterns in UX: How to Recognize and Avoid Them." Taxonomy of dark patterns with examples. (nngroup.com/articles/deceptive-patterns/)
615
+ - **FTC.** "Bringing Dark Patterns to Light" (2022). Regulatory report on deceptive design practices. (ftc.gov/reports/bringing-dark-patterns-light)
616
+ - **Interaction Design Foundation.** "What are Affordances?" Comprehensive treatment of affordance theory in UX. (interaction-design.org/literature/topics/affordances)
617
+ - **Laws of UX.** "Jakob's Law." Concise definition with visual examples. (lawsofux.com/jakobs-law/)
618
+
619
+ ### Standards & Guidelines
620
+ - **Apple Human Interface Guidelines** — Platform mental model conventions for iOS, iPadOS, macOS, watchOS, tvOS (developer.apple.com/design/human-interface-guidelines/)
621
+ - **Material Design 3** — Google's design system encoding Android platform conventions (m3.material.io)
622
+ - **WCAG 2.2** — Accessibility standards that intersect with mental model considerations around predictability and consistency (w3.org/WAI/WCAG22/quickref/)
623
+ - **Nielsen's 10 Usability Heuristics** — The heuristic framework that operationalizes mental model alignment (nngroup.com/articles/ten-usability-heuristics/)