هيكل التطبيق

نظرة عامة

link

Web

tanrei-app-shell

schedule

SwiftUI

TanreiAppShell

radio_button_unchecked

Jetpack Compose

TanreiAppShell

radio_button_unchecked

Flutter

TanreiAppShell

radio_button_unchecked

React Native

AppShell

radio_button_unchecked

مولَّد من docs/status/status.json, specs/app-shell.spec.json

هيكل التطبيق (app shell) هو إطار النافذة. يضع المناطق في أماكنها ولا يرسم شيئًا من محتواها: فالترويسة شريط التطبيق الذي عندك، والتنقل درج التنقل الذي عندك، والتذييل تخطيطك أنت. وما يضيفه الهيكل هو ما ينساه الإطار المصنوع باليد: المعالم (landmarks)، ومجموعة واحدة من عروض النافذة، والمسافة التي تقتطعها الترويسة اللاصقة (sticky) من وجهة الرابط، وطريق تتجاوز به لوحة المفاتيح الإطار.

الإطار نافذة كاملة، ولذلك ليس في هذه الصفحة مثال حيّ له: فالهيكل المرسوم داخل صفحة كان سيأخذ فئة نافذة تلك الصفحة. نماذج الاختبار (fixtures) التي تحت المواصفات مسرودة مع خصائصها؛ وكل منها يُرسم وحده في نافذة خاصة به في الاختبارات.

على الويب هو <tanrei-app-shell> حول مناطقك أنت. وليس للعنصر جذر ظل (shadow root)، فالعنصر <header> هو مَعلم ترويسة الصفحة (banner)، والعنصر <main> الوحيد هو مَعلمها الرئيسي، يقرؤهما المتصفح من دون سكربت ويقرؤهما الزاحف. والمنصات الأخرى لم تنفّذه بعد.

الاستخدام

link

<link rel="stylesheet" href="@tanrei/web/app-shell.css" />

<tanrei-app-shell aside-order="before" aside-label="في هذه الصفحة">
  <a class="tanrei-link" data-standalone slot="skip-link" href="#main">التخطّي إلى المحتوى</a>
  <header slot="header">
    <tanrei-app-bar headline="Tanrei">
      <tanrei-button slot="navigation" data-app-shell-menu variant="text" label="القائمة">
        <span slot="icon">menu</span>
      </tanrei-button>
    </tanrei-app-bar>
  </header>
  <tanrei-navigation-drawer slot="navigation" responsive collapsible label="التوثيق">
    …
  </tanrei-navigation-drawer>
  <aside slot="aside">…</aside>
  <main id="main" tabindex="-1">…</main>
  <footer slot="footer">…</footer>
</tanrei-app-shell>

<script type="module">
  import '@tanrei/web/components/app-shell';
</script>

import { AppBar, AppShell, Button, NavigationDrawer } from '@tanrei/react';
import '@tanrei/web/app-shell.css';

<AppShell asideLabel="في هذه الصفحة" onWindowClassChange={(event) => setWindowClass(event.detail.windowClass)}>
  <a className="tanrei-link" data-standalone slot="skip-link" href="#main">التخطّي إلى المحتوى</a>
  <header slot="header">
    <AppBar headline="Tanrei">
      <Button slot="navigation" data-app-shell-menu variant="text" label="القائمة"><span slot="icon">menu</span></Button>
    </AppBar>
  </header>
  <NavigationDrawer slot="navigation" responsive collapsible label="التوثيق">…</NavigationDrawer>
  <main id="main" tabIndex={-1}>{children}</main>
  <aside slot="aside">…</aside>
  <footer slot="footer">…</footer>
</AppShell>

ورقة الأنماط @tanrei/web/app-shell.css تخطّط الإطار كله قبل أن يعمل أي سكربت، فالصفحة المصيَّرة على خادم لا تتحرك حين يصل السكربت، ورابط التخطي يعمل والسكربت موقوف. والعنصر يضيف ورقة الأنماط نفسها إلى الصفحة من تلقاء نفسه.

ما تكتبه

link

المنطقة ابن له خاصية HTML (attribute) المسماة slot. والمنطقة الرئيسية هي العنصر <main> الوحيد الذي ليست له.

المنطقة	على الويب	ما يعطيها الهيكل
رابط التخطي (skip link)	<a class="tanrei-link" data-standalone slot="skip-link" href="#main">	أول موضع تتوقف عنده لوحة المفاتيح. ولا يُرسم إلا ما دام عليه تركيز لوحة المفاتيح.
الإعلان	عنصر <div slot="announcement"> حول تنويه (callout)	عرض الإطار كله فوق الترويسة.
الترويسة	عنصر <header slot="header"> حول شريط التطبيق الذي عندك	العرض كله. وتبقى في الأعلى والصفحة تُمرَّر.
التنقل	<tanrei-navigation-drawer slot="navigation" responsive>	حافة البداية، بإحدى ثلاث طرق عرض.
المنطقة الرئيسية	<main id="main" tabindex="-1">	هوامش جانبية (gutters)، وحدًّا للعرض، ووجهة رابط التخطي.
المنطقة الجانبية (aside)	عنصر <aside slot="aside">، أو لوحة جانبية	حافة النهاية في النافذة العريضة. وفي غيرها فوق المحتوى الرئيسي أو تحته.
التذييل	<footer slot="footer">	نهاية الصفحة، وهوامش جانبية وفراغًا.
شريط التنقل	<tanrei-navigation-bar slot="navigation-bar">	الحافة السفلية، في النافذة الضيقة فقط.

اكتب المناطق بالترتيب الذي تمرّ به لوحة المفاتيح: رابط التخطي، ثم الإعلان، ثم الترويسة، ثم التنقل، ثم المنطقة الجانبية حين تأتي قبل المحتوى الرئيسي، ثم المنطقة الرئيسية، ثم المنطقة الجانبية حين تأتي بعده، ثم التذييل، ثم شريط التنقل. ورقة الأنماط تضعها في أماكنها بأسمائها ولا تغيّر ترتيب التركيز أبدًا. والمنطقة التي تتركها لا تأخذ حيّزًا ولا تضيف مَعلمًا.

المواصفات

link

البنية

الجزء	الوصف
1 container	The frame itself: the whole window (or the whole page), filled with the product's surface color. It carries no state and takes no input.
2 skip-link · اختياري	A Link the product gives ("Skip to content") that the shell keeps out of sight until the keyboard reaches it, then shows in a small raised box at the top start corner of the window. The first thing the keyboard reaches; following it moves focus to the main region.
3 announcement · اختياري	A strip across the top of the frame, above the header, for a notice that concerns the whole product (a callout the product places there: an outage, a new version, a page that is not translated).
4 header · اختياري	The region across the top that names the product or the screen and holds its search and its actions: the product's app bar. The page's banner landmark.
5 menu-button · اختياري	An icon-only Button the product puts in its header and marks as the shell's. The shell shows it only while the navigation has no place in the layout, and it opens the navigation over the content.
6 navigation · اختياري	The region at the start edge that holds the product's destinations: a navigation drawer. Beside the main content in a wide window, its column of icons in a narrower one, over the content in a narrow one.
7 main	The content the page is for, and the page's one main landmark. Inset from the frame by a gutter and, by default, no wider than a readable width.
8 aside · اختياري	Content that supports the main content: an outline of the page, details of the selected thing, related links. Beside the main content at the end edge in a wide window, above or below it in a narrower one. A complementary landmark.
9 footer · اختياري	The region at the end of the page for what belongs to the whole site: its links, its legal line, its language and theme controls. The page's content-information landmark. Shown while the product fills it and has not hidden it (footerHidden).
10 navigation-bar · اختياري	The place at the bottom edge for a navigation bar, shown only in a narrow window, for a product whose three to five top-level destinations stay in reach of the thumb.
11 outline · اختياري	The hairline the shell draws between two regions that touch, where the system parts things with a line and the region's own component draws none: above the footer, and at the edge of an aside that is not a side sheet.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
scroll	page | main	"page"	What scrolls. page: the whole page scrolls in the window, the header stays at the top (headerPosition) and the navigation and the aside stay in view beside the content; the default, because it is what find-in-page, anchors, the back button's return to where the reader was, and a phone browser's collapsing bars are built for. main: the frame is exactly as tall as the window and only the main region scrolls inside it, for an app whose panes scroll apart from each other (a mail client, an editor).
headerPosition	sticky | static	"sticky"	Whether the header stays at the top of the window while the page scrolls (sticky) or scrolls away with it (static: an article that should have the whole window). Ignored while scroll is main, where the header never moves.
mainWidth	contained | full	"contained"	contained: the main region's content is no wider than the shell's readable width and is centred in the room the region has, for pages that are read. full: it takes all the room inside the gutters, for a table, a board, an editor.
asideOrder	after | before	"after"	Where the aside stands in reading and focus order, and so where it is drawn when it is not beside the main content. after: it follows the main content and is drawn below it (related links, details). before: it precedes the main content and is drawn above it (an outline of the page, which is of use only before the page is read). Beside the main content it is drawn at the end edge either way.
footerHidden	boolean	false	Whether the footer is left out of the frame although the product fills it: a screen that is a task rather than a page of the site (a checkout, a sign-in, an editor, a full-window map) keeps the site's footer markup and shows none. While true the footer takes no space, draws no line, is no landmark and has no stop in focus order, exactly as an empty footer region. The footer is shown only while the product fills the footer slot and this is false: footerHidden never makes a footer of an unfilled slot.
separation	auto | divider | gap	"auto"	How regions that touch are told apart. auto takes the design system's choice through comp.app-shell.separation; divider draws the one hairline; gap draws nothing and leaves the regions' own spaces. It concerns only the edges the shell draws: a component in a region that has an edge of its own (an app bar, a navigation drawer, a side sheet) keeps it.
navigationOpen	boolean	false	Whether the navigation is presented over the content, while it has no place of its own in the layout (or only its column). The menu button asks for true; closing the navigation, and any change of the window's class, makes it false. Ignored while the navigation stands beside the content.
asideLabel	string	""	Names the aside for assistive technology, in the product's language ("On this page"). Required where the aside is filled and what it holds does not name itself (a side sheet is named by its headline).

المنافذ

المنفذ	الوصف
default	The main region: the page's content. A fixture's content string is plain text.
skip-link	The skip link: a standalone Link whose destination is the main region, with the product's words ("Skip to content"). More than one may be given ("Skip to navigation"); each is shown while it has focus.
announcement	The notice above the header: a callout the product places, drawn across the frame's width.
header	The header: the product's app bar, with its search and its actions, and the menu button in its navigation slot.
navigation	The navigation: a navigation drawer, which draws each of the three presentations itself. Anything else is placed beside the content where the navigation has a place and is not shown where it has none.
aside	The aside: the product's supporting content, or a side sheet.
footer	The footer: the product's own layout of links, a legal line and controls. The shell gives it a place and an inset and no anatomy.
navigation-bar	A navigation bar for the bottom edge of a narrow window.

الأحداث

الحدث	الوصف
windowClassChange	The shell decided the window's class for the first time, or the window's width changed it; carries compact, medium or expanded. A product switches what follows the class and has no setting of its own for it: a search's presentation, a side sheet's variant, the form of an outline.
navigationOpenChange	The navigation asks to be presented over the content or to be put away: the menu button was activated (true), or the open navigation closed — by its scrim, Escape, the platform's back, a drag, a destination that was activated, or a change of the window's class (false). Carries the value asked for.

العناصر

أنواع العناصر التي يكررها المكوّن. يسرد كل نموذج اختبار عناصره بالترتيب، وتسمّي كل منصة كل نوع بأسلوبها.

menu-button

The one icon-only Button in the header that opens the navigation: a Button of the text variant and the medium size with the menu glyph and no label, unless the product sets otherwise, which the shell shows and hides and does not restyle.

الخاصية	النوع	القيمة الافتراضية	الوصف
label	string	""	Its accessible name ("Menu"), as the Button's label. Required.

المنفذ	الوصف
icon	Its glyph, as the Button's icon slot. A fixture item's content is this glyph.

الحدث	الوصف
click	The button was activated, as the Button's click. The shell answers it itself (APS-7); a product need not.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-button	TanreiButton	TanreiButton	TanreiButton	Button
label · الخاصية	label	label	contentDescription	semanticLabel	accessibilityLabel
click · الحدث	click	action	onClick	onPressed	onPress
ملاحظات	An icon-only <tanrei-button> anywhere inside the header region, marked with the data-app-shell-menu attribute: usually the app bar's slot="navigation" child. The glyph is its content.	An icon-only TanreiButton in the header, marked .tanreiAppShellMenuButton(); the shell reads the mark from the environment and hides the button outside the modal presentation.	An icon-only TanreiButton in the header with Modifier.tanreiAppShellMenuButton(); the shell draws it only in the modal presentation.	An icon-only TanreiButton wrapped in TanreiAppShellMenuButton, placed in the header; the wrapper builds nothing outside the modal presentation.	An icon-only Button element passed as menuButton; the shell hands it to the header through context (useAppShellMenuButton()) and renders it only in the modal presentation.

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
APS-1	THE app shell SHALL fill the window with comp.app-shell.container.color, hand everything it holds comp.app-shell.content.color as the platform's inherited foreground, and place its regions in this order: the announcement across the top; the header across the top below it; then a row that holds the navigation at the start edge, the main region, and the aside at the end edge; the footer across the bottom of the page; and the navigation bar across the bottom edge of the window. A region that holds nothing, and the footer WHILE footerHidden is true (APS-31), SHALL take no space, draw nothing and add no landmark, and the regions beside it SHALL take its room. THE app shell SHALL draw no elevation and no corner of its own.
APS-2	THE app shell SHALL give the window one of three classes by its width alone: compact WHILE the window is narrower than comp.app-shell.breakpoint.medium, medium WHILE it is at least that wide and narrower than comp.app-shell.breakpoint.expanded, and expanded WHILE it is at least comp.app-shell.breakpoint.expanded wide. It SHALL derive the class anew whenever the width changes, SHALL never store it, and SHALL NOT read the window's height, the device, the pointer or the orientation for it. WHERE the platform measures a window in a unit that grows with the reader's text size (the web's rem) the two widths SHALL be compared in that unit, so that enlarged text moves the frame to a narrower class before its columns become too narrow to read.
APS-3	WHEN the app shell first decides the window's class, and WHEN a change of the window's width changes it, THE app shell SHALL emit windowClassChange exactly once with the class, and SHALL make the present class known to everything it holds through the platform's own channel for inherited values, so that a component inside it can follow the class without measuring the window itself. A change of width inside one class SHALL emit nothing.
APS-4	THE app shell SHALL choose how the navigation is presented from the window's class: WHILE the class is expanded, beside the main region (the standard presentation); WHILE it is medium and what the navigation region holds has a collapsed form (a collapsible navigation drawer), as that collapsed form beside the main region, widening over the content WHILE navigationOpen is true (the column presentation); and otherwise with no place in the layout, presented over the content WHILE navigationOpen is true (the modal presentation). A navigation drawer in the region SHALL be drawn in each presentation exactly as a responsive drawer draws it (NVD-53 to NVD-55), and the two SHALL never disagree, because comp.app-shell.breakpoint.medium and comp.app-shell.breakpoint.expanded and the two widths that drawer reads alias the same window classes of the system (sys.breakpoint.medium, sys.breakpoint.expanded). WHILE the presentation is modal and the region holds something that cannot present itself over the content THE app shell SHALL NOT show it, SHALL keep it from focus and from assistive technology, and in debug builds SHALL report that the navigation of a narrow window needs a navigation drawer.
APS-5	WHILE the navigation has a place in the layout THE app shell SHALL put it at the start edge of the row, as wide as what it holds draws itself (a navigation drawer's width in its present form) and never wider than the window less sys.target.touch, SHALL give the main region all the room that is left, and SHALL add no padding, fill or edge to it. WHILE scroll is page THE app shell SHALL keep the navigation in view while the page scrolls — from below the header WHILE the header is sticky, else from the top of the window, to the window's bottom edge — and what it holds SHALL scroll inside that height by itself (NVD-61), never the page with it.
APS-6	WHILE the navigation's presentation is modal and the navigation region holds something THE app shell SHALL show the menu button where the product put it in the header; WHILE the presentation is standard or column, or the navigation region is empty, THE app shell SHALL NOT show the menu button, SHALL keep it from focus and from assistive technology, and SHALL give its place to what is beside it. THE app shell SHALL NOT restyle the menu button: it SHALL render as the icon-only Button it is, from its own tokens, with its own press, focus ring and minimum target.
APS-7	WHEN the menu button is activated THE app shell SHALL emit navigationOpenChange exactly once with true and become open — by setting navigationOpen itself on the web, through its binding where navigationOpen is one, and by the product setting it elsewhere — and what the navigation region holds SHALL present itself over the content as a modal overlay (a navigation drawer as NVD-19 says), taking focus. WHEN the open navigation closes (NVD-20, NVD-21) THE app shell SHALL emit navigationOpenChange exactly once with false, navigationOpen SHALL become false the same way, and focus SHALL return to the menu button. THE app shell SHALL expose the menu button as collapsed or expanded, controlling the navigation. WHEN the window's class changes WHILE navigationOpen is true THE app shell SHALL close the navigation at once and emit navigationOpenChange once with false (NVD-54).
APS-8	THE app shell SHALL inset the main region's content from the region's start and end by the gutter of the window's class — comp.app-shell.gutter.compact, comp.app-shell.gutter.medium or comp.app-shell.gutter.expanded — and from its top and bottom by comp.app-shell.main.padding-block. WHILE mainWidth is contained the content SHALL be no wider than comp.app-shell.main.max-width and SHALL be centred in the room the region has inside its gutters; WHILE mainWidth is full it SHALL take all of that room. THE main region SHALL never be wider than the room the row leaves it: content that cannot shrink (a table, a line of code) SHALL scroll inside its own box (PRS-15), and SHALL NOT widen the frame or make the page scroll sideways.
APS-9	WHILE the window's class is expanded THE app shell SHALL place the aside beside the main region at the end edge of the row, comp.app-shell.aside.width wide, its content inset by comp.app-shell.aside.padding-inline at the start and the end and by comp.app-shell.main.padding-block at the top and the bottom, so that its first line stands level with the main content's; WHILE scroll is page it SHALL keep the aside in view while the page scrolls, as APS-5 says of the navigation, and the aside SHALL scroll inside that height by itself when its content is taller. WHILE the class is medium or compact THE app shell SHALL place the aside in the main region's column, with the main region's gutters and, WHILE mainWidth is contained, its width and centring: above the main content WHILE asideOrder is before and below it WHILE asideOrder is after, comp.app-shell.aside.gap from it, scrolling with it.
APS-10	WHERE the aside holds a component that takes its own width in the layout and draws its own edge (a standard side sheet, SSH-1 and SSH-7) THE app shell SHALL give the aside that component's width in place of comp.app-shell.aside.width, SHALL add no inset to it and SHALL draw no edge beside it; WHERE it holds a component that presents itself over the content (a modal side sheet) the aside SHALL take no space in any class. THE app shell SHALL NOT change the variant of what the aside holds: a product that wants a sheet beside the content in an expanded window and over it in a narrower one sets the sheet's variant from windowClassChange.
APS-11	WHILE scroll is page THE app shell SHALL place the footer after the row of the navigation, the main region and the aside, across the frame's whole width, so that it is reached at the end of the page and the navigation and the aside stop staying in view where it begins; WHILE scroll is main THE app shell SHALL keep the footer at the bottom of the frame, below the row and above the navigation bar, always in view. THE app shell SHALL inset the footer's content by the gutter of the window's class (APS-8) at the start and the end and by comp.app-shell.footer.padding-block at the top and the bottom, and SHALL lay out nothing inside it: the footer's columns, links and controls are the product's.
APS-31	WHILE footerHidden is true THE app shell SHALL NOT show the footer, whatever the footer slot holds: the footer SHALL take no space, draw no line (APS-18), add no landmark (APS-21) and have no stop in focus order (APS-22), the regions beside it SHALL take its room, and WHILE scroll is page the navigation and the aside SHALL stay in view to the end of the page (APS-5, APS-9). WHILE footerHidden is false THE app shell SHALL show the footer exactly while the product fills the footer slot (APS-1, APS-11): it SHALL NOT draw a footer, or expose a content-information landmark, for a slot the product left unfilled. WHEN footerHidden changes THE app shell SHALL draw the new arrangement at once, without a motion of its own, SHALL keep what the footer slot holds as the product gave it, and IF keyboard focus is in the footer as it is hidden SHALL move focus to the main region.
APS-32	THE app shell SHALL draw each region in a stacking order of its own, so that nothing a region holds — whatever level its own stacking order (a z-index) gives it — is drawn over another region: WHILE scroll is page THE app shell SHALL draw the header and the navigation bar over every other region, the footer included, while the page scrolls under them, and SHALL draw the footer over the navigation and the aside. WHILE the skip link has keyboard focus THE app shell SHALL draw it over every region (APS-19). THE app shell SHALL itself be one stacking order within the page, so that no level of its parts competes with what the product draws outside the frame. What stands over the whole frame — a menu, a popover, a tooltip, a snackbar, a dialog, a sheet, a modal drawer — SHALL be drawn above it by the platform's own layer for overlays, never by a level within a region.
APS-12	WHILE the announcement region holds something THE app shell SHALL place it across the frame's whole width above the header, with no inset of its own, in every class; WHILE scroll is page the announcement SHALL scroll away with the page and a sticky header SHALL then rest at the top of the window, and WHILE scroll is main it SHALL stay above the header. WHEN what the announcement holds is removed or closes (a callout whose open becomes false) THE app shell SHALL give its room back at once.
APS-13	WHILE the window's class is compact and the navigation-bar region holds something THE app shell SHALL keep it at the bottom edge of the window across the frame's whole width, over the bottom system inset as the bar itself lays out (NVB-18), in view while the page scrolls, and SHALL end the page, or the frame, above it so that nothing is covered by it; WHILE the class is medium or expanded THE app shell SHALL NOT show the navigation-bar region, SHALL keep it from focus and from assistive technology, and SHALL give it no space. THE app shell SHALL NOT choose between the bar and the navigation for the product: a product whose bar is its navigation in a compact window gives no menu button.
APS-14	WHILE scroll is page THE app shell SHALL be at least as tall as the window and as tall as its content, SHALL let the window's own scrolling view scroll the page, and SHALL make no region a scrolling view except the navigation and the aside where APS-5 and APS-9 keep them in view; so that the platform's find-in-page, a link to a place in the page, the return to where the reader was, and a browser's collapsing bars work as they do on a page without a shell.
APS-15	WHILE scroll is main THE app shell SHALL be exactly as tall as the window, less the on-screen keyboard where one covers it, SHALL keep the announcement, the header, the footer and the navigation bar in place, and SHALL make the main region the one scrolling view of the frame, reachable and scrollable from the keyboard, with the aside scrolling inside its own height WHILE it is beside the main region and with the main region WHILE it is above or below it. THE window itself SHALL NOT scroll.
APS-16	WHILE scroll is page and headerPosition is sticky THE app shell SHALL keep the header at the top of the window, above the main region, the navigation and the aside, while the page scrolls under it; WHILE headerPosition is static the header SHALL scroll away with the page. THE app shell SHALL NOT fill, raise or edge the header: an app bar in it draws its own scrolled condition from the scrolling view it is connected to (APB-9), which is the window WHILE scroll is page and the main region WHILE scroll is main.
APS-17	THE app shell SHALL hold the height of what it keeps over the top of the scrolling view — a sticky header's present height, measured again whenever the header changes size, and nothing WHILE headerPosition is static — and SHALL make it known to the scrolling view and to everything it holds, so that a heading or any other place a link or the address moves the view to (PRS-23), and an element that takes keyboard focus, come to rest below the header and never under it; likewise for the navigation bar's height at the bottom. A heading's own space before it (PRS-6) is added to that distance by the prose, not by the shell.
APS-18	WHILE separation is auto THE app shell SHALL part its regions as comp.app-shell.separation names, and WHILE separation is divider or gap as that value says, whatever the token says: divider draws a line comp.app-shell.outline.width thick in comp.app-shell.outline.color along the footer's top edge, along the start edge of an aside that stands beside the main region, and between the main content and an aside that stands above or below it, in the middle of comp.app-shell.aside.gap; gap draws no line and leaves the same spaces. The lines SHALL take no room of their own. THE app shell SHALL draw no line beside a region whose component draws its own edge (APS-10, APS-16) and none around the navigation, the announcement or the navigation bar. WHEN separation names a value the app shell does not define it SHALL be treated as auto.
APS-19	WHILE the skip-link region holds a Link THE app shell SHALL make it the first element the keyboard reaches in the frame, before the announcement and the header, SHALL draw nothing of it while it does not have keyboard focus and still keep it in the focus order and exposed to assistive technology, and WHILE it has keyboard focus SHALL draw it comp.app-shell.skip-link.offset from the top and the start edges of the window, inside the system insets, above every region and every sticky part: in a box filled with comp.app-shell.skip-link.container.color and raised by comp.app-shell.skip-link.container.elevation, with corners comp.app-shell.skip-link.container.shape eased by sys.shape.corner-smoothing, padded by comp.app-shell.skip-link.container.padding-inline and comp.app-shell.skip-link.container.padding-block, its text in comp.app-shell.skip-link.label.typescale; the Link SHALL keep its own color, underline, focus ring and states (LNK-1). The box SHALL appear and go at once, without motion, and SHALL move no other part of the frame.
APS-20	WHEN the skip link is followed THE app shell SHALL move keyboard focus to the main region itself — not to the first control in it — and bring the region's top into view below the header (APS-17) at once, without a scrolling motion, so that the next Tab reaches the first focusable element of the content and a screen reader starts reading there; the main region SHALL take focus only this way and SHALL NOT be a stop of the Tab order.
APS-21	THE app shell SHALL expose each filled region as the landmark it is: the header as the page's banner, the navigation and the navigation bar as what they hold expose (a navigation landmark named by its own label), the main region as the page's one main landmark, the aside as a complementary landmark named by asideLabel (or by what it holds, where that names itself), and the footer as the page's content information; the announcement and the skip link SHALL add no landmark. IF the frame holds no main region, or more than one, or an aside that has no name, THE app shell SHALL still lay out what it holds, and in debug builds SHALL report it.
APS-22	THE app shell SHALL NOT be focusable and SHALL move focus through its regions in reading order, the same in every class and in either layout direction: the skip link, the announcement, the header, the navigation, the aside WHILE asideOrder is before, the main region's content, the aside WHILE asideOrder is after, the footer, the navigation bar. A region that is not shown (APS-4, APS-6, APS-13, APS-31) SHALL have no stop in that order. THE app shell SHALL NOT keep focus inside a region that has a place in the layout: only a region presented over the content holds it.
APS-23	WHEN the window's class changes THE app shell SHALL draw the new arrangement at once, without a motion of its own; SHALL keep scroll, headerPosition, mainWidth, asideOrder, footerHidden and separation as they are; SHALL keep the reader at the same place in the main content as far as the new arrangement allows; and IF keyboard focus is on something the new arrangement does not show (the menu button, a navigation bar's destination) SHALL move it to the main region, unless the navigation it holds has already moved it (NVD-54).
APS-24	WHERE the app shell is rendered before the window's width is known or before its own code runs (a page rendered on a server) THE app shell SHALL already be laid out for the window's class by the platform's layout alone — every region in its place, the regions that the class does not show taking no space, the skip link first and working — SHALL present nothing over the content, SHALL make nothing inert, and SHALL emit no event until the class is decided; its own code SHALL then add only what layout cannot: the events, the menu button's opening of the navigation, and the measured distance of APS-17, without moving anything that was already drawn.
APS-25	WHILE the text size is enlarged THE app shell SHALL keep its gutters and insets, let every region grow with its text, and SHALL need no scrolling in two directions at any width down to 320 points: in a compact window the frame is one column, the main region never narrower than the window less two gutters, and only a block that scrolls in its own box (APS-8) scrolls sideways. THE app shell SHALL NOT fix the height of any region.
APS-26	WHERE the platform's forced-colors or increased-contrast mode replaces the product's colors THE app shell SHALL let the system's colors fill its frame, SHALL draw the lines of APS-18 in the system's text color WHILE they are drawn, and SHALL draw an edge comp.app-shell.outline.width thick in the system's text color around the skip link's box, because the mode removes the fill and the elevation that set it apart.
APS-27	THE app shell SHALL extend its fill under every system inset (status bar, camera cutout, home indicator, window caption) and SHALL keep the main region's, the aside's and the footer's content inside the start, end and bottom insets; the header, the navigation and the navigation bar lay themselves out over the insets at their own edges (APB-10, NVD-25, NVB-18), and the app shell SHALL NOT inset them a second time.
APS-28	THE app shell 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 app shell is shown THE app shell SHALL draw itself for the new direction at once, without a motion of its own, keeping the window's class, navigationOpen and the reader's place in the content. WHERE the layout direction is right-to-left the navigation SHALL stand at the right edge and the aside at the left, the skip link's box at the top right, the menu button where the header puts its start, and the lines of APS-18 on the mirrored edges; the order of APS-22 SHALL NOT change, and nothing a region holds SHALL be mirrored by the shell.
APS-29	WHEN scroll, headerPosition, mainWidth or asideOrder names a value the app shell does not define THE app shell SHALL render with that prop's default, and in debug builds report the unknown value.
APS-30	THE app shell SHALL NOT restyle, resize or re-order what the product puts in a region beyond the place and the insets this spec gives, SHALL NOT decide which page is shown, follow a link, load anything, remember anything beyond its own lifetime (which page, how far a region was scrolled, whether the navigation was collapsed) or set the document's title or language; and SHALL NOT scroll anything with motion: every movement it causes (APS-17, APS-20, APS-23) is at once, whether or not motion is reduced.
APS-33	WHILE the navigation region holds a navigation drawer whose filterable is true and whose filterShortcut holds exactly one chord, and the navigation's presentation is modal and navigationOpen is false, WHEN the person presses that chord anywhere in the window — read as SRC-38 reads a chord and with its exceptions (a press something else has taken, a key repeating while held, an input-method composition and, for a chord without mod, ctrl or alt, focus in an element that takes text) — THE app shell SHALL keep the press from doing anything else, open the navigation as an activation of the menu button does (APS-7: navigationOpenChange with true), and ask the drawer to focus its filter (NVD-88), so that focus is in the drawer's filter field once it is open. WHILE the drawer is shown — beside the main region, or as its column — the drawer answers the chord itself (NVD-87) and THE app shell SHALL NOT. THE app shell SHALL bind no other key for the navigation.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-app-shell	TanreiAppShell	TanreiAppShell	TanreiAppShell	AppShell
scroll · الخاصية	scroll	scroll	scroll	scroll	scroll
headerPosition · الخاصية	headerPosition	headerPosition	headerPosition	headerPosition	headerPosition
mainWidth · الخاصية	mainWidth	mainWidth	mainWidth	mainWidth	mainWidth
asideOrder · الخاصية	asideOrder	asideOrder	asideOrder	asideOrder	asideOrder
footerHidden · الخاصية	footerHidden	isFooterHidden	footerHidden	footerHidden	footerHidden
separation · الخاصية	separation	separation	separation	separation	separation
navigationOpen · الخاصية	navigationOpen	isNavigationPresented	navigationOpen	navigationOpen	navigationOpen
asideLabel · الخاصية	asideLabel	asideLabel	asideLabel	asideSemanticLabel	asideLabel
windowClassChange · الحدث	windowclasschange	onWindowClassChange	onWindowClassChange	onWindowClassChanged	onWindowClassChange
navigationOpenChange · الحدث	navigationopenchange	isNavigationPresented	onNavigationOpenChange	onNavigationOpenChanged	onNavigationOpenChange
ملاحظات	An element and a stylesheet: <tanrei-app-shell> attaches no shadow root, and the package's @tanrei/web/app-shell.css lays out its light-DOM children from the element's name, its attributes and each child's slot attribute alone, so a page rendered on a server is laid out before the element is defined and with scripts off (APS-24). The regions are the product's own semantic elements: <a class="tanrei-link" data-standalone slot="skip-link" href="#main">, <div slot="announcement">, <header slot="header"> around a <tanrei-app-bar>, <tanrei-navigation-drawer slot="navigation" responsive>, the one <main id="main" tabindex="-1"> child without a slot (the default region), <aside slot="aside" aria-label="…">, <footer slot="footer"> and <tanrei-navigation-bar slot="navigation-bar">, written in the order of APS-22; the stylesheet places them on a grid by name and never reorders focus. Attributes: scroll, header-position, main-width, aside-order, footer-hidden, separation, navigation-open, aside-label. The window's class is chosen by @media conditions in rem; a custom property cannot stand in a media condition, so the generator writes the two widths into the stylesheet from the active system's tokens (one stylesheet per system that changes them). The menu button is hidden by the same conditions, with :has(> [slot="navigation"][collapsible]) telling the column presentation from the modal one. Sticky parts are position: sticky; the frame and each region are isolation: isolate (APS-32), the footer is z-index: 1, the header and the navigation bar 2 and the focused skip link 3 — levels within the frame, which no z-index inside a region reaches; the navigation and the aside are align-self: start with a maximum block size of the dynamic viewport height less the scroll offset and overflow: auto with overscroll-behavior: contain. scroll="main" makes the host 100dvh high and the <main> the scroller. It does not yet follow the part of APS-15 that has an aside above or below the main region scroll with it: a stylesheet cannot make the <main> and its sibling <aside slot="aside"> one scrolling view, and making the frame itself the scroller in that arrangement would take the scrolling view away from the <main> that the app bar's scroll-target (APS-16) and the skip link (APS-17, APS-20) name, and would need the announcement's and the navigation bar's heights before the element is defined (APS-24). Until it does, a product that uses scroll="main" and wants the aside to scroll with the content in a compact or medium window writes that content inside the <main> for those classes. The stylesheet defines --tanrei-app-shell-scroll-offset on the document's root (until the element is defined: the small app bar's height while the header is sticky, else 0) and sets the root's scroll-padding-block-start from it — or the main element's while scroll is main; once defined, the element measures the header with a ResizeObserver and rewrites the property. The product's own sticky parts (a table's header row) read the same property. --tanrei-prose-scroll-offset stays 0 inside a shell: the scroll padding already clears the header, and prose adds only a heading's own space. The upgraded element adds: the read-only windowClass property, reflected as the data-window-class state attribute, and windowclasschange with detail.windowClass, from two matchMedia listeners (no resize listener and no frame loop); the menu button's click, which sets navigationOpen and the open of a <tanrei-navigation-drawer> in the navigation region, follows that drawer's close, and writes aria-expanded and aria-controls through the Button's element properties; role and aria-label on a region whose element does not already give the landmark (a <tanrei-app-bar slot="header"> with no <header> around it; an aside without a name takes aside-label); tabindex="-1" on a <main> that lacks it; and the debug reports of APS-4, APS-21 and APS-29. It listens to nothing while no region needs it. With scroll="main" the product names the main element's id in the app bar's scroll-target. footer-hidden gives the footer region display: none from the stylesheet (with !important, so a product's own display on its <footer> cannot bring it back): it then has no box, no landmark and no focus stop, its measured height is 0, and the element moves focus that was inside it to the main region. The skip link is hidden with a clip, never display: none, and shown on :focus-visible; under forced-colors: active its box gains a CanvasText border. Insets are env(safe-area-inset-*). A filterable drawer’s chord (APS-33): the element holds one keydown listener on the window while the navigation’s presentation is modal, navigationOpen is false and the drawer in the navigation region is filterable with exactly one chord in filterShortcut (read as the drawer reads it); the chord opens the navigation as the menu button does and then calls the drawer’s focusFilter(). The React wrapper renders the same light DOM on a server.	TanreiAppShell(scroll:, headerPosition:, mainWidth:, asideOrder:, isFooterHidden:, separation:, isNavigationPresented: Binding<Bool>, asideLabel:) { main } header: { … } navigation: { … } aside: { … } footer: { … } announcement: { … } navigationBar: { … }. A layout of its own, not NavigationSplitView, whose column widths and collapsing cannot be set from the tokens. The window's class comes from the width of the scene (a GeometryReader at the root, in points; Dynamic Type does not change it) and is published as the environment value \.tanreiWindowClass, which a search or a side sheet inside the shell reads. scroll: .page is one ScrollView holding the announcement, the main content, a stacked aside and the footer, with the header in .safeAreaInset(edge: .top) and the navigation and the aside beside it; .main keeps the footer in .safeAreaInset(edge: .bottom). The header's height is published as \.tanreiAppShellScrollOffset and applied as the scroll view's content margin, so ScrollViewReader.scrollTo rests below it. Regions are exposed with accessibilityElement(children: .contain) and one entry each in a custom rotor, the aside labelled by asideLabel. No skip link: VoiceOver's rotor and Full Keyboard Access's group navigation move between regions.	TanreiAppShell(navigationOpen, onNavigationOpenChange, modifier, scroll, headerPosition, mainWidth, asideOrder, footerHidden, separation, asideLabel, onWindowClassChange, announcement = {}, header = {}, navigation = {}, aside = {}, footer = {}, navigationBar = {}) { contentPadding -> main }, in the manner of a scaffold with a custom Layout. The window's class comes from LocalWindowInfo.current.containerSize in dp and is provided as LocalTanreiWindowClass. scroll = Page nests the main content, a stacked aside and the footer in one vertical scroll with the header pinned through a nested-scroll connection; the measured header height is provided as LocalTanreiAppShellScrollOffset and as contentPadding. Regions are exposed with Modifier.semantics { isTraversalGroup = true; paneTitle = … }, the aside's from asideLabel. System insets through WindowInsets.safeDrawing. No skip link: TalkBack and keyboard traversal groups move between regions.	TanreiAppShell({ required Widget main, Widget? announcement, header, navigation, aside, footer, navigationBar, bool navigationOpen, bool footerHidden = false, ValueChanged<bool>? onNavigationOpenChanged, … }), a widget of its own in the manner of a scaffold (CustomMultiChildLayout), not Scaffold, whose drawer and bar slots draw Material's own. The window's class comes from MediaQuery.sizeOf(context).width in logical pixels and is inherited as TanreiWindowClass.of(context). scroll: page is a CustomScrollView with a pinned header sliver; the header's height is inherited as TanreiAppShellScrollOffset.of(context) and applied as scroll padding for Scrollable.ensureVisible. Regions are Semantics(container: true, explicitChildNodes: true, label: …) in a FocusTraversalGroup with an ordered policy (APS-22). Insets from MediaQuery.viewPaddingOf. No skip link, except on Flutter for the web, which is not a target of this package.	<AppShell navigationOpen onNavigationOpenChange header={…} navigation={…} aside={…} footer={…} footerHidden announcement={…} navigationBar={…} menuButton={…}>{main}</AppShell>. The window's class comes from useWindowDimensions().width and is given by context (useWindowClass()). scroll="page" is one ScrollView with stickyHeaderIndices for the header; the header's height is measured with onLayout and given by context (useAppShellScrollOffset()). Regions carry accessibilityRole where the platform has one (header, menu, summary) and accessibilityLabel; the order of APS-22 is the order of the rendered views. Insets from the safe-area context the package already depends on. The layout direction is the app's. No skip link.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--tanrei-comp-app-shell-aside-gap	sys.space.space300	24px
--tanrei-comp-app-shell-aside-padding-inline	sys.space.space200	16px
--tanrei-comp-app-shell-aside-width	—	240px
--tanrei-comp-app-shell-breakpoint-expanded	sys.breakpoint.expanded	1024px
--tanrei-comp-app-shell-breakpoint-medium	sys.breakpoint.medium	600px
--tanrei-comp-app-shell-container-color	sys.color.surface	#ffffff
--tanrei-comp-app-shell-content-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-app-shell-footer-padding-block	sys.space.space400	32px
--tanrei-comp-app-shell-gutter-compact	sys.space.space200	16px
--tanrei-comp-app-shell-gutter-expanded	sys.space.space400	32px
--tanrei-comp-app-shell-gutter-medium	sys.space.space300	24px
--tanrei-comp-app-shell-main-max-width	—	768px
--tanrei-comp-app-shell-main-padding-block	sys.space.space400	32px
--tanrei-comp-app-shell-outline-color	sys.color.outline-variant	#000000 · 8%
--tanrei-comp-app-shell-outline-width	sys.border.hairline	1px
--tanrei-comp-app-shell-separation	sys.behavior.separation	0
--tanrei-comp-app-shell-skip-link-container-color	sys.color.surface-container-high	#f3f3f3
--tanrei-comp-app-shell-skip-link-container-elevation	sys.elevation.level3	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 1px 0px rgb(0 0 0 / 0.04), 0px 4px 8px -4px rgb(0 0 0 / 0.04), 0px 16px 24px -8px rgb(0 0 0 / 0.06)
--tanrei-comp-app-shell-skip-link-container-padding-block	sys.space.space150	12px
--tanrei-comp-app-shell-skip-link-container-padding-inline	sys.space.space200	16px
--tanrei-comp-app-shell-skip-link-container-shape	sys.shape.corner.small	6px
--tanrei-comp-app-shell-skip-link-offset	sys.space.space100	8px
--tanrei-comp-app-shell-skip-link-label-typescale	sys.typescale.label	500 14px/1.4286

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

expanded

asideLabel: On this page items: 1 slots: skip-link, header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-main-only

slots: header مرسوم وحده في نافذة بحجم 1280 × 800

expanded-no-aside

slots: header, navigation, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-footer-hidden

footerHidden: true asideLabel: On this page slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-no-navigation

asideLabel: On this page slots: header, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-announcement

asideLabel: On this page slots: announcement, header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-full

mainWidth: full slots: header, navigation, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-divider

separation: divider asideLabel: On this page slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-gap

separation: gap asideLabel: On this page slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-scroll-main

scroll: main asideLabel: Details slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

expanded-rtl

asideLabel: في هذه الصفحة direction: rtl slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 1280 × 800

medium

asideLabel: Related items: 1 slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 800 × 800

medium-aside-before

asideOrder: before asideLabel: On this page items: 1 slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 800 × 800

compact

asideLabel: Related items: 1 slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 400 × 800

compact-aside-before

asideOrder: before asideLabel: On this page items: 1 slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 400 × 800

compact-announcement

items: 1 slots: announcement, header, navigation, footer مرسوم وحده في نافذة بحجم 400 × 800

compact-navigation-bar

slots: header, navigation, footer, navigation-bar مرسوم وحده في نافذة بحجم 400 × 800

compact-scroll-main

scroll: main slots: header, navigation, footer, navigation-bar مرسوم وحده في نافذة بحجم 400 × 800

compact-rtl

asideOrder: before asideLabel: في هذه الصفحة direction: rtl items: 1 slots: header, navigation, aside, footer مرسوم وحده في نافذة بحجم 400 × 800

compact-narrowest

asideLabel: Related items: 1 slots: announcement, header, navigation, aside, footer مرسوم وحده في نافذة بحجم 320 × 640

مولَّد من specs/app-shell.spec.json, tokens/comp/app-shell.tokens.json, design/tokens/

الإرشادات

link

ثلاث فئات للنافذة

link

يعطي الهيكل النافذة واحدة من ثلاث فئات بحسب عرضها وحده.

الفئة	العرض	التنقل	المنطقة الجانبية	زر القائمة	شريط التنقل	الهامش الجانبي
compact	أقل من 600	فوق المحتوى، حين يُفتح	فوق المحتوى الرئيسي أو تحته	يظهر	يظهر	16
medium	من 600 إلى 1023	عمود أيقونات الدرج حيث يكون له collapsible. وإلا فكما في الفئة compact	فوقه أو تحته	يظهر ما لم يظهر العمود	لا يظهر	24
expanded	1024 فأكثر	بجانب المحتوى	بجانب المحتوى، عند حافة النهاية	لا يظهر	لا يظهر	32

• العرضان هما الرمزان sys.breakpoint.medium و sys.breakpoint.expanded. ودرج التنقل الذي له responsive يقرأ الرمزين نفسيهما، فيتغيّر الإطار والدرج معًا.
• على الويب تُقارَن العروض بالوحدة rem. والقارئ الذي يكبّر الصفحة يحصل على الترتيب الأضيق قبل أن تضيق الأعمدة حتى تتعذّر قراءتها.
• الحدث windowclasschange يخبرك بالفئة، والخاصية windowClass تحملها. بدِّل منها ما لا يبدّله الهيكل: طريقة عرض البحث، وطراز اللوحة الجانبية، وهيئة مخطَّط الصفحة.
• على الويب يرث كل ما في الإطار أيضًا --tanrei-app-shell-window-class، فتستطيع ورقة أنماط أن تتبع الفئة باستعلام حاوية عن النمط (style container query) ومن دون سكربت.

زر القائمة

link

ضع في الترويسة زرًّا واحدًا من المكوّن Button بأيقونة وحدها، وعلِّمه بالخاصية data-app-shell-menu. يُظهره الهيكل فقط ما دام التنقل بلا مكان في التخطيط. والضغط عليه يفتح الدرج فوق المحتوى وينقل التركيز إليه. وإغلاق الدرج يعيد التركيز إلى الزر. والزر يقول هل التنقل موسَّع.

الخاصية navigationOpen (navigation-open) تحمل تلك الحالة، والحدث navigationopenchange يخبرك حين يغيّرها شخص. وتغيّر فئة النافذة يغلق التنقل.

ما الذي يُمرَّر

link

scroll	ما الذي يُمرَّر	يُستخدم لـ
page (الافتراضي)	النافذة تمرّر الصفحة. الترويسة لاصقة، والتنقل والمنطقة الجانبية يبقيان في مجال الرؤية بجانب المحتوى.	صفحات تُقرأ: التوثيق، والمقالات، والإعدادات.
main	الإطار هو النافذة تمامًا، والمنطقة الرئيسية وحدها تُمرَّر.	تطبيق تُمرَّر لوحاته كلٌّ على حدة: عميل بريد، أو محرر.

• فضِّل القيمة page. فالبحث في الصفحة، والروابط إلى عنوان قسم، والعودة إلى حيث كان القارئ، وأشرطة متصفح الهاتف التي تنطوي، كلها تعمل كما تعمل في صفحة بلا هيكل.
• القيمة headerPosition: static تدع الترويسة تذهب مع الصفحة حين تُمرَّر.
• مع scroll: main على الويب، سمِّ معرّف العنصر الرئيسي في خاصية شريط التطبيق scroll-target.
• مع scroll: main على الويب، تبقى المنطقة الجانبية المرسومة فوق المحتوى الرئيسي أو تحته (في نافذة من الفئة compact أو medium) ثابتة في مكانها فيما تُمرَّر المنطقة الرئيسية؛ فهي لا تُمرَّر معها بعد. والمحتوى الذي ينبغي أن يُمرَّر مع الصفحة مكانه داخل <main>.
• على الويب اسم خاصية JavaScript هو scrolls، لأن لكل عنصر من قبلُ دالة scroll(). وخاصية HTML هي scroll.

الروابط إلى عنوان قسم تستقر تحت الترويسة

link

يقيس الهيكل الترويسة اللاصقة ويعطي منطقة تمرير الصفحة حشوًا بذلك المقدار. فالرابط إلى عنوان قسم، والعنصر الذي يأخذ تركيز لوحة المفاتيح، يستقران تحت الترويسة، لا خلفها أبدًا. وعلى الويب تكون المسافة نفسها في --tanrei-app-shell-scroll-offset على الجذر، لأجزائك اللاصقة أنت، كصف الترويسة في جدول. وداخل الهيكل اترك --tanrei-prose-scroll-offset بالقيمة 0.

ما الذي يعلو ماذا

link

• تعلو الترويسة وشريط التنقل كل ما يُمرَّر تحتهما، والتذييل منه. لا يرتفع فوقهما شيء من المنطقة الرئيسية أو المنطقة الجانبية أو التذييل، أيًّا كانت قيمة z-index له: فكل منطقة ترصّ ما تحويه داخلها هي.
• القوائم والنوافذ المنبثقة (popovers) والتلميحات والإشعارات القصيرة ومربعات الحوار واللوحات تعلو الهيكل كله. ومكوّنات Tanrei منها ترسم نفسها هناك: على الويب، في الطبقة العليا (top layer) للمتصفح. ارسم أي طبقة عائمة تصنعها أنت بالطريقة نفسها، عنصرًا بخاصية popover أو <dialog> يُفتح بـ showModal()، لا بقيمة z-index كبيرة أبدًا.
• وعلى الويب يكون الهيكل سياقَ تراصٍّ (stacking context) قائمًا بذاته، فلا يتنافس أي مستوى داخله مع ما ترسمه صفحتك خارجه.

عرض المنطقة الرئيسية

link

• القيمة mainWidth: contained (الافتراضية) تُبقي المحتوى بعرض لا يزيد على 768 وتوسّطه في حيّزه. استخدمها لصفحات تُقرأ.
• القيمة mainWidth: full تأخذ الحيّز كله داخل الهوامش الجانبية. استخدمها لجدول أو لوحة مهام أو محرر.
• المحتوى الذي لا يستطيع أن ينكمش، كجدول عريض أو سطر من الشيفرة، يُمرَّر داخل صندوقه. ولا يوسّع الإطار أبدًا.

المنطقة الجانبية

link

• في نافذة من الفئة expanded تقف المنطقة الجانبية بجانب المحتوى الرئيسي، بعرض 240، وتبقى في مجال الرؤية والصفحة تُمرَّر.
• في نافذة أضيق تنضم إلى عمود المحتوى الرئيسي. القيمة asideOrder: before ترسمها فوق المحتوى الرئيسي، وذلك يناسب مخطَّطًا للصفحة. والقيمة after (الافتراضية) ترسمها تحته، وذلك يناسب الروابط ذات الصلة.
• الخاصية asideOrder هي ترتيب القراءة أيضًا. على الويب، اكتب العنصر <aside> في تلك الجهة من العنصر <main> في الترميز.
• سمِّ المنطقة الجانبية بالخاصية asideLabel، بلغتك.
• اللوحة الجانبية الموضوعة في المنطقة الجانبية تحتفظ بعرضها وحافتها. عيِّن طرازها من الحدث windowclasschange.

التذييل

link

• يُعرض التذييل ما دمت تملأ منطقته. وإن لم تملأها فلا تذييل ولا مَعلم.
• الخاصية footerHidden (footer-hidden) تُخفي تذييلًا ملأته، دون أن تُخرجه من الترميز. استعملها في شاشة هي مهمة لا صفحة من الموقع: إتمام شراء، أو تسجيل دخول، أو محرر. عندئذ لا يأخذ التذييل مساحة، ولا يرسم خطًا، ولا يكون مَعلمًا، ولا موضع توقف فيه للوحة المفاتيح، ويبقى التنقل والمنطقة الجانبية ظاهرين حتى نهاية الصفحة.
• إخفاء التذييل في أثناء وجود التركيز داخله ينقل التركيز إلى المنطقة الرئيسية.

الخطوط بين المناطق

link

separation	ما يرسمه
auto (الافتراضي)	ما اختاره نظام التصميم: خطوط في النظام الافتراضي.
divider	خط رفيع فوق التذييل، وعند حافة البداية لمنطقة جانبية تقف بجانب المحتوى، وبين المحتوى الرئيسي ومنطقة جانبية مرصوصة معه.
gap	لا خط. والفراغات نفسها.

الخطوط لا تأخذ حيّزًا. ولا يرسم الهيكل أي خط حول الترويسة ولا التنقل ولا الإعلان ولا شريط التنقل: فتلك المكوّنات ترسم حوافها بنفسها. وشريط التطبيق في الترويسة يرسم حافته السفلية وهو ساكن، حدًّا لمنطقة تبقى في مكانها، ويُبقيها والصفحة تُمرَّر تحته؛ اضبط dividerVisibility للشريط على scroll ليُظهرها فقط حين يصير تحته محتوى.

افعل

link

• أعطِ كل صفحة عنصر <main> واحدًا، وأعطِه المعرّف الذي يسمّيه رابط التخطي.
• اكتب كلمات رابط التخطي بلغتك. لا يتضمن Tanrei أي كلمات.
• استخدم في منطقة التنقل درج تنقل له responsive.

لا تفعل

link

• لا تضع عنوان الصفحة ولا وصفها ولا إجراءاتها في الهيكل. فمكانها رأس الصفحة، وهو أول ما في المنطقة الرئيسية.
• لا تضع تذييل مقال (السابق والتالي، ورابط التعديل) في منطقة التذييل. فهو ينهي المحتوى الرئيسي. ومنطقة التذييل لما يخص الموقع كله.
• لا تغيّر ترتيب المناطق بلغة CSS. فترتيب الترميز هو ترتيب التركيز.

إمكانية الوصول

link

الدور

none

التسمية

The shell has no role and no name. Its regions are the page's landmarks: banner (the header), navigation (named by the label of the navigation drawer or the navigation bar it holds), main (exactly one, unnamed), complementary (the aside, named by asideLabel or by the side sheet's headline) and content information (the footer, while it is shown: an unfilled or hidden footer is no landmark). The skip link is named by its own text and the menu button by its label, both in the product's language: Tanrei ships no words.

الحد الأدنى للهدف

تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء
Tab / Shift+Tab	Moves through the frame in reading order: the skip link, the announcement, the header, the navigation, the main content and the aside in the order asideOrder gives, the footer, the navigation bar. The shell itself is not a stop.
Enter, on the skip link	Moves focus to the main region and brings its top into view below the header.
Enter / Space, on the menu button	Opens the navigation over the content and moves focus into it; Escape there closes it and returns focus to the menu button (the navigation drawer's own keys).
/ (a filterable drawer's chord, in a narrow window)	Opens the navigation over the content and moves focus to the drawer's filter field (APS-33). Where the drawer is shown, the drawer answers it.

ملاحظات

• The shell takes no input: the skip link is a Link and the menu button an icon-only Button, and each meets the minimum target by its own spec (LNK-17, BTN-5).
• The skip link is what lets a keyboard pass the header and the navigation in one step (WCAG 2.4.1); the landmarks let a screen reader do the same. Both are needed: a sighted keyboard user has no landmark list.
• Focus is never hidden by the frame (WCAG 2.4.11): the scrolling view keeps the height of the sticky header and of the navigation bar clear when it brings a focused element into view (APS-17).
• Reading order, focus order and the order of the markup are one order in every window class (APS-22), which is why the aside's place is a setting (asideOrder) and not something the layout rearranges by width.
• Reflow (WCAG 1.4.10): at 320 points the frame is one column; the widths that decide the class grow with the text on the web (APS-2), so 200 % text in a 1280 window is laid out as a medium one.
• A second navigation landmark is not an error: a navigation drawer, a navigation bar, breadcrumbs and a pagination each name themselves, and only one of the drawer and the bar is shown at a time unless the product keeps both.
• On SwiftUI, Compose, Flutter and React Native there is no skip link: each platform's assistive technology moves between regions by its own gesture or rotor, and the shell marks the regions for it.

مولَّد من specs/app-shell.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

link

• كل منطقة مملوءة هي مَعلمها: الترويسة (banner)، والتنقل، والرئيسي، والتكميلي (complementary)، ومعلومات المحتوى (content information). والمنطقة التي لا يعطي عنصرها المَعلم تُعطى الدور.
• رابط التخطي أول موضع تتوقف عنده لوحة المفاتيح. واتباعه ينقل التركيز إلى المنطقة الرئيسية نفسها، وأعلاها ظاهر تحت الترويسة. وضغطة Tab التالية تبلغ أول عنصر تحكم في المحتوى.
• المفتاح Tab يمرّ بالمناطق بترتيب القراءة، وهو الترتيب نفسه في كل فئات النافذة وفي اتجاهَي التخطيط كليهما، من اليسار إلى اليمين ومن اليمين إلى اليسار. والمنطقة غير المعروضة لا موضع توقف لها.
• وجهة الرابط والعنصر الذي عليه التركيز لا يُتركان أبدًا خلف الترويسة اللاصقة ولا خلف شريط التنقل.
• حين تتغيّر فئة النافذة والتركيز على شيء لم يعد معروضًا، كزر القائمة، ينتقل التركيز إلى المنطقة الرئيسية.
• التذييل المخفي (footerHidden) ليس في شجرة إمكانية الوصول، ولا موضع توقف فيه للوحة المفاتيح.
• عند تكبير النص إلى 200% في نافذة عرضها 320 يكون الإطار عمودًا واحدًا ولا يُمرَّر شيء أفقيًّا.
• في الألوان المفروضة (forced colors) تُرسم الخطوط وصندوق رابط التخطي بلون نص النظام.
• في تخطيط من اليمين إلى اليسار يقف التنقل في اليمين والمنطقة الجانبية في اليسار. وترتيب التركيز لا يتغيّر.

ما عليك فعله

link

• عنصر <main> واحد بالضبط في كل صفحة. وبنيات التنقيح (debug) تبلّغ عن غيابه، وعن وجود أكثر من واحد.
• اسم للمنطقة الجانبية (asideLabel)، وقيمة label على درج التنقل وعلى شريط التنقل. فمَعلما تنقل في صفحة واحدة يحتاجان إلى اسمين.
• كلمات رابط التخطي وتسمية زر القائمة.
• عنوان واحد من المستوى 1 في كل صفحة، في المنطقة الرئيسية: هو عنوان رأس الصفحة.