@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
package/expertise/design/foundations/rtl-design.md ADDED
@@ -0,0 +1,585 @@
1
+ # RTL (Right-to-Left) Design -- Design Expertise Module
2
+
3
+ > A comprehensive foundation for designing applications that correctly support right-to-left (RTL) languages including Arabic, Hebrew, Farsi (Persian), and Urdu. RTL design extends far beyond mirroring a layout -- it requires understanding bidirectional text algorithms, typographic conventions unique to each script, icon directionality semantics, CSS logical properties, and platform-specific APIs. Over 500 million native speakers use RTL scripts as their primary language, making RTL support a fundamental requirement for any globally distributed product.
4
+
5
+ > **Category:** Foundation
6
+ > **Applies to:** All platforms (Web, iOS, Android, Flutter, Desktop)
7
+ > **Key sources:** Material Design RTL/BiDi guidelines, Apple HIG Internationalization, W3C Internationalization Best Practices, MDN CSS Logical Properties
8
+
9
+ ---
10
+
11
+ ## 1. Core Principles
12
+
13
+ ### 1.1 RTL Mirroring -- What Mirrors and What Does Not
14
+
15
+ An RTL layout is the mirror image of an LTR layout. However, mirroring is not universal -- certain elements must remain unmirrored to preserve meaning.
16
+
17
+ **Elements that MUST mirror:**
18
+
19
+ | Element | LTR | RTL |
20
+ |---|---|---|
21
+ | Navigation flow | Left to right | Right to left |
22
+ | Sidebar/drawer | Opens from left | Opens from right |
23
+ | Back/forward buttons | Back=left, Forward=right | Back=right, Forward=left |
24
+ | List item leading icons | Icon on left of text | Icon on right of text |
25
+ | Progress bars / Sliders | Fill/min on left | Fill/min on right |
26
+ | Toggle switches | Off=left, On=right | Off=right, On=left |
27
+ | Tab order | First tab on left | First tab on right |
28
+ | Form layouts | Label left, input right | Label right, input left |
29
+ | Pagination | Previous left, next right | Previous right, next left |
30
+ | Carousels | Swipe left for next | Swipe right for next |
31
+ | Vertical scrollbar | Right side | Left side |
32
+ | Rating stars (partial fill) | Fill left to right | Fill right to left |
33
+ | Timelines | Past left, future right | Past right, future left |
34
+ | Breadcrumbs | Flow left to right | Flow right to left |
35
+
36
+ **Elements that must NOT mirror:**
37
+
38
+ | Element | Reason |
39
+ |---|---|
40
+ | Media playback controls (play, pause, skip) | Represent tape direction, not reading direction |
41
+ | Clocks and circular progress indicators | Clocks turn clockwise universally |
42
+ | Checkmarks and X marks | Universal symbols, no directional meaning |
43
+ | Brand logos | Identity elements must remain consistent |
44
+ | Numeric keypads | Layout is standardized globally |
45
+ | Graphs/charts (x-axis) | Mathematical convention, not linguistic |
46
+ | Images and photographs | Content is not directional |
47
+ | Circular refresh indicators | Clockwise rotation is universal |
48
+ | Code editors/snippets | Programming languages are always LTR |
49
+
50
+ ### 1.2 Bidirectional (BiDi) Text Handling
51
+
52
+ Bidirectional text occurs when RTL and LTR content coexist in the same string -- extremely common since Arabic text routinely contains English brand names, URLs, and numbers. The Unicode Bidirectional Algorithm (UBA, UAX #9) handles most cases automatically, but edge cases require manual intervention.
53
+
54
+ **When the algorithm needs help:**
55
+ - Weak characters (punctuation, spaces) at RTL/LTR boundaries can attach to the wrong direction
56
+ - Paths with mixed scripts: `"/users/محمد/documents"` may render incorrectly
57
+ - Phone numbers with country codes: the plus sign is a weak character
58
+
59
+ **HTML solutions:**
60
+
61
+ ```html
62
+ <html dir="rtl" lang="ar"> <!-- Base direction -->
63
+ <p>المستخدم <bdi>@john_doe</bdi> أضاف تعليقا</p> <!-- Isolate embedded LTR -->
64
+ <code dir="ltr">npm install package</code> <!-- Force LTR for code -->
65
+ <textarea dir="auto"></textarea> <!-- Auto-detect for UGC -->
66
+ ```
67
+
68
+ **Key Unicode control characters:**
69
+
70
+ | Character | Code Point | Usage |
71
+ |---|---|---|
72
+ | LRM (Left-to-Right Mark) | U+200E | Force LTR ordering at ambiguous boundaries |
73
+ | RLM (Right-to-Left Mark) | U+200F | Force RTL ordering at ambiguous boundaries |
74
+ | LRI (Left-to-Right Isolate) | U+2066 | Isolate LTR content without affecting surroundings |
75
+ | RLI (Right-to-Left Isolate) | U+2067 | Isolate RTL content without affecting surroundings |
76
+ | FSI (First Strong Isolate) | U+2068 | Auto-detect direction and isolate |
77
+ | PDI (Pop Directional Isolate) | U+2069 | End isolation |
78
+
79
+ ### 1.3 CSS Logical Properties
80
+
81
+ CSS logical properties replace physical directional values with flow-relative values. When `dir="rtl"` is set, they automatically flip without additional CSS rules.
82
+
83
+ **Property mapping (horizontal writing mode):**
84
+
85
+ | Physical Property | Logical Property | LTR = | RTL = |
86
+ |---|---|---|---|
87
+ | `margin-left` | `margin-inline-start` | margin-left | margin-right |
88
+ | `margin-right` | `margin-inline-end` | margin-right | margin-left |
89
+ | `padding-left` | `padding-inline-start` | padding-left | padding-right |
90
+ | `padding-right` | `padding-inline-end` | padding-right | padding-left |
91
+ | `border-left` | `border-inline-start` | border-left | border-right |
92
+ | `left` | `inset-inline-start` | left | right |
93
+ | `right` | `inset-inline-end` | right | left |
94
+ | `text-align: left` | `text-align: start` | left | right |
95
+ | `text-align: right` | `text-align: end` | right | left |
96
+ | `float: left` | `float: inline-start` | left | right |
97
+ | `border-top-left-radius` | `border-start-start-radius` | top-left | top-right |
98
+
99
+ **Shorthand usage:**
100
+
101
+ ```css
102
+ .element {
103
+ margin-block: 10px; /* top and bottom */
104
+ margin-inline: 30px 20px; /* start and end */
105
+ padding-inline: 24px 16px;
106
+ border-inline-start: 2px solid blue;
107
+ }
108
+ ```
109
+
110
+ Browser support: Chrome 87+, Firefox 66+, Safari 15+, Edge 87+. Production-ready.
111
+
112
+ ### 1.4 Flexbox and Grid RTL Behavior
113
+
114
+ Flexbox and CSS Grid automatically respond to document direction. `flex-direction: row` lays items right-to-left when `dir="rtl"` is set. CSS Grid column definitions also reverse. Named grid areas reverse physical placement. No code changes needed -- just avoid hardcoding `left`/`right` on flex/grid children.
115
+
116
+ ### 1.5 Text Alignment
117
+
118
+ Always use `start`/`end` instead of `left`/`right`. Center alignment works identically in both directions. Most UI frameworks default to "natural" alignment that matches reading direction automatically.
119
+
120
+ ### 1.6 Number Handling
121
+
122
+ Numbers in RTL languages are always read left to right. The digit sequence `123` is never displayed as `321`. However, numeral glyphs vary by locale.
123
+
124
+ | Language/Region | Glyphs | Unicode Range |
125
+ |---|---|---|
126
+ | Arabic (Gulf states) | ٠١٢٣٤٥٦٧٨٩ | U+0660-U+0669 |
127
+ | Persian / Urdu | ۰۱۲۳۴۵۶۷۸۹ | U+06F0-U+06F9 |
128
+ | Hebrew / Maghreb Arabic | 0123456789 | U+0030-U+0039 |
129
+
130
+ **Key rules:**
131
+ - Digit sequences are always LTR in visual order
132
+ - Currency/percentage symbols follow locale conventions (Arabic: `%25` reads visually as "25%")
133
+ - Phone numbers are always LTR
134
+ - Use `Intl.NumberFormat` / locale-aware APIs -- never manually construct number strings
135
+
136
+ ```javascript
137
+ new Intl.NumberFormat('ar-EG').format(1234567.89) // "١٬٢٣٤٬٥٦٧٫٨٩"
138
+ new Intl.NumberFormat('ar-MA').format(1234567.89) // "1.234.567,89" (Western numerals)
139
+ ```
140
+
141
+ ### 1.7 Typography Considerations
142
+
143
+ **Arabic script specifics:**
144
+ - **Connected letters (cursive joining):** Arabic is always cursive. Each letter has up to four forms: isolated, initial, medial, final. The rendering engine must perform contextual shaping.
145
+ - **No uppercase/lowercase:** Use bold weight, color, or size for emphasis instead of capitalization.
146
+ - **Larger font sizes needed:** Increase Arabic font size by 20-25% relative to Latin for equivalent readability. Minimum readable body size: 16-18px (vs. 14-16px for Latin).
147
+ - **Line height:** Arabic body text needs line-height of 1.8-2.0 (vs. 1.4-1.6 for Latin) due to connected script and diacritical marks above/below letters.
148
+ - **No italics:** Arabic has no italic tradition. CSS `font-style: italic` produces ugly results or no effect. Never use italics for Arabic.
149
+ - **Bold with caution:** Heavy bold reduces legibility. Prefer medium or semi-bold weights.
150
+ - **Kashida (elongation):** Arabic justification elongates connecting strokes rather than adding inter-word space. CSS kashida support is limited; prefer right-aligned text over justified.
151
+
152
+ **Hebrew script:** Disconnected letters (simpler than Arabic), no case distinction, font size increase of 5-10% sufficient, visual sizing closer to Latin.
153
+
154
+ **Font recommendations:**
155
+
156
+ | Font | Script | Best For |
157
+ |---|---|---|
158
+ | Noto Sans Arabic | Arabic | Broad coverage, Google ecosystem |
159
+ | Cairo | Arabic | Modern geometric UIs, headings |
160
+ | IBM Plex Sans Arabic | Arabic | Enterprise, dev platforms |
161
+ | Tajawal / Almarai | Arabic | Clean mobile UIs, body text |
162
+ | Heebo | Hebrew | Modern web UIs |
163
+ | IBM Plex Sans Hebrew | Hebrew | Enterprise applications |
164
+ | Vazirmatn | Farsi | Persian/Farsi UIs |
165
+ | Noto Nastaliq Urdu | Urdu | Urdu content (Nastaliq style) |
166
+
167
+ **CSS font stack example:**
168
+
169
+ ```css
170
+ :root[dir="rtl"][lang="ar"] {
171
+ --font-family: 'Noto Sans Arabic', 'Cairo', 'Tahoma', sans-serif;
172
+ --font-size-base: 1.1rem; /* ~20% larger than LTR base */
173
+ --line-height-base: 1.8;
174
+ }
175
+ :root[dir="rtl"][lang="he"] {
176
+ --font-family: 'Heebo', 'Noto Sans Hebrew', 'Arial Hebrew', sans-serif;
177
+ --font-size-base: 1.05rem;
178
+ --line-height-base: 1.6;
179
+ }
180
+ ```
181
+
182
+ ### 1.8 Icon Mirroring Rules
183
+
184
+ Mirror icons that communicate direction relative to reading flow. Do not mirror icons representing real-world objects or universal symbols.
185
+
186
+ **Icons that MUST mirror:** Back/forward arrows, undo/redo, reply/reply-all, list bullets (indented), sort arrows, send button, text indent/outdent, open-in-new-window, chevrons in lists/accordions, exit/logout with arrow, volume slider icon, assignment/share icons with arrows.
187
+
188
+ **Icons that must NOT mirror:** Search (magnifying glass), checkmark, X/close, plus/minus, media controls (play, pause, stop, skip), clock, refresh (circular), download/upload (vertical), star/heart/bookmark, settings gear, trash/delete, camera/photo, lock/unlock, Wi-Fi/Bluetooth/signal strength.
189
+
190
+ **Special case:** Question mark icon mirrors in Arabic/Farsi (the glyph `؟` is mirrored) but does NOT mirror in Hebrew.
191
+
192
+ ---
193
+
194
+ ## 2. Do's and Don'ts
195
+
196
+ ### Do's
197
+
198
+ 1. **Use CSS logical properties everywhere.** Replace every `margin-left`, `padding-right`, `left`, `right` with logical equivalents. This is the single most impactful change.
199
+ 2. **Test with real Arabic/Hebrew text.** Never use Lorem Ipsum. Arabic has different word lengths, connection behaviors, and vertical extents.
200
+ 3. **Use `dir="auto"` for user-generated content.** Let the browser detect direction from the first strong directional character.
201
+ 4. **Increase font size for Arabic by 20-25%.** Arabic glyphs at the same px as Latin are visually much smaller.
202
+ 5. **Set both `dir` and `lang` on `<html>`.** `dir` controls layout; `lang` enables font selection, hyphenation, and screen reader pronunciation.
203
+ 6. **Use `<bdi>` to isolate bidirectional text.** Wrap usernames, URLs, file paths, code within RTL text.
204
+ 7. **Use `text-align: start/end` not `left/right`.** Logical alignment auto-flips with direction.
205
+ 8. **Mirror navigation patterns.** Hamburger menus open from right, sidebars on right, swipe-back from right edge.
206
+ 9. **Use `:dir(rtl)` for direction-specific styles.** It evaluates computed direction (not just attribute), unlike `[dir="rtl"]`.
207
+ 10. **Use locale-aware APIs** (`Intl.NumberFormat`, `Intl.DateTimeFormat`) for all formatted output.
208
+ 11. **Increase touch targets for Arabic.** Arabic characters are wider; buttons need more horizontal padding.
209
+ 12. **Provide separate mirrored icon assets** when CSS `transform: scaleX(-1)` produces poor results on asymmetric icons.
210
+ 13. **Test with both short and long Arabic strings.** Arabic translations can be 20-30% longer or shorter than English.
211
+ 14. **Handle mixed-direction form validation.** Error messages referencing field names in another script need bidi isolation.
212
+
213
+ ### Don'ts
214
+
215
+ 1. **Don't mirror brand logos.** Logos are identity marks that must remain consistent.
216
+ 2. **Don't mirror universal icons.** Checkmarks, stars, media controls, clocks, and real-world object icons have no directional meaning.
217
+ 3. **Don't use text in images.** Raster text cannot be mirrored or translated automatically.
218
+ 4. **Don't hardcode `left`/`right` in CSS.** Every hardcoded directional property is a bug in RTL.
219
+ 5. **Don't assume all RTL users read the same way.** Arabic, Hebrew, Farsi, and Urdu have different typographic conventions and cultural expectations.
220
+ 6. **Don't use CSS `direction: rtl` as sole mechanism.** Use the HTML `dir` attribute. W3C recommends markup over CSS because CSS can be disabled and does not convey structural information.
221
+ 7. **Don't use italics for Arabic/Hebrew.** Arabic has no italic tradition; it produces ugly or no results.
222
+ 8. **Don't justify Arabic body text.** Standard CSS justify adds inter-word spacing, which looks unnatural. Arabic justification uses kashida (stroke elongation). Prefer right-aligned.
223
+ 9. **Don't forget to mirror animations.** Slide-in, page transitions, and horizontal loading indicators must reverse for RTL.
224
+ 10. **Don't neglect scrollbar position.** Vertical scrollbars should appear on the left in RTL. Browsers handle this with `dir="rtl"`, but custom implementations may not.
225
+ 11. **Don't use directional Unicode characters as UI indicators.** `>`, `-->`, `>>>` will not mirror. Use proper icons or CSS-generated content.
226
+ 12. **Don't neglect bidirectional URL/email/path testing.** Without `<bdi>` isolation, they render in garbled order inside RTL text.
227
+ 13. **Don't assume number inputs work automatically.** Numeric inputs may need `dir="ltr"` while labels remain RTL.
228
+ 14. **Don't rely on automatic mirroring for complex layouts.** Dashboards, marketing pages, and asymmetric designs may need dedicated RTL layout variants.
229
+
230
+ ---
231
+
232
+ ## 3. Platform Variations
233
+
234
+ ### 3.1 Web (HTML/CSS/JavaScript)
235
+
236
+ **Setting document direction:**
237
+
238
+ ```html
239
+ <html dir="rtl" lang="ar">
240
+ ```
241
+
242
+ **Core implementation pattern:**
243
+
244
+ ```css
245
+ /* Use logical properties for all spacing and positioning */
246
+ .card {
247
+ margin-inline-start: 16px;
248
+ padding-inline-end: 24px;
249
+ border-inline-start: 4px solid var(--accent);
250
+ text-align: start;
251
+ }
252
+
253
+ /* Direction-specific overrides when logical properties are insufficient */
254
+ .icon-arrow:dir(rtl) {
255
+ transform: scaleX(-1);
256
+ }
257
+
258
+ /* :dir() evaluates computed direction (including inherited),
259
+ unlike [dir="rtl"] which only matches the attribute */
260
+ ```
261
+
262
+ **Flexbox and Grid** auto-reverse with `dir="rtl"` -- `flex-direction: row` becomes right-to-left, grid column definitions reverse. No CSS changes needed.
263
+
264
+ **Bidirectional content isolation:**
265
+
266
+ ```html
267
+ <p>المستخدم <bdi>@john_doe</bdi> أضاف تعليقا</p> <!-- Isolate username -->
268
+ <code dir="ltr">npm install package</code> <!-- Force LTR for code -->
269
+ <textarea dir="auto"></textarea> <!-- Auto-detect for UGC -->
270
+ <input type="email" dir="ltr"> <!-- Email always LTR -->
271
+ ```
272
+
273
+ **Framework support:**
274
+ - **Bootstrap 5+:** Built-in RTL via `bootstrap.rtl.css`. Set `dir="rtl"` and swap stylesheet.
275
+ - **Tailwind CSS:** RTL via `rtl:` variant modifier (`rtl:mr-4`). Enable with `dir="rtl"` on element.
276
+ - **Material UI (MUI):** Set `direction: 'rtl'` in theme, wrap with `<CacheProvider>` using `stylis-plugin-rtl`.
277
+ - **Next.js / React:** Set `dir` and `lang` on `<html>` via `app/layout.tsx`. Use `next-intl` or `react-i18next` for locale routing.
278
+
279
+ ### 3.2 iOS (UIKit / SwiftUI)
280
+
281
+ **UISemanticContentAttribute** controls whether a view's content flips in RTL. Set on any UIView:
282
+
283
+ ```swift
284
+ // Default: mirror in RTL (layout elements, navigation)
285
+ view.semanticContentAttribute = .unspecified
286
+
287
+ // Never mirror (media playback controls)
288
+ view.semanticContentAttribute = .playback
289
+
290
+ // Never mirror (spatial/physical representations, brand logos)
291
+ view.semanticContentAttribute = .spatial
292
+ view.semanticContentAttribute = .forceLeftToRight
293
+
294
+ // Force RTL regardless of system locale (for testing)
295
+ view.semanticContentAttribute = .forceRightToLeft
296
+ ```
297
+
298
+ **Auto Layout:** Always use `leadingAnchor`/`trailingAnchor` (not `leftAnchor`/`rightAnchor`):
299
+
300
+ ```swift
301
+ // Correct: auto-adapts to RTL
302
+ label.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16)
303
+ label.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16)
304
+
305
+ // Incorrect: hardcoded, breaks in RTL
306
+ label.leftAnchor.constraint(equalTo: view.leftAnchor, constant: 16)
307
+ ```
308
+
309
+ **Detecting layout direction:**
310
+
311
+ ```swift
312
+ let isRTL = UIView.userInterfaceLayoutDirection(
313
+ for: view.semanticContentAttribute
314
+ ) == .rightToLeft
315
+ ```
316
+
317
+ **UIView.appearance for global overrides:**
318
+
319
+ ```swift
320
+ UISwitch.appearance().semanticContentAttribute = .forceLeftToRight // All switches stay LTR
321
+ ```
322
+
323
+ **SwiftUI:** Respects system locale automatically. Test with `.environment(\.layoutDirection, .rightToLeft)`. Mirror images with `.flipsForRightToLeftLayoutDirection(true)`.
324
+
325
+ **Text alignment:** UIKit defaults to `.natural` which auto-aligns by language. Do not override with `.left`.
326
+
327
+ ### 3.3 Android
328
+
329
+ **Enabling RTL support:**
330
+
331
+ ```xml
332
+ <!-- AndroidManifest.xml -->
333
+ <application android:supportsRtl="true" ... >
334
+ ```
335
+
336
+ **Layout XML -- use `start`/`end` instead of `left`/`right`:**
337
+
338
+ ```xml
339
+ <!-- Correct: adapts to RTL -->
340
+ <TextView
341
+ android:layout_marginStart="16dp"
342
+ android:layout_marginEnd="8dp"
343
+ android:paddingStart="12dp"
344
+ android:textAlignment="viewStart"
345
+ android:drawableStart="@drawable/ic_arrow" />
346
+
347
+ <!-- Incorrect: hardcoded direction -->
348
+ <TextView
349
+ android:layout_marginLeft="16dp"
350
+ android:paddingLeft="12dp"
351
+ android:drawableLeft="@drawable/ic_arrow" />
352
+ ```
353
+
354
+ For API < 17 backward compat, provide both: `marginLeft` + `marginStart`, `marginRight` + `marginEnd`.
355
+
356
+ **Drawable auto-mirroring (API 19+):** Set `android:autoMirrored="true"` on vector drawables for directional icons (arrows, chevrons). Non-directional icons should not use this flag.
357
+
358
+ **Programmatic direction control:**
359
+
360
+ ```kotlin
361
+ view.layoutDirection = View.LAYOUT_DIRECTION_RTL
362
+ val isRTL = view.layoutDirection == View.LAYOUT_DIRECTION_RTL
363
+
364
+ // React to direction changes
365
+ override fun onRtlPropertiesChanged(layoutDirection: Int) {
366
+ super.onRtlPropertiesChanged(layoutDirection)
367
+ }
368
+ ```
369
+
370
+ **Jetpack Compose:** Respects system locale automatically. Test with:
371
+
372
+ ```kotlin
373
+ CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl) {
374
+ MyScreen()
375
+ }
376
+ ```
377
+
378
+ ### 3.4 Flutter
379
+
380
+ Flutter provides comprehensive RTL support through `Directionality` and `TextDirection`. `MaterialApp` sets direction from device locale automatically.
381
+
382
+ **Locale-based automatic RTL:**
383
+
384
+ ```dart
385
+ MaterialApp(
386
+ locale: Locale('ar'), // Arabic locale -> automatic RTL
387
+ supportedLocales: [Locale('en'), Locale('ar'), Locale('he')],
388
+ )
389
+ ```
390
+
391
+ **Explicit direction control:**
392
+
393
+ ```dart
394
+ Directionality(
395
+ textDirection: TextDirection.rtl,
396
+ child: MyWidget(),
397
+ )
398
+ ```
399
+
400
+ **Use directional variants (critical for RTL correctness):**
401
+
402
+ ```dart
403
+ // Correct: adapts to direction
404
+ EdgeInsetsDirectional.only(start: 16, end: 8)
405
+ AlignmentDirectional.centerStart
406
+ BorderRadiusDirectional.only(topStart: Radius.circular(8))
407
+
408
+ // Incorrect: hardcoded, breaks in RTL
409
+ EdgeInsets.only(left: 16, right: 8)
410
+ Alignment.centerLeft
411
+ ```
412
+
413
+ `Row` auto-reverses children when `TextDirection.rtl` is ambient. No code changes needed.
414
+
415
+ **Direction detection:**
416
+
417
+ ```dart
418
+ bool isRTL = Directionality.of(context) == TextDirection.rtl;
419
+ // Content-based detection (intl package):
420
+ bool isRTL = Bidi.detectRtlDirectionality(userText);
421
+ ```
422
+
423
+ ---
424
+
425
+ ## 4. Common Mistakes in AI-Generated Designs
426
+
427
+ ### 4.1 LTR-Only Mockups with "Just Mirror It" Assumptions
428
+ AI generates LTR-only layouts assuming mechanical mirroring works. It does not: asymmetric designs, shadow directions, gradient angles, and complex dashboard layouts require deliberate RTL redesign.
429
+
430
+ ### 4.2 Testing with Fake Arabic Text
431
+ AI tools generate Arabic-looking placeholder text with incorrect letter joining, wrong word lengths, and missing diacritical marks. Always test with real content from native speakers.
432
+
433
+ ### 4.3 Hardcoded Directional Values
434
+ AI-generated CSS consistently uses physical properties instead of logical equivalents. Every instance is an RTL bug.
435
+
436
+ ```css
437
+ /* AI-generated (broken for RTL) */
438
+ .sidebar { margin-left: 20px; float: left; }
439
+ .drawer { left: 0; transform: translateX(-100%); }
440
+
441
+ /* Correct */
442
+ .sidebar { margin-inline-start: 20px; float: inline-start; }
443
+ .drawer { inset-inline-start: 0; transform: translateX(-100%); }
444
+ /* Note: translateX may still need :dir(rtl) override */
445
+ ```
446
+
447
+ ### 4.4 Ignoring Bidirectional Text Scenarios
448
+ AI rarely handles: chat mixing Arabic and English, search results with Arabic descriptions and English brands, forms with Arabic labels but LTR inputs (email, URL), error messages referencing field names in a different script.
449
+
450
+ ### 4.5 Arabic Text at Latin Font Sizes
451
+ AI applies the same `font-size: 14px` to both Latin and Arabic. Arabic at 14px is significantly less legible. Minimum readable Arabic body size on screens: 16-18px.
452
+
453
+ ### 4.6 Wrong Font Fallback Chains
454
+ AI specifies only Latin fonts without Arabic-capable alternatives in the stack.
455
+
456
+ ```css
457
+ /* Broken for Arabic */
458
+ font-family: 'Roboto', 'Helvetica', sans-serif;
459
+
460
+ /* Correct: includes Arabic-capable fonts */
461
+ font-family: 'Roboto', 'Noto Sans Arabic', 'Tahoma', sans-serif;
462
+ ```
463
+
464
+ Without explicit Arabic fonts, the browser falls back to system fonts with poor glyph quality or wrong weight matching.
465
+
466
+ ### 4.7 Forgetting to Mirror Animations
467
+ Slide-in drawers, toasts, progress animations, and page transitions that move left-to-right are almost never reversed for RTL in AI-generated code.
468
+
469
+ ### 4.8 Symmetric-Looking Designs That Are Asymmetric
470
+ Cards with image-left/text-right look symmetric but are structurally asymmetric. AI generates them with hardcoded `flex-direction: row` and physical margins, making them impossible to mirror correctly without refactoring to logical properties.
471
+
472
+ ---
473
+
474
+ ## 5. Decision Framework
475
+
476
+ ### 5.1 Mirror or Not -- Decision Tree
477
+
478
+ ```
479
+ Is it a brand element (logo, brand icon)? -> Do NOT mirror
480
+ Is it a real-world physical object (camera, trash)? -> Do NOT mirror
481
+ Does it indicate horizontal direction (arrow, chevron)? -> MIRROR
482
+ Does it represent media playback or tape direction? -> Do NOT mirror
483
+ Does it represent circular motion (clock, refresh)? -> Do NOT mirror
484
+ Does it contain text or numbers? -> Do NOT mirror (text self-directs)
485
+ Is it a layout/navigation element (sidebar, tabs)? -> MIRROR
486
+ Ambiguous? -> Do NOT mirror (safe default)
487
+ ```
488
+
489
+ ### 5.2 Handling Mixed LTR/RTL Content
490
+
491
+ 1. **Set base direction to match primary language.** Arabic page = `dir="rtl"`. Embedded English handled by Unicode bidi algorithm.
492
+ 2. **Isolate embedded opposite-direction content.** `<bdi>` for inline, `dir="ltr"` on block containers.
493
+ 3. **Use `dir="auto"` for unknown content.** User-generated text, API responses, dynamic strings.
494
+ 4. **Explicit direction for form inputs.** Email, URL, code inputs = `dir="ltr"`. Number inputs = `dir="ltr"`.
495
+ 5. **Handle concatenated strings carefully.** When building "Welcome, USERNAME" programmatically, wrap the variable with bidi isolation.
496
+
497
+ ### 5.3 Font Selection Guidance
498
+
499
+ | Criterion | Recommendation |
500
+ |---|---|
501
+ | Broad coverage / Google ecosystem | Noto Sans Arabic, Noto Sans Hebrew |
502
+ | Modern geometric UI | Cairo (Arabic), Heebo (Hebrew) |
503
+ | Enterprise / IBM design language | IBM Plex Sans Arabic/Hebrew |
504
+ | Variable font needed | Noto Sans Arabic (variable), Vazirmatn (Farsi) |
505
+ | Nastaliq style (Urdu) | Noto Nastaliq Urdu |
506
+ | System fonts (no loading) | Tahoma (Win), Geeza Pro (macOS), Droid Arabic Naskh (Android) |
507
+
508
+ ### 5.4 Automatic Mirroring vs. Dedicated RTL Layout
509
+
510
+ **Automatic mirroring is sufficient when:** layout is structurally symmetric, CSS logical properties used consistently, design system supports RTL natively, content is simple (lists, forms, text-heavy pages).
511
+
512
+ **Dedicated RTL layout variants needed when:** heavily asymmetric designs, complex dashboards, marketing/landing pages with directional visual flow, layouts with diagonal/angled elements, onboarding with directional illustrations.
513
+
514
+ ### 5.5 Cross-Platform Property Quick Reference
515
+
516
+ | Concept | Web (CSS) | iOS (UIKit) | Android (XML) | Flutter |
517
+ |---|---|---|---|---|
518
+ | Start margin | `margin-inline-start` | `leadingAnchor` | `marginStart` | `EdgeInsetsDirectional.start` |
519
+ | End margin | `margin-inline-end` | `trailingAnchor` | `marginEnd` | `EdgeInsetsDirectional.end` |
520
+ | Text align start | `text-align: start` | `.natural` | `textAlignment="viewStart"` | `TextAlign.start` |
521
+ | Direction attr | `dir="rtl"` | `semanticContentAttribute` | `layoutDirection` | `TextDirection.rtl` |
522
+ | Auto-mirror icon | `transform: scaleX(-1)` | `.flipsForRightToLeftLayoutDirection` | `autoMirrored="true"` | `matchTextDirection: true` |
523
+ | Detect RTL | `:dir(rtl)` pseudo-class | `effectiveUserInterfaceLayoutDirection` | `view.layoutDirection` | `Directionality.of(context)` |
524
+
525
+ ---
526
+
527
+ ## 6. Quick Reference Checklist
528
+
529
+ ### Document and Markup
530
+ - [ ] `<html>` has `dir="rtl"` and appropriate `lang` attribute
531
+ - [ ] User-generated content containers use `dir="auto"`
532
+ - [ ] Email, URL, and code inputs have explicit `dir="ltr"`
533
+ - [ ] Embedded opposite-direction text wrapped in `<bdi>`
534
+ - [ ] Phone numbers and numeric sequences isolated with `dir="ltr"`
535
+
536
+ ### CSS and Layout
537
+ - [ ] Zero instances of physical `margin-left/right`, `padding-left/right` (use logical equivalents)
538
+ - [ ] Zero instances of `float: left/right` (use `inline-start`/`inline-end`)
539
+ - [ ] Zero instances of `text-align: left/right` (use `start`/`end`)
540
+ - [ ] Absolute/fixed positioning uses `inset-inline-start/end` not `left`/`right`
541
+ - [ ] Border-radius uses logical properties
542
+ - [ ] Flexbox/Grid layouts verified in RTL
543
+
544
+ ### Typography
545
+ - [ ] Arabic font specified in font-family stack
546
+ - [ ] Arabic font size increased 20-25% relative to Latin
547
+ - [ ] Arabic line-height set to 1.8-2.0
548
+ - [ ] No italic styling on Arabic text
549
+ - [ ] Bold limited to medium/semi-bold for Arabic
550
+ - [ ] Hebrew font specified if supporting Hebrew
551
+
552
+ ### Icons and Images
553
+ - [ ] Directional icons (arrows, chevrons, reply, undo) mirrored in RTL
554
+ - [ ] Non-directional icons (search, close, star, media controls) NOT mirrored
555
+ - [ ] Brand logos NOT mirrored
556
+ - [ ] No text embedded in raster images
557
+
558
+ ### Navigation and Interaction
559
+ - [ ] Sidebar/drawer opens from the right
560
+ - [ ] Back button on right, forward on left
561
+ - [ ] Tab order reversed (first tab on right)
562
+ - [ ] Swipe gestures reversed
563
+ - [ ] Pagination controls mirrored
564
+
565
+ ### Numbers and Data
566
+ - [ ] Numbers formatted via locale-aware APIs
567
+ - [ ] Correct numeral glyphs for target locale
568
+ - [ ] Currency/percentage symbols positioned per locale
569
+ - [ ] Date formats follow locale conventions
570
+
571
+ ### Animation and Transitions
572
+ - [ ] Horizontal slide animations reversed for RTL
573
+ - [ ] Progress bar fill direction reversed
574
+ - [ ] Circular indicators (spinners, clocks) NOT reversed
575
+
576
+ ### Testing
577
+ - [ ] Tested with real Arabic/Hebrew content (not Lorem Ipsum)
578
+ - [ ] Tested with long strings (overflow/truncation)
579
+ - [ ] Tested with mixed LTR+RTL content in same view
580
+ - [ ] Validated by native speakers
581
+ - [ ] Tested on devices with RTL system locale
582
+
583
+ ---
584
+
585
+ *Researched: 2026-03-07 | Sources: [Material Design Bidirectionality (M2)](https://m2.material.io/design/usability/bidirectionality.html), [Material Design 3 Bidirectionality](https://m3.material.io/foundations/layout/understanding-layout/bidirectionality-rtl), [Apple HIG Right to Left](https://developer.apple.com/design/human-interface-guidelines/right-to-left), [W3C Internationalization BiDi Best Practices](https://www.w3.org/International/geo/html-tech/tech-bidi.html), [W3C Arabic Layout Requirements](https://www.w3.org/TR/alreq/), [MDN CSS Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Logical_properties_and_values), [MDN :dir() pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir), [Flutter Directionality class](https://api.flutter.dev/flutter/widgets/Directionality-class.html), [Android RTL Support](https://developer.android.com/training/basics/supporting-devices/languages), [RTL Styling 101](https://rtlstyling.com/posts/rtl-styling/), [Bootstrap RTL](https://getbootstrap.com/docs/5.3/getting-started/rtl/)*