@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,550 @@
1
+ # Responsive Web Design -- Platform Expertise Module
2
+
3
+ > Responsive web design ensures that web content adapts fluidly across all screen sizes and input
4
+ > modalities -- from 320px mobile screens to 4K desktop monitors. This module covers mobile-first
5
+ > strategy, modern CSS layout, component adaptation, fluid typography, responsive media,
6
+ > performance, and accessibility. The goal is universal access through progressive enhancement.
7
+
8
+ ---
9
+
10
+ ## 1. Platform Design Language
11
+
12
+ ### Web Design Philosophy
13
+
14
+ **Universal Access.** The web is the most accessible platform ever created. A responsive site
15
+ must work for everyone -- users on slow 3G with budget phones, power users with ultrawide
16
+ monitors, screen reader users, keyboard-only navigators, and users with motor impairments.
17
+
18
+ **Progressive Enhancement.** Start with the most basic technology layer and enhance upward:
19
+ 1. **Content layer** -- semantic HTML that works without CSS or JS
20
+ 2. **Presentation layer** -- CSS that adapts layout, typography, and spacing
21
+ 3. **Interaction layer** -- JavaScript that adds interactivity for capable browsers
22
+
23
+ Never gate critical content behind JavaScript. Forms should submit via native `<form>`.
24
+ Navigation should use `<a>` tags. Content should be readable with stylesheets disabled.
25
+
26
+ > Source: [Progressive Enhancement -- MDN](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement)
27
+
28
+ ### Mobile-First Approach
29
+
30
+ **Mobile-first is the standard.** Design and code for the smallest viewport first, then
31
+ enhance for larger screens using `min-width` media queries:
32
+
33
+ - Forces content prioritization -- if it does not fit on 320px, question whether it is needed
34
+ - Results in smaller CSS payloads for mobile (base styles are mobile, enhancements are additive)
35
+ - Aligns with traffic reality -- mobile accounts for over 60% of global web traffic
36
+ - Produces cleaner CSS -- adding complexity is easier than removing it
37
+
38
+ ```css
39
+ /* Base styles are for small screens */
40
+ .container { display: flex; flex-direction: column; padding: 1rem; }
41
+
42
+ @media (min-width: 768px) {
43
+ .container { flex-direction: row; padding: 2rem; }
44
+ }
45
+ @media (min-width: 1024px) {
46
+ .container { max-width: 1200px; margin-inline: auto; }
47
+ }
48
+ ```
49
+
50
+ **Desktop-first (`max-width`) is an anti-pattern** for new projects -- it produces bloated
51
+ CSS and frequent breakage on small screens.
52
+
53
+ > Source: [Responsive Web Design Basics -- web.dev](https://web.dev/articles/responsive-web-design-basics)
54
+
55
+ ### Content-First Breakpoints
56
+
57
+ Do not define breakpoints based on specific devices. Let content dictate breakpoints:
58
+ 1. Start at 320px
59
+ 2. Slowly expand the viewport
60
+ 3. When the layout looks awkward, add a breakpoint
61
+ 4. Repeat until you reach the widest layout
62
+
63
+ > Source: [Logical Breakpoints -- Smashing Magazine](https://www.smashingmagazine.com/2013/03/logical-breakpoints-responsive-design/)
64
+
65
+ ### Modern CSS Capabilities
66
+
67
+ **Container Queries (`@container`)** -- the most significant responsive advancement since
68
+ media queries. Style elements based on container size, not viewport:
69
+
70
+ ```css
71
+ .card-container { container-type: inline-size; }
72
+
73
+ @container (min-width: 400px) {
74
+ .card { display: grid; grid-template-columns: 200px 1fr; }
75
+ }
76
+ @container (max-width: 399px) {
77
+ .card { display: flex; flex-direction: column; }
78
+ }
79
+ ```
80
+
81
+ Use `@container` for component-level adaptation and `@media` for page-level layout.
82
+
83
+ > Source: [Container Queries: Netflix Case Study -- web.dev](https://web.dev/case-studies/netflix-cq),
84
+ > [CSS Container Queries -- CSS-Tricks](https://css-tricks.com/css-container-queries/)
85
+
86
+ **`:has()` Selector** -- parent-aware and content-aware styling without JavaScript:
87
+
88
+ ```css
89
+ .card:has(img) { display: grid; grid-template-columns: 250px 1fr; }
90
+ figure:has(figcaption) img { margin-bottom: 0.5rem; }
91
+ .grid:has(:nth-child(4)) { grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); }
92
+ ```
93
+
94
+ > Source: [New Front-End Features 2025 -- Smashing Magazine](https://www.smashingmagazine.com/2024/12/new-front-end-features-for-designers-in-2025/)
95
+
96
+ **CSS Subgrid** -- nested grid items participate in parent grid tracks, solving card alignment:
97
+
98
+ ```css
99
+ .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; }
100
+ .card { display: grid; grid-template-rows: subgrid; grid-row: span 3; }
101
+ ```
102
+
103
+ > Source: [Subgrid -- MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Subgrid)
104
+
105
+ **`clamp()`, `min()`, `max()`** -- fluid values without media queries:
106
+
107
+ ```css
108
+ .element { width: clamp(300px, 50%, 800px); font-size: clamp(1rem, 2.5vw, 2rem); }
109
+ ```
110
+
111
+ > Source: [CSS min(), max(), and clamp() -- web.dev](https://web.dev/articles/min-max-clamp)
112
+
113
+ ---
114
+
115
+ ## 2. Layout & Navigation Patterns
116
+
117
+ ### Responsive Breakpoints
118
+
119
+ | Token | Width | Target |
120
+ |---|---|---|
121
+ | `xs` | 320px | Small phones (iPhone SE) |
122
+ | `sm` | 480px | Large phones / landscape small phones |
123
+ | `md` | 768px | Tablets (portrait iPad) |
124
+ | `lg` | 1024px | Landscape tablets, small laptops |
125
+ | `xl` | 1280px | Standard desktop / laptop |
126
+ | `2xl` | 1440px | Large desktop monitors |
127
+ | `3xl` | 1920px | Full HD and ultrawide |
128
+
129
+ Use `em` units for breakpoints (e.g., `48em` = 768px) to respect user font-size preferences:
130
+
131
+ ```css
132
+ @media (min-width: 48em) { /* tablet */ }
133
+ @media (min-width: 64em) { /* desktop */ }
134
+ @media (min-width: 80em) { /* large */ }
135
+ ```
136
+
137
+ > Source: [CSS Media Queries Guide -- CSS-Tricks](https://css-tricks.com/a-complete-guide-to-css-media-queries/)
138
+
139
+ ### Navigation Patterns
140
+
141
+ **Mobile (< 768px):**
142
+ - **Hamburger menu** -- standard off-canvas slide-in for primary navigation
143
+ - **Bottom tab bar** -- preferred for high-frequency navigation (max 5 items). Research shows
144
+ bottom nav increases user sessions vs hamburger. Aligns with thumb-zone ergonomics
145
+ - **Priority+ pattern** -- show as many items as fit, overflow into "More" menu
146
+
147
+ **Tablet (768--1024px):**
148
+ - Horizontal top navigation with abbreviated labels or icons
149
+ - Collapsible sidebar that toggles open/closed
150
+
151
+ **Desktop (> 1024px):**
152
+ - Horizontal top navigation with full text labels
153
+ - Persistent sidebar for complex apps (dashboards, admin panels)
154
+ - Mega menus for content-rich sites with deep IA
155
+
156
+ > Source: [Bottom Navigation on Mobile Web -- Smashing Magazine](https://www.smashingmagazine.com/2019/08/bottom-navigation-pattern-mobile-web-pages/),
157
+ > [Mobile Navigation Patterns -- Smashing Magazine](https://www.smashingmagazine.com/2017/05/basic-patterns-mobile-navigation/)
158
+
159
+ ### Max Content Width & Grid Systems
160
+
161
+ ```css
162
+ .content-wrapper {
163
+ width: 100%;
164
+ max-width: 1200px; /* 1200-1440px standard */
165
+ margin-inline: auto;
166
+ padding-inline: clamp(1rem, 5vw, 3rem);
167
+ }
168
+ .prose { max-width: 65ch; margin-inline: auto; } /* 45-75 chars for readability */
169
+ ```
170
+
171
+ **Auto-responsive grid** (no media queries -- the RAM pattern):
172
+
173
+ ```css
174
+ .auto-grid {
175
+ display: grid;
176
+ grid-template-columns: repeat(auto-fit, minmax(min(250px, 100%), 1fr));
177
+ gap: 1.5rem;
178
+ }
179
+ ```
180
+
181
+ The `min(250px, 100%)` inside `minmax()` prevents overflow on narrow viewports.
182
+
183
+ > Source: [RAM Layout Pattern -- web.dev](https://web.dev/patterns/layout/repeat-auto-minmax),
184
+ > [Complete Guide to CSS Grid -- CSS-Tricks](https://css-tricks.com/snippets/css/complete-guide-grid/)
185
+
186
+ ### Sticky Headers
187
+
188
+ ```css
189
+ .site-header {
190
+ position: sticky; top: 0; z-index: 100;
191
+ background: var(--surface); backdrop-filter: blur(8px);
192
+ }
193
+
194
+ @media (max-width: 47.99em) {
195
+ .bottom-nav {
196
+ position: fixed; bottom: 0; left: 0; right: 0; z-index: 100;
197
+ padding-bottom: env(safe-area-inset-bottom);
198
+ }
199
+ body { padding-bottom: calc(60px + env(safe-area-inset-bottom)); }
200
+ }
201
+ ```
202
+
203
+ Keep sticky headers compact (60-80px max). Account for `env(safe-area-inset-*)` on
204
+ notched/Dynamic Island devices. Consider auto-hide on scroll-down, show on scroll-up.
205
+
206
+ > Source: [Sticky Menus UX Guidelines -- Smashing Magazine](https://www.smashingmagazine.com/2023/05/sticky-menus-ux-guidelines/)
207
+
208
+ ### Responsive Images
209
+
210
+ **Resolution switching** (same image, different sizes):
211
+ ```html
212
+ <img src="hero-800.jpg"
213
+ srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w, hero-1600.jpg 1600w"
214
+ sizes="(min-width: 1200px) 1200px, (min-width: 768px) 90vw, 100vw"
215
+ alt="Descriptive alt text" loading="lazy" decoding="async" width="1600" height="900">
216
+ ```
217
+
218
+ **Art direction** (different crops per breakpoint):
219
+ ```html
220
+ <picture>
221
+ <source media="(min-width: 1024px)" srcset="hero-wide.jpg">
222
+ <source media="(min-width: 768px)" srcset="hero-medium.jpg">
223
+ <img src="hero-mobile.jpg" alt="Descriptive alt text">
224
+ </picture>
225
+ ```
226
+
227
+ Rules:
228
+ - Global default: `img { max-width: 100%; height: auto; }`
229
+ - Use `loading="lazy"` on all images except the LCP (above-the-fold) image
230
+ - Use `fetchpriority="high"` on the LCP image
231
+ - Always provide `width` and `height` attributes to prevent CLS
232
+ - Prefer AVIF > WebP > JPEG for photos; SVG for icons and illustrations
233
+
234
+ > Source: [Responsive Images -- MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images),
235
+ > [Responsive Images Done Right -- Smashing Magazine](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/)
236
+
237
+ ---
238
+
239
+ ## 3. Component Conventions
240
+
241
+ ### Responsive Tables
242
+
243
+ **Horizontal scroll** (comparison data, many columns):
244
+ ```css
245
+ .table-wrapper {
246
+ overflow-x: auto; -webkit-overflow-scrolling: touch;
247
+ /* Add role="region" tabindex="0" aria-labelledby in HTML for accessibility */
248
+ }
249
+ ```
250
+
251
+ **Card/stacked layout** (record-based data on mobile):
252
+ ```css
253
+ @media (max-width: 47.99em) {
254
+ table, thead, tbody, th, td, tr { display: block; }
255
+ thead { display: none; }
256
+ td::before { content: attr(data-label); font-weight: 600; display: block; }
257
+ }
258
+ ```
259
+
260
+ **Priority columns** (show critical columns only on mobile, reveal more at wider breakpoints):
261
+ ```css
262
+ .col-priority-2 { display: none; }
263
+ @media (min-width: 48em) { .col-priority-2 { display: table-cell; } }
264
+ @media (min-width: 64em) { .col-priority-3 { display: table-cell; } }
265
+ ```
266
+
267
+ > Source: [Responsive Tables -- Smashing Magazine](https://www.smashingmagazine.com/2022/12/accessible-front-end-patterns-responsive-tables-part1/),
268
+ > [Responsive Data Tables -- CSS-Tricks](https://css-tricks.com/responsive-data-tables/)
269
+
270
+ ### Responsive Forms
271
+
272
+ - **Mobile:** single-column always. Full-width inputs, min 48px height, stack labels above inputs
273
+ - **Desktop:** two-column for related short fields (First Name / Last Name)
274
+ - Set `font-size >= 1rem` on inputs to prevent iOS Safari auto-zoom on focus
275
+ - Use appropriate `inputmode` attributes (`numeric`, `email`, `tel`, `url`)
276
+
277
+ ```css
278
+ .form-grid { display: grid; grid-template-columns: 1fr; gap: 1rem; }
279
+ @media (min-width: 48em) { .form-grid { grid-template-columns: 1fr 1fr; } }
280
+ .form-grid .full-width { grid-column: 1 / -1; }
281
+ .form-input { min-height: 48px; font-size: 1rem; padding: 0.75rem 1rem; width: 100%; }
282
+ ```
283
+
284
+ ### Responsive Modals & Dialogs
285
+
286
+ Use native `<dialog>` with `.showModal()`. Mobile: bottom-sheet. Desktop: centered overlay.
287
+
288
+ ```css
289
+ dialog { border: none; border-radius: 1rem; padding: 0; max-width: min(90vw, 560px); }
290
+ dialog::backdrop { background: rgb(0 0 0 / 0.5); }
291
+
292
+ @media (max-width: 47.99em) {
293
+ dialog { margin: auto 0 0 0; max-width: 100%; width: 100%;
294
+ border-radius: 1rem 1rem 0 0; max-height: 85dvh; }
295
+ }
296
+ @media (min-width: 48em) { dialog { margin: auto; } }
297
+ ```
298
+
299
+ > Source: [Building a Dialog Component -- web.dev](https://web.dev/articles/building/a-dialog-component)
300
+
301
+ ### Touch vs Mouse/Keyboard
302
+
303
+ Use CSS interaction media features -- do not assume input modality from screen size:
304
+
305
+ ```css
306
+ @media (pointer: coarse) { .btn { min-height: 48px; min-width: 48px; } }
307
+ @media (pointer: fine) { .btn { min-height: 32px; } }
308
+
309
+ @media (hover: hover) { .btn:hover { background: var(--primary-hover); } }
310
+ @media (hover: none) { .btn:active { background: var(--primary-active); } }
311
+ ```
312
+
313
+ Key rules:
314
+ - **Never rely on hover for critical information.** Tooltips on hover are inaccessible on touch
315
+ - **Touch targets: min 48x48px** (Google recommendation). WCAG 2.5.8 AA: 24x24px; AAA: 44x44px
316
+ - **Spacing between targets: min 8px** to prevent accidental taps
317
+ - **Sticky hover:** on touch, `:hover` persists after tap. Wrap in `@media (hover: hover)`
318
+ - Support both touch and keyboard: every element must be focusable and operable via keyboard
319
+
320
+ > Source: [Interaction -- web.dev](https://web.dev/learn/design/interaction),
321
+ > [Hover and Pointer Media Queries -- Smashing Magazine](https://www.smashingmagazine.com/2022/03/guide-hover-pointer-media-queries/),
322
+ > [Accessible Tap Targets -- web.dev](https://web.dev/articles/accessible-tap-targets)
323
+
324
+ ---
325
+
326
+ ## 4. Typography & Spacing System
327
+
328
+ ### Fluid Typography
329
+
330
+ Use `clamp()` for font sizes that scale smoothly without breakpoint jumps:
331
+
332
+ ```css
333
+ :root {
334
+ --text-sm: clamp(0.875rem, 0.8rem + 0.35vw, 1rem);
335
+ --text-base: clamp(1rem, 0.925rem + 0.4vw, 1.125rem);
336
+ --text-lg: clamp(1.125rem, 1rem + 0.6vw, 1.375rem);
337
+ --text-xl: clamp(1.25rem, 1.1rem + 0.75vw, 1.625rem);
338
+ --text-2xl: clamp(1.5rem, 1.25rem + 1.25vw, 2.25rem);
339
+ --text-3xl: clamp(1.875rem, 1.5rem + 1.875vw, 3rem);
340
+ --text-4xl: clamp(2.25rem, 1.75rem + 2.5vw, 4rem);
341
+ }
342
+ ```
343
+
344
+ **Accessibility:** use `rem`/`em` bounds (not `px`) so user font-size preferences are respected.
345
+ `clamp()` with fixed `px` bounds can fail WCAG 1.4.4 (Resize Text) if users cannot scale to 200%.
346
+
347
+ > Source: [Modern Fluid Typography -- Smashing Magazine](https://www.smashingmagazine.com/2022/01/modern-fluid-typography-css-clamp/),
348
+ > [Fluid Typography with Baseline CSS -- web.dev](https://web.dev/articles/baseline-in-action-fluid-type)
349
+
350
+ ### Responsive Spacing Scale
351
+
352
+ ```css
353
+ :root {
354
+ --space-xs: clamp(0.5rem, 0.425rem + 0.375vw, 0.75rem);
355
+ --space-sm: clamp(0.75rem, 0.65rem + 0.5vw, 1rem);
356
+ --space-md: clamp(1rem, 0.875rem + 0.625vw, 1.5rem);
357
+ --space-lg: clamp(1.5rem, 1.25rem + 1.25vw, 2.5rem);
358
+ --space-xl: clamp(2rem, 1.625rem + 1.875vw, 3.5rem);
359
+ --space-2xl: clamp(3rem, 2.5rem + 2.5vw, 5rem);
360
+ }
361
+ ```
362
+
363
+ > Source: [Fluidly Scaling Type and Spacing -- CSS-Tricks](https://css-tricks.com/consistent-fluidly-scaling-type-and-spacing/)
364
+
365
+ ### Content Readability
366
+
367
+ - Optimal line length: **45-75 characters** (~65ch ideal) for body text
368
+ - Body line-height: **1.5-1.8** (WCAG 1.4.12 requires at least 1.5)
369
+ - Heading line-height: **1.1-1.3** (tighter for large text)
370
+
371
+ ---
372
+
373
+ ## 5. Viewport Units & User Preferences
374
+
375
+ ### Modern Viewport Units
376
+
377
+ Mobile browsers have dynamic toolbars that change viewport height. Use new units:
378
+
379
+ | Unit | Meaning | Use Case |
380
+ |---|---|---|
381
+ | `svh` | Small viewport height (toolbars visible) | Safe for fixed hero sections |
382
+ | `lvh` | Large viewport height (toolbars hidden) | Use with caution |
383
+ | `dvh` | Dynamic (updates as toolbars show/hide) | Dynamic layouts, modal max-height |
384
+
385
+ > Source: [Viewport Units -- web.dev](https://web.dev/blog/viewport-units)
386
+
387
+ ### User Preference Queries
388
+
389
+ ```css
390
+ @media (prefers-color-scheme: dark) { /* dark mode colors */ }
391
+ @media (prefers-reduced-motion: reduce) { *, *::before, *::after {
392
+ animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }
393
+ @media (prefers-contrast: more) { /* increase borders, outlines */ }
394
+ ```
395
+
396
+ > Source: [prefers-reduced-motion -- web.dev](https://web.dev/articles/prefers-reduced-motion),
397
+ > [prefers-color-scheme -- web.dev](https://web.dev/articles/prefers-color-scheme)
398
+
399
+ ---
400
+
401
+ ## 6. Performance for Responsive Sites
402
+
403
+ ### Core Web Vitals Targets
404
+
405
+ | Metric | Good | Needs Improvement | Poor |
406
+ |---|---|---|---|
407
+ | LCP (Largest Contentful Paint) | < 2.5s | 2.5--4.0s | > 4.0s |
408
+ | INP (Interaction to Next Paint) | < 200ms | 200--500ms | > 500ms |
409
+ | CLS (Cumulative Layout Shift) | < 0.1 | 0.1--0.25 | > 0.25 |
410
+
411
+ ### Responsive Performance Rules
412
+
413
+ 1. **Serve sized images.** Use `srcset`/`sizes` so mobile downloads smaller files
414
+ 2. **Set explicit dimensions.** `width`/`height` on images and video, or `aspect-ratio` in CSS
415
+ 3. **Prioritize LCP image.** `fetchpriority="high"`, URL discoverable in HTML (not data-src)
416
+ 4. **Lazy-load below fold.** `loading="lazy"` on all images except the LCP element
417
+ 5. **Font strategy.** `font-display: swap`, preload critical fonts, prefer variable fonts
418
+ 6. **Animate safely.** Use `transform` and `opacity` -- never animate width/height/margin
419
+
420
+ > Source: [Web Vitals -- web.dev](https://web.dev/articles/vitals),
421
+ > [Optimize LCP -- web.dev](https://web.dev/articles/optimize-lcp)
422
+
423
+ ---
424
+
425
+ ## 7. Strategy: Combining @media, @container, and :has()
426
+
427
+ | Concern | Tool | Example |
428
+ |---|---|---|
429
+ | Page layout | `@media` | 1-column to sidebar at 1024px |
430
+ | Component layout | `@container` | Card vertical/horizontal based on container width |
431
+ | User preferences | `@media` | Dark mode, reduced motion |
432
+ | Input modality | `@media` | Touch targets for `pointer: coarse` |
433
+ | Content-aware style | `:has()` | Layout changes when card contains an image |
434
+ | Fluid values | `clamp()` | Font/spacing scales without breakpoints |
435
+
436
+ > Source: [The New Responsive -- web.dev](https://web.dev/new-responsive)
437
+
438
+ ---
439
+
440
+ ## 8. Common Mistakes
441
+
442
+ ### 8.1 Desktop-First Design That Breaks on Mobile
443
+ Design for 1440px then squeeze to 375px. **Fix:** Start with mobile wireframes, use
444
+ `min-width` queries, test at 320px first.
445
+
446
+ ### 8.2 Fixed Pixel Values Instead of Relative Units
447
+ `width: 800px`, `font-size: 24px`. **Fix:** Use `%`, `rem`, `em`, `ch`, `vw`, `fr`,
448
+ `clamp()`. Reserve `px` for borders and hairlines only.
449
+
450
+ ### 8.3 Not Testing on Real Devices
451
+ Chrome DevTools does not replicate real touch, iOS Safari quirks, or slow 3G. **Fix:** Test
452
+ on low-end Android, iPhone (Safari), tablet, and real slow networks.
453
+
454
+ ### 8.4 Horizontal Scroll on Mobile
455
+ Common culprits: images without `max-width: 100%`, fixed-width elements, flex without
456
+ `flex-wrap: wrap`, grid without `min()` in `minmax()`, `100vw` including scrollbar width,
457
+ absolute positioning. **Debug:** `* { outline: 1px solid red; }`
458
+
459
+ > Source: [Overflow Issues -- Smashing Magazine](https://www.smashingmagazine.com/2021/04/css-overflow-issues/)
460
+
461
+ ### 8.5 Tiny Touch Targets on Mobile Web
462
+ 24px buttons on touch devices. **Fix:** Min 48x48px touch area with 8px spacing.
463
+
464
+ ### 8.6 Hover-Dependent Information
465
+ Tooltips or content visible only on `:hover`. **Fix:** Make content accessible via `:focus`
466
+ or visible by default. Wrap hover enhancements in `@media (hover: hover)`.
467
+
468
+ ### 8.7 Missing Viewport Meta Tag
469
+ Omitting it causes mobile browsers to render at desktop width. **Fix:** Always include:
470
+ `<meta name="viewport" content="width=device-width, initial-scale=1">`.
471
+ Never use `user-scalable=no` -- it disables pinch-to-zoom (WCAG 1.4.4 violation).
472
+
473
+ ### 8.8 Ignoring Landscape Orientation
474
+ Phone landscape is ~667px wide but only ~375px tall. **Fix:** Use `min-height` not
475
+ `height: 100vh` for hero sections.
476
+
477
+ ### 8.9 Loading Desktop Assets on Mobile
478
+ 2MB hero images on 3G. **Fix:** `srcset`/`sizes`, subset fonts, code-split JS.
479
+
480
+ ### 8.10 Forgetting Safe Area Insets
481
+ Content hidden behind notch/Dynamic Island. **Fix:**
482
+ `padding-bottom: env(safe-area-inset-bottom)` on fixed elements.
483
+
484
+ ---
485
+
486
+ ## 9. Responsive Web Design Checklist
487
+
488
+ ### Foundation
489
+ - [ ] Viewport meta tag: `<meta name="viewport" content="width=device-width, initial-scale=1">`
490
+ - [ ] CSS is mobile-first (`min-width` media queries)
491
+ - [ ] Base font size >= 16px (`1rem`) to prevent iOS auto-zoom
492
+ - [ ] Global `img { max-width: 100%; height: auto; }`
493
+ - [ ] No horizontal scroll at any width from 320px to 1920px
494
+
495
+ ### Layout
496
+ - [ ] Content within max-width (1200-1440px) with centered container
497
+ - [ ] Grids use `repeat(auto-fit, minmax(min(X, 100%), 1fr))` pattern
498
+ - [ ] Navigation adapts per breakpoint (hamburger/bottom bar, horizontal, sidebar)
499
+ - [ ] Prose constrained to 45-75 characters per line
500
+ - [ ] Sticky headers compact (60-80px) with safe area insets
501
+
502
+ ### Media
503
+ - [ ] Responsive images with `srcset` and `sizes`
504
+ - [ ] Art direction uses `<picture>` for different crops
505
+ - [ ] LCP image has `fetchpriority="high"` and is not lazy-loaded
506
+ - [ ] All media has explicit dimensions or `aspect-ratio` (prevents CLS)
507
+
508
+ ### Interaction & Accessibility
509
+ - [ ] Touch targets >= 48x48px with >= 8px spacing
510
+ - [ ] Hover effects wrapped in `@media (hover: hover)`
511
+ - [ ] `prefers-reduced-motion` respected
512
+ - [ ] Pinch-to-zoom not disabled
513
+ - [ ] All interactive elements keyboard-accessible
514
+
515
+ ### Components
516
+ - [ ] Tables use scroll, card layout, or priority columns on mobile
517
+ - [ ] Forms single-column on mobile, inputs >= 48px tall, `font-size >= 1rem`
518
+ - [ ] Modals are bottom-sheet (mobile) / centered overlay (desktop)
519
+ - [ ] Typography uses fluid `clamp()` values
520
+
521
+ ### Performance
522
+ - [ ] Core Web Vitals pass: LCP < 2.5s, INP < 200ms, CLS < 0.1
523
+ - [ ] Tested on real devices (low-end Android, iPhone, tablet)
524
+ - [ ] Tested on slow network (3G throttle minimum)
525
+
526
+ ---
527
+
528
+ ## References
529
+
530
+ - [Responsive Web Design Basics -- web.dev](https://web.dev/articles/responsive-web-design-basics)
531
+ - [The New Responsive -- web.dev](https://web.dev/new-responsive)
532
+ - [Responsive Web Design -- MDN](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design)
533
+ - [Container Queries: Netflix Case Study -- web.dev](https://web.dev/case-studies/netflix-cq)
534
+ - [CSS Container Queries -- CSS-Tricks](https://css-tricks.com/css-container-queries/)
535
+ - [Container Queries Primer -- Smashing Magazine](https://www.smashingmagazine.com/2021/05/complete-guide-css-container-queries/)
536
+ - [Complete Guide to CSS Grid -- CSS-Tricks](https://css-tricks.com/snippets/css/complete-guide-grid/)
537
+ - [Modern Fluid Typography -- Smashing Magazine](https://www.smashingmagazine.com/2022/01/modern-fluid-typography-css-clamp/)
538
+ - [CSS min(), max(), clamp() -- web.dev](https://web.dev/articles/min-max-clamp)
539
+ - [Accessible Tap Targets -- web.dev](https://web.dev/articles/accessible-tap-targets)
540
+ - [Hover and Pointer Media Queries -- Smashing Magazine](https://www.smashingmagazine.com/2022/03/guide-hover-pointer-media-queries/)
541
+ - [Responsive Images -- MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images)
542
+ - [Bottom Navigation Pattern -- Smashing Magazine](https://www.smashingmagazine.com/2019/08/bottom-navigation-pattern-mobile-web-pages/)
543
+ - [Responsive Tables -- Smashing Magazine](https://www.smashingmagazine.com/2022/12/accessible-front-end-patterns-responsive-tables-part1/)
544
+ - [Overflow Issues in CSS -- Smashing Magazine](https://www.smashingmagazine.com/2021/04/css-overflow-issues/)
545
+ - [Web Vitals -- web.dev](https://web.dev/articles/vitals)
546
+ - [New Front-End Features 2025 -- Smashing Magazine](https://www.smashingmagazine.com/2024/12/new-front-end-features-for-designers-in-2025/)
547
+ - [Viewport Units -- web.dev](https://web.dev/blog/viewport-units)
548
+ - [Subgrid -- MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Subgrid)
549
+ - [Accessible Responsive Design -- web.dev](https://web.dev/articles/accessible-responsive-design)
550
+ - [WCAG Target Sizes -- Smashing Magazine](https://www.smashingmagazine.com/2024/07/getting-bottom-minimum-wcag-conformant-interactive-element-size/)