rtl-design

RTL 设计

打造正确（方向、双向文本、数字、日历、Unicode）且美观（针对波斯语调校的排版和字体搭配方案）的 RTL 界面——绝不把 LTR 设计简单镜像后了事。波斯语是核心模块，方向层同样适用于阿拉伯语和希伯来语。

要避免两种失败模式：沿用 LTR 习惯（使用物理方向的 CSS、图标不翻转、拉丁字体度量），以及“技术上是 RTL”的粗糙设计（方向正确，但拉丁文本行高过窄，所有地方都用同一种默认字体）。

核心规则 — 始终遵循

方向与布局

1. 在根元素设置一次方向（<html dir="rtl" lang="fa"> / Flutter locale fa）。绝不要用 text-align/float/反转行顺序来伪造 RTL。
2. 使用逻辑方向，而非物理方向：用 margin-inline-start，而不是 margin-left；用 EdgeInsetsDirectional，而不是 EdgeInsets.only(left:)；用 start/end，而不是 left/right。只有对固定物理位置的元素（视频控件、地图、代码编辑器）才使用物理方向值。
3. 翻转有方向性的图标：尖括号、箭头、返回/前进、撤销/重做、回复、发送、分页。**绝不翻转：**播放/暂停、媒体快进/倒带、音量、电话、时钟、Logo、对勾、搜索、刷新。通过 transform: scaleX(-1) / matchTextDirection 翻转，而不是创建重复资源。

文本与数据 4. 波斯语使用 ی（U+06CC）和 ک（U+06A9）——在波斯语文本中使用阿拉伯语的 ي/ك 属于错误。应在输入边界处进行规范化。 5. 数字：UI 文本使用波斯数字 ۰–۹；电话号码、OTP/代码、银行卡号和技术 ID 使用拉丁数字（作为 LTR 文本片段）；波斯语中绝不使用阿拉伯-印度数字 ٠–٩。 6. 面向波斯语用户的日期：使用 Jalali 日历、波斯语月份名称和波斯数字——«۵ مرداد ۱۴۰۵»。存储 ISO/公历日期；展示时再转换。 7. 使用 dir="auto"/<bdi>/unicode-bidi: isolate 隔离 LTR 文本片段（电子邮件、URL、电话号码、代码、拉丁语名称）——标点顺序错乱意味着缺少隔离。 8. 正确处理 ZWNJ（半空格）：写作 می‌شود，而非 «می شود»/«میشود»。在存储、搜索和截断过程中保留 U+200C。

排版（最低要求——完整的审美指南见 references/typography.md） 9. 波斯语正文行高设为 1.8–2.0（拉丁文本的 1.5 会显得过窄）；标题行高设为 1.4。 10. 波斯语文本绝不设置字间距——这会拆散连写字形，并破坏 PDF 文本层。应将设计系统的默认值清零（Material 3 会设置默认值）。 11. 使用前确认字体确实能正确呈现波斯语——一些常见的“阿拉伯语”字体完全不含 پ چ ژ گ（见 typography.md §3）。字体栈末尾始终添加已知可用的后备字体，这样缺少字体时会回退，而不是显示豆腐块。 12. 使用真实的波斯语长字符串测试所有受空间限制的界面（«استانداردسازی زیرساخت‌های بین‌المللی»），而不是 «تست»。

路由 — 按需阅读

场景	阅读内容
构建/审查 Web UI（CSS、React/Next、Tailwind、图标、双向文本、表单、动效）	references/web.md
Flutter 项目（Directional 组件、图标、Jalali 软件包、TextField、测试）	references/flutter.md
字体（安全性、许可、搭配）、字体度量、数字/ZWNJ 细节、字样展示页	references/typography.md

审计模式——零 Token 检测器

对于现有代码，先运行确定性检测器（不使用 LLM，也不需要依赖项）：

python3 scripts/detect.py <path>

JSON 会输出到标准输出：包含规则 ID、严重级别、文件:行号、代码片段和建议的发现项。 退出码 0 = 无问题，1 = 发现问题，2 = 用法错误。使用 --format text 可输出便于人阅读的格式。输出数量有上限（默认 300 条发现项；counts 始终包含完整统计数，truncated 标记是否触及上限）——如果违规数量很大，可使用 --rules 按规则或目录逐项修复。

它会捕获机械性违规（阿拉伯语字母 ي/ك、错误的数字、波斯数字之间的 ASCII 分隔符、物理方向的 CSS/Flutter 属性、波斯语文本上的字母间距、波斯语正文的拉丁语行高、缺少 dir/硬编码 dir、拉丁语数据输入缺少 dir="ltr"、می 后缺少 ZWNJ）。修复每一项 error；结合上下文检查每一项 warning（其中一些有合理的例外——发现项会指出具体情况）。设计上合理的代码行（例如数字/波斯语 ی 规范化映射）应添加行内 rtl-ignore 注释，或在上一行添加 rtl-ignore-next。检测器只是基础检查，不能覆盖所有情况——还要检查正则表达式无法发现的问题：手势/拖动计算和嵌套的方向性区域（flutter.md §10、web.md §6）、视觉层级、图标方向语义、溢出行为、配方质量。

完成前——验证自己的输出

每当你在这些规则约束下创建或编辑 UI 文件，都应对所写内容运行检测器，并在报告完成工作之前修复每一项发现：

python3 scripts/detect.py <the files you touched> --format text

这不是可有可无的润色。写下规则只能解决大部分问题；运行检查才能补上缺口，因为残留的缺陷恰恰是那些在截图中看起来没问题的情况——用户输入时会乱序的电话字段、波斯数字之间的 ASCII 逗号、波斯语正文采用拉丁语行高。应将非空结果视为未完成的工作，而不是建议。

Claude Code 用户可以将这一流程自动化，不必靠记忆来执行——请参阅 references/hooks.md。

与其他设计技能协同使用

此技能可以与通用设计技能结合使用（品味、结构、色彩、动效仍由它们负责）。发生冲突时，应优先满足 RTL/波斯语书写系统的需求——通用技能通常假设使用拉丁语书写系统：拒绝它们为标题建议的字母间距、拉丁语行高（1.4–1.5），以及为波斯语文本建议的拉丁字体（如 Inter）；改用此技能的度量标准、字体配方和图标镜像规则。通用技能的质量检查是针对拉丁语校准的，因此通用设计检查工具通过并不代表波斯语正确——也要运行 scripts/detect.py。

工作流

• **新建 UI：**确认目标平台和语言 → 从第一行代码起应用核心规则（事后补做 RTL 的成本高达 10 倍）→ 按氛围选择排版配方，不要默认选择 → 加载平台参考文档以了解具体细节 → 使用长字符串和混合双向文本进行压力测试。
• **将 LTR 本地化为 RTL：**运行检测器检查机械性问题 → 对照镜像/禁止镜像列表逐一检查图标 → 将物理方向属性替换为逻辑方向属性 → 然后重新设计排版（度量标准，而不只是字体）——没有波斯语排版度量标准的翻译，正是“技术上是 RTL”却粗制滥造的根源。
• **“该用什么字体？”：**绝不要只推荐一种字体。使用 typography.md 中的选择阶梯和配方，遵守许可要求（优先免费字体；推荐商业字体时须注明名称并仅提供官方链接；绝不捆绑商业字体文件），如果用户想查看选项，则提供字体样张页面（typography.md §10）。