الخطوات
طريقة عمل تُعرض خطواتٍ مرقَّمة، لكل خطوة حلقة فيها رقمها، وعنوان اختياري، ومتن من محتواك، ويصلها بالتي تليها خط رفيع. هي قائمة مرتبة تُقرأ، وليست عنصر تحكم ولا سجلًّا للتقدم أبدًا.
- الفئة
- الاحتواء
- الرموز
comp.steps- المستوى
- أساسي
- Web
tanrei-stepsschedule - SwiftUI
TanreiStepsradio_button_unchecked - Jetpack Compose
TanreiStepsradio_button_unchecked - Flutter
TanreiStepsradio_button_unchecked - React Native
Stepsradio_button_unchecked
مولَّد من docs/status/status.json, specs/steps.spec.json
عناوين ومتون
الاقتراح
اكتب المواصفة أو غيّرها، وغيّر الرموز حيث يحتاج التغيير إليها.
التحقق
افحص المخططات (schemas) وقواعد الرموز وتباين كل مخطط لوني.
التوليد
أعد بناء مخرجات الرموز والهياكل الأولية ومصفوفة الحالة.
ثلاثة أشياء تتشابه في المظهر وليست شيئًا واحدًا:
| المكوّن | ما هو | هل له حالات | ما يقوله |
|---|---|---|---|
| قائمة مرتبة في النص المتصل (prose) | عناصر لها ترتيب، كل منها عبارة أو جملة | لا | «هذه، بهذا الترتيب» |
| الخطوات | طريقة عمل تُقرأ ثم تُنفَّذ في مكان آخر | لا | «افعل هذا، ثم هذا» |
| مؤشر الخطوات (stepper) | موضع الشخص في مسار يديره المنتج | نعم | «أنت هنا» |
ليس في الخطوات خطوة حالية ولا منجزة ولا فاشلة، والعلامة ليست عنصر تحكم. أما إتمام الشراء أو معالج الإعداد فيحتاج إلى مؤشر خطوات، وليس في Tanrei مؤشر خطوات بعد.
على الويب، الخطوات صنف (class) على القائمة المرتبة التي تكتبها أنت، لا عنصر مستقل. فالقائمة هي قائمة المستند قبل أن يعمل أي سكربت، وعنصر <ol> الذي يكتبه محوِّل Markdown يحتاج إلى صنف واحد ولا يحتاج إلى عنصر يغلّفه، ومن دون ورقة الأنماط هي قائمة المتصفح المرقَّمة.
أما SwiftUI و Compose و Flutter و React Native فمخطَّط لها: الأسماء التي بجانب كل منصة في أعلى هذه الصفحة هي ما تعطيها إياه المواصفة، ولا شيء منها متاح هناك بعد. وليس في React مكوّن Steps بعد كذلك، فاستخدم القائمة مع الصنف.
<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/steps.css" />
<!-- بين عناصر تحكم: لوحة، أو مربع حوار، أو بطاقة. -->
<ol class="tanrei-steps" role="list">
<li>احفظ الملف في المجلد الذي يحوي إعدادات المشروع.</li>
<li>اذكر اسم الملف في الإعدادات.</li>
<li>شغّل البناء وأودِع ما يكتبه.</li>
</ol>
<!-- في صفحة للقراءة، بعناوين، تكمل مجموعة سابقة. -->
<ol class="tanrei-steps" role="list" data-size="large" start="4" aria-label="سير العمل، تتمة">
<li>
<p class="tanrei-steps-title">التنفيذ</p>
<p>نفّذ التغيير على كل منصة تسردها المواصفة.</p>
</li>
<li>
<!-- عنوان هو عنوان قسم في الصفحة: يحتفظ بدوره ومستواه. -->
<h3 id="check">الفحص</h3>
<p>شغّل كل الفحوص بالترتيب.</p>
<pre><code>pnpm check</code></pre>
</li>
</ol>
<script type="module">
// اختياري: عمود العلامات في مجموعة فيها أرقام من ثلاث خانات، وإعادة الترقيم حين تتغير `start` وقت التشغيل،
// وتقارير التنقيح. والحزمة `@tanrei/web` تحمّله أيضًا.
import '@tanrei/web/steps';
</script>import '@tanrei/web/steps.css';
<ol className="tanrei-steps" role="list" data-size="large">
<li>
<p className="tanrei-steps-title">التثبيت</p>
<p>أضف الحزمة إلى المشروع.</p>
</li>
</ol>| الخاصية | على الويب |
|---|---|
label |
الخاصية aria-label (أو aria-labelledby تسمّي عنوان القسم الذي قبل القائمة) |
start |
الخاصية start للقائمة نفسها |
size: large |
القيمة data-size="large" |
| خطوة | عنصر <li> |
العنوان title للخطوة |
أول ابن لعنصر القائمة وله class="tanrei-steps-title" (عنصر <p>) |
| منفذ العنوان | عنوان قسم (من h2 إلى h6) ابنًا أول لعنصر القائمة |
اكتب role="list" على القائمة: أحد محرّكات المتصفحات يُسقط دلالة القائمة عن قائمة أزيلت علاماتها.
سطر واحد لكل خطوة، ومجموعة تكمل أخرى
- احفظ الملف في المجلد الذي يحوي إعدادات المشروع.
- اذكر اسم الملف في الإعدادات، تحت مفتاح طبقة التصميم.
- شغّل البناء وأودِع ما يكتبه.
- التسعة تبقى في دائرة.
- وكذلك العشرة.
- وكذلك الأحد عشر: الثلاث كلها تبدأ عند حافة واحدة.
الحجم الكبير، مع كتلة في المتن
أضف الحزمة إلى المشروع.
npm install @tanrei/webحمّل ورقة الأنماط مرة واحدة، قبل أي نمط آخر في الصفحة.
- العلامة حلقة بخط النظام الرفيع فيها رقم الخطوة، عرضها 24 في الحجم medium و 28 في الحجم large. الرقم من خانة أو خانتين يُبقيها دائرة؛ والرقم الأطول يوسّعها إلى كبسولة، ويبقى محتوى كل الخطوات يبدأ عند حافة واحدة.
- خط الوصل يمتد من كل حلقة إلى التي تليها، ويتوقف قبل أن يبلغ أيًّا منهما. والخطوة الأخيرة لا خط لها.
- العنوان اختياري. هو نص من خطوته وليس عنوان قسم، إلا إذا أعطيت عنوان قسم ابنًا أول لعنصر القائمة: عندئذ يُرسم كأي عنوان ويحتفظ بدوره ومستواه، فتدخل الخطوة في مخطَّط عناوين الصفحة.
- المتن هو محتواك. بين الكتلتين 8، وبين الخطوتين 16. والكتلة التي ليست نصًّا (كتلة شيفرة، أو جدول، أو علامات تبويب، أو تنويه) تأخذ عرض المتن كله.
- الحجمان هما حجما النص المتصل: الحجم medium بين عناصر التحكم، والحجم large في صفحة غايتها النص. والخطوات التي داخل نص متصل تأخذ حجم ذلك النص.
- الألوان: الرقم والعنوان والمتن تأخذ لون المحتوى للسطح الذي تقع عليه الخطوات. والحلقة وخط الوصل يُرسمان كلاهما بلون الخط الرفيع الواحد في النظام. ولا تعبئة لشيء.
البنية
| الجزء | الوصف |
|---|---|
1 list | The ordered list itself: one column of steps, as wide as its container gives it. It has no fill, no edge, no padding and no state of its own, and it brings no text color. |
2 step | One item of the list: its marker at the start, and beside it its content — a title, where it has one, and a body. A step has no state: none is current, done or failed. |
3 marker | What begins a step: a ring in the system's one hairline holding the step's number. At least as high and as wide as the marker's height of the size; a circle in the default system, widened into a pill by a number too long for one. The ring is decorative; the number is the step's number, exposed once with the list item. |
4 connector · اختياري | The line from a step's marker to the next step's: the same hairline, on the marker column's centre line, kept a small distance from both rings. It shows that the steps are one sequence and where a step of several blocks ends. Decorative. The last step has none. |
5 title · اختياري | A step's name, in a few words ("Install", "Say where each output goes"), set at the body's size in a heading weight. Text of its step and not a heading, unless the product gives a heading of its own as the title. |
6 body · اختياري | A step's content: what the product puts in it. Text placed directly takes the body's text style; long-form blocks are set as prose; a block that is not text — a code block, a table, tabs — takes the body's whole width. |
الخصائص
| الخاصية | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
label | string | "" | The list's accessible name, in the product's language ("Installing the package"). Not drawn. Give one where no heading directly before the steps already says what the procedure is. |
start | number | 1 | The number of the first step; each following step's number is one more. For a procedure that a note, a heading or a choice between tabs interrupts and that continues in a second set of steps ("4, 5, 6"). A whole number. |
size | medium | large | "medium" | The size of the steps' text, in prose's two sizes. Medium sets the body in the interface's own text style, for steps among controls: a panel, a dialog, a card. Large sets it in the style for long reading, for a page whose purpose is the text. Steps inside a prose are given that prose's size. A design system may add values. |
العناصر
أنواع العناصر التي يكررها المكوّن. يسرد كل نموذج اختبار عناصره بالترتيب، وتسمّي كل منصة كل نوع بأسلوبها.
step
One step of the procedure: an optional title and a body. Its number comes from its place in the list and from start, never from a prop of its own.
| الخاصية | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
title | string | "" | The step's name, in a few words. Plain text: drawn first in the step, read with the step, and not a heading. A title that is a heading of the page is given in the title slot instead. |
| المنفذ | الوصف |
|---|---|
title | The title as content of the product's own: a heading of the level the page's outline needs (so the step is in the page's table of contents and can be linked to). Drawn in the title's text style whatever its level; its role and level are kept. Takes the place of the title prop. |
| المواصفة | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| العنصر | li | TanreiStep | TanreiStep | TanreiStep | Step |
title · الخاصية | tanrei-steps-title | title | title | title | title |
| ملاحظات | An <li> of the list; its children are the body. The title is the item's first child where that child is a heading (h2 to h6) or carries class="tanrei-steps-title" (a <p> for a title that is not a heading): the spec's title prop and its title slot are the same element on this platform, told apart by the tag the product chose. | TanreiStep(_ title: String? = nil) { body } in the steps' view builder; TanreiStep(title: { Text(…).accessibilityAddTraits(.isHeader) }) { body } is the title slot. | TanreiStep(title: String? = null) { body } in TanreiStepsScope; an overload takes title: @Composable () -> Unit with Modifier.semantics { heading() } for the title slot. | TanreiStep(title: 'Install', child: …); titleWidget: takes a widget wrapped in Semantics(header: true) for the title slot. | <Step title="Install">…</Step>; title also takes an element with accessibilityRole="header" for the title slot. |
الحالات
السلوك
متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.
| المعرّف | المتطلب |
|---|---|
STP-1 | THE steps SHALL lay out its steps in one column, in the order they are given, each step a row of two parts: its marker, in a column at the steps' start edge, and its content — its title, where it has one, and its body — beside it. The marker column SHALL be as wide as the widest marker of the set and never narrower than the marker's height of the size (comp.steps.marker.height.medium for medium, comp.steps.marker.height.large for large), each marker centred in it; every step's content SHALL begin at one edge, comp.steps.marker.gap after that column, and run to the steps' end edge. THE steps SHALL separate the end of one step from the beginning of the next by comp.steps.step.gap, SHALL give the first step no space before it and the last step no space after it, and SHALL draw no fill, no edge around itself and no elevation. |
STP-2 | THE steps SHALL draw each step's marker as a ring with the step's number at its centre: a box at least comp.steps.marker.height.medium high and wide for medium (comp.steps.marker.height.large for large), with corners comp.steps.marker.shape, never larger than half the box's height and eased by sys.shape.corner-smoothing, no fill, and an edge comp.steps.marker.outline.width wide in comp.steps.marker.outline.color drawn inside the box's size; the number SHALL be set on one line in comp.steps.marker.label.typescale.medium for medium (comp.steps.marker.label.typescale.large for large), in the content color of the surface the steps sit on, with at least comp.steps.marker.padding-inline between it and the ring at the start and at the end, so that a number too long for a circle widens its marker into a pill and is never cut. |
STP-3 | THE steps SHALL place each marker at the top of its step with its centre on the centre of the step's first line of text — the title's first line where the step has a title, else the first line of the body; WHERE the marker is taller than that line THE steps SHALL lower the step's content by half the difference, so that the marker's top is the step's top and no marker reaches into the space above its step; WHERE a step begins with a block that is not text (a code block, a table, a picture) THE steps SHALL place the marker's top on that block's top. |
STP-4 | THE steps SHALL number its steps in order: the first step's number is start and each following step's is one more than the one before it. THE number SHALL be written as a whole number in the digits 0 to 9, with no period, bracket or other mark beside it and no word before it. WHEN a step is added, removed or moved, or start changes, THE steps SHALL draw every step's new number at once, without a motion. |
STP-5 | WHILE a step is followed by another step THE steps SHALL draw a connector between their two markers: a straight line comp.steps.connector.thickness thick in comp.steps.connector.color, on the centre line of the marker column, from comp.steps.connector.gap below the upper marker's bottom edge to comp.steps.connector.gap above the lower marker's top edge, through the space between the two steps, however tall the upper step's content is. THE steps SHALL draw no connector after the last step and none for a set of one step; a connector SHALL take no room in the layout, SHALL never be drawn over a marker or over a step's content, and SHALL be kept from assistive technology. |
STP-6 | WHERE a step has a title THE steps SHALL draw it first in the step's content, in comp.steps.title.typescale.medium for medium (comp.steps.title.typescale.large for large) and the content color of the surface the steps sit on, SHALL wrap it and never cut it, and SHALL begin the step's body comp.steps.title.gap below it. A title given as text SHALL be exposed as text of its step and SHALL NOT be a heading; WHERE the product gives the title as content of its own in the step's title slot — a heading of the level its page's outline needs — THE steps SHALL draw it as any title, in the same text style whatever its level, and SHALL change neither its role nor its level. A step with a title and no body SHALL be drawn as its marker and its title alone. THE steps SHALL set the title's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them. |
STP-7 | THE steps SHALL draw the content a step is given as that step's body and SHALL give it comp.steps.body.typescale.medium for medium (comp.steps.body.typescale.large for large) as the text style its text takes where nothing inside sets another. THE steps SHALL give the body no color of its own: its text takes the content color of the surface the steps sit on, so the same steps read on a page, in a card and in a callout. The body SHALL wrap and SHALL never be cut or limited to a number of lines. WHERE the body holds more than one block THE steps SHALL separate two blocks that follow each other by comp.steps.body.gap, whatever they are, and SHALL give the first block no space before it and the last block no space after it; the body's long-form blocks — paragraphs, lists, a quote — SHALL otherwise be set as prose of the steps' size sets them (PRS-1 to PRS-3, PRS-19), a link in them SHALL be underlined at rest (PRS-17), and THE steps SHALL add no style to anything inside a component placed in a body. |
STP-8 | THE steps SHALL give every block of a body that is not text — a code block, a table, a set of tabs, a callout, a figure or a picture, any component — the whole inline size of the body, from the edge every step's content begins at (STP-1) to the steps' end edge, and such a block SHALL scroll inside its own box when its content cannot shrink (PRS-15). WHILE the steps sit in a prose that keeps a measure THE steps themselves SHALL take that prose's full width as a block that is not text (PRS-18), and the text blocks of a body SHALL be kept no wider than comp.prose.measure times their font size, from the body's start edge; WHERE the steps sit outside a prose, or in one without a measure, every block of a body SHALL take the body's full inline size. |
STP-9 | WHERE a step's body holds a list THE steps SHALL leave it a list of prose, nested one depth below the steps: an ordered list is marked with lowercase letters and an unordered one with a ring (PRS-9's second depth), set in by prose's own inset from the body's start edge, so that sub-steps never repeat the steps' numbers and never draw markers or connectors of their own. WHERE the product places a set of steps inside a step's body THE steps SHALL draw it as a set of its own, numbered from its own start and laid out in the body's width, and in debug builds SHALL report that steps are nested. |
STP-10 | THE steps SHALL lay itself out as a block in the flow of its container: it SHALL take the whole inline size the container gives it, with its start edge on the start edge of the text around it; it SHALL bring no outer space of its own (PRS-15: the space between it and its neighbours is its container's), SHALL never be wider than its container, SHALL have no minimum width and no maximum width, and SHALL NOT scroll. |
STP-11 | THE steps SHALL NOT take pointer, touch or keyboard input, SHALL NOT take focus or be a stop in the focus order, and SHALL NOT change anything they draw under a pointer, a press or focus: a step has no current, completed, error, hovered, focused, pressed, selected or disabled state, a marker is not a control, and the steps emit no event. What the product places in a body — a link, a code block's copy button, tabs — takes input by its own spec, and text in a title and a body SHALL remain selectable where the platform lets text be selected. |
STP-12 | THE steps SHALL be exposed to assistive technology as an ordered list of as many items as it has steps, named by label where label is not empty, and each step as one item of that list holding, in this order, its number, its title and its body. Each step's number SHALL be exposed exactly once, as the item's number, and SHALL be the number the marker draws (STP-4), also where start is not 1; the ring and the connector SHALL be kept from assistive technology. THE steps SHALL NOT expose a step as current, done or failed, and SHALL add no role to a title or to anything in a body. |
STP-13 | WHEN label, a step's title or a step's body changes THE steps SHALL draw and expose the new value at once, without a motion, and SHALL NOT announce the change by itself. |
STP-14 | WHILE the text size is enlarged THE steps SHALL grow each number, title and body with it and grow each marker with its number, keeping the marker's height of the size as a minimum; THE steps SHALL keep comp.steps.marker.gap, comp.steps.step.gap, comp.steps.title.gap, comp.steps.body.gap and comp.steps.connector.gap as they are, wrap, set no fixed height on a step, lose no content when the reader raises line height, paragraph spacing, letter spacing or word spacing, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %, except inside a block that scrolls in its own box (STP-8). |
STP-15 | WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE steps SHALL draw each ring and each connector in the platform's text color at their own widths, and each number, title and body in that text color; nothing the steps draw relies on a fill. |
STP-16 | WHERE the layout direction is right-to-left THE steps SHALL mirror its two parts and apply its spaces by logical start and end, so that the marker column and the connectors are at the right and each step's content is at its left, beginning at one edge and running to the steps' left edge; a body's blocks that are not text SHALL still take the body's whole inline size (STP-8). |
STP-17 | THE steps SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the steps are shown THE steps SHALL draw themselves for the new direction at once, without a motion of their own, keeping what they show. |
STP-18 | THE steps SHALL draw a step's number as a left-to-right run whose digits are never reversed, in every layout direction, and SHALL lay out a title given as text as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a command, a file's name and a version keep their own order in a right-to-left layout and reorder nothing beside them; THE steps SHALL still place the title and align its lines by the layout direction, not by the text's own. The body's blocks are laid out as prose lays out a block (PRS-25): each by its own first strong character unless the content states a direction, with its lines aligned to the start edge of the layout. |
STP-19 | WHEN size names a value that the active design system does not have THE steps SHALL render with the default size's tokens, and in debug builds report the unknown value. IF start is not a whole number THE steps SHALL number from 1 and in debug builds report it; a start of zero or below is a whole number and is drawn as it is. |
STP-20 | IF the steps hold no step THE steps SHALL draw nothing, take no space and expose nothing, and in debug builds report that a set of steps is empty. IF a step has neither a title nor a body THE steps SHALL still draw its marker, count it in the numbering and in the list's items, and in debug builds report that a step is empty: a number is never skipped, so the numbers a reader sees are the numbers the content has. |
مطابقة الأسماء بين المنصات
التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.
| المواصفة | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| المكوّن | tanrei-steps | TanreiSteps | TanreiSteps | TanreiSteps | Steps |
label · الخاصية | aria-label | label | label | semanticLabel | accessibilityLabel |
start · الخاصية | start | start | start | start | start |
size · الخاصية | data-size | size | size | size | size |
| ملاحظات | Form: a class on the product's own ordered list, not an element — <ol class="tanrei-steps" role="list"> with <li> children — styled by one optional stylesheet of the package, @tanrei/web/steps.css, whose selectors are wrapped in :where() so one class on the product's side wins. The list stays the document's list: it is an ordered list before any script runs and for whatever reads the page as built, a Markdown renderer's <ol> needs one class and no wrapper, and there is nothing to define, so nothing changes place after the page loads; without the stylesheet it is the browser's numbered list. start is the <ol>'s own attribute, label is aria-label (or aria-labelledby naming the heading before it), data-size="large" is the size. The marker is the item's ::before showing the item's number from a counter that honours start (the implicit list-item counter where the three engines agree on it, else a counter of the stylesheet's set from start by the package's script); the connector is the item's ::after, absolutely placed, with pointer-events: none. One shared marker column (STP-1) is a grid on the <ol> with the items as subgrids. list-style: none removes list semantics in one engine's accessibility tree, which is why the contract writes role="list" on the <ol>; the number in ::before is generated content, read once with the item (STP-12), and the test of STP-12 is run with a screen reader in each engine. The number is drawn with unicode-bidi: isolate and direction: ltr (STP-18); a title is dir="auto"-like through unicode-bidi: plaintext with physical alignment by :dir(), as productText() does. STP-3 uses 1lh of the item's first line. Inside a .tanrei-prose the list is not an island (it is a class on an <ol>, not a Tanrei element), so prose's own rules keep reaching the paragraphs, lists, links and inline code of each body at any depth, with no second prose to open and no limit of depth; steps.css takes back from prose.css what a set of steps draws itself: the list's inset, its markers, the item gap, the measure on the list (STP-8) and the gap between an item's blocks (STP-7), and a list inside an item is already prose's second depth (STP-9). Outside a prose the stylesheet alone sets the body's text style and the gaps between an item's direct children; long-form content there is wrapped by the product in <div class="tanrei-prose" data-measure="false"> around the list. Under forced-colors: active the ring and the connector are CanvasText (STP-15). The package's script, where it is loaded, adds only the debug reports of STP-9, STP-19 and STP-20. React: Steps and Step render the same <ol> and <li>; Step takes title (text, rendered as <p class="tanrei-steps-title">) or a heading as its first child. | TanreiSteps(label:, start:, size:) { TanreiStep("Install") { … } }. A Layout that measures the widest marker, places contents at one edge and draws the connectors in a background; not a List, so it brings no rows, separators or scrolling. Each step is an accessibility container whose first element's label is the number; the set is exposed as a list through the platform's list semantics where it has them and named by label. The body is the product's views; rendered text goes through the prose layout. | TanreiSteps(label, start, size) { TanreiStep("Install") { … } }. A custom Layout, not a LazyColumn: a procedure is short and is never recycled. CollectionInfo and CollectionItemInfo expose the list and each item; the number is the first text of the item; the ring and the connector are drawn in drawBehind and have no semantics. | TanreiSteps(semanticLabel:, start:, size:, children: [TanreiStep(…)]). Not the framework's Stepper, which is a control with a current step. A CustomMultiChildLayout-style render object for the shared column; connectors painted by a CustomPainter excluded from semantics. Follows Directionality. | <Steps accessibilityLabel="…" start={1} size="medium"><Step title="Install">…</Step></Steps>. accessibilityRole="list" on the container; each step's number is the first text of its item. The marker column's width is measured once per set (onLayout). Follows the app's direction where an ancestor's is not known. |
الرموز
| الرمز | يشير إلى | القيمة المحلولة (فاتح) |
|---|---|---|
--tanrei-comp-steps-body-gap | sys.space.space100 | 8px |
--tanrei-comp-steps-connector-color | sys.color.outline-variant | |
--tanrei-comp-steps-connector-gap | sys.space.space50 | 4px |
--tanrei-comp-steps-connector-thickness | sys.border.hairline | 1px |
--tanrei-comp-steps-marker-gap | sys.space.space150 | 12px |
--tanrei-comp-steps-marker-height-large | — | 28px |
--tanrei-comp-steps-marker-height-medium | — | 24px |
--tanrei-comp-steps-marker-outline-color | sys.color.outline-variant | |
--tanrei-comp-steps-marker-outline-width | sys.border.hairline | 1px |
--tanrei-comp-steps-marker-padding-inline | sys.space.space50 | 4px |
--tanrei-comp-steps-marker-shape | sys.shape.corner.full | 9999px |
--tanrei-comp-steps-step-gap | sys.space.space200 | 16px |
--tanrei-comp-steps-title-gap | sys.space.space50 | 4px |
--tanrei-comp-steps-body-typescale-large | sys.typescale.body-large | 400 16px/1.625 |
--tanrei-comp-steps-body-typescale-medium | sys.typescale.body | 400 14px/1.5714 |
--tanrei-comp-steps-marker-label-typescale-large | sys.typescale.label | 500 14px/1.4286 |
--tanrei-comp-steps-marker-label-typescale-medium | sys.typescale.label-small | 500 12px/1.3333 |
--tanrei-comp-steps-title-typescale-large | sys.typescale.heading-5 | 500 16px/1.5 |
--tanrei-comp-steps-title-typescale-medium | sys.typescale.heading-6 | 500 14px/1.4286 |
نماذج الاختبار
عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.
size: medium (15)
short
label: What to do next items: 3 titles
label: The workflow items: 6 titles-only
label: The workflow items: 3 long-bodies
label: Moving an account items: 3 long-title
label: Moving an account items: 2 single
label: What to do next items: 1 start
label: The workflow, continued start: 4 items: 3 two-digits
label: The workflow, continued start: 9 items: 3 three-digits
label: The workflow, continued start: 99 items: 3 rtl
label: البدء direction: rtl items: 3 rtl-two-digits
label: البدء start: 9 direction: rtl items: 3 ltr-title-rtl
label: البدء direction: rtl items: 3 with-code-medium
label: Use nested-list
label: Moving an account in-prose
label: Handing a notebook over size: large (10)
large
label: The workflow size: large items: 4 large-short
label: What to do next size: large items: 3 large-long-bodies
label: Moving an account size: large items: 3 large-two-digits
label: The workflow, continued start: 9 size: large items: 3 japanese
label: 自分のデザインシステムを作る size: large items: 3 with-code
label: Use size: large with-table-and-tabs
label: Your own design system size: large in-prose-large
label: Handing a notebook over size: large titles-as-headings
label: Handing a notebook over size: large with-code-rtl
label: الاستخدام size: large direction: rtl مولَّد من specs/steps.spec.json, tokens/comp/steps.tokens.json, design/tokens/
داخل .tanrei-prose ليست الخطوات جزيرة معزولة: الفقرات والقوائم والروابط والشيفرة المضمَّنة في كل خطوة تبقى للنص المتصل. تأخذ الخطوات عرض النص المتصل كله، فكتلة الشيفرة في خطوة تأخذ العمود، والفقرات داخل الخطوة تبقى تقف عند حدّ طول السطر (measure). والقائمة التي داخل خطوة تُعلَّم بحروف (إن كانت مرتبة) أو بحلقات (إن كانت غير مرتبة)، فلا تكرر الخطوات الفرعية أرقام الخطوات أبدًا. والملف @tanrei/web/prose.css يحمل قواعد الخطوات، فلا تحتاج صفحة من النص المتصل إلى ورقة أنماط ثانية.
- مع العنوان، اكتب المتن في عناصر (
<p>): النص المكتوب مباشرة بعد العنوان لا يمكن إعطاؤه الفراغ الذي تحت العنوان. - في نص متصل يحتفظ بحدّ لطول السطر، تُلزَم الخطوة التي هي نص وحده ذلك الحدّ. أما النص المكتوب مباشرة في خطوة تحمل كتلًا أيضًا فلا يُلزَمه: اكتبه في عنصر
<p>. - الخطوة التي تبدأ بكتلة شيفرة أو بصورة يكون أعلى علامتها عند أعلى تلك الكتلة. والنص المكتوب مباشرة قبل كتلة كهذه (عنصر قائمة متراصّ في Markdown) لا تراه ورقة الأنماط: اكتبه في عنصر
<p>. - الرقم من ثلاث خانات أو أكثر يوسّع علامته إلى كبسولة. وعمود العلامات في المجموعة كلها لا يتبعها إلا مع سكربت الحزمة، الذي يقيسه؛ ومن دون السكربت تمتد علامة كهذه إلى الفراغ الذي بجانبها.
- من دون سكربت الحزمة لا يُعاد رسم تغيّر
startوقت التشغيل في محرّكين من محرّكات المتصفحات.
- قل ما هي طريقة العمل في عنوان أو جملة قبلها. وحيث لا شيء يقول ذلك، أعطِ القائمة
label. - اقصر الخطوة على عمل واحد وما يحتاج إليه القارئ لتنفيذه.
- استخدم
startلمتابعة طريقة عمل تقطعها ملاحظة أو اختيار بين تبويبات. - استخدم قائمة مرتبة من النص المتصل، بلا الصنف، لعناصر كل منها عبارة وليست طريقة عمل.
- لا تستخدم الخطوات لإظهار التقدم في مسار. لا خطوة حالية ولا منجزة.
- لا تضع خطوات داخل خطوات. الخطوات الفرعية قائمة مرتبة في المتن.
- لا تجعل كل عنوان عنوان قسم: الصفحة التي يسرد مخطَّط عناوينها كل خطوة من كل طريقة عمل أصعب في التنقل.
- الدور
list- التسمية
- An ordered list, named by label where the product gives one; where a heading directly before the steps says what the procedure is, no label is needed. Each step is a list item read as its number, its title and its body, in that order. The number is the list item's own and is read once; the ring and the connector are decorative and hidden. A title is text of its item, or the product's own heading where the product gave one.
- الحد الأدنى للهدف
- تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px
لوحة المفاتيح
| المفاتيح | الإجراء |
|---|
ملاحظات
- Not interactive: the steps take no input and no focus (STP-11), so there is no target of their own to size and minimumTarget holds trivially. What is pressable inside a body — a link, a copy button, tabs — meets the minimum target by its own spec.
- Order is carried by structure, not by the drawing: the steps are an ordered list whose items have numbers (STP-12), so a reader who does not see the rings and the connector loses nothing. That is also why forced colors and a missing stylesheet cost nothing but the look.
- The number a person hears is the number a person sees (STP-12), also for a set that continues another with start. A platform whose list semantics would announce a position ("1 of 3") in place of the drawn number adds the number to the item's text instead of relying on the position.
- Contrast is the surface's: the steps bring no text color (STP-2, STP-6, STP-7), so the number, the title and the body have the contrast of the content color of the surface they sit on, which the default system holds to 4.5:1. The ring and the connector are decorative — the number is read without the ring, and the order without the line — and are not held to 3:1, as the divider's line and a quote's line are not.
- A title is not a heading by default, because a page whose outline lists every step of every procedure is harder to move through by headings. Where the steps are the page's sections (a long guide with one screen of content per step), give each title as a heading in the title slot; its level is the page's, and the steps do not change it (STP-6).
- Steps say nothing about progress (STP-11, STP-12): no step is current, done or failed, and none can be. A flow in which the person is somewhere — a checkout, a set-up wizard — needs a component that exposes the current step, which this is not.
- Text size, text spacing and reflow: STP-14. A long procedure is never cut, collapsed or paged by the component.
مولَّد من specs/steps.spec.json, tokens/sys/measure.tokens.json
- تبقى الخطوات القائمة المرتبة للمستند: قائمة عدد عناصرها عدد الخطوات، يُقرأ كل منها برقمه ثم عنوانه ثم متنه.
- الرقم الذي يسمعه الشخص هو الرقم الذي يراه، وكذلك في مجموعة تكمل أخرى بالخاصية
start. - الحلقة وخط الوصل زخرفيان ومخفيان. والترتيب تحمله القائمة، فلا يضيع شيء في الألوان المفروضة (forced colors) ولا من دون ورقة الأنماط.
- النص يكبر مع إعدادات القارئ ويلتفّ. ولا يُمرَّر جانبيًّا إلا كتلة تُمرَّر داخل صندوقها، ككتلة الشيفرة.
- اكتب
role="list"على القائمة. - سمِّ طريقة العمل بعنوان قبلها، أو بالخاصية
aria-label. - لا تجعل العنوان عنوان قسم إلا حيث تكون الخطوات أقسامًا من الصفحة.