diff --git a/packages/docs/CLAUDE.md b/packages/docs/CLAUDE.md index 07cbc49f3..9f4b923a1 100644 --- a/packages/docs/CLAUDE.md +++ b/packages/docs/CLAUDE.md @@ -262,7 +262,9 @@ disabled meant every landing section below the fold was invisible permanently. The site is dressed in ranui's design system. `packages/ranui/docs/DESIGN.md` is the spec; §11 ("Composition — the page, not the component") is the part that governs pages rather than -widgets, and every rule in it came from a failure on this site. +widgets, and every rule in it came from a failure on this site. §12 ("Information +architecture") sits one level above it: which shape a dense page should take before any of +§11 arranges it. `pnpm -F docs verify:design` runs ranui's checker over `styles/` against `design-baseline.json`, which is a **ratchet**: a violation count that rises fails as a new diff --git a/packages/docs/build/langs/messages/cn.ts b/packages/docs/build/langs/messages/cn.ts index d1d28e81c..ce8e5eebd 100644 --- a/packages/docs/build/langs/messages/cn.ts +++ b/packages/docs/build/langs/messages/cn.ts @@ -173,6 +173,7 @@ const cn: LocaleMessages = { foundations: '基础能力', design_system: '设计系统', design_guidelines: '设计规范', + information_architecture: '信息架构', coding_guidelines: '编码规范', theming: 'Theme 主题系统', themeswitch: '主题切换', diff --git a/packages/docs/build/langs/messages/de.ts b/packages/docs/build/langs/messages/de.ts index c82022882..7f2243302 100644 --- a/packages/docs/build/langs/messages/de.ts +++ b/packages/docs/build/langs/messages/de.ts @@ -173,6 +173,7 @@ const de: LocaleMessages = { foundations: 'Grundlagen', design_system: 'Designsystem', design_guidelines: 'Designrichtlinien', + information_architecture: 'Informationsarchitektur', coding_guidelines: 'Coding-Richtlinien', theming: 'Theming', themeswitch: 'Theme-Umschalter', diff --git a/packages/docs/build/langs/messages/en.ts b/packages/docs/build/langs/messages/en.ts index 25f464ac1..ce7b0b3aa 100644 --- a/packages/docs/build/langs/messages/en.ts +++ b/packages/docs/build/langs/messages/en.ts @@ -173,6 +173,7 @@ const en: LocaleMessages = { foundations: 'Foundations', design_system: '', design_guidelines: '', + information_architecture: '', coding_guidelines: '', theming: 'Theming', themeswitch: '', diff --git a/packages/docs/build/langs/messages/es.ts b/packages/docs/build/langs/messages/es.ts index 5e5f65ad1..56298619b 100644 --- a/packages/docs/build/langs/messages/es.ts +++ b/packages/docs/build/langs/messages/es.ts @@ -173,6 +173,7 @@ const es: LocaleMessages = { foundations: 'Fundamentos', design_system: 'Sistema de diseño', design_guidelines: 'Guía de diseño', + information_architecture: 'Arquitectura de información', coding_guidelines: 'Guía de código', theming: 'Temas', themeswitch: 'Cambio de tema', diff --git a/packages/docs/build/langs/messages/fa.ts b/packages/docs/build/langs/messages/fa.ts index d2f833a7d..99db5dfd5 100644 --- a/packages/docs/build/langs/messages/fa.ts +++ b/packages/docs/build/langs/messages/fa.ts @@ -173,6 +173,7 @@ const fa: LocaleMessages = { foundations: 'پایه‌ها', design_system: 'سیستم طراحی', design_guidelines: 'راهنمای طراحی', + information_architecture: 'معماری اطلاعات', coding_guidelines: 'راهنمای کدنویسی', theming: 'پوسته', themeswitch: 'تعویض پوسته', diff --git a/packages/docs/build/langs/messages/ja.ts b/packages/docs/build/langs/messages/ja.ts index f775d18f1..e054a4dcd 100644 --- a/packages/docs/build/langs/messages/ja.ts +++ b/packages/docs/build/langs/messages/ja.ts @@ -173,6 +173,7 @@ const ja: LocaleMessages = { foundations: '基盤', design_system: 'デザインシステム', design_guidelines: 'デザインガイドライン', + information_architecture: '情報アーキテクチャ', coding_guidelines: 'コーディング規約', theming: 'テーマ', themeswitch: 'テーマ切り替え', diff --git a/packages/docs/build/langs/messages/ko.ts b/packages/docs/build/langs/messages/ko.ts index dc527dc70..d83502f20 100644 --- a/packages/docs/build/langs/messages/ko.ts +++ b/packages/docs/build/langs/messages/ko.ts @@ -173,6 +173,7 @@ const ko: LocaleMessages = { foundations: '기반', design_system: '디자인 시스템', design_guidelines: '디자인 가이드', + information_architecture: '정보 구조', coding_guidelines: '코딩 가이드', theming: '테마', themeswitch: '테마 전환', diff --git a/packages/docs/build/langs/messages/pt.ts b/packages/docs/build/langs/messages/pt.ts index 13b73cd70..9001df79d 100644 --- a/packages/docs/build/langs/messages/pt.ts +++ b/packages/docs/build/langs/messages/pt.ts @@ -173,6 +173,7 @@ const pt: LocaleMessages = { foundations: 'Fundamentos', design_system: 'Design system', design_guidelines: 'Diretrizes de design', + information_architecture: 'Arquitetura da informação', coding_guidelines: 'Diretrizes de código', theming: 'Temas', themeswitch: 'Alternador de tema', diff --git a/packages/docs/build/langs/structure.ts b/packages/docs/build/langs/structure.ts index b09c2eda1..0cbd19e76 100644 --- a/packages/docs/build/langs/structure.ts +++ b/packages/docs/build/langs/structure.ts @@ -540,6 +540,12 @@ export const SIDEBAR: Record = { items: [ { kind: 'suffix', key: 'design_system', name: 'Design system', link: '/src/ranui/design-system/' }, { kind: 'suffix', key: 'design_guidelines', name: 'Design guidelines', link: '/src/ranui/design-guides/' }, + { + kind: 'suffix', + key: 'information_architecture', + name: 'Information architecture', + link: '/src/ranui/information-architecture/', + }, { kind: 'suffix', key: 'coding_guidelines', name: 'Coding guidelines', link: '/src/ranui/coding-guides/' }, { kind: 'full', key: 'theming', link: '/src/ranui/theme/' }, { kind: 'suffix', key: 'themeswitch', name: 'ThemeSwitch', link: '/src/ranui/theme-switch/' }, diff --git a/packages/docs/cn/src/ranui/design-guides/index.md b/packages/docs/cn/src/ranui/design-guides/index.md index 10671a592..72acdfe77 100644 --- a/packages/docs/cn/src/ranui/design-guides/index.md +++ b/packages/docs/cn/src/ranui/design-guides/index.md @@ -8,6 +8,7 @@ description: '用 ranui 做界面的设计规范：先定角色再由令牌给 本页讲的是**取舍**：该用哪个令牌、上线前该检查什么。令牌清单本身在 [设计系统](/cn/src/ranui/design-system/)，运行时切换与覆盖在[主题系统](/cn/src/ranui/theme/)。 +在这一切之前，页面该是什么形状，在[信息架构](/cn/src/ranui/information-architecture/)。 这些规则的完整、可机器校验版本在仓库里： [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md)。 diff --git a/packages/docs/cn/src/ranui/design-system/index.md b/packages/docs/cn/src/ranui/design-system/index.md index a5edf8c9c..c66fb73e0 100644 --- a/packages/docs/cn/src/ranui/design-system/index.md +++ b/packages/docs/cn/src/ranui/design-system/index.md @@ -8,13 +8,14 @@ ranui 构建于其上的**设计语言**，以及表达这套语言的**完整** `--ran-*` 自定义属性，都附上它在明暗两套主题下的取值。组件读的是这些令牌而不是写死的数值，所以覆盖 一个令牌就能改变所有用到它的地方。 -三个页面回答三个不同的问题，刻意拆开： - -| 页面 | 回答 | -| ---------------------------------------- | ------------------------ | -| **设计系统**（本页） | 令牌**是什么**，即词汇表 | -| [设计规范](/cn/src/ranui/design-guides/) | 做界面时**如何取舍** | -| [主题系统](/cn/src/ranui/theme/) | 运行时**如何切换与覆盖** | +四个页面回答四个不同的问题，刻意拆开： + +| 页面 | 回答 | +| --------------------------------------------------- | ------------------------ | +| **设计系统**（本页） | 令牌**是什么**，即词汇表 | +| [设计规范](/cn/src/ranui/design-guides/) | 做界面时**如何取舍** | +| [信息架构](/cn/src/ranui/information-architecture/) | 页面本身该是**什么形状** | +| [主题系统](/cn/src/ranui/theme/) | 运行时**如何切换与覆盖** | > **适用场景**：需要查某个令牌的名字或取值（颜色角色、间距档位、图标尺寸、投影层级、缓动曲线）， > 或想理解这些阶梯为什么长这样。 diff --git a/packages/docs/cn/src/ranui/information-architecture/index.md b/packages/docs/cn/src/ranui/information-architecture/index.md new file mode 100644 index 000000000..0f88744cf --- /dev/null +++ b/packages/docs/cn/src/ranui/information-architecture/index.md @@ -0,0 +1,191 @@ +--- +description: '在挑第一个令牌之前，先把高密度页面的形状定下来：定义页面的三个问题、回答主问题的表达骨架，以及每一类信息该放在哪里。' +--- + +# Information architecture 信息架构 + +页面该长成什么**形状**。这件事要在挑颜色、定间距之前决定。 + +这一节的其他几页回答的是零件的问题。本页回答的是排在它们前面的那个问题：这块屏幕要装的东西 +这么多，用户到底是来做什么的，什么样的排布能让他做成。 + +| 页面 | 回答 | +| ---------------------------------------- | ------------------------------ | +| **信息架构**（本页） | 页面该是**什么形状** | +| [设计系统](/cn/src/ranui/design-system/) | 令牌**是什么**：词汇表 | +| [设计规范](/cn/src/ranui/design-guides/) | 做界面时**怎么在它们之间取舍** | +| [主题系统](/cn/src/ranui/theme/) | 运行时**怎么切换和覆盖** | + +> **适用场景**：要做一块同时装着多个对象、多种状态以及它们之间关系的屏幕，比如控制台、仪表盘、 +> 后台、工作台、监控页。落地页和单一转化的表单不算，那类页面的成败取决于说服力，而不是用户能不能 +> 在密集信息里判断准确。 + +数据齐了不等于页面设计好了。接口返回的字段一个不落，筛选、状态标签、批量操作也都在，用户照样不 +知道该先看哪儿。缺的不是信息，是顺序。 + +## 动组件之前先回答三个问题 {#three-questions} + +1. **用户打开页面，最该先看到的是哪一件事？** 这是页面的主信息。 +2. **为了看懂它，还必须同时看到什么？** 关联资源、关联模型、上下文。 +3. **看完之后他要做什么？** 作判断、执行操作，或者接着往下想。 + +这三个问题要在打开组件清单之前答完。三个答案清楚的页面很少选错形状；跳过它们的页面，最后都是照 +着接口返回的结构长出来的。 + +**一个页面只有一个主模型。** 辅助模型可以帮着理解和操作主模型，但不能来抢首屏。 + +## 形状由任务决定，不由返回值决定 {#shape} + +大部分形状不对的页面，都出自这两个顺手的选择： + +- 接口返回了数组，于是做成表格。 +- 路由里带了一个 ID，于是做成详情页。 + +这两件事都不构成理由。同一个对象在不同任务下是不同的形状：查找时 issue 是一个**集合**，处理时 +是一条**状态流**，协作时是一条**讨论线索**，审计时是一串**事件序列**。记录里有日期，只能说明数 +据里有日期，不能说明这一页就该是日历。 + +## 怎么选表达骨架 {#skeletons} + +选那个能让用户最少转几道弯就回答出主问题的排布。 + +| 用户眼前要回答的问题 | 必须放在一起的信息 | 表达骨架 | +| -------------------------------- | -------------------------------------- | --------------- | +| 这些之间差在哪儿？ | 参与比较的字段，列的位置固定 | 二维对照表 | +| 是哪一个，我要点进去 | 名称、标识、状态 | 列表 / 资源目录 | +| 是哪一个，看图就认得出来 | 图放在最显眼处，名称和字段围着它排 | 卡片网格 | +| 这个对象是什么，现在什么状态？ | 身份、状态、主操作，然后才是属性 | 分区详情 | +| 它属于哪里？ | 路径、父级、同级 | 层级树 | +| 谁依赖它，改了会影响到谁？ | 上下游、影响范围 | 关系列表 | +| 我走到第几步了，接下来是什么？ | 阶段、当前输入、后面的步骤 | 分步向导 | +| 每一条在哪个阶段，推动它就是干活 | 列代表阶段，卡片带身份和阻塞点 | 看板 | +| 为什么卡住了？ | 阶段概要，再到单步结果，再到原始日志 | 追踪下钻 | +| 现在健康吗，影响面有多大？ | 对象名、状态，以及把状态改掉的那个事件 | 状态墙 | +| 发生了什么，先后顺序，谁干的？ | 时间、操作者、事件类型 | 事件时间线 | +| 谁提了什么，别人怎么回的？ | 作者、发言、回复结构 | 讨论线程 | +| 改之前和改之后差在哪儿？ | 两个版本并排 | 并排比较 | +| 趋势怎么样，异常在哪儿？ | 指标、它的比较基准、进明细的入口 | 仪表盘 | +| 这段时间被谁占着，会不会撞车？ | 开始、结束、时长放在同一根轴上 | 日历排期 | +| 我接下来该处理哪一条？ | 一侧是队列，另一侧是这一条的详情 | 主从工作台 | +| 哪些规则生效，会影响到什么？ | 配置项、生效范围、造成的后果 | 配置表单 | +| 这段正文说了什么？ | 正文按顺序读，旁边给一份大纲 | 连续文档 | +| 它在哪儿？ | 位置、边界、分布 | 地图与画布 | + +### 最容易选反的几对 {#swapped-pairs} + +- **时间线还是分步向导。** 时间线讲已经发生过什么，按先后排；分步向导讲你现在在哪一步、下一步是 + 什么。两者长得像，指向的时间方向却相反。 +- **看板还是筛选。** 只有当拖动卡片本身就是那个操作时，看板才成立。列如果只是几组存下来的筛选条 + 件，那就是做了个要拖一下才能用的筛选器。 +- **日历还是时间线。** 日历回答的是占用和冲突，时间线回答的是先后。记录里的日期不负责在这两者之 + 间做选择，问题才负责。 +- **卡片网格还是表格。** 图要么是识别的锚点，要么不是。如果选择是靠比数字做出来的，把预览缩成第 + 一列的小图，反而压掉了真正决定结果的字段。 +- **关系图还是关系列表。** 只有当路径本身或影响怎么扩散就是判断依据时，才值得画图。否则一份分好 + 组的上下游列表读起来更快。 +- **正文还是字段格子。** 需要顺着读下来的文字就让它保持文字。把每一段都切成卡片或者键值对，正好 + 毁掉了它原本好读的地方。 + +不要因为做得出来就把三种视图都做一遍。每多一种视图，就多一套筛选、多一份状态映射、多一组要同步 +维护的操作。等到第二种用法确实高频了再加，而不是为了以防万一先加上。 + +## 每一类信息该放在哪里 {#placement} + +| 信息 | 回答的问题 | 该放在 | 不该落到 | +| -------- | ------------------ | -------------------------------------------- | -------------------------------- | +| **身份** | 这是什么？ | 标题、对象概要 | 表格最后一列，或者某个标签页后面 | +| **状态** | 现在怎么样？ | 标题区或概要区 | 只能在详情字段里翻到 | +| **属性** | 它是什么样的？ | 详情正文，按人理解的方式分组 | 照着接口字段顺序摊平 | +| **关联** | 它和谁有关系？ | 自己的区块或标签页，归属、依赖、引用分开表达 | 混进属性表里 | +| **变更** | 和之前差在哪儿？ | 差异区块、时间线 | 只显示改完之后的值 | +| **证据** | 凭什么这么判断？ | 紧挨着这个判断，可以展开 | 另开一个日志页 | +| **操作** | 现在我能做什么？ | 主操作在标题区，其余的挨着各自作用的对象 | 塞进「更多」里 | +| **反馈** | 刚才那下做成了吗？ | 紧挨着操作，保住任务上下文 | 一个和上下文断开的全局提示 | + +**每条信息只有一个权威位置。** 别处只放摘要或入口，并且指回那个权威位置。 + +## 阅读顺序 {#reading-order} + +```text +页面身份 +→ 当前状态或异常 +→ 主任务和主操作 +→ 判断所需的信息 +→ 关联、变更、证据 +→ 次要信息和低频操作 +``` + +- **一页只有一个视觉上的主标题。** 分节标题靠语义推进，不要用字号假装层级。 +- **一个任务区里最多一个主操作。** 主按钮代表最可能、价值最高的下一步，不是最危险的那一步。危险 + 操作用危险语义表达，不该长期占着最重的视觉分量。 +- 警告色和危险色留给真正需要用户注意的状态。整页都是绿的，信号就已经花掉了。 +- 徽标、标签、横幅共用同一份注意力预算。只强调那些会改变判断和动作的信息。 + +## 信息密度 {#density} + +密度不是单位面积里塞了多少控件，而是用户一眼能拿走多少**可用来判断**的信息。把间距收紧只提高了视 +觉密度，有效密度原地不动；删掉不相关的字段、把需要对比的东西摆到一起，才是真的提高。 + +| 档位 | 适用场景 | 换来什么 | +| -------- | -------------------------------- | -------------------------------------------- | +| **宽松** | 首次使用、低频配置、高风险确认 | 解释的空间、更大的分组间距、看得见的影响预览 | +| **标准** | 大多数列表、详情和表单 | 可扫读性和每屏信息量之间的默认平衡 | +| **紧凑** | 高频专家工作台：监控、运维、审计 | 稳定的列宽、短文案、键盘效率、可保存的视图 | + +- 一个页面里**最多用相邻的两档**。标准页面里嵌一张紧凑的表格没问题，每个区块各发明一套标尺不行。 +- 紧凑不等于「字号和点击区域一起缩小」。容器留白和行高可以收紧，正文的可读性、看得见的焦点圈和指 + 针目标尺寸不能。 +- 对专家用户来说，列管理、保存视图、批量操作和快捷键，都比一次显示更多内容更有用。 + +## 怎么维持任务上下文 {#context} + +骨架定下来之后，再决定辅助内容放在哪儿： + +| 用户正在… | 就给他 | +| ------------------------------------ | ----------------------------------------------------- | +| 在对象或证据之间反复切换 | 主从分栏：一侧队列，一侧当前这条 | +| 瞥一眼很轻、看完就走的内容 | 可展开行（`r-disclosure-row`）或气泡卡（`r-popover`） | +| 处理可以分享出去、或者需要宽度的内容 | 一条独立路由 | +| 做一次确认，或者填一个字段 | 弹窗（`r-modal`） | + +**弹窗不是一层导航。** 只要需要可复制的链接、浏览历史、并排比较，或者刷新之后工作还得在，就给它一 +条路由。 + +## 这一层 ranui 能给你什么 {#with-ranui} + +ranui 在页面形状上是刻意不表态的：它提供基础件和令牌，不提供页面模板。这一层它能给的是： + +- `r-section` 划出骨架的各个内容带，`r-card` 承载真正独立的重复条目。卡片里不要再套卡片；表单字 + 段用小标题或分隔线分组就够了。 +- `r-tabs` 表达**同一个对象的平级视图**（它的讨论、它的检查、它的差异），不要拿来放互不相干的模 + 块，那是导航的事。 +- `r-disclosure-row` 做渐进展开，`r-popover` 和 `r-dropdown` 承载临时上下文，`r-modal` 只做上面 + 那张表允许它做的事。 +- `r-state-dot` 表达状态，并且永远带上文字标签：[不能只靠颜色](/cn/src/ranui/design-guides/#accessibility)。 +- 首屏加载时用 `r-skeleton`，长到会让人犯嘀咕的操作配 `r-progress`，结果用 `r-message` 告诉他。 + +ranui **没有表格、树、日历、看板和时间线**。自己实现时，用[令牌](/cn/src/ranui/design-system/)和 +[设计规范](/cn/src/ranui/design-guides/)去搭，不要另起一套视觉体系：间距取自标尺，字体按角色定， +颜色来自语义令牌，每一个可达状态都要设计到。 + +## 典型做坏的方式 {#anti-patterns} + +- 接口返回的每个字段都变成一行详情，身份、状态、关联和证据以同样的分量一起涌出来。 +- 用卡片、颜色和装饰性间距堆出层次感，却没说清该先看哪儿、要据此作出什么判断。 +- 几个操作同时用主按钮样式，或者把一个低频操作摆进标题区。 +- 状态、属性、关联和变更混进同一张表，结果哪儿都比不出来。 +- 用户只是想查个名字和状态，却给了他一张关系图。 +- 用弹窗装一条长流程、一次比较，或者别人一定会想发链接出去的内容。 +- 同一句话在标题、概要、标签页和表格里各出现一遍，哪一次都没带来新信息。 + +## 页面上线前的检查清单 + +- [ ] 主信息、关联信息、用户的下一步动作，三样都写下来了。 +- [ ] 表达骨架是从问题选出来的，不是从返回值的形状推出来的。 +- [ ] 页面只有一个主模型，辅助视图服务于它而不是和它抢。 +- [ ] 不看需求文档，五秒内能说出这一页的对象、当前状态和主操作。 +- [ ] 比较发生在同一个地方，不需要跨标签页或跨页面记住某个值。 +- [ ] 每条信息只有一个权威位置，别处都指回去。 +- [ ] 密度与使用频次匹配，且没有出现超过相邻两档的情况。 +- [ ] 长文本、大数字和窄屏都不会把信息顺序打乱。 +- [ ] 对判断没有帮助的区块、字段、标签和按钮，都删掉了。 diff --git a/packages/docs/de/src/ranui/design-guides/index.md b/packages/docs/de/src/ranui/design-guides/index.md index 157218ef0..a893a5b89 100644 --- a/packages/docs/de/src/ranui/design-guides/index.md +++ b/packages/docs/de/src/ranui/design-guides/index.md @@ -6,7 +6,7 @@ description: 'Gestaltungsregeln für Oberflächen mit ranui: eine Rolle wählen Die Regeln, denen eine aus ranui-Komponenten gebaute Oberfläche folgen sollte, damit sie sich als **ein System** liest und nicht als Haufen von Teilen. -Auf dieser Seite geht es um **Urteilsvermögen**: zu welchem Token man greift und was vor der Auslieferung zu prüfen ist. Der Tokenkatalog selbst ist das [Designsystem](/de/src/ranui/design-system/); Umschalten und Überschreiben zur Laufzeit ist die [Themengestaltung](/de/src/ranui/theme/). Die vollständige, maschinell durchgesetzte Fassung dieser Regeln liegt im Repository als [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). +Auf dieser Seite geht es um **Urteilsvermögen**: zu welchem Token man greift und was vor der Auslieferung zu prüfen ist. Der Tokenkatalog selbst ist das [Designsystem](/de/src/ranui/design-system/); Umschalten und Überschreiben zur Laufzeit ist die [Themengestaltung](/de/src/ranui/theme/); welche Form die Seite vor alledem annimmt, ist die [Informationsarchitektur](/de/src/ranui/information-architecture/). Die vollständige, maschinell durchgesetzte Fassung dieser Regeln liegt im Repository als [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). > **Einsetzen, wenn** du eine Seite anlegst oder aus ``-Elementen eine Komponente auf Anwendungsebene baust und über eine Farbe, einen Abstand, eine Textgröße, einen Schatten oder eine Bewegungsdauer entscheiden musst. Die kurze Antwort ist immer dieselbe: **Wähle eine Rolle und lass das Token den Wert bestimmen.** diff --git a/packages/docs/de/src/ranui/design-system/index.md b/packages/docs/de/src/ranui/design-system/index.md index 030a4fe6d..412a296d2 100644 --- a/packages/docs/de/src/ranui/design-system/index.md +++ b/packages/docs/de/src/ranui/design-system/index.md @@ -6,13 +6,14 @@ description: 'Die Designsprache von ranui und die vollständige Token-Referenz: Die **Designsprache**, aus der ranui gebaut ist, und der **vollständige** Katalog der Tokens, die sie ausdrücken: jede globale `--ran-*`-Custom-Property, die die Bibliothek deklariert, samt ihrem Wert in beiden Themes. Komponenten lesen diese Tokens, statt Werte festzuschreiben — ein Token zu überschreiben gestaltet also alles um, was es verwendet. -Drei Seiten beantworten drei verschiedene Fragen, und sie sind bewusst getrennt: - -| Seite | Beantwortet | -| ----------------------------------------------------- | ------------------------------------------------------ | -| **Designsystem** (diese Seite) | _Was_ die Tokens sind: das Vokabular | -| [Gestaltungsleitlinien](/de/src/ranui/design-guides/) | _Wie man wählt_, wenn man eine Oberfläche baut | -| [Themengestaltung](/de/src/ranui/theme/) | _Wie man sie zur Laufzeit umschaltet und überschreibt_ | +Vier Seiten beantworten vier verschiedene Fragen, und sie sind bewusst getrennt: + +| Seite | Beantwortet | +| ------------------------------------------------------------------ | ------------------------------------------------------ | +| **Designsystem** (diese Seite) | _Was_ die Tokens sind: das Vokabular | +| [Gestaltungsleitlinien](/de/src/ranui/design-guides/) | _Wie man wählt_, wenn man eine Oberfläche baut | +| [Informationsarchitektur](/de/src/ranui/information-architecture/) | _Welche Form_ die Seite selbst haben soll | +| [Themengestaltung](/de/src/ranui/theme/) | _Wie man sie zur Laufzeit umschaltet und überschreibt_ | > **Einsetzen, wenn** du den Namen oder den Wert eines Tokens brauchst (eine Farbrolle, eine Abstandsstufe, eine Symbolgröße, eine Schattenstufe, eine Beschleunigungskurve) oder verstehen willst, warum die Skalen so geformt sind, wie sie sind. diff --git a/packages/docs/de/src/ranui/information-architecture/index.md b/packages/docs/de/src/ranui/information-architecture/index.md new file mode 100644 index 000000000..e621a53d9 --- /dev/null +++ b/packages/docs/de/src/ranui/information-architecture/index.md @@ -0,0 +1,235 @@ +--- +description: 'Wie eine informationsdichte Seite ihre Form bekommt, bevor das erste Token gewählt wird: die drei Fragen, die die Seite festlegen, das Skelett, das die Hauptfrage beantwortet, und der Platz jeder Art von Information.' +--- + +# Informationsarchitektur + +Welche **Form** eine Seite annimmt. Das wird vor jeder Farbe und jedem Abstand entschieden. + +Die übrigen Seiten dieses Abschnitts beantworten Fragen zu den Teilen. Diese beantwortet die +Frage davor: Bei allem, was der Bildschirm tragen muss, wozu ist die lesende Person gekommen, +und welche Anordnung lässt sie das tun? + +| Seite | Beantwortet | +| ------------------------------------------------- | ------------------------------------------------ | +| **Informationsarchitektur** (diese Seite) | _Welche Form_ die Seite haben soll | +| [Designsystem](/de/src/ranui/design-system/) | _Was_ die Tokens sind: das Vokabular | +| [Designrichtlinien](/de/src/ranui/design-guides/) | _Wie man wählt_, wenn man eine Oberfläche baut | +| [Themes](/de/src/ranui/theme/) | _Wie man zur Laufzeit wechselt und überschreibt_ | + +> **Dann lesen**, wenn eine Oberfläche entsteht, die mehrere Objekte, mehrere Zustände und +> deren Beziehungen zugleich tragen muss: eine Konsole, ein Dashboard, ein Backoffice, ein +> Arbeitsplatz, eine Monitoring-Seite. Nicht eine Landingpage oder ein Formular mit einer +> einzigen Conversion — die gewinnen oder verlieren über Überzeugung, nicht darüber, ob +> jemand in dichter Information richtig urteilen kann. + +Vollständige Daten sind keine gestaltete Seite. Eine Oberfläche kann jedes Feld zeigen, das +die API liefert, mit Filtern, Statusabzeichen und Massenaktionen, und die lesende Person weiß +trotzdem nicht, worauf sie zuerst schauen soll. Es fehlt keine Information, es fehlt die +Reihenfolge. + +## Drei Fragen vor jeder Komponente {#three-questions} + +1. **Was ist das eine, das beim Ankommen zu sehen sein muss?** Das ist die Hauptinformation + der Seite. +2. **Was muss sonst noch sichtbar sein, damit sie Sinn ergibt?** Verwandte Ressourcen, + verwandte Modelle, Kontext. +3. **Was geschieht danach?** Etwas beurteilen, etwas tun oder weiter nachdenken. + +Alle drei werden beantwortet, bevor die Komponentenliste aufgeht. Eine Seite mit drei klaren +Antworten wählt selten die falsche Form; eine Seite, die sie überspringt, ordnet sich am Ende +um die API-Antwort herum. + +**Eine Seite, ein Hauptmodell.** Unterstützende Modelle dürfen helfen, das Hauptmodell zu +verstehen oder zu bedienen. Sie dürfen ihm nicht den ersten Bildschirm streitig machen. + +## Die Form folgt der Aufgabe, nicht der Nutzlast {#shape} + +Zwei Abkürzungen erzeugen die meisten schlecht geformten Seiten: + +- Der Endpunkt lieferte ein Array, also wurde es eine Tabelle. +- Die Route trägt eine ID, also wurde es eine Detailseite. + +Keine von beiden ist ein Grund. Dasselbe Objekt nimmt unter einer anderen Aufgabe eine andere +Form an: ein Issue ist eine **Sammlung**, solange gesucht wird, ein **Statusfluss**, solange +daran gearbeitet wird, ein **Diskussionsstrang** beim Zusammenarbeiten und eine +**Ereignisfolge** beim Prüfen. Dass ein Datensatz ein Datumsfeld hat, sagt, dass in den Daten +ein Datum steht. Es sagt nicht, dass die Seite ein Kalender ist. + +## Das Skelett wählen {#skeletons} + +Wähle die Anordnung, die die Hauptfrage mit den wenigsten gedanklichen Umrechnungen +beantwortet. + +| Die Frage vor der lesenden Person | Was zusammenstehen muss | Skelett | +| ------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------- | +| Worin unterscheiden sich diese? | Die verglichenen Felder, in festen Spalten | Vergleichstabelle | +| Welches ist es, damit ich es öffnen kann? | Name, Kennung, Status | Liste / Ressourcenkatalog | +| Welches ist es, wenn das Bild es mir sagt? | Zuerst das Bild, darum Name und Felder | Kartenraster | +| Was ist dieses Objekt und wie steht es gerade? | Identität, Status, Hauptaktion, dann Attribute | Detailseite in Abschnitten | +| Wozu gehört es? | Pfad, Elternknoten, Geschwister | Hierarchiebaum | +| Was hängt davon ab, was bricht bei einer Änderung? | Vorgelagert und nachgelagert, Wirkungsradius | Nachbarschaftsliste | +| In welchem Schritt bin ich und was folgt? | Stufe, aktuelle Eingabe, die nächsten Schritte | Schrittfolge | +| In welcher Stufe steckt jedes Element, Verschieben _ist_ die Arbeit | Die Stufe als Spalte, Identität und Blocker auf der Karte | Kanban | +| Warum hängt es fest? | Stufenüberblick, dann Ergebnis je Schritt, dann Rohlog | Trace mit Drilldown | +| Ist es gesund, und wie weit reicht der Schaden? | Objektname, Status und das Ereignis, das ihn änderte | Statuswand | +| Was ist passiert, in welcher Reihenfolge, durch wen? | Zeitpunkt, Akteur, Ereignisart | Ereignis-Zeitleiste | +| Wer hat was gesagt und wie wurde geantwortet? | Verfasser, Beitrag, Antwortstruktur | Diskussionsstrang | +| Was hat sich geändert, vorher gegen nachher? | Die beiden Fassungen nebeneinander | Diff-Ansicht | +| Wie ist der Trend und wo sitzt die Anomalie? | Die Kennzahl, ihre Bezugslinie, der Weg ins Detail | Dashboard | +| Wann ist das belegt und wann kollidiert es? | Beginn, Ende und Dauer auf einer Achse | Kalender / Terminplanung | +| Was bearbeite ich als Nächstes? | Die Warteschlange auf der einen, das Element auf der anderen Seite | Master-Detail-Arbeitsplatz | +| Welche Regeln greifen und was betreffen sie? | Die Einstellung, ihr Geltungsbereich, ihre Folge | Konfigurationsformular | +| Was sagt dieser Text? | Der Fließtext der Reihe nach, daneben eine Gliederung | Fortlaufendes Dokument | +| Wo ist es? | Position, Grenzen, Verteilung | Karte / Zeichenfläche | + +### Paare, die verwechselt werden {#swapped-pairs} + +- **Zeitleiste oder Schritte.** Die Zeitleiste erzählt, was bereits geschehen ist, der Reihe + nach. Schritte sagen, wo man ist und was kommt. Sie sehen ähnlich aus und zeigen in + entgegengesetzte Zeitrichtungen. +- **Kanban oder Filter.** Kanban stimmt, wenn das Verschieben einer Karte _die_ Aktion ist. + Sind die Spalten gespeicherte Filterbedingungen, wurde ein Filter gebaut, der eine + Ziehbewegung kostet. +- **Kalender oder Zeitleiste.** Der Kalender beantwortet Belegung und Kollision, die Zeitleiste + Reihenfolge. Das Datum im Datensatz entscheidet nicht zwischen beiden, die Frage tut es. +- **Kartenraster oder Tabelle.** Entweder ist das Bild der Wiedererkennungsanker oder nicht. + Wird über Zahlen entschieden, begräbt ein Vorschaubild in der ersten Spalte genau die + Felder, an denen die Entscheidung hängt. +- **Graph oder Nachbarschaftsliste.** Zeichne den Graphen nur, wenn der Pfad oder die + Ausbreitung selbst das Urteil ist. Sonst liest sich eine gruppierte Liste von Vor- und + Nachgelagertem schneller. +- **Dokument oder Feldraster.** Fließtext, der der Reihe nach gelesen wird, bleibt Fließtext. + Jeden Absatz in eine Karte oder eine Schlüssel-Wert-Zeile zu hacken, zerstört genau das, was + ihn lesbar machte. + +Bau nicht alle drei Ansichten, nur weil es geht. Jede zusätzliche Ansicht ist ein weiterer +Filtersatz, eine weitere Statuszuordnung und ein weiterer Satz Aktionen, der synchron bleiben +muss. Füge die zweite hinzu, wenn die zweite Nutzung wirklich häufig ist, nicht vorsorglich. + +## Wo welche Information hingehört {#placement} + +| Information | Beantwortet | Gehört nach | Darf nicht landen | +| --------------- | -------------------------- | ------------------------------------------------------------------- | -------------------------------------------- | +| **Identität** | Was ist das? | Titel, Objektüberblick | In die letzte Spalte oder hinter einen Tab | +| **Status** | Wie steht es gerade? | Titel- oder Überblicksbereich | Nur in einem Detailfeld auffindbar | +| **Attribute** | Wie ist es beschaffen? | Detailtext, gruppiert, wie Menschen darüber denken | Flach in der Reihenfolge der API-Felder | +| **Beziehungen** | Womit hängt es zusammen? | Eigener Bereich oder Tab, Besitz, Abhängigkeit und Verweis getrennt | Vermischt in der Attributtabelle | +| **Änderungen** | Was ist anders als vorher? | Diff-Bereich, Zeitleiste | Nur als der neue Wert gezeigt | +| **Belege** | Warum trägt dieses Urteil? | Direkt neben dem Urteil, aufklappbar | Auf einer Logseite anderswo | +| **Aktionen** | Was kann ich jetzt tun? | Hauptaktion im Titelbereich, der Rest neben seinem Objekt | Vergraben unter „mehr“ | +| **Rückmeldung** | Was hat das bewirkt? | Neben der Aktion, mit erhaltenem Aufgabenkontext | Ein globaler Toast ohne Bezug zum Gegenstand | + +**Jede Tatsache hat genau einen maßgeblichen Ort.** Überall sonst stehen eine Zusammenfassung +oder ein Einstieg, der dorthin zurückführt. + +## Lesereihenfolge {#reading-order} + +```text +Seitenidentität +→ aktueller Status oder Ausnahme +→ Hauptaufgabe und Hauptaktion +→ die Information, die das Urteil braucht +→ Beziehungen, Änderungen, Belege +→ Nebeninformation und selten genutzte Aktionen +``` + +- **Eine visuelle Hauptüberschrift pro Seite.** Abschnittsüberschriften schreiten semantisch + voran, nicht über eine Schriftgröße, die Hierarchie vortäuscht. +- **Höchstens eine Hauptaktion pro Aufgabenbereich.** Der Hauptbutton ist der + wahrscheinlichste nächste Schritt, nicht der zerstörerischste. Gefährliches bekommt + Gefahrensemantik, nicht das größte visuelle Gewicht. +- Warn- und Gefahrenfarbe gehören Zuständen, die wirklich Aufmerksamkeit brauchen. Eine Seite, + auf der alles grün ist, hat ihr Signal bereits ausgegeben. +- Badges, Tags und Banner teilen sich ein Aufmerksamkeitsbudget. Hervorgehoben wird nur, was + eine Entscheidung ändern würde. + +## Dichte {#density} + +Dichte ist nicht, wie viele Bedienelemente pro Fläche passen, sondern wie viel _brauchbare_ +Information ein Blick mitnimmt. Engere Abstände heben die visuelle Dichte und lassen die +wirksame genau dort, wo sie war; irrelevante Felder zu entfernen und den Vergleich an einen +Ort zu legen, hebt die echte. + +| Stufe | Wo sie hingehört | Was sie einbringt | +| ------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | +| **Großzügig** | Erstnutzung, seltene Konfiguration, riskante Bestätigung | Raum zum Erklären, größere Gruppenabstände, sichtbare Wirkungsvorschau | +| **Standard** | Die meisten Listen, Details und Formulare | Das Standardgleichgewicht aus Überfliegbarkeit und Information je Bildschirm | +| **Kompakt** | Arbeitsplätze für Profis: Monitoring, Betrieb, Audit | Stabile Spaltenbreiten, kurze Texte, Tastatureffizienz, gespeicherte Ansichten | + +- Verwende auf einer Seite **höchstens zwei benachbarte Stufen**. Eine kompakte Tabelle in + einer Standardseite ist in Ordnung; dass jeder Bereich seinen eigenen Maßstab erfindet, + nicht. +- Kompakt heißt nicht „Schrift und Trefferflächen zusammen schrumpfen“. Innenabstand und + Zeilenhöhe dürfen enger werden; Lesbarkeit des Fließtexts, sichtbarer Fokusring und + Zeigerzielgröße nicht. +- Für Profis bringen Spaltenverwaltung, gespeicherte Ansichten, Massenaktionen und Kürzel mehr + als auf einmal mehr zu zeigen. + +## Aufgabenkontext halten {#context} + +Steht das Skelett, wird entschieden, wo der unterstützende Inhalt lebt: + +| Die lesende Person… | bekommt | +| --------------------------------------------------- | --------------------------------------------------------------------------- | +| wechselt ständig zwischen Objekten oder Belegen | eine Master-Detail-Teilung: die Warteschlange links, das Element rechts | +| wirft einen Blick auf etwas Leichtes und Flüchtiges | eine aufklappbare Zeile (`r-disclosure-row`) oder ein Popover (`r-popover`) | +| arbeitet an etwas Teilbarem oder Platzbedürftigem | eine eigene Route | +| bestätigt etwas oder tippt ein einzelnes Feld | einen Dialog (`r-modal`) | + +**Ein Dialog ist keine Navigationsebene.** Alles, was einen kopierbaren Link, Verlauf, einen +Vergleich nebeneinander oder Arbeit braucht, die einen Reload übersteht, bekommt eine Route. + +## Was ranui auf dieser Ebene beisteuert {#with-ranui} + +ranui bezieht bewusst keine Position zur Seitenform: es liefert Primitive und Tokens, keine +Seitenvorlagen. Was es hier gibt: + +- `r-section` für die Bänder, in die ein Skelett zerfällt, `r-card` für einen wirklich + eigenständigen wiederholten Eintrag. Nie eine Karte in einer Karte; Formularfelder werden + mit einer Überschrift oder einer Trennlinie gruppiert. +- `r-tabs` für **gleichrangige Ansichten eines Objekts** (seine Diskussion, seine Prüfungen, + sein Diff), nie für unverwandte Module: dafür ist die Navigation da. +- `r-disclosure-row` für schrittweise Offenlegung, `r-popover` und `r-dropdown` für flüchtigen + Kontext, `r-modal` nur für das, was die Tabelle oben ihm erlaubt. +- `r-state-dot` für Status, immer mit Beschriftung: + [nie allein über Farbe](/de/src/ranui/design-guides/#accessibility). +- `r-skeleton`, solange der erste Bildschirm lädt, `r-progress` für alles, was lang genug + dauert, um jemanden zweifeln zu lassen, `r-message` für das Ergebnis. + +In ranui gibt es **keine Tabelle, keinen Baum, keinen Kalender, kein Kanban und keine +Zeitleiste**. Wer eines baut, baut es auf [den Tokens](/de/src/ranui/design-system/) und den +[Designrichtlinien](/de/src/ranui/design-guides/) auf statt auf einem zweiten visuellen +System: Abstände aus der Skala, Schrift nach Rolle, Farbe aus semantischen Tokens, jeder +erreichbare Zustand entworfen. + +## Antimuster {#anti-patterns} + +- Jedes Feld, das der Endpunkt liefert, wird eine Detailzeile, sodass Identität, Status, + Beziehungen und Belege alle mit demselben Gewicht ankommen. +- Hierarchie aus Karten, Farbe und dekorativen Abständen hergestellt, ohne zu sagen, was + zuerst zu lesen ist. +- Mehrere Aktionen teilen sich den Hauptstil, oder eine seltene Aktion sitzt im Titelbereich. +- Status, Attribute, Beziehungen und Änderungen in einer Tabelle vermischt, sodass sich + nirgends ein Vergleich bilden lässt. +- Ein Beziehungsgraph, wo jemand nur einen Namen und einen Status nachschlagen wollte. +- Ein Dialog, der einen langen Ablauf, einen Vergleich oder etwas trägt, dessen Link jemand + verschicken will. +- Derselbe Satz in Titel, Überblick, Tab-Beschriftung und Tabelle wiederholt, ohne irgendwo + etwas Neues zu ergänzen. + +## Checkliste vor dem Ausliefern einer Seite + +- [ ] Hauptinformation, unterstützende Information und die nächste Aktion sind aufgeschrieben. +- [ ] Das Skelett wurde aus der Frage gewählt, nicht aus der Form der Antwort. +- [ ] Die Seite hat ein Hauptmodell; unterstützende Ansichten dienen ihm, statt zu + konkurrieren. +- [ ] Ohne Spezifikation sind Objekt, Status und Hauptaktion in fünf Sekunden klar. +- [ ] Der Vergleich passiert an einem Ort; nichts muss über Tabs oder Seiten hinweg erinnert + werden. +- [ ] Jede Tatsache hat einen maßgeblichen Ort, und überall sonst wird darauf verlinkt. +- [ ] Die Dichte passt zur Nutzungshäufigkeit, und es treten nicht mehr als zwei benachbarte + Stufen auf. +- [ ] Langer Text, große Zahlen und ein schmaler Viewport brechen die Informationsordnung nicht. +- [ ] Jeder Block, jedes Feld, jedes Tag und jeder Button ohne Beitrag zum Urteil wurde + gelöscht. diff --git a/packages/docs/es/src/ranui/design-guides/index.md b/packages/docs/es/src/ranui/design-guides/index.md index 1536def16..5f37f0317 100644 --- a/packages/docs/es/src/ranui/design-guides/index.md +++ b/packages/docs/es/src/ranui/design-guides/index.md @@ -6,7 +6,7 @@ description: 'Reglas de diseño para construir pantallas con ranui: elige un rol Las reglas que debe seguir una pantalla hecha con componentes de ranui para que se lea como **un sistema** y no como un montón de piezas. -Esta página trata del **criterio**: a qué token echar mano, qué comprobar antes de publicar. El catálogo de tokens en sí es el [sistema de diseño](/es/src/ranui/design-system/); cambiar y sobrescribir en tiempo de ejecución es la [tematización](/es/src/ranui/theme/). La versión completa de estas reglas, la que se comprueba automáticamente, vive en el repositorio como [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). +Esta página trata del **criterio**: a qué token echar mano, qué comprobar antes de publicar. El catálogo de tokens en sí es el [sistema de diseño](/es/src/ranui/design-system/); cambiar y sobrescribir en tiempo de ejecución es la [tematización](/es/src/ranui/theme/); qué forma toma la página antes de todo eso es la [arquitectura de información](/es/src/ranui/information-architecture/). La versión completa de estas reglas, la que se comprueba automáticamente, vive en el repositorio como [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). > **Úsalas cuando** estés maquetando una página o construyendo un componente propio a partir de elementos `` y tengas que decidir un color, un espacio, un tamaño de texto, una sombra o una duración de animación. La respuesta corta es siempre la misma: **elige un rol y deja que el token ponga el valor.** diff --git a/packages/docs/es/src/ranui/design-system/index.md b/packages/docs/es/src/ranui/design-system/index.md index e77535b63..f0c8622aa 100644 --- a/packages/docs/es/src/ranui/design-system/index.md +++ b/packages/docs/es/src/ranui/design-system/index.md @@ -6,13 +6,14 @@ description: 'El lenguaje de diseño de ranui y la referencia completa de sus to El **lenguaje de diseño** con el que está hecho ranui, y el catálogo **completo** de los tokens que lo expresan: todas las propiedades personalizadas `--ran-*` globales que declara la biblioteca, con su valor en ambos temas. Los componentes leen estos tokens en vez de escribir valores a mano, así que sobrescribir uno reestiliza todo lo que lo consume. -Tres páginas responden a tres preguntas distintas, y están separadas a propósito: - -| Página | Responde | -| ------------------------------------------------ | ---------------------------------------------------------- | -| **Sistema de diseño** (esta página) | _Qué_ son los tokens: el vocabulario | -| [Pautas de diseño](/es/src/ranui/design-guides/) | _Cómo elegir_ entre ellos al construir una pantalla | -| [Tematización](/es/src/ranui/theme/) | _Cómo cambiarlos y sobrescribirlos_ en tiempo de ejecución | +Cuatro páginas responden a cuatro preguntas distintas, y están separadas a propósito: + +| Página | Responde | +| ---------------------------------------------------------------------- | ---------------------------------------------------------- | +| **Sistema de diseño** (esta página) | _Qué_ son los tokens: el vocabulario | +| [Pautas de diseño](/es/src/ranui/design-guides/) | _Cómo elegir_ entre ellos al construir una pantalla | +| [Arquitectura de información](/es/src/ranui/information-architecture/) | _Qué forma_ debe tomar la página misma | +| [Tematización](/es/src/ranui/theme/) | _Cómo cambiarlos y sobrescribirlos_ en tiempo de ejecución | > **Úsala cuando** necesites el nombre o el valor de un token (un rol de color, un paso de espacio, un tamaño de icono, un nivel de sombra, una curva de aceleración) o quieras entender por qué las escalas tienen la forma que tienen. diff --git a/packages/docs/es/src/ranui/information-architecture/index.md b/packages/docs/es/src/ranui/information-architecture/index.md new file mode 100644 index 000000000..9dd3b8e57 --- /dev/null +++ b/packages/docs/es/src/ranui/information-architecture/index.md @@ -0,0 +1,225 @@ +--- +description: 'Cómo dar forma a una página de alta densidad antes de elegir el primer token: las tres preguntas que fijan la página, el esqueleto que responde a la principal y dónde va cada tipo de información.' +--- + +# Arquitectura de información + +Qué **forma** toma una página. Se decide antes que cualquier color o espacio. + +Las demás páginas de esta sección responden preguntas sobre las piezas. Esta responde la que +viene antes: con todo lo que la pantalla tiene que sostener, ¿a qué vino quien la abre y qué +disposición le permite hacerlo? + +| Página | Responde | +| ------------------------------------------------- | ---------------------------------------------------------- | +| **Arquitectura de información** (esta página) | _Qué forma_ debe tomar la página | +| [Sistema de diseño](/es/src/ranui/design-system/) | _Qué_ son los tokens: el vocabulario | +| [Pautas de diseño](/es/src/ranui/design-guides/) | _Cómo elegir_ entre ellos al construir una pantalla | +| [Temas](/es/src/ranui/theme/) | _Cómo cambiarlos y sobrescribirlos_ en tiempo de ejecución | + +> **Úsalo cuando** empieces una pantalla que debe sostener varios objetos, varios estados y +> las relaciones entre ellos: una consola, un panel, un backoffice, un puesto de trabajo, una +> página de monitoreo. No una landing ni un formulario de conversión única, que se ganan o se +> pierden por persuasión y no por si alguien puede juzgar bien entre información densa. + +Tener todos los datos no es tener la página diseñada. Una pantalla puede mostrar cada campo +que devuelve la API, con filtros, etiquetas de estado y acciones masivas, y aun así dejar a +quien la lee sin saber qué mirar primero. No falta información: falta el orden. + +## Tres preguntas antes de cualquier componente {#three-questions} + +1. **¿Qué es lo único que debe verse al llegar?** Esa es la información principal de la + página. +2. **¿Qué más tiene que estar visible para entenderla?** Los recursos relacionados, los + modelos relacionados, el contexto. +3. **¿Qué hará después?** Juzgar algo, actuar sobre algo o seguir pensando en algo. + +Responde las tres antes de abrir la lista de componentes. Una página con esas tres respuestas +claras rara vez elige mal la forma; una que las saltea termina organizada alrededor de la +respuesta de la API. + +**Una página, un modelo principal.** Los modelos de apoyo pueden ayudar a entender o a operar +el principal. No pueden disputarle la primera pantalla. + +## La forma sigue a la tarea, no al payload {#shape} + +Dos atajos producen casi todas las páginas mal formadas: + +- El endpoint devolvió un array, así que se volvió una tabla. +- La ruta lleva un ID, así que se volvió una página de detalle. + +Ninguno es una razón. El mismo objeto toma otra forma bajo otra tarea: un issue es una +**colección** mientras buscas, un **flujo de estados** mientras lo trabajas, un **hilo de +discusión** mientras colaboras y una **secuencia de eventos** mientras auditas. Que un +registro tenga fecha dice que hay una fecha en los datos. No dice que la página sea un +calendario. + +## Cómo elegir el esqueleto {#skeletons} + +Elige la disposición que responde la pregunta principal con menos conversiones mentales. + +| La pregunta que tiene delante | Qué debe quedar junto | Esqueleto | +| -------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------- | +| ¿En qué se diferencian estos? | Los campos comparados, en columnas fijas | Tabla de comparación | +| ¿Cuál es, para poder abrirlo? | Nombre, identificador, estado | Lista / catálogo de recursos | +| ¿Cuál es, si la imagen me lo dice? | Primero la imagen, alrededor el nombre y los campos | Rejilla de tarjetas | +| ¿Qué es este objeto y cómo está ahora? | Identidad, estado, acción principal y luego atributos | Detalle por secciones | +| ¿A qué pertenece? | Ruta, padre, hermanos | Árbol jerárquico | +| ¿Qué depende de esto y qué se rompe si cambia? | Aguas arriba y aguas abajo, radio de impacto | Lista de adyacencia | +| ¿En qué paso voy y qué sigue? | Etapa, entrada actual, los pasos posteriores | Flujo por pasos | +| ¿En qué etapa está cada ítem, si moverlo _es_ el trabajo | La etapa como columna, identidad y bloqueos en la tarjeta | Kanban | +| ¿Por qué se detuvo? | Resumen de etapa, luego resultado por paso, luego el log crudo | Traza con profundización | +| ¿Está sano y hasta dónde llega el daño? | Nombre del objeto, estado y el evento que lo cambió | Muro de estado | +| ¿Qué pasó, en qué orden y por obra de quién? | Momento, actor, tipo de evento | Línea de tiempo de eventos | +| ¿Quién dijo qué y cómo se respondió? | Autor, mensaje, estructura de respuestas | Hilo de discusión | +| ¿Qué cambió, antes contra después? | Las dos versiones, lado a lado | Vista de diferencias | +| ¿Cuál es la tendencia y dónde está la anomalía? | La métrica, su línea base, la entrada al detalle | Panel de indicadores | +| ¿Cuándo está ocupado y cuándo choca? | Inicio, fin y duración sobre un mismo eje | Calendario / agenda | +| ¿Qué atiendo a continuación? | La cola de un lado, el ítem del otro | Banco de trabajo maestro-detalle | +| ¿Qué reglas aplican y qué afectan? | El ajuste, su alcance, su consecuencia | Formulario de configuración | +| ¿Qué dice este texto? | El cuerpo en orden, con un índice al lado | Documento continuo | +| ¿Dónde está? | Posición, límites, distribución | Mapa / lienzo | + +### Pares que se confunden {#swapped-pairs} + +- **Línea de tiempo o pasos.** La línea de tiempo cuenta lo que ya ocurrió, en orden. Los + pasos dicen dónde estás y qué viene. Se parecen y apuntan en direcciones opuestas del tiempo. +- **Kanban o filtro.** El kanban corresponde cuando mover una tarjeta _es_ la acción. Si las + columnas son condiciones de filtrado guardadas, construiste un filtro que cuesta un arrastre. +- **Calendario o línea de tiempo.** El calendario responde ocupación y choque; la línea de + tiempo responde orden. La fecha del registro no elige entre ambos; la pregunta sí. +- **Rejilla de tarjetas o tabla.** O la imagen es el ancla de reconocimiento o no lo es. Si la + elección se hace comparando números, una miniatura en la primera columna entierra los campos + que deciden. +- **Grafo o lista de adyacencia.** Dibuja el grafo solo cuando el camino o la propagación sean + el juicio en sí. Si no, una lista agrupada de aguas arriba y aguas abajo se lee más rápido. +- **Documento o cuadrícula de campos.** La prosa que se lee en orden sigue siendo prosa. + Trocear cada párrafo en una tarjeta o en un par clave-valor destruye lo que la hacía legible. + +No construyas las tres vistas porque puedes. Cada vista extra es otro juego de filtros, otro +mapeo de estados y otro conjunto de acciones que mantener en sincronía. Agrega la segunda +cuando el segundo uso sea realmente frecuente, no por si acaso. + +## Dónde va cada tipo de información {#placement} + +| Información | Responde | Va en | No debe terminar en | +| --------------------- | ------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------- | +| **Identidad** | ¿Qué es esto? | Título, resumen del objeto | La última columna o detrás de una pestaña | +| **Estado** | ¿Cómo está ahora? | Zona de título o de resumen | Solo localizable en un campo de detalle | +| **Atributos** | ¿Cómo es? | Cuerpo del detalle, agrupado como lo piensa la gente | Aplanado en el orden de los campos de la API | +| **Relaciones** | ¿Con qué se conecta? | Su propia zona o pestaña, con pertenencia, dependencia y referencia distinguidas | Mezclado en la tabla de atributos | +| **Cambios** | ¿Qué difiere de antes? | Zona de diferencias, línea de tiempo | Mostrado solo como el valor nuevo | +| **Evidencia** | ¿Por qué ese juicio es seguro? | Junto al juicio, desplegable | Una página de logs en otra parte | +| **Acciones** | ¿Qué puedo hacer ahora? | La principal en la zona de título, el resto junto a su objeto | Enterradas bajo «más» | +| **Retroalimentación** | ¿Qué hizo eso? | Junto a la acción, conservando el contexto de la tarea | Un aviso global desligado de aquello que trata | + +**Cada dato tiene exactamente un lugar autoritativo.** En los demás va un resumen o una +entrada que enlaza de vuelta. + +## Orden de lectura {#reading-order} + +```text +Identidad de la página +→ estado actual o excepción +→ tarea principal y acción principal +→ la información que el juicio necesita +→ relaciones, cambios, evidencia +→ información secundaria y acciones poco frecuentes +``` + +- **Un solo encabezado principal visual por página.** Los encabezados de sección avanzan por + semántica, no por un tamaño de fuente que finge jerarquía. +- **Como mucho una acción principal por zona de tarea.** El botón principal es el siguiente + paso más probable, no el más destructivo. Lo peligroso lleva semántica de peligro, no el + mayor peso visual. +- El color de aviso y de peligro es para estados que de verdad requieren atención. Una página + toda en verde ya gastó su señal. +- Insignias, etiquetas y banners comparten un mismo presupuesto de atención. Destaca solo lo + que cambiaría una decisión. + +## Densidad {#density} + +La densidad no es cuántos controles caben por centímetro cuadrado, sino cuánta información +_utilizable_ se lleva alguien en una mirada. Apretar el espaciado sube la densidad visual y +deja la efectiva donde estaba; quitar campos irrelevantes y poner la comparación en un solo +sitio sube la de verdad. + +| Nivel | Dónde corresponde | Qué compra | +| ------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| **Holgada** | Primer uso, configuración poco frecuente, confirmación de riesgo | Espacio para explicar, grupos más separados, vista previa del impacto | +| **Estándar** | La mayoría de listas, detalles y formularios | El equilibrio por defecto entre escaneo e información por pantalla | +| **Compacta** | Puestos de trabajo expertos: monitoreo, operación, auditoría | Anchos de columna estables, textos cortos, eficiencia de teclado, vistas guardadas | + +- Usa **como mucho dos niveles contiguos** en una página. Una tabla compacta dentro de una + página estándar está bien; que cada zona invente su propia escala, no. +- Compacto no es «encoger el texto y las zonas de toque a la vez». El relleno del contenedor y + la altura de línea pueden ajustarse; la legibilidad del cuerpo, el anillo de foco visible y + el tamaño del objetivo puntero, no. +- Para usuarios expertos, la gestión de columnas, las vistas guardadas, las acciones masivas y + los atajos rinden más que mostrar más de una vez. + +## Mantener el contexto de la tarea {#context} + +Con el esqueleto elegido, decide dónde vive el contenido de apoyo: + +| Quien lee está… | Dale | +| ----------------------------------------------------- | -------------------------------------------------------------------- | +| Alternando entre objetos o evidencias una y otra vez | Una división maestro-detalle: la cola a un lado, el ítem al otro | +| Echando un vistazo a algo ligero y pasajero | Una fila desplegable (`r-disclosure-row`) o un popover (`r-popover`) | +| Trabajando en algo compartible o que necesita espacio | Su propia ruta | +| Confirmando, o escribiendo un solo campo | Un modal (`r-modal`) | + +**Un modal no es una capa de navegación.** Todo lo que necesite un enlace copiable, historial, +una comparación lado a lado o trabajo que sobreviva a una recarga, lleva ruta. + +## Qué aporta ranui en esta capa {#with-ranui} + +ranui es deliberadamente neutral sobre la forma de la página: entrega primitivas y tokens, no +plantillas. Lo que sí te da aquí: + +- `r-section` para las bandas en que se divide un esqueleto y `r-card` para una entrada + repetida genuinamente independiente. Nunca una tarjeta dentro de otra; agrupa campos de + formulario con un encabezado o un separador. +- `r-tabs` para **vistas pares de un mismo objeto** (su conversación, sus verificaciones, su + diff), nunca para módulos sin relación: de eso se encarga la navegación. +- `r-disclosure-row` para la divulgación progresiva, `r-popover` y `r-dropdown` para contexto + pasajero, y `r-modal` solo para lo que la tabla anterior le permite. +- `r-state-dot` para el estado, siempre con su etiqueta: + [nunca solo color](/es/src/ranui/design-guides/#accessibility). +- `r-skeleton` mientras carga la primera pantalla, `r-progress` para lo bastante largo como + para hacer dudar a alguien, `r-message` para el resultado. + +En ranui **no hay tabla, árbol, calendario, kanban ni línea de tiempo**. Cuando construyas +una, hazlo sobre [los tokens](/es/src/ranui/design-system/) y las +[pautas de diseño](/es/src/ranui/design-guides/) en lugar de levantar un segundo sistema +visual: el espaciado de la escala, la tipografía por rol, el color de los tokens semánticos y +todos los estados alcanzables diseñados. + +## Antipatrones {#anti-patterns} + +- Cada campo que devuelve el endpoint se convierte en una fila de detalle, así que identidad, + estado, relaciones y evidencia llegan con el mismo peso. +- Jerarquía fabricada con tarjetas, color y espaciado decorativo, sin decir nada sobre qué + leer primero. +- Varias acciones compartiendo el estilo principal, o una acción poco frecuente instalada en + la zona de título. +- Estado, atributos, relaciones y cambios mezclados en una tabla, de modo que no se puede + formar ninguna comparación. +- Un grafo de relaciones cuando solo se quería consultar un nombre y un estado. +- Un modal cargando un flujo largo, una comparación o algo cuyo enlace alguien querrá enviar. +- La misma frase repetida en el título, el resumen, la pestaña y la tabla, sin aportar nada + nuevo en ninguno. + +## Lista de verificación antes de publicar una página + +- [ ] La información principal, la de apoyo y la siguiente acción están escritas. +- [ ] El esqueleto se eligió desde la pregunta, no desde la forma de la respuesta. +- [ ] La página tiene un modelo principal y las vistas de apoyo lo sirven en vez de competir. +- [ ] Sin leer la especificación, el objeto, su estado y la acción principal se entienden en + cinco segundos. +- [ ] La comparación ocurre en un solo sitio; nada obliga a recordar algo entre pestañas o + páginas. +- [ ] Cada dato tiene un lugar autoritativo y los demás enlazan a él. +- [ ] La densidad corresponde a la frecuencia de uso y no aparecen más de dos niveles contiguos. +- [ ] Textos largos, números grandes y un viewport angosto no rompen el orden de la información. +- [ ] Se eliminó todo bloque, campo, etiqueta y botón que no ayuda a juzgar. diff --git a/packages/docs/fa/src/ranui/design-guides/index.md b/packages/docs/fa/src/ranui/design-guides/index.md index 6cd347826..4c9437861 100644 --- a/packages/docs/fa/src/ranui/design-guides/index.md +++ b/packages/docs/fa/src/ranui/design-guides/index.md @@ -6,7 +6,7 @@ description: 'قواعد طراحی برای ساختن صفحه با ranui: ن قواعدی که صفحه‌ای ساخته‌شده از کامپوننت‌های ranui باید رعایت کند تا **یک سامانه** خوانده شود، نه تلی از قطعه. -موضوع این صفحه **قضاوت** است: سراغ کدام توکن بروید و پیش از انتشار چه چیزی را بررسی کنید. خودِ فهرست توکن‌ها [سیستم طراحی](/fa/src/ranui/design-system/) است و تعویض و بازنویسی در زمان اجرا [پوسته‌بندی](/fa/src/ranui/theme/). نسخه کامل و ماشین‌اجباریِ این قواعد در مخزن است، در [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). +موضوع این صفحه **قضاوت** است: سراغ کدام توکن بروید و پیش از انتشار چه چیزی را بررسی کنید. خودِ فهرست توکن‌ها [سیستم طراحی](/fa/src/ranui/design-system/) است و تعویض و بازنویسی در زمان اجرا [پوسته‌بندی](/fa/src/ranui/theme/). اینکه صفحه پیش از همهٔ این‌ها چه شکلی می‌گیرد، [معماری اطلاعات](/fa/src/ranui/information-architecture/) است. نسخه کامل و ماشین‌اجباریِ این قواعد در مخزن است، در [`packages/ranui/docs/DESIGN.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md). > **کجا به کار می‌آید:** وقتی صفحه‌ای را می‌چینید یا از عناصر `` کامپوننتی در سطح برنامه می‌سازید و باید درباره یک رنگ، یک فاصله، یک اندازه متن، یک سایه یا یک مدت حرکت تصمیم بگیرید. پاسخ کوتاه همیشه یکی است: **نقش را انتخاب کنید و مقدار را به توکن بسپارید.** diff --git a/packages/docs/fa/src/ranui/design-system/index.md b/packages/docs/fa/src/ranui/design-system/index.md index e1e3b450c..dfa765096 100644 --- a/packages/docs/fa/src/ranui/design-system/index.md +++ b/packages/docs/fa/src/ranui/design-system/index.md @@ -6,13 +6,14 @@ description: 'زبان طراحی ranui و مرجع کامل توکن‌هایش **زبان طراحی**ای که ranui از آن ساخته شده، و فهرست **کامل** توکن‌هایی که آن را بیان می‌کنند: هر ویژگی سفارشی سراسری `--ran-*` که کتابخانه اعلام می‌کند، با مقدارش در هر دو پوسته. کامپوننت‌ها به‌جای نوشتن مقدار ثابت این توکن‌ها را می‌خوانند، پس بازنویسی یک توکن، ظاهر هر چیزی را که آن را مصرف می‌کند عوض می‌کند. -سه صفحه به سه پرسش متفاوت پاسخ می‌دهند و عمداً از هم جدا مانده‌اند: - -| صفحه | پاسخ می‌دهد به | -| --------------------------------------------- | ------------------------------------------------ | -| **سیستم طراحی** (همین صفحه) | توکن‌ها _چیستند_: واژگان | -| [راهنمای طراحی](/fa/src/ranui/design-guides/) | هنگام ساختن یک صفحه، _چگونه_ میانشان انتخاب کنیم | -| [پوسته‌بندی](/fa/src/ranui/theme/) | _چگونه_ در زمان اجرا عوض و بازنویسی‌شان کنیم | +چهار صفحه به چهار پرسش متفاوت پاسخ می‌دهند و عمداً از هم جدا مانده‌اند: + +| صفحه | پاسخ می‌دهد به | +| --------------------------------------------------------- | ------------------------------------------------ | +| **سیستم طراحی** (همین صفحه) | توکن‌ها _چیستند_: واژگان | +| [راهنمای طراحی](/fa/src/ranui/design-guides/) | هنگام ساختن یک صفحه، _چگونه_ میانشان انتخاب کنیم | +| [معماری اطلاعات](/fa/src/ranui/information-architecture/) | خودِ صفحه باید _چه شکلی_ داشته باشد | +| [پوسته‌بندی](/fa/src/ranui/theme/) | _چگونه_ در زمان اجرا عوض و بازنویسی‌شان کنیم | > **کجا به کار می‌آید:** وقتی نام یا مقدار یک توکن را لازم دارید (نقش یک رنگ، پله‌ای از فاصله، اندازه یک آیکن، رده‌ای از سایه، منحنی شتاب) یا می‌خواهید بدانید چرا مقیاس‌ها همین شکل را دارند. diff --git a/packages/docs/fa/src/ranui/information-architecture/index.md b/packages/docs/fa/src/ranui/information-architecture/index.md new file mode 100644 index 000000000..643e33b2e --- /dev/null +++ b/packages/docs/fa/src/ranui/information-architecture/index.md @@ -0,0 +1,207 @@ +--- +description: 'چگونه پیش از انتخاب نخستین توکن، شکل یک صفحهٔ پرتراکم را تعیین کنیم: سه پرسشی که صفحه را تثبیت می‌کند، اسکلتی که به پرسش اصلی پاسخ می‌دهد، و جای هر گونه اطلاعات.' +--- + +# معماری اطلاعات + +اینکه صفحه چه **شکلی** می‌گیرد. این پیش از هر رنگ و هر فاصله تصمیم گرفته می‌شود. + +صفحه‌های دیگر این بخش به پرسش‌هایی دربارهٔ قطعه‌ها پاسخ می‌دهند. این صفحه به پرسشی پاسخ می‌دهد که +پیش از آن‌ها می‌آید: با این همه چیزی که باید روی صفحه جا بگیرد، خواننده برای چه آمده و کدام چیدمان +می‌گذارد کارش را بکند؟ + +| صفحه | پاسخ می‌دهد | +| --------------------------------------------- | -------------------------------------------- | +| **معماری اطلاعات** (همین صفحه) | صفحه باید _چه شکلی_ داشته باشد | +| [سیستم طراحی](/fa/src/ranui/design-system/) | توکن‌ها _چیستند_: واژگان | +| [راهنمای طراحی](/fa/src/ranui/design-guides/) | هنگام ساختن صفحه _چگونه میانشان انتخاب کنیم_ | +| [پوسته‌ها](/fa/src/ranui/theme/) | در زمان اجرا _چگونه عوض و بازنویسی کنیم_ | + +> **وقتی به کار می‌آید** که صفحه‌ای را آغاز می‌کنید که باید چند شیء، چند وضعیت و نسبت‌های میانشان را +> با هم نگه دارد: یک کنسول، یک داشبورد، یک پنل مدیریت، یک میز کار، یک صفحهٔ پایش. نه یک صفحهٔ فرود و +> نه فرمی با یک تبدیل واحد؛ سرنوشت آن‌ها را اقناع تعیین می‌کند، نه اینکه کسی در انبوه اطلاعات درست +> داوری کند یا نه. + +کاملِ داده یعنی طراحی‌شدنِ صفحه نیست. صفحه‌ای می‌تواند همهٔ فیلدهایی را که API برمی‌گرداند نشان دهد، +با فیلتر و برچسب وضعیت و عملیات گروهی، و خواننده باز هم نداند اول به کجا نگاه کند. آنچه کم است +اطلاعات نیست، ترتیب است. + +## سه پرسش پیش از هر مؤلفه {#three-questions} + +1. **آن یک چیزی که خواننده در بدو ورود باید ببیند چیست؟** این اطلاعات اصلی صفحه است. +2. **برای فهمیدنش چه چیز دیگری باید دیده شود؟** منابع مرتبط، مدل‌های مرتبط، زمینه. +3. **بعد از آن چه می‌کند؟** چیزی را داوری می‌کند، کاری انجام می‌دهد، یا به فکر کردن ادامه می‌دهد. + +هر سه را پیش از باز کردن فهرست مؤلفه‌ها پاسخ دهید. صفحه‌ای که این سه پاسخ را روشن دارد کمتر شکل را +اشتباه می‌گیرد؛ صفحه‌ای که از آن‌ها می‌گذرد سرانجام حول پاسخ API سامان می‌گیرد. + +**هر صفحه، یک مدل اصلی.** مدل‌های پشتیبان می‌توانند به فهم یا کار با مدل اصلی کمک کنند، اما نباید +بر سر نمای نخست با آن رقابت کنند. + +## شکل از وظیفه پیروی می‌کند، نه از داده بازگشتی {#shape} + +بیشتر صفحه‌های بدشکل از این دو میان‌بر زاده می‌شوند: + +- سرویس یک آرایه برگرداند، پس جدول شد. +- مسیر یک شناسه دارد، پس صفحهٔ جزئیات شد. + +هیچ‌کدام دلیل نیست. همان شیء زیر وظیفه‌ای دیگر شکلی دیگر می‌گیرد: یک ایشیو هنگام جست‌وجو یک +**مجموعه** است، هنگام رسیدگی یک **جریان وضعیت**، هنگام همکاری یک **رشتهٔ گفت‌وگو**، و هنگام ممیزی یک +**توالی رویداد**. اینکه رکورد فیلد تاریخ دارد یعنی در داده تاریخی هست؛ یعنی این نیست که صفحه تقویم است. + +## انتخاب اسکلت بیان {#skeletons} + +چیدمانی را انتخاب کنید که با کمترین تبدیل ذهنی به پرسش اصلی پاسخ می‌دهد. + +| پرسشی که پیش روی خواننده است | چه چیزهایی باید کنار هم بنشینند | اسکلت بیان | +| ----------------------------------------------------- | --------------------------------------------- | --------------------- | +| این‌ها در چه چیزی فرق دارند؟ | فیلدهای مقایسه‌شونده، در ستون‌های ثابت | جدول مقایسه | +| کدام یکی است، تا بازش کنم؟ | نام، شناسه، وضعیت | فهرست / کاتالوگ منابع | +| کدام یکی است، وقتی تصویر می‌گویدش؟ | اول تصویر، نام و فیلدها گرداگردش | شبکهٔ کارت‌ها | +| این شیء چیست و اکنون در چه حال است؟ | هویت، وضعیت، کنش اصلی، و سپس ویژگی‌ها | جزئیات بخش‌بندی‌شده | +| به کجا تعلق دارد؟ | مسیر، والد، هم‌ترازها | درخت سلسله‌مراتبی | +| چه چیزی به آن وابسته است و تغییرش چه را می‌شکند؟ | بالادست و پایین‌دست، دامنهٔ اثر | فهرست مجاورت | +| در کدام گامم و بعد چیست؟ | مرحله، ورودی کنونی، گام‌های پس از آن | جریان گام‌به‌گام | +| هر مورد در کدام مرحله است، و جابه‌جایی _خودِ_ کار است | ستون همان مرحله، هویت و موانع روی کارت | کانبان | +| چرا گیر کرده است؟ | خلاصهٔ مرحله، سپس نتیجهٔ هر گام، سپس لاگ خام | ردیابی با ریزکاوی | +| سالم است و دامنهٔ آسیب تا کجاست؟ | نام شیء، وضعیت، و رویدادی که وضعیت را عوض کرد | دیوار وضعیت | +| چه رخ داد، به چه ترتیب، به دست چه کسی؟ | زمان، کنشگر، نوع رویداد | خط زمانی رویدادها | +| چه کسی چه گفت و چگونه پاسخ داده شد؟ | نویسنده، پیام، ساختار پاسخ‌ها | رشتهٔ گفت‌وگو | +| چه تغییر کرد، پیش در برابر پس؟ | دو نسخه، کنار هم | نمای تفاوت | +| روند چگونه است و ناهنجاری کجاست؟ | سنجه، خط مبنایش، ورودی به جزئیات | داشبورد | +| این بازه کِی اشغال است و کِی تداخل می‌کند؟ | آغاز، پایان و مدت روی یک محور | تقویم / زمان‌بندی | +| بعد سراغ کدام بروم؟ | صف در یک سو، همان مورد در سوی دیگر | میز کار اصلی‑جزئیات | +| کدام قواعد اعمال می‌شوند و بر چه اثر دارند؟ | تنظیم، دامنهٔ اعمالش، پیامدش | فرم پیکربندی | +| این متن چه می‌گوید؟ | متن به ترتیب، با فهرستی در کنارش | سند پیوسته | +| کجاست؟ | موقعیت، مرز، پراکندگی | نقشه / بوم | + +### جفت‌هایی که جابه‌جا گرفته می‌شوند {#swapped-pairs} + +- **خط زمانی یا گام‌ها.** خط زمانی می‌گوید چه رخ داده، به ترتیب. گام‌ها می‌گویند کجایید و چه در پیش + است. شبیه هم‌اند و در زمان به دو سوی مخالف اشاره می‌کنند. +- **کانبان یا فیلتر.** کانبان وقتی درست است که جابه‌جا کردن کارت _خودِ_ کنش باشد. اگر ستون‌ها شرط‌های + فیلترِ ذخیره‌شده باشند، فیلتری ساخته‌اید که یک کشیدن خرج برمی‌دارد. +- **تقویم یا خط زمانی.** تقویم به اشغال و تداخل پاسخ می‌دهد، خط زمانی به ترتیب. تاریخِ درون رکورد + میان این دو انتخاب نمی‌کند؛ پرسش انتخاب می‌کند. +- **شبکهٔ کارت یا جدول.** یا تصویر لنگر بازشناسی است یا نیست. اگر انتخاب با مقایسهٔ عدد انجام + می‌شود، تصویر کوچکِ ستون اول همان فیلدهایی را دفن می‌کند که تصمیم به آن‌ها بند است. +- **گراف یا فهرست مجاورت.** گراف را تنها وقتی بکشید که خودِ مسیر یا انتشار مبنای داوری باشد. وگرنه + فهرستی گروه‌بندی‌شده از بالادست و پایین‌دست سریع‌تر خوانده می‌شود. +- **سند یا شبکهٔ فیلد.** متنی که به ترتیب خوانده می‌شود متن می‌ماند. خرد کردن هر بند به یک کارت یا یک + سطر کلید‑مقدار دقیقاً همان چیزی را از بین می‌برد که خواندنی‌اش کرده بود. + +سه نما را فقط به این دلیل که می‌شود نسازید. هر نمای اضافی یعنی یک دست فیلتر دیگر، یک نگاشت وضعیت +دیگر، و یک دسته کنش دیگر که باید هماهنگ بماند. دومی را وقتی اضافه کنید که کاربرد دوم واقعاً پرتکرار +شده باشد، نه محض احتیاط. + +## جای هر گونه اطلاعات {#placement} + +| اطلاعات | به چه پاسخ می‌دهد | جایش | نباید سر از اینجا درآورد | +| ------------ | -------------------------- | ------------------------------------------------------ | -------------------------------------- | +| **هویت** | این چیست؟ | عنوان، خلاصهٔ شیء | آخرین ستون، یا پشت یک زبانه | +| **وضعیت** | اکنون چطور است؟ | ناحیهٔ عنوان یا ناحیهٔ خلاصه | جایی که فقط در یک فیلد جزئیات پیدا شود | +| **ویژگی‌ها** | چگونه است؟ | متن جزئیات، گروه‌بندی‌شده به شیوهٔ فهم آدم‌ها | مسطح و به ترتیب فیلدهای API | +| **نسبت‌ها** | به چه چیزی وصل است؟ | ناحیه یا زبانهٔ خودش، با تفکیک مالکیت، وابستگی و ارجاع | قاطی‌شده در جدول ویژگی‌ها | +| **تغییرها** | نسبت به قبل چه فرقی دارد؟ | ناحیهٔ تفاوت، خط زمانی | فقط نمایش مقدار تازه | +| **شواهد** | چرا این داوری قابل اتکاست؟ | درست کنار همان داوری، با قابلیت باز شدن | یک صفحهٔ لاگ در جایی دیگر | +| **کنش‌ها** | اکنون چه می‌توانم بکنم؟ | کنش اصلی در ناحیهٔ عنوان، بقیه کنار شیء خودشان | مدفون زیر «بیشتر» | +| **بازخورد** | آن کار چه کرد؟ | کنار کنش، با حفظ زمینهٔ وظیفه | اعلانی سراسری و بریده از موضوعش | + +**هر واقعیت دقیقاً یک جای مرجع دارد.** هر جای دیگر خلاصه یا ورودی‌ای می‌گذارد که به آن بازپیوند بدهد. + +## ترتیب خواندن {#reading-order} + +```text +هویت صفحه +→ وضعیت کنونی یا استثنا +→ وظیفهٔ اصلی و کنش اصلی +→ اطلاعاتی که داوری لازم دارد +→ نسبت‌ها، تغییرها، شواهد +→ اطلاعات فرعی و کنش‌های کم‌تکرار +``` + +- **در هر صفحه یک عنوان اصلی بصری.** عنوان‌های بخش با معنا پیش می‌روند، نه با اندازهٔ قلمی که ادای + سلسله‌مراتب درمی‌آورد. +- **در هر ناحیهٔ وظیفه حداکثر یک کنش اصلی.** دکمهٔ اصلی محتمل‌ترین گام بعدی است، نه ویرانگرترین. کار + خطرناک معنای خطر می‌گیرد، نه سنگین‌ترین وزن بصری. +- رنگ هشدار و خطر برای وضعیت‌هایی است که واقعاً توجه می‌خواهند. صفحه‌ای که همه‌اش سبز است سیگنالش را + از پیش خرج کرده است. +- نشان، برچسب و بنر همه از یک بودجهٔ توجه برمی‌دارند. تنها چیزی را برجسته کنید که تصمیم را عوض کند. + +## تراکم اطلاعات {#density} + +تراکم یعنی اینکه در یک نگاه چقدر اطلاعاتِ _به‌دردخور برای داوری_ برداشته می‌شود، نه اینکه در هر وجب +چند کنترل جا شده. فشردن فاصله‌ها فقط تراکم بصری را بالا می‌برد و تراکم مؤثر را همان‌جا می‌گذارد؛ +حذف فیلدهای بی‌ربط و آوردن مقایسه به یک جا آن دیگری را بالا می‌برد. + +| سطح | جای مناسبش | چه می‌خرد | +| ------------- | ---------------------------------------------- | ------------------------------------------------------------ | +| **گشاده** | نخستین استفاده، پیکربندی کم‌تکرار، تأیید پرخطر | جا برای توضیح، فاصلهٔ گروهی بیشتر، پیش‌نمایش اثر | +| **استاندارد** | بیشتر فهرست‌ها، جزئیات و فرم‌ها | توازن پیش‌فرض میان اسکن‌پذیری و اطلاعات در هر نما | +| **فشرده** | میزهای کار حرفه‌ای: پایش، عملیات، ممیزی | عرض ستون پایدار، متن کوتاه، کارایی صفحه‌کلید، نمای ذخیره‌شده | + +- در یک صفحه **حداکثر دو سطح مجاور** به کار ببرید. جدولی فشرده درون صفحه‌ای استاندارد اشکالی ندارد؛ + اینکه هر ناحیه مقیاس خودش را اختراع کند اشکال دارد. +- فشردگی یعنی «کوچک کردن هم‌زمان متن و ناحیهٔ لمس» نیست. فاصلهٔ داخلی ظرف و ارتفاع سطر را می‌شود + جمع کرد؛ خوانایی متن، حلقهٔ فوکوس دیدنی و اندازهٔ هدف اشاره‌گر را نمی‌شود. +- برای کاربران حرفه‌ای، مدیریت ستون، نمای ذخیره‌شده، عملیات گروهی و میان‌برها بیش از نشان دادن + یک‌بارهٔ محتوای بیشتر به کار می‌آیند. + +## نگه داشتن زمینهٔ وظیفه {#context} + +وقتی اسکلت انتخاب شد، تصمیم بگیرید محتوای پشتیبان کجا بنشیند: + +| خواننده دارد… | به او بدهید | +| ------------------------------------------------- | ---------------------------------------------------------- | +| میان شیءها یا شواهد مدام رفت‌وبرگشت می‌کند | تقسیم اصلی‑جزئیات: صف در یک سو، مورد در سوی دیگر | +| نگاهی گذرا به چیزی سبک و زودگذر می‌اندازد | سطر بازشونده (`r-disclosure-row`) یا پاپ‌اور (`r-popover`) | +| روی چیزی قابل هم‌رسانی یا نیازمند پهنا کار می‌کند | مسیر مستقل خودش | +| تأیید می‌کند، یا یک فیلد می‌نویسد | یک مودال (`r-modal`) | + +**مودال یک لایهٔ ناوبری نیست.** هر چیزی که پیوند قابل کپی، تاریخچه، مقایسهٔ کنار هم، یا کاری که از +بارگذاری دوباره جان به در ببرد لازم دارد، مسیر می‌گیرد. + +## ranui در این لایه چه می‌دهد {#with-ranui} + +ranui دربارهٔ شکل صفحه عمداً موضعی ندارد: عناصر پایه و توکن می‌دهد، نه قالب صفحه. آنچه اینجا به دست +می‌دهد این است: + +- `r-section` برای نوارهایی که اسکلت به آن‌ها تقسیم می‌شود و `r-card` برای مدخل تکرارشوندهٔ واقعاً + مستقل. هرگز کارت درون کارت؛ فیلدهای فرم را با یک عنوان یا یک جداکننده گروه کنید. +- `r-tabs` برای **نماهای هم‌ترازِ یک شیء** (گفت‌وگویش، بررسی‌هایش، تفاوتش)، نه برای ماژول‌های بی‌ربط؛ + آن کارِ ناوبری است. +- `r-disclosure-row` برای آشکارسازی تدریجی، `r-popover` و `r-dropdown` برای زمینهٔ گذرا، و `r-modal` + تنها برای آنچه جدول بالا به آن اجازه می‌دهد. +- `r-state-dot` برای وضعیت، همیشه همراه برچسبش: + [هرگز تنها با رنگ نه](/fa/src/ranui/design-guides/#accessibility). +- `r-skeleton` تا وقتی نمای نخست بار می‌شود، `r-progress` برای هر کاری که آن‌قدر طول بکشد که کسی را + به تردید بیندازد، و `r-message` برای نتیجه. + +در ranui **جدول، درخت، تقویم، کانبان و خط زمانی وجود ندارد.** وقتی یکی را می‌سازید، به‌جای برپا کردن +یک نظام بصری دوم، آن را روی [توکن‌ها](/fa/src/ranui/design-system/) و +[راهنمای طراحی](/fa/src/ranui/design-guides/) بسازید: فاصله از مقیاس، قلم بر پایهٔ نقش، رنگ از +توکن‌های معنایی، و طراحی هر وضعیت دست‌یافتنی. + +## الگوهای نادرست {#anti-patterns} + +- هر فیلدی که سرویس برمی‌گرداند یک سطر جزئیات می‌شود، و هویت، وضعیت، نسبت‌ها و شواهد همه با یک وزن + سر می‌رسند. +- سلسله‌مراتبی که از کارت و رنگ و فاصلهٔ تزیینی ساخته شده، بی‌آنکه چیزی دربارهٔ اینکه اول چه بخوانیم + گفته باشد. +- چند کنش که سبک دکمهٔ اصلی را میان خود تقسیم کرده‌اند، یا کنشی کم‌تکرار که در ناحیهٔ عنوان نشسته. +- وضعیت و ویژگی و نسبت و تغییر که در یک جدول قاطی شده‌اند، طوری که هیچ‌جا مقایسه‌ای شکل نمی‌گیرد. +- گراف نسبت‌ها، آنجا که خواننده فقط می‌خواست نام و وضعیتی را ببیند. +- مودالی که جریانی طولانی، یک مقایسه، یا چیزی را حمل می‌کند که کسی پیوندش را خواهد فرستاد. +- یک جمله که در عنوان و خلاصه و نام زبانه و جدول تکرار می‌شود و هیچ‌جا چیز تازه‌ای نمی‌افزاید. + +## سیاههٔ بررسی پیش از انتشار یک صفحه + +- [ ] اطلاعات اصلی، اطلاعات پشتیبان و کنش بعدی خواننده نوشته شده‌اند. +- [ ] اسکلت از دل پرسش انتخاب شده، نه از شکل پاسخ سرویس. +- [ ] صفحه یک مدل اصلی دارد و نماهای پشتیبان به‌جای رقابت با آن، در خدمتش‌اند. +- [ ] بی‌آنکه سند نیازمندی خوانده شود، شیء و وضعیتش و کنش اصلی در پنج ثانیه روشن است. +- [ ] مقایسه در یک جا رخ می‌دهد؛ هیچ‌چیز لازم نیست میان زبانه‌ها یا صفحه‌ها به خاطر سپرده شود. +- [ ] هر واقعیت یک جای مرجع دارد و باقی جاها به آن پیوند می‌دهند. +- [ ] تراکم با تکرار استفاده می‌خواند و بیش از دو سطح مجاور دیده نمی‌شود. +- [ ] متن بلند، عدد بزرگ و نمای باریک ترتیب اطلاعات را نمی‌شکنند. +- [ ] هر بلوک و فیلد و برچسب و دکمه‌ای که به داوری کمک نمی‌کند حذف شده است. diff --git a/packages/docs/ja/src/ranui/builder/index.md b/packages/docs/ja/src/ranui/builder/index.md index 5875f0fe0..1dcb0a53c 100644 --- a/packages/docs/ja/src/ranui/builder/index.md +++ b/packages/docs/ja/src/ranui/builder/index.md @@ -121,7 +121,7 @@ Div() | 形 | 使うもの | ふるまい | | -------------------------------- | ------------------------------------ | -------------------------------------------------------- | -| 分岐がひとつ | `Show({ when, children, fallback })` | `when` の_真偽_ が反転したときだけ作り直します。 | +| 分岐がひとつ | `Show({ when, children, fallback })` | `when` の**真偽** が反転したときだけ作り直します。 | | 分岐が複数 | `Switch` + `Match` | 選ばれる枝が変わったときだけ作り直します。 | | 安定した id を持つリスト | `For({ each, key, render })` | `key` で項目を突き合わせ、**そのノードを使い回します**。 | | 位置そのものが同一性であるリスト | `Index({ each, render })` | 各位置のノードを使い回し、項目自体がシグナルになります。 | diff --git a/packages/docs/ja/src/ranui/coding-guides/index.md b/packages/docs/ja/src/ranui/coding-guides/index.md index eff399bbe..e711219b8 100644 --- a/packages/docs/ja/src/ranui/coding-guides/index.md +++ b/packages/docs/ja/src/ranui/coding-guides/index.md @@ -4,7 +4,7 @@ description: 'ranui で作るためのエンジニアリング規約。エント # コーディングガイドライン -ranui で_作る_ための手引きです。コンポーネントの契約とは何か、Shadow DOM の境界がどこで慣れたルールを変えてしまうのか、そして踏む前に知っておく価値のある間違いはどれか。 +ranui で**作る**ための手引きです。コンポーネントの契約とは何か、Shadow DOM の境界がどこで慣れたルールを変えてしまうのか、そして踏む前に知っておく価値のある間違いはどれか。 その見た目の側は[デザインガイドライン](/ja/src/ranui/design-guides/)、トークンは[デザインシステム](/ja/src/ranui/design-system/)にあります。 @@ -44,7 +44,7 @@ import 'ranui'; // 全部 ## コンポーネントの契約 -各要素の正確な属性、プロパティ、イベント（`detail` の形も）、スロット、パーツはソースから生成され、[`COMPONENTS.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/COMPONENTS.md) にまとまっています。以下のルールは、その表が語ら_ない_ことです。 +各要素の正確な属性、プロパティ、イベント（`detail` の形も）、スロット、パーツはソースから生成され、[`COMPONENTS.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/COMPONENTS.md) にまとまっています。以下のルールは、その表が語ら**ない**ことです。 ### 属性は文字列、プロパティは型を持つ @@ -59,7 +59,7 @@ select.showSearch = true; // プロパティ — キャメルケース select.setAttribute('showsearch', ''); // 属性 — 小文字 ``` -- **真偽の属性は存在するかどうかで決まります。** ネイティブの `