# Responsive requirements

Responsive behavior is mandatory for the initial application. These are implementation requirements, not an optional design decision. They extend the prototype's visual identity to smaller screens.

## Arabic and English layouts

Support both Arabic RTL and English LTR as required by [the project language instructions](PROJECT_INSTRUCTIONS.md#arabic-and-english-support). The rules below describe the Arabic baseline; mirror directional placement for English using logical layout properties. The desktop sidebar and mobile drawer appear on the right in Arabic and on the left in English.

Keep the language switcher reachable on login pages, desktop headers, and phone layouts. Allow language/theme controls and translated actions to wrap naturally. Long English labels must remain readable without shrinking the whole interface or causing page-wide overflow. Keep directional icons consistent with navigation direction.

## Viewport and configuration

Use `width=device-width, initial-scale=1, viewport-fit=cover`. Let the interface reflow at its natural size. Do not depend on a fixed 1100px viewport, application-wide CSS zoom, or custom zoom controls to fit a phone. Preserve native browser zoom.

Store all breakpoint thresholds and associated shared dimensions in the root `style-theme.config.json`. The following are the initial required ranges; generate media queries from their configured thresholds.

| Range   | Width                     | Required layout                                                  |
| ------- | ------------------------- | ---------------------------------------------------------------- |
| Phone   | Below `640px`             | One primary column, compact header, right-side navigation drawer |
| Tablet  | `640px` to below `1024px` | Navigation drawer, two-column grids where content fits           |
| Desktop | `1024px` and above        | Persistent `276px` sidebar; desktop content proportions          |

Use mobile-first rules at `640px` and `1024px` so fractional widths do not leave gaps. Base component layout on available content width as well as viewport size; a persistent sidebar must not force cards or forms to overflow.

## Navigation and shell

- At desktop widths, show the right-side sidebar and keep the content area flexible with `min-width:0`.
- Below desktop width, show a compact sticky header with the Masar identity and a labeled menu button. The sidebar opens from the right as a drawer over a backdrop.
- Drawer width is at most `290px` and `86vw`; configure both dimensions centrally.
- Support close button, backdrop click, and Escape. Move focus into the open drawer, contain focus while modal, restore it to the menu button, and prevent background scrolling.
- Respect safe-area insets and use dynamic viewport units where supported for drawer/dialog height.
- Use content gutters of `16px` on phones, `24px` on tablets, and the prototype's `32px` on desktop, all sourced from configuration.

## Content and controls

- Login role cards: one column on phones; two columns from tablet width when space permits.
- KPI cards: two columns on phones and tablets; four on desktop where labels fit. Allow a single column at very narrow available widths rather than clipping values.
- Split dashboard sections: stack on phones and tablets; use the prototype's desktop split only when both sections remain readable.
- Forms: one column on phones; two on larger screens where labels and inputs fit. Full-width fields continue to span the entire form.
- Case editor: move the step navigation above the editor below desktop width. Steps may scroll horizontally without scrolling the entire page; keep the current step visible.
- Page headings and action groups wrap naturally. Filters become full-width controls on phones; action buttons wrap or stack without losing their labels.
- Card grids must allow cards narrower than the prototype's `270px` minimum when necessary to fit the available width.
- Tabs may scroll horizontally in their own region. Preserve access to every tab and a visible selected state.
- Use at least `44 × 44px` interactive targets for buttons, icon controls, navigation items, and tabs. Keep source icon dimensions independently configurable.
- Keep primary form text at least `16px` on phones and preserve legible Arabic line-height. Long school names, validation messages, and action labels must wrap.

## Tables and dialogs

The backend administration shell follows [the dashboard UI contract](PROJECT_INSTRUCTIONS.md#administration-ui-and-ux). Desktop navigation is a sidebar, not a horizontal replacement menu. The navbar includes avatar/account controls and reachable appearance/language settings; hide secondary captions on phones when needed, keeping accessible names intact. Account/settings popovers must stay within viewport gutters.

Module Create and Edit actions open modals over the current table or detail view. Keep header/close controls and footer Save/Cancel actions visible while the body scrolls. A changed-form close action opens a confirmation that can return to the intact editor. Both dialogs must contain keyboard focus; closing restores focus to the relevant trigger. Language switching must retain an open modal's fields, selections, and changed-form protection.

Verify that successful saves keep the current filters/page and update the displayed records. Verify related-record hyperlinks by following user-to-school, school-to-directorate, and supervisor/counselor links. On school details, manager contacts and the reserved Students section must reflow without implying that managers or students are login users.

- Confine horizontal table scrolling to the table wrapper. The page itself must fit the viewport.
- Preserve header associations, readable values, and access to row actions. Provide a visible overflow cue and an accessible name/focus path for scrollable table regions.
- Use `min-width:0` for enclosing grid/flex children; do not hide overflow to conceal clipped content.
- On phones, dialogs fit the viewport with `16px` outer gutters; forms and detail lists inside them use one column.
- Dialog bodies scroll within the available dynamic height; title, close control, validation, and footer actions remain reachable with the on-screen keyboard open.
- Keep toasts within viewport gutters and safe-area insets. Do not cover primary actions with persistent overlays.

## Required acceptance checks

Verify representative pages at widths `320`, `375`, `640`, `768`, `1024`, and `1440px`, plus phone landscape and browser zoom at 200%. Check both languages in both themes, with real Arabic/English labels and long values.

Cover login, counselor dashboard, register filters/table/form, case editor, supervisor review, navigation drawer, dialogs, and printing. Confirm:

1. No page-wide horizontal overflow; tables and tabs can scroll locally.
2. No clipped headings, unreadable scaled text, overlapping actions, or inaccessible controls.
3. Keyboard focus, drawer/dialog close behavior, and focus restoration work.
4. Forms remain usable with validation messages and an on-screen keyboard.
5. Both themes retain readable interaction states and visible focus.
6. Reduced-motion preference is respected.
7. Printed Arabic reports include complete values and omit navigation/transient controls.
8. A breakpoint or gutter changed in `style-theme.config.json` updates the rendered layout through the normal build process.
9. Switching Arabic/English updates translated content, page language, and reading direction; sidebars/drawers mirror correctly and keyboard focus remains usable.
10. The selected language survives navigation, reload, login, and logout. Switching language does not clear entered form data or unsaved drafts, change stored identifiers, or bypass access rules.

These checks are acceptance requirements for implemented features. The Stage 1 shell uses real responsive reflow; see [the Stage 1 verification record](STAGE_1_FOUNDATION.md#verification) for checks actually completed. Workflow-specific checks remain pending until those workflows exist.


## Selectors and modal scrolling

Long create/edit dialogs must fit the dynamic viewport with a visible header and action footer. Only their content body scrolls; preserve touch/keyboard scrolling, visible focus, and contained scroll behavior. Style scrollbars with shared theme tokens without hiding them. Show a subtle overflow hint while more fields remain below. Expandable record pickers must use bounded results, wrapping removable selection chips, and touch-sized controls. Keep selections across search and close/reopen actions. Verify 320px/375px widths and short landscape heights in Arabic/English; Save/Cancel must stay within the viewport, without horizontal overflow.


## Student forms and Excel import

Student actions and school/filter controls must wrap at 320px. Keep the student and import-preview tables in their own horizontally scrollable regions. Add/import dialogs reuse the viewport-bound header/body/footer structure and retain visible Save/Preview/Import/Cancel actions. Show the selected school and validation errors inside the dialog; long row-error lists must scroll with the body. Changing language must preserve the draft/file/preview, while changing the selected upload clears its old preview. Use touch-sized native file/select controls and support Arabic RTL and English LTR.
