@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,552 @@
1
+ # Responsive Design — Expertise Module
2
+
3
+ > A responsive design specialist ensures that web interfaces adapt fluidly across the full spectrum of devices, viewport sizes, and user contexts. The scope spans fluid grids, flexible media, media queries, container queries, mobile-first strategy, responsive typography, breakpoint architecture, performance optimization, and cross-device testing. The discipline was formalized by Ethan Marcotte in his seminal 2010 A List Apart article and has since evolved from viewport-centric layouts to component-driven responsive systems.
4
+
5
+ ---
6
+
7
+ ## 1. What This Discipline Covers
8
+
9
+ ### 1.1 Definition and Origins
10
+
11
+ Responsive web design (RWD) is an approach to building interfaces that adapt to browsers, viewport dimensions, devices, and user preferences. Ethan Marcotte coined the term in his May 25, 2010 article on A List Apart, identifying three foundational ingredients: **fluid grids** (relative units instead of fixed pixels), **flexible images** (media that scale within containers), and **media queries** (CSS conditionals based on device characteristics). The concept drew on John Allsopp's 2000 "A Dao of Web Design," which argued the web's inherent flexibility should be embraced.
12
+
13
+ (Source: [Responsive Web Design — A List Apart](https://alistapart.com/article/responsive-web-design/))
14
+ (Source: [Ethan Marcotte — Responsive Design at 10](https://ethanmarcotte.com/wrote/responsive-design-at-10/))
15
+
16
+ ### 1.2 Fluid Grids
17
+
18
+ Marcotte's foundational formula: `target / context = result`. A 300px element inside a 960px container becomes 31.25%. Modern CSS evolves this with `fr` units in CSS Grid, `flex-grow`/`flex-shrink` in Flexbox, and viewport-relative units (`vw`, `vh`, `dvh`, `svh`, `lvh`).
19
+
20
+ ### 1.3 Flexible Images and Media
21
+
22
+ ```css
23
+ img, video, embed, object, iframe {
24
+ max-width: 100%;
25
+ height: auto;
26
+ }
27
+ ```
28
+
29
+ Modern additions: `aspect-ratio: 16/9` prevents layout shifts, `object-fit: cover | contain` controls replaced content fill, and explicit `width`/`height` HTML attributes enable browser aspect-ratio calculation before CSS loads (preventing CLS).
30
+
31
+ (Source: [web.dev — Responsive Images](https://web.dev/learn/design/responsive-images))
32
+
33
+ ### 1.4 Media Queries
34
+
35
+ ```css
36
+ /* Viewport-based */
37
+ @media (min-width: 768px) { ... }
38
+ @media (768px <= width <= 1024px) { ... } /* Modern range syntax */
39
+
40
+ /* Feature-based */
41
+ @media (hover: hover) { ... }
42
+ @media (pointer: fine) { ... }
43
+
44
+ /* User preference-based */
45
+ @media (prefers-color-scheme: dark) { ... }
46
+ @media (prefers-reduced-motion: reduce) { ... }
47
+ @media (prefers-contrast: more) { ... }
48
+ ```
49
+
50
+ (Source: [MDN — CSS media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries))
51
+
52
+ ### 1.5 Container Queries
53
+
54
+ The most significant evolution since Marcotte's original formulation. Styles apply based on parent container size rather than viewport, enabling component-level responsiveness.
55
+
56
+ ```css
57
+ .card-container {
58
+ container: card / inline-size;
59
+ }
60
+
61
+ @container card (min-width: 400px) {
62
+ .card { display: grid; grid-template-columns: 1fr 2fr; }
63
+ }
64
+ ```
65
+
66
+ Production-ready in all major browsers (Chrome 105+, Firefox 110+, Safari 16+). Use **media queries** for macro layout (page columns, sidebar visibility) and **container queries** for component adaptation (cards, widgets, navbars).
67
+
68
+ (Source: [MDN — CSS Container Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries))
69
+ (Source: [web.dev — The New Responsive](https://web.dev/articles/new-responsive))
70
+
71
+ ### 1.6 Mobile-First Strategy
72
+
73
+ Base styles target smallest screens; complexity is added via `min-width` queries. This aligns with progressive enhancement: deliver essentials first, enhance for larger contexts.
74
+
75
+ ```css
76
+ /* Base: mobile */
77
+ .grid { display: flex; flex-direction: column; gap: 1rem; }
78
+
79
+ /* Tablet+ */
80
+ @media (min-width: 768px) {
81
+ .grid { flex-direction: row; flex-wrap: wrap; }
82
+ .grid > * { flex: 1 1 calc(50% - 0.5rem); }
83
+ }
84
+
85
+ /* Desktop+ */
86
+ @media (min-width: 1200px) {
87
+ .grid > * { flex: 1 1 calc(33.333% - 0.667rem); }
88
+ }
89
+ ```
90
+
91
+ **Why it matters:** smaller devices load only what they need, forces content prioritization, aligns with progressive enhancement, and matches market reality (~60% mobile traffic globally).
92
+
93
+ (Source: [BrowserStack — Mobile-First Design](https://www.browserstack.com/guide/how-to-implement-mobile-first-design))
94
+
95
+ ---
96
+
97
+ ## 2. Core Methods & Frameworks
98
+
99
+ ### 2.1 Breakpoint Systems
100
+
101
+ | Tier | Range | Typical Devices |
102
+ |------|-------|-----------------|
103
+ | XS | < 576px | Small phones (portrait) |
104
+ | SM | 576-767px | Large phones, small tablets |
105
+ | MD | 768-991px | Tablets (portrait) |
106
+ | LG | 992-1199px | Tablets (landscape), small laptops |
107
+ | XL | 1200-1399px | Desktops, laptops |
108
+ | 2XL | >= 1400px | Large monitors |
109
+
110
+ **Content-based breakpoints** (recommended over device-based): set where the layout visually breaks, regardless of device widths. More resilient because it responds to content needs. **Component-level breakpoints** via container queries let individual components define their own thresholds. Best practices: centralize breakpoint values (CSS custom properties or SCSS variables), limit to 4-6 major breakpoints, name for intent not device.
111
+
112
+ (Source: [NN/g — Breakpoints in Responsive Design](https://www.nngroup.com/articles/breakpoints-in-responsive-design/))
113
+
114
+ ### 2.2 Responsive Layout Patterns
115
+
116
+ **Mostly Fluid:** Fluid grid with `max-width` on large screens, single column on small. Simplest pattern for content-heavy pages.
117
+
118
+ ```css
119
+ .grid {
120
+ display: grid;
121
+ grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
122
+ gap: 1.5rem;
123
+ }
124
+ ```
125
+
126
+ **Column Drop:** Multi-column layouts that progressively drop columns as viewport narrows. Content stacks vertically at smallest breakpoint.
127
+
128
+ **Layout Shifter:** Content fundamentally rearranges at breakpoints (not just reflow). Uses `grid-template-areas` for readable layout definitions. Most flexible but requires more CSS.
129
+
130
+ ```css
131
+ .layout { grid-template-areas: "header" "main" "sidebar" "footer"; }
132
+
133
+ @media (min-width: 768px) {
134
+ .layout {
135
+ grid-template-columns: 1fr 2fr;
136
+ grid-template-areas: "header header" "sidebar main" "footer footer";
137
+ }
138
+ }
139
+ ```
140
+
141
+ **Off-Canvas:** Content pushed off-screen until triggered. Common for mobile navigation, filters, settings panels.
142
+
143
+ **Tiny Tweaks:** Minor CSS adjustments (font size, padding) without structural changes. For simple single-column layouts.
144
+
145
+ (Source: [UXPin — 5 Timeless Responsive Design Layouts](https://www.uxpin.com/studio/blog/5-useful-responsive-design-layouts-to-consider/))
146
+
147
+ ### 2.3 Responsive Images with srcset and picture
148
+
149
+ **Resolution switching:**
150
+
151
+ ```html
152
+ <img
153
+ src="hero-800.jpg"
154
+ srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w, hero-1600.jpg 1600w"
155
+ sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
156
+ alt="Description" width="2000" height="1000" loading="lazy" decoding="async">
157
+ ```
158
+
159
+ - `srcset` provides image sources with intrinsic widths; `sizes` tells the browser expected display width at each breakpoint
160
+ - Browser chooses optimal source considering viewport, DPR, and network conditions
161
+
162
+ **Art direction with picture:**
163
+
164
+ ```html
165
+ <picture>
166
+ <source media="(min-width: 1200px)" srcset="hero-desktop.avif" type="image/avif">
167
+ <source media="(min-width: 600px)" srcset="hero-tablet.webp" type="image/webp">
168
+ <source srcset="hero-mobile.webp" type="image/webp">
169
+ <img src="hero-fallback.jpg" alt="Description" width="2000" height="1000">
170
+ </picture>
171
+ ```
172
+
173
+ Use `<picture>` for serving different compositions per viewport (art direction) or format negotiation (AVIF > WebP > JPEG). Format recommendations: AVIF for high-detail photos (~50% smaller than JPEG, ~95% browser support), WebP for general purpose (~25-34% smaller, ~96% support), SVG for vectors.
174
+
175
+ (Source: [web.dev — The Picture Element](https://web.dev/learn/design/picture-element))
176
+ (Source: [MDN — Responsive Images](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images))
177
+
178
+ ### 2.4 Responsive Typography with clamp()
179
+
180
+ ```css
181
+ h1 { font-size: clamp(2rem, 5vw + 1rem, 4.5rem); }
182
+ h2 { font-size: clamp(1.5rem, 3vw + 0.75rem, 3rem); }
183
+ body {
184
+ font-size: clamp(1rem, 0.5vw + 0.875rem, 1.25rem);
185
+ line-height: clamp(1.4, 0.2vw + 1.3, 1.6);
186
+ }
187
+ ```
188
+
189
+ The three values: minimum (floor), preferred (target combining `vw` + `rem`), maximum (ceiling). **Critical rules:** always combine `vw` with `rem` in preferred value (using `vw` alone ignores user font-size preferences and breaks zoom), use `rem` for min/max to respect user settings, keep viewport coefficient consistent across heading levels for proportional scaling. Test at 200% zoom (WCAG SC 1.4.4).
190
+
191
+ **Fluid spacing:**
192
+
193
+ ```css
194
+ :root {
195
+ --space-sm: clamp(0.75rem, 1vw + 0.5rem, 1.25rem);
196
+ --space-md: clamp(1rem, 2vw + 0.5rem, 2rem);
197
+ --space-lg: clamp(1.5rem, 3vw + 0.75rem, 3.5rem);
198
+ }
199
+ ```
200
+
201
+ (Source: [Smashing Magazine — Modern Fluid Typography Using CSS Clamp](https://www.smashingmagazine.com/2022/01/modern-fluid-typography-css-clamp/))
202
+ (Source: [web.dev — Responsive and Fluid Typography](https://web.dev/articles/baseline-in-action-fluid-type))
203
+
204
+ ### 2.5 Container Queries in Practice
205
+
206
+ **Container query units:** `cqw` (1% container width), `cqh` (1% container height), `cqi`/`cqb` (inline/block size), `cqmin`/`cqmax`.
207
+
208
+ ```css
209
+ .card-container { container: card / inline-size; }
210
+
211
+ .card { display: flex; flex-direction: column; }
212
+ .card__image { aspect-ratio: 16 / 9; width: 100%; }
213
+
214
+ @container card (min-width: 450px) {
215
+ .card { flex-direction: row; }
216
+ .card__image { width: 40%; aspect-ratio: 1; }
217
+ }
218
+
219
+ @container card (min-width: 700px) {
220
+ .card__body { display: grid; grid-template-columns: 1fr auto; }
221
+ }
222
+ ```
223
+
224
+ Performance: avoid excessive nesting of queried containers. Use `@supports (container-type: inline-size)` for progressive enhancement.
225
+
226
+ (Source: [Josh W. Comeau — Container Queries Unleashed](https://www.joshwcomeau.com/css/container-queries-unleashed/))
227
+
228
+ ---
229
+
230
+ ## 3. Deliverables
231
+
232
+ ### 3.1 Responsive Wireframes
233
+
234
+ Produce at three to five key viewport widths showing structural changes:
235
+
236
+ | Viewport | Width | Focus |
237
+ |----------|-------|-------|
238
+ | Mobile (portrait) | 375px | Single column, stacked content, mobile nav |
239
+ | Tablet (portrait) | 768px | Two-column grids, expanded nav, sidebar |
240
+ | Desktop | 1280px | Full layout, multi-column, persistent nav |
241
+
242
+ Optional: mobile landscape (667px), large desktop (1920px), ultra-wide (2560px). Must communicate: which elements stack/reflow/hide, navigation mode changes, content priority shifts, touch target sizing, interaction model changes.
243
+
244
+ ### 3.2 Breakpoint Documentation
245
+
246
+ The contract between design and development:
247
+
248
+ ```
249
+ ## Global Breakpoints
250
+ | Token | Value | CSS Property | Usage |
251
+ |---------|---------|---------------|----------------------------|
252
+ | mobile | 0-599px | --bp-mobile | Base styles, single column |
253
+ | tablet | 600px | --bp-tablet | Two-column layouts |
254
+ | desktop | 1024px | --bp-desktop | Full nav, three columns |
255
+ | wide | 1440px | --bp-wide | Max-width, density |
256
+
257
+ ## Component Breakpoints
258
+ | Component | Container Break | Behavior Change |
259
+ |---------------|-----------------|--------------------------|
260
+ | ProductCard | 400px | Vertical -> horizontal |
261
+ | NavigationBar | 768px | Hamburger -> persistent |
262
+ | DataTable | 600px | Card view -> table view |
263
+ ```
264
+
265
+ ### 3.3 Responsive Component Specs
266
+
267
+ Each design system component documents: layout behavior per breakpoint, content rules (truncation, line clamping), interaction model (hover vs. tap), container query thresholds, spacing tokens, and accessibility annotations (focus order changes, screen reader differences).
268
+
269
+ ---
270
+
271
+ ## 4. Tools & Techniques
272
+
273
+ ### 4.1 Browser DevTools Responsive Mode
274
+
275
+ - **Chrome:** `Cmd+Shift+M` — device presets, DPR simulation, network throttling, touch sim, media query bar, CSS Grid/Flexbox overlays
276
+ - **Firefox:** `Cmd+Opt+M` — touch sim, DPR, screenshot capture, throttling
277
+ - **Safari:** Develop > Enter Responsive Design Mode — Apple device presets
278
+
279
+ Key technique: use free-form resizing (not fixed presets) — drag viewport edge slowly to find natural breakpoints. Enable "Show media queries" to visualize active breakpoints.
280
+
281
+ ### 4.2 BrowserStack and Cross-Device Testing
282
+
283
+ 3,000+ real device/browser combinations. Testing strategy: prioritize from analytics, cover Chrome/Android + Safari/iOS + Chrome/Windows + Safari/macOS + Edge (~85-90% of users), include at least one low-end Android device, test landscape on tablets, verify touch interactions on physical devices.
284
+
285
+ (Source: [BrowserStack — Responsive Testing](https://www.browserstack.com/responsive))
286
+
287
+ ### 4.3 Figma Auto-Layout and Breakpoints
288
+
289
+ Auto-layout mirrors CSS Flexbox: "Fill container" = `flex: 1`, "Hug contents" = `width: fit-content`. Use min/max width constraints to simulate `clamp()`. Create separate frames at each breakpoint width, use component variants for responsive states. Annotate breakpoint behavior directly on frames, export design tokens mapping to CSS custom properties.
290
+
291
+ (Source: [Figma — Responsive Website Design](https://www.figma.com/resource-library/responsive-website-design/))
292
+ (Source: [UX Collective — Working with Breakpoints in Figma](https://uxdesign.cc/working-with-breakpoints-in-figma-testing-and-documenting-responsive-designs-db1c27237c0f))
293
+
294
+ ### 4.4 Additional Tools
295
+
296
+ | Tool | Purpose |
297
+ |------|---------|
298
+ | Responsively App | Multiple viewports simultaneously (open-source) |
299
+ | Polypane | Multi-pane responsive, accessibility, performance testing |
300
+ | Chrome Lighthouse | Automated responsive + performance auditing |
301
+ | Sizzy | Multi-viewport browser with synchronized scrolling |
302
+
303
+ ---
304
+
305
+ ## 5. Common Failures
306
+
307
+ ### 5.1 Desktop-First Design
308
+
309
+ Starting with full desktop layout and squeezing into mobile produces subtractive design — hiding content and degrading experience. **Fix:** adopt mobile-first CSS, write base styles for 375px, use `min-width` queries exclusively.
310
+
311
+ ### 5.2 Fixed Widths
312
+
313
+ Elements set to fixed pixels (`width: 960px`) overflow on smaller viewports. Common sources: legacy frameworks, third-party embeds, images without `max-width`, wide tables. **Fix:** relative units (`%`, `vw`, `fr`, `rem`), `max-width: 100%` globally, `overflow-x: auto` on tables.
314
+
315
+ ### 5.3 Horizontal Scroll
316
+
317
+ The most visible responsive failure. Causes: fixed widths, missing `box-sizing: border-box`, `100vw` including scrollbar width (use `100%` instead), third-party scripts, long unbroken text.
318
+
319
+ **Diagnostic:**
320
+ ```javascript
321
+ document.querySelectorAll('*').forEach(el => {
322
+ if (el.scrollWidth > document.documentElement.clientWidth) console.log('Overflow:', el);
323
+ });
324
+ ```
325
+
326
+ **Fix:**
327
+ ```css
328
+ *, *::before, *::after { box-sizing: border-box; }
329
+ .content { overflow-wrap: break-word; word-break: break-word; }
330
+ pre, code { overflow-x: auto; max-width: 100%; }
331
+ ```
332
+
333
+ (Source: [OneNine — Common Responsive Design Failures and Fixes](https://onenine.com/common-responsive-design-failures-and-fixes/))
334
+
335
+ ### 5.4 Unreadable Text on Mobile
336
+
337
+ **Rules:** min body text 16px (1rem) to prevent iOS Safari auto-zoom, max line length ~65 characters (`max-width: 65ch`), min line-height 1.5, min contrast 4.5:1 normal text / 3:1 large text (WCAG SC 1.4.3).
338
+
339
+ ### 5.5 Unusable Forms on Mobile
340
+
341
+ Inputs below 44px height, labels beside (not above) inputs, overridden native pickers, missing `inputmode` attributes. **Fix:** `font-size: 1rem` (prevents iOS zoom), `min-height: 48px`, stack fields on mobile, use appropriate `type` and `inputmode`:
342
+
343
+ ```html
344
+ <input type="email" inputmode="email" autocomplete="email">
345
+ <input type="tel" inputmode="tel" autocomplete="tel">
346
+ <input type="number" inputmode="numeric" pattern="[0-9]*">
347
+ ```
348
+
349
+ ### 5.6 Image Bloat
350
+
351
+ Images account for >60% of page weight. Single source for all viewports wastes bandwidth and degrades LCP. **Fix:** `srcset`/`sizes` on all content images, `<picture>` for art direction, `loading="lazy"` below fold only, AVIF/WebP with JPEG fallback, generate sizes at build (300w, 600w, 900w, 1200w, 1800w).
352
+
353
+ (Source: [web.dev — Serve Responsive Images](https://web.dev/articles/serve-responsive-images))
354
+
355
+ ---
356
+
357
+ ## 6. Integration with Development
358
+
359
+ ### 6.1 CSS Grid for Responsive Layouts
360
+
361
+ ```css
362
+ /* Auto-responsive grid — no media queries needed */
363
+ .grid {
364
+ display: grid;
365
+ grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
366
+ gap: 1.5rem;
367
+ }
368
+ ```
369
+
370
+ Key features: `auto-fit`/`auto-fill` with `minmax()` for intrinsic responsiveness, `fr` units for proportional distribution, `min()` inside `minmax()` prevents overflow, `grid-template-areas` for readable layout shifts, `subgrid` for child alignment with parent tracks.
371
+
372
+ ### 6.2 Flexbox for Responsive Components
373
+
374
+ Best for one-dimensional flows. Use `flex-wrap: wrap` for natural reflow, `margin-top: auto` to push elements to bottom regardless of content height, `gap` for consistent spacing.
375
+
376
+ **Grid vs. Flexbox decision:**
377
+
378
+ | Concern | CSS Grid | Flexbox |
379
+ |---------|----------|---------|
380
+ | Dimension | Two-dimensional | One-dimensional |
381
+ | Driven by | Layout-first | Content-first |
382
+ | Best for | Page layouts, card grids | Navigation, component internals |
383
+
384
+ Use Grid for page structure, Flexbox for component internals.
385
+
386
+ ### 6.3 Container Queries in Component Libraries
387
+
388
+ ```jsx
389
+ // React — wrapper provides containment context
390
+ function Card({ title, image, children }) {
391
+ return (
392
+ <div className="card-wrapper"> {/* container: card / inline-size */}
393
+ <article className="card">
394
+ <img className="card__image" src={image} alt="" />
395
+ <div className="card__body"><h3>{title}</h3>{children}</div>
396
+ </article>
397
+ </div>
398
+ );
399
+ }
400
+ ```
401
+
402
+ Components respond to their wrapper's dimensions, making them portable across sidebar, main column, or full-width contexts.
403
+
404
+ ### 6.4 Tailwind CSS Responsive Utilities
405
+
406
+ Mobile-first prefix system: `sm:` (640px), `md:` (768px), `lg:` (1024px), `xl:` (1280px), `2xl:` (1536px).
407
+
408
+ ```html
409
+ <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
410
+ <div class="p-4 sm:p-6">
411
+ <h2 class="text-lg md:text-xl lg:text-2xl">Title</h2>
412
+ <p class="text-sm md:text-base line-clamp-2 md:line-clamp-3">Content</p>
413
+ </div>
414
+ </div>
415
+
416
+ <!-- Responsive visibility -->
417
+ <nav class="hidden md:flex">Desktop nav</nav>
418
+ <button class="md:hidden">Menu</button>
419
+ ```
420
+
421
+ Container queries (Tailwind v3.4+): `@container` with `@md:`, `@lg:` prefixes.
422
+
423
+ (Source: [Tailwind CSS — Responsive Design](https://tailwindcss.com/docs/responsive-design))
424
+
425
+ ### 6.5 Testing Across Devices
426
+
427
+ **Testing pyramid:**
428
+ 1. **Unit tests** — test container query breakpoint logic
429
+ 2. **Automated visual regression** — Percy, Chromatic at 3+ viewports
430
+ 3. **Browser DevTools** — primary development workflow
431
+ 4. **Cloud device farm** — BrowserStack, LambdaTest for breadth
432
+ 5. **Real devices** — final validation, touch/gesture accuracy
433
+
434
+ **Automated example (Playwright):**
435
+
436
+ ```javascript
437
+ const viewports = [
438
+ { width: 375, height: 812, name: 'mobile' },
439
+ { width: 768, height: 1024, name: 'tablet' },
440
+ { width: 1280, height: 800, name: 'desktop' },
441
+ ];
442
+
443
+ for (const vp of viewports) {
444
+ test(`homepage at ${vp.name}`, async ({ page }) => {
445
+ await page.setViewportSize({ width: vp.width, height: vp.height });
446
+ await page.goto('/');
447
+ await expect(page).toHaveScreenshot(`homepage-${vp.name}.png`);
448
+ });
449
+ }
450
+ ```
451
+
452
+ CI/CD: run visual regression on every PR, Lighthouse CI per viewport, flag horizontal overflow as failures.
453
+
454
+ (Source: [BrowserStack — Responsive vs Cross Browser Testing](https://www.browserstack.com/guide/responsive-design-testing-vs-cross-browser-testing))
455
+
456
+ ---
457
+
458
+ ## 7. Viewport Meta Tag
459
+
460
+ A hard requirement. Without it, mobile browsers render at virtual desktop width (~980px) and scale down.
461
+
462
+ ```html
463
+ <meta name="viewport" content="width=device-width, initial-scale=1">
464
+ ```
465
+
466
+ Never set `user-scalable=no` or `maximum-scale=1` — disables pinch-zoom and violates WCAG SC 1.4.4.
467
+
468
+ (Source: [MDN — Viewport meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag))
469
+
470
+ ---
471
+
472
+ ## 8. Quick Reference Checklist
473
+
474
+ ### Critical
475
+ - [ ] Viewport meta tag present: `<meta name="viewport" content="width=device-width, initial-scale=1">`
476
+ - [ ] No horizontal scroll at any width from 320px to 2560px
477
+ - [ ] No fixed-width containers — all use relative units
478
+ - [ ] `box-sizing: border-box` set globally
479
+ - [ ] Images have `max-width: 100%`
480
+ - [ ] Body text >= 16px (1rem) on all viewports
481
+ - [ ] Touch targets >= 44x44px (48x48px preferred)
482
+ - [ ] Forms usable on mobile — labels above inputs, correct `inputmode`
483
+ - [ ] User can zoom — no `user-scalable=no` or `maximum-scale=1`
484
+
485
+ ### Layout & Navigation
486
+ - [ ] Mobile-first CSS — `min-width` queries add complexity
487
+ - [ ] Navigation adapts (persistent desktop, hamburger/bottom mobile)
488
+ - [ ] Content stacks logically without information loss
489
+ - [ ] Grid uses `auto-fit`/`auto-fill` with `minmax()`
490
+ - [ ] Container queries for multi-context components
491
+
492
+ ### Typography & Spacing
493
+ - [ ] `clamp()` with `rem` + `vw` (not `vw` alone)
494
+ - [ ] Line length <= 75 characters (`max-width: 65ch`)
495
+ - [ ] Line height >= 1.5 for body text
496
+ - [ ] Spacing scales via fluid values or responsive tokens
497
+
498
+ ### Images & Media
499
+ - [ ] `srcset` and `sizes` on content images
500
+ - [ ] `<picture>` for art direction
501
+ - [ ] AVIF/WebP with JPEG fallback
502
+ - [ ] Explicit `width`/`height` on `<img>` tags (CLS prevention)
503
+ - [ ] `loading="lazy"` below fold only (not on LCP image)
504
+ - [ ] Video/iframe embeds are responsive
505
+
506
+ ### Performance
507
+ - [ ] LCP image sized per viewport, not lazy-loaded
508
+ - [ ] CLS < 0.1 during responsive reflow
509
+ - [ ] `font-display: swap` or `optional`
510
+ - [ ] Third-party embeds wrapped in responsive containers
511
+
512
+ ### Accessibility
513
+ - [ ] Focus indicators visible at all viewport sizes
514
+ - [ ] Focus order logical across layout shifts
515
+ - [ ] `prefers-reduced-motion` respected
516
+ - [ ] 200% zoom causes no content loss or horizontal scroll (WCAG SC 1.4.4)
517
+
518
+ ### Testing
519
+ - [ ] Tested on real iOS Safari and real Android Chrome
520
+ - [ ] Both portrait and landscape on mobile/tablet
521
+ - [ ] Browser text size at maximum
522
+ - [ ] Visual regression at 3+ viewport widths
523
+ - [ ] Lighthouse mobile: Performance > 90, Accessibility > 90
524
+
525
+ ---
526
+
527
+ ## 9. Canonical References
528
+
529
+ ### Foundational Texts
530
+ - Ethan Marcotte, ["Responsive Web Design"](https://alistapart.com/article/responsive-web-design/), A List Apart, May 2010
531
+ - Ethan Marcotte, [*Responsive Web Design*](https://ethanmarcotte.com/books/responsive-web-design/) (A Book Apart, 2011)
532
+ - Ethan Marcotte, [*Responsive Design: Patterns & Principles*](https://ethanmarcotte.com/books/responsive-design-patterns-and-principles/) (A Book Apart, 2015)
533
+
534
+ ### Web Platform Documentation
535
+ - [web.dev — Learn Responsive Design](https://web.dev/learn/design)
536
+ - [web.dev — Responsive Web Design Basics](https://web.dev/articles/responsive-web-design-basics)
537
+ - [web.dev — The New Responsive](https://web.dev/articles/new-responsive)
538
+ - [web.dev — Responsive and Fluid Typography](https://web.dev/articles/baseline-in-action-fluid-type)
539
+ - [MDN — Responsive Web Design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design)
540
+ - [MDN — CSS Media Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries)
541
+ - [MDN — CSS Container Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries)
542
+ - [MDN — Responsive Images](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images)
543
+ - [MDN — Viewport Meta Tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag)
544
+
545
+ ### Tools, Frameworks & Patterns
546
+ - [Tailwind CSS — Responsive Design](https://tailwindcss.com/docs/responsive-design)
547
+ - [BrowserStack — Responsive Testing](https://www.browserstack.com/responsive)
548
+ - [Figma — Responsive Website Design](https://www.figma.com/resource-library/responsive-website-design/)
549
+ - [NN/g — Breakpoints in Responsive Design](https://www.nngroup.com/articles/breakpoints-in-responsive-design/)
550
+ - [Smashing Magazine — Modern Fluid Typography Using CSS Clamp](https://www.smashingmagazine.com/2022/01/modern-fluid-typography-css-clamp/)
551
+ - [Josh W. Comeau — Container Queries Unleashed](https://www.joshwcomeau.com/css/container-queries-unleashed/)
552
+ - Brad Frost, [This Is Responsive](https://bradfrost.github.io/this-is-responsive/patterns.html)