System Requirements Document for bronze-msarak

1. Introduction

bronze-msarak is a UI/UX development engagement on top of an existing, complete project: مشارك | Masarak — an Arabic-first (RTL) academic and career guidance platform for Yemeni high-school students and anonymous visitors. Masarak helps students explore RIASEC-based inclinations, browse and compare academic specialisations, and receive clear, interpreted, non-diagnostic recommendations. It is explicitly not a psychodiagnostic tool; it is exploratory guidance.

The product intent of this engagement is narrow and explicit: the Masarak project already exists and is complete, and the work is to develop professional, creative UI/UX for its interfaces that meets the needs of its users. This is a design-and-front-end development effort carried out inside the existing repository — not a rebuild, not a re-architecture, and not a new product.

The audience for this work is twofold:

• مطوّر الواجهات (UI/UX Developer) — the person who opens the Masarak repository, reviews the current interfaces, and implements the improved UI/UX inside the existing project.
• مالك المشروع / صاحب القرار — the project owner/decision-maker who directs improvement priorities and approves the final interface design against the goal of professionalism, creativity, and user fit.

The end beneficiaries whose needs the improved interfaces must serve are the platform's own users: Yemeni high-school students and anonymous visitors.

2. System Overview

Masarak is a Laravel monolith with Blade templates, Tailwind CSS, and JavaScript/Fetch client logic, backed by MySQL 8.4.x, using Laravel session authentication (sessions, cookies, CSRF, password hashing). The specialisation catalogue is static data (resources/data/specializations.json), not a database table, and there is no admin CRUD over it. RIASEC scoring is processed server-side. The platform is Arabic RTL and responsive.

The current engagement adds a first-party working surface layer on top of this existing project so that the UI/UX improvement work can be opened, reviewed, directed, implemented, previewed, and approved. That layer consists of four destinations:

• Landing — the public entry point that states plainly that the project exists and that the scope of work is developing its interfaces to meet user needs, before entering the workspace.
• Current UI — a dedicated space for opening and reviewing the existing Masarak interfaces before implementing improvements.
• Design Workspace — the primary working space for implementing UI/UX improvements inside the existing project, where the decision-maker can direct priorities and approve the design.
• Preview — a dedicated destination for previewing the developed interfaces and verifying that they fit user needs before approval.

Actors. Two accepted human personas: the UI/UX Developer and the Project Owner / Decision-Maker. The GitHub repository at https://github.com/Bito-Tech/msarak is an external provider-owned surface (repository hosting, issues, pull requests, reviews, actions) — it is not a first-party page and is not a persona. The Masarak application itself (Laravel/Blade runtime, RIASEC scoring, session auth) is a system actor.

Accepted behaviour in scope. Reviewing the current interfaces; implementing professional, creative UI/UX improvements inside the existing project; directing improvement priorities; previewing developed interfaces; verifying user-need fit; approving the final design; and the repository/development-environment access that makes this work executable.

Narrow exclusions. The project is already complete; the work is limited to developing the interfaces (UI/UX) and is not a rebuild of the project. Out of MVP scope for Masarak itself: admin dashboard, admin statistics, CRUD over specialisations, public API, standalone mobile app, psychometric diagnostics, and binding academic/professional decisions. Excluded technology: React, Vue, SPA, Laravel Breeze, Laravel Sanctum, JWT, API tokens, SQLite, MariaDB.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The improved interfaces are delivered as first-party Blade/Tailwind views inside the existing Masarak Laravel application, served locally at http://127.0.0.1:8000 with a /up health check. The repository that holds the project is provider-owned (GitHub) and is reached through the provider's own surfaces — the browser repository view, issues, pull requests, reviews, and actions. This SRD does not re-implement repository hosting; it treats the repository as an external destination that the Developer and Owner use.

Access ownership. The Landing destination is publicly reachable and requires no identity. Current UI, Design Workspace, and Preview require an established identity, because the work they carry — reviewing the existing interfaces, implementing and directing improvements, and previewing and approving a design — is durable, actor-specific, resumable work that must remain bound to the correct participant. First-use identity establishment and returning verification are therefore part of the accepted lifecycle: a person establishes access once, and thereafter resumes the same working state. This is application-owned identity continuity only; it does not establish differentiated permissions, role-based visibility, or permission controls over shared product state, and no such differentiation is claimed anywhere in this document.

Current vs. future boundary. Everything described in Sections 3, 5, and 2c is current. The Masarak platform's own student-facing journeys (assessment, results, recommendations) are current product behaviour of the existing project and are the subject matter of the interface work; the improvements to those interfaces are the current deliverable. No future-horizon items are accepted in the authoritative thread, so none are asserted.

2b. Source Content Inventory

The reference directive for https://github.com/Bito-Tech/msarak declares content_source with authoritative authority. The following verified facts are preserved item by item.

Project identity

• Project name: مشارك | Masarak
• Description (README.md at project root): Academic and career guidance platform for Yemeni high-school students that helps explore RIASEC-based inclinations, academic specializations, and personalized recommendations. Not a psychodiagnostic tool, but exploratory guidance.

Problem statement

• Lack of specialization knowledge
• Unclear personal preferences
• Reliance on opinion
• Difficulty comparing options
• Lack of contextual content

Target users

• Student: explore specializations; understand professional inclinations initially; receive clear interpreted results and recommendations; resume exploration.
• Visitor: learn about the platform; browse and compare specializations; do things before sign-up.

MVP scope

• Specialization catalog (static)
• Browse and compare specializations
• Account registration, login, logout
• Student progress persistence
• Exploratory assessment: 18 items, 4 options
• Save answers during assessment
• RIASEC score calculation on server
• Non-diagnostic interpretive feedback
• Multiple recommendations
• Store previous results
• Arabic RTL and responsive UI
• Automated tests and build checks before merge

Out of MVP scope

• Admin dashboard
• Admin statistics
• CRUD specializations
• Public API
• Standalone mobile app
• Psychometric diagnostics
• Binding academic/professional decisions

Team members

• الحارث الداهية — Technical Lead / Integration / Repository Coordination
• مالك — Backend & Business Logic
• أيمن — Frontend & UX
• عبدالله حمود — Testing, Data & QA
• ملاطف — Content, Specializations & UAT

External reviewer

• م. طارق العمري — External Technical Reviewer — GitHub: @tareq-alomari

Technologies

• Backend: Laravel 12
• PHP runtime: PHP 8.2+
• Database: MySQL 8.4.x
• ORM: Eloquent
• Frontend: Blade
• Styling: Tailwind CSS
• Client logic: JavaScript / Fetch
• Auth: Laravel Session + Cookies + CSRF
• Build tool: Vite
• Node version: Node.js 24.x
• PHP packages manager: Composer 2.x
• JS packages manager: npm
• Testing: PHPUnit / Laravel Tests
• Version control: Git
• Collaboration: GitHub

Technical decisions

• Laravel Monolith
• Blade + Tailwind CSS
• JavaScript / Fetch
• MySQL 8.4.x
• Laravel Session Authentication
• routes/web.php
• Static specialization catalog
• Server-side RIASEC processing

Excluded tech stack

• React
• Vue
• SPA
• Laravel Breeze
• Laravel Sanctum
• JWT
• API Tokens
• SQLite
• MariaDB

Specialization data

• File: resources/data/specializations.json
• Database table: no
• Admin CRUD: no

Project documents

• AI_Log.md
• DELIVERABLES_CHECKLIST.md
• docs/ (system design, workflows, use cases, etc.)

Workflow

• Uses: GitHub Issues, Branches, Commits, Pull Requests, Reviews, Projects
• Flow: Issue → Branch → Implementation → Commit → Push → Pull Request → Review → Squash Merge → Delete Branch
• Branch: main (protected)

Requirements

• Git 2.x
• PHP 8.2+
• Composer 2.x
• Node.js 24.x
• npm
• MySQL 8.4.x

Setup scripts

• check-environment.bat
• setup-database.bat
• setup-project.bat
• verify-project.bat
• start-project.bat

Verification results

• Environment check: PASS
• Project setup: PASS
• Full verification: PASS

Test environment

• Laravel: 12.69.1
• PHP: 8.2.12
• Composer: 2.9.5
• Node.js: 24.13.1
• npm: 11.8.0
• MySQL: 8.4.11
• Git: 2.50.1

Project structure

• Root directories: .github, app, bootstrap, config, database, docs, public, resources, routes, scripts, tests
• Files: .editorconfig, .env.example, .gitattributes, .gitignore, AI_Log.md, DELIVERABLES_CHECKLIST.md, composer.json, composer.lock, package.json, package-lock.json, phpunit.xml, vite.config.js

Project rules

• No direct push to main
• No .env commit
• No secrets
• Track composer.lock
• Track package-lock.json
• No composer/npm update in setup
• No features outside scope without an issue
• AI-generated code must be understood
• Document AI usage in AI_Log.md
• Verify before issue complete

Pre-merge checks

• php artisan test
• npm run build
• scripts/verify-project.bat

Project status

• Completed: foundation setup, documentation setup, repo and protection, templates, labels, GitHub project workflow, milestones, initial issues distribution, CI actions, setup scripts, clean clone success
• In progress: batch execution per milestone, closing remaining issues, final verification and release prep
• Note: Individual issue completion tracked via Issues/Milestones/PRs; setup success ≠ feature completion.

Security

• No credentials in repo
• .env local only
• Use sessions, cookies, CSRF, password hash
• No root MySQL for runtime

Quick reference

• Scripts run to PASS environment → setup → verify → start; then access on http://127.0.0.1:8000 (+ /up health check)

Structure reference (repository navigation and tree)

• Navigation menu: Code, Issues, Pull Requests, Discussions, Actions, Projects, Security and quality, Insights
• Repository tree: .github, app, bootstrap, config, database, docs, public, resources, routes, scripts, tests, .editorconfig, .env.example, .gitattributes, .gitignore, AI_Log.md, DELIVERABLES_CHECKLIST.md, composer.json, composer.lock, package.json, package-lock.json, phpunit.xml, vite.config.js
• docs/ subfolders: 00-baseline, 01-management, 02-system-design, 03-system-analysis, 04-assessment, assets

Feature reference

• Workspace setup scripts: check-environment.bat, setup-database.bat, setup-project.bat, verify-project.bat, start-project.bat
• Health check endpoint: /up
• Git workflow: Issue → Branch → Implementation → Commit → Push → Pull Request → Review → Squash Merge → Delete Branch
• Pre-merge checks: php artisan test, npm run build, verify-project.bat
• AI usage logging: documented in AI_Log.md

2c. Page Content and Component Coverage

Landing

• Information and state: Public, no identity required. States plainly that the Masarak project exists and is complete, and that the current scope of work is developing its interfaces (UI/UX) to be professional, creative, and fit for user needs. Presents the two working roles and the entry into the workspace. No protected state is shown or reachable from here.
• Primary action: Enter the workspace (which requires establishing or verifying identity, handled at the access boundary, not on this page).
• Supporting actions: Read the scope statement; read the role descriptions; reach the repository link.
• Domain entities: Project (Masarak), scope statement, role (Developer, Owner), repository reference.
• Component responsibilities:
  • Kraft-ground hero field with a 3px ink rule at the very top and a stamped "مشارك / MASARAK" badge in the top-right corner.
  • Oversized stacked Arabic headline "اكتشف مسارك" in IBM Plex Sans Arabic 700 at clamp(48px, 11vw, 120px), running right-to-left across the full width.
  • A single 2px ink rule beneath the headline and a one-line subhead in 18px muted type stating the scope of work.
  • A cluster of three rotated circular stamps (RIASEC, 18 سؤالاً, نتيجة فورية) in primary orange and mustard on the left third, overlapping the headline block by 24px but never covering any glyph.
  • Primary CTA "ابدأ الاستكشاف" as a solid orange pill pinned to the bottom-right of the headline block with a 4px hard ink shadow; secondary text link "تصفح التخصصات" beside it.
  • A scope-and-roles ruled panel stating that the project is complete and the work is interface development, with the Developer and Owner roles described.
  • A repository reference block linking to https://github.com/Bito-Tech/msarak.
  • A specialisations ticker strip (the only permitted marquee), which stops entirely under prefers-reduced-motion and wraps into ruled rows.
• States:
  • Loading: static-first; the hero and scope panel render immediately, with the ticker strip filling in.
  • Empty: not applicable — the page is a fixed public statement; if the repository reference cannot be resolved, the block shows the plain URL as text.
  • Success: the visitor reads the scope statement and reaches the workspace entry or the repository link.
  • Error: if the workspace entry cannot be reached, the page states that access could not be established and offers a retry.
  • Recovery: retry the entry; the scope statement and repository link remain available regardless.

Current UI

• Information and state: Requires identity. Shows the existing Masarak interfaces as they stand today, opened from the repository, so they can be reviewed before improvements are implemented. Carries the review state: which interfaces have been reviewed and which have not.
• Primary action: Open and review a current interface.
• Supporting actions: Mark an interface as reviewed; record a review note against an interface; move to the Design Workspace to act on a finding.
• Domain entities: Interface (a current Masarak view), review status, review note, reviewer.
• Component responsibilities:
  • Ruled panel list of current interfaces, each a card with a top stamp bar, 2px ink border, 8px radius, and a 4px hard offset ink shadow.
  • Per-interface review control and review-note field.
  • Review-status stamp (starburst or circular badge, 2px ink stroke, rotated −8° to 6°) marking reviewed interfaces.
  • A ruled summary row showing reviewed vs. remaining counts in tabular numerals.
  • A hand-off control into the Design Workspace for the selected interface.
• States:
  • Loading: ruled skeleton rows in the card list.
  • Empty: no interfaces opened yet — a ruled panel states that no current interface has been opened and offers the first open action.
  • Success: an interface is opened and its review status is recorded; the summary row updates.
  • Error: an interface fails to open — the card shows an inline error with a retry, and the rest of the list stays usable.
  • Recovery: retry the failed open; previously recorded review status is preserved.

Design Workspace

• Information and state: Requires identity. The primary working space for implementing UI/UX improvements inside the existing project. Holds the improvement items, their priority as directed by the Owner, their implementation state, and the design approval state.
• Primary action: Implement a UI/UX improvement against a current interface.
• Supporting actions: Owner directs priority on an improvement item; Developer records the implementation; Owner approves or returns the design; Developer sends the result to Preview.
• Domain entities: Improvement item, target interface, priority, implementation state, design approval state, directing actor, approving actor.
• Component responsibilities:
  • Ruled improvement-item list with priority chips as 999px pills and 2px ink borders.
  • Priority-direction control available to the Owner, with the directing actor recorded.
  • Implementation panel for the Developer, with the target interface and the change described.
  • Approval control for the Owner, with a forest-green (#2F4A3C) "result confirmed / recommendation saved" state reserved strictly for approved items.
  • Hand-off control into Preview.
  • A ruled activity row showing the last state change per item in tabular numerals.
• States:
  • Loading: ruled skeleton rows in the improvement list.
  • Empty: no improvement items yet — a ruled panel states that no improvement has been recorded and offers the first create action.
  • Success: an improvement is implemented and its state advances; approval turns the item to the forest-green confirmed state.
  • Error: a save fails — the item keeps its previous state, an inline error appears, and the entered change is not lost.
  • Recovery: retry the save; the item returns to its last confirmed state if the retry is abandoned.

Preview

• Information and state: Requires identity. Shows the developed interfaces so they can be checked against user needs before approval. Holds the preview state per improvement and the verification outcome.
• Primary action: Preview a developed interface.
• Supporting actions: Record a user-need verification outcome; return an item to the Design Workspace; confirm the previewed result.
• Domain entities: Preview (a developed interface state), verification outcome, verifying actor, related improvement item.
• Component responsibilities:
  • Ruled preview frame with a 2px ink border and a 4px hard offset ink shadow, rendering the developed interface.
  • Verification control recording whether the previewed interface fits user needs.
  • Return-to-workspace control for items that do not pass verification.
  • Confirmation stamp (starburst or circular badge, 2px ink stroke, rotated −8° to 6°) on confirmed previews, in the forest-green confirmed state.
  • A ruled comparison row pairing the current interface reference with the previewed result.
• States:
  • Loading: ruled placeholder frame while the preview resolves.
  • Empty: nothing to preview yet — a ruled panel states that no developed interface is ready and links back to the Design Workspace.
  • Success: the preview renders and the verification outcome is recorded; confirmation shows the forest-green stamp.
  • Error: the preview fails to render — an inline error with a retry appears, and the verification control stays disabled until it renders.
  • Recovery: retry the render; a returned item reappears in the Design Workspace with its state intact.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-01 — Review the current Masarak interfaces (explicit) As a مطوّر الواجهات (UI/UX Developer), I should open the existing Masarak interfaces from the repository and review them, so that I understand what is there before changing it.

• Trigger/input: the Developer opens Current UI with an established identity.
• Observable result: the current interfaces are listed and openable; opening one shows it as it stands today.
• Access state: identity required.
• Failure/recovery: if an interface fails to open, an inline error with retry appears and the rest of the list stays usable.
• Continuation: the Developer records a review note and moves to the Design Workspace.

FR-02 — Record a review finding against a current interface (required_inference) As a مطوّر الواجهات (UI/UX Developer), I should record what I found when reviewing a current interface, so that the finding survives the review session and can be acted on.

• Trigger/input: the Developer records a note against an opened interface.
• Observable result: the interface carries a review status and the note; the reviewed/remaining summary updates.
• Access state: identity required.
• Failure/recovery: a failed save keeps the previous status and preserves the entered note.
• Continuation: the finding is available in the Design Workspace as the basis for an improvement item.

FR-03 — Implement professional, creative UI/UX improvements inside the existing project (explicit) As a مطوّر الواجهات (UI/UX Developer), I should implement UI/UX improvements inside the existing Masarak project, so that its interfaces become professional, creative, and fit for user needs.

• Trigger/input: the Developer selects an improvement item in Design Workspace and records the implementation against a target interface.
• Observable result: the improvement item advances its implementation state and is bound to the target interface.
• Access state: identity required.
• Failure/recovery: a failed save leaves the item in its previous state and does not discard the entered change.
• Continuation: the item is sent to Preview for verification.

FR-04 — Direct improvement priorities (explicit) As a مالك المشروع / صاحب القرار, I should direct which interface improvements take priority, so that the work is aimed at what matters most for the project and its users.

• Trigger/input: the Owner sets or changes the priority on an improvement item in Design Workspace.
• Observable result: the item's priority changes and the directing actor is recorded.
• Access state: identity required.
• Failure/recovery: a failed priority change leaves the previous priority in place and shows an inline error.
• Continuation: the Developer works the items in the directed order.

FR-05 — Preview the developed interfaces (explicit) As a مطوّر الواجهات (UI/UX Developer), I should preview the developed interfaces, so that I can see the result of the improvement before it is approved.

• Trigger/input: the Developer opens Preview for a developed interface.
• Observable result: the developed interface renders in the preview frame, paired with the current interface reference.
• Access state: identity required.
• Failure/recovery: if the preview fails to render, an inline error with retry appears and the verification control stays disabled.
• Continuation: the Developer records a verification outcome or returns the item to the Design Workspace.

FR-06 — Verify that the developed interfaces fit user needs (explicit) As a مالك المشروع / صاحب القرار, I should verify that the developed interfaces fit user needs, so that approval is based on the stated goal rather than on appearance alone.

• Trigger/input: the Owner reviews a rendered preview in Preview and records a verification outcome.
• Observable result: the verification outcome is recorded against the improvement item.
• Access state: identity required.
• Failure/recovery: an item that does not pass verification is returned to the Design Workspace with its state intact.
• Continuation: passing items proceed to approval; returned items are reworked.

FR-07 — Approve the final interface design (explicit) As a مالك المشروع / صاحب القرار, I should approve the final interface design, so that the improved UI/UX is settled and the work can be closed.

• Trigger/input: the Owner approves an improvement item in Design Workspace after a passing verification.
• Observable result: the item enters the confirmed state, marked with the forest-green confirmed treatment.
• Access state: identity required.
• Failure/recovery: a failed approval leaves the item unapproved and shows an inline error.
• Continuation: the approved design is the settled interface for that target.

FR-08 — Reach the workspace from a public entry (required_inference) As a visitor or either working role, I should reach a public entry that states what this project is and what the current work is, so that I know where I am before entering the workspace.

• Trigger/input: the person opens Landing.
• Observable result: the scope statement, the two role descriptions, and the workspace entry are visible; no protected state is shown.
• Access state: none.
• Failure/recovery: if the workspace entry cannot be reached, the page states this and offers a retry; the scope statement and repository link remain available.
• Continuation: the person enters the workspace, which requires establishing or verifying identity.

FR-09 — Establish identity on first use and verify it on return (required_inference) As a مطوّر الواجهات (UI/UX Developer) or مالك المشروع / صاحب القرار, I should establish access once and be verified on return, so that my review, improvement, priority, verification, and approval work stays bound to me and can be resumed.

• Trigger/input: the person enters the workspace for the first time, or returns to it.
• Observable result: on first use, access is established; on return, the person is verified and their prior working state is available.
• Access state: this is the anonymous entry interaction that establishes access to the protected destinations; it is not itself a protected destination.
• Failure/recovery: failed establishment or verification reports the failure and allows retry without losing the entered information.
• Continuation: the person lands in the workspace with their prior state.
• Boundary: this establishes identity continuity only. It does not create differentiated permissions, role-based visibility, or permission controls over shared product state.

FR-10 — Access the project repository and development environment (required_inference) As a مطوّر الواجهات (UI/UX Developer), I should access the Masarak repository and a working development environment, so that the interface improvements can actually be made and run.

• Trigger/input: the Developer opens https://github.com/Bito-Tech/msarak and the local project environment.
• Observable result: the repository state is visible and the local environment runs, reachable at http://127.0.0.1:8000 with /up reporting health.
• Access state: provider-owned repository access plus local environment access.
• Failure/recovery: environment checks are run through check-environment.bat, setup-database.bat, setup-project.bat, verify-project.bat, and start-project.bat; a failing check is corrected and re-run.
• Continuation: the Developer proceeds to review the current interfaces.
• Boundary: the repository is provider-owned; this SRD does not re-implement repository hosting, issues, pull requests, reviews, or actions.

FR-11 — Keep the work inside the existing project's scope and rules (explicit) As a مطوّر الواجهات (UI/UX Developer), I should work within the existing project's rules, so that the interface work does not become a rebuild or an out-of-scope feature.

• Trigger/input: any change made during the engagement.
• Observable result: the change is an interface change to the existing project; no rebuild occurs; no feature outside scope is added without an issue.
• Access state: not applicable.
• Failure/recovery: a change that would exceed scope is raised as an issue rather than merged.
• Continuation: the change proceeds through the accepted workflow.
• Constraints carried: no direct push to main; no .env commit; no secrets; composer.lock and package-lock.json tracked; no composer/npm update in setup; AI-generated code must be understood; AI usage documented in AI_Log.md; verify before issue complete; pre-merge checks are php artisan test, npm run build, and scripts/verify-project.bat.

4. User Personas

مطوّر الواجهات (UI/UX Developer)

Product context. The Developer works on the interfaces of Masarak — a project that already exists and is complete. Their context is not greenfield: there is a running Laravel/Blade/Tailwind application, a static specialisation catalogue, an 18-item RIASEC assessment, and a set of existing views. The Developer's job is to raise the quality of those views to a professional, creative standard that serves the platform's actual users — Yemeni high-school students and anonymous visitors — without rebuilding the project.

Primary goal. To deliver UI/UX that is professional, creative, and genuinely meets user needs, implemented inside the existing project.

Distinct accepted responsibilities. Opening the repository and the local environment; reviewing the current interfaces as they stand; recording what was found; implementing improvements against specific interfaces; sending results to preview; and keeping every change inside the existing project's scope and rules.

Relevant inputs and decisions. Which interface to review next; what the review found; how to implement the improvement; whether the result is ready to preview; whether a change would exceed scope and must become an issue instead.

Interactions with other accepted participants. The Developer receives priority direction from the Owner and hands developed interfaces to the Owner for verification and approval. The Developer also depends on the provider-owned repository and the local environment, which are external and system surfaces rather than people.

Observable success. Current interfaces are reviewed and their findings recorded; improvements are implemented against named interfaces; previews render; the Owner's verification passes and the design is approved; the pre-merge checks pass.

What makes this role different. The Developer is the only persona that produces the interface change. The Owner directs and judges; the Developer builds and submits. The Developer's work is measured by whether the delivered interfaces hold up under the Owner's user-need verification, not by whether the work was started.

مالك المشروع / صاحب القرار

Product context. The Owner represents the project's own side — the person accountable for Masarak's quality and for whether the interface work actually serves its users. They are not implementing the views; they are steering and signing off on them.

Primary goal. To ensure the interface work lands on what matters most and that the final design is genuinely professional, creative, and fit for user needs.

Distinct accepted responsibilities. Directing which improvements take priority; verifying that developed interfaces fit user needs; approving the final interface design.

Relevant inputs and decisions. Which interfaces most need improvement; whether a previewed interface meets the stated goal; whether to approve or return an item for rework.

Interactions with other accepted participants. The Owner directs the Developer's priorities and receives the Developer's developed interfaces for verification and approval. The Owner's decisions are what move an item from implemented to confirmed.

Observable success. Priorities are set and visible on the improvement items; verification outcomes are recorded; the final design is approved and marked confirmed.

What makes this role different. The Owner is the only persona that judges and settles the work. The Developer can implement and preview, but only the Owner's verification and approval close an item. The Owner's decisions are directional and terminal rather than productive.

5. Core User Flows

Flow A — Developer reviews the current interfaces

1. The Developer opens https://github.com/Bito-Tech/msarak in the provider's repository surface and confirms the project state.
2. The Developer runs the local environment scripts in order — check-environment.bat, setup-database.bat, setup-project.bat, verify-project.bat, start-project.bat — and confirms the application is reachable at http://127.0.0.1:8000 with /up reporting health.
3. The Developer opens Landing and reads the scope statement: the project exists and is complete, and the work is developing its interfaces to meet user needs.
4. The Developer enters the workspace. Because this is first use, access is established here; on later visits the Developer is verified and returns to the same working state.
5. The Developer lands in Current UI and opens a current Masarak interface.
6. The Developer reviews it and records a finding against it. The interface takes a review status and the reviewed/remaining summary updates.
7. Failure path: if an interface fails to open, an inline error with a retry appears on that card; the rest of the list stays usable and previously recorded review status is preserved.
8. Continuation: the Developer moves to the Design Workspace with the finding as the basis for an improvement item.

Flow B — Owner directs improvement priorities

1. The Owner enters the workspace with an established identity and lands in Design Workspace.
2. The Owner reviews the improvement items and their current priorities.
3. The Owner sets or changes the priority on an item. The priority changes and the directing actor is recorded.
4. Failure path: if the priority change fails to save, the previous priority stays in place and an inline error appears; the Owner retries.
5. Continuation: the Developer works the items in the directed order.

Flow C — Developer implements an improvement

1. The Developer opens Design Workspace and selects an improvement item, which carries the target interface and the Owner's directed priority.
2. The Developer implements the UI/UX improvement inside the existing project against that target interface.
3. The Developer records the implementation on the item. The item advances its implementation state and stays bound to the target interface.
4. Failure path: if the save fails, the item keeps its previous state and the entered change is not lost; the Developer retries.
5. Continuation: the Developer sends the item to Preview.

Flow D — Developer previews the developed interface

1. The Developer opens Preview for the developed interface.
2. The preview frame renders the developed interface, paired with the current interface reference so the change can be seen against what it replaced.
3. Failure path: if the preview fails to render, an inline error with a retry appears and the verification control stays disabled until it renders.
4. Continuation: the Developer records a verification outcome, or returns the item to the Design Workspace.

Flow E — Owner verifies user-need fit and approves the design

1. The Owner opens Preview for a developed interface and reviews it against the stated goal: professional, creative, and fit for user needs.
2. The Owner records a verification outcome.
3. If the interface does not pass: the Owner returns it to the Design Workspace with its state intact, and the Developer reworks it (Flow C).
4. If the interface passes: the Owner moves to Design Workspace and approves the item.
5. The item enters the confirmed state, marked with the forest-green confirmed treatment. The approved design is the settled interface for that target.
6. Failure path: if the approval fails to save, the item stays unapproved and an inline error appears; the Owner retries.
7. Continuation: the settled interface is the outcome of the engagement for that target.

Flow F — Developer keeps the work inside scope and merges it

1. The Developer confirms the change is an interface change to the existing project and not a rebuild.
2. If the change would exceed scope, the Developer raises an issue rather than proceeding.
3. The Developer works on a branch — never a direct push to main — and commits without .env or secrets.
4. The Developer runs the pre-merge checks: php artisan test, npm run build, and scripts/verify-project.bat.
5. The Developer opens a pull request following the accepted flow: Issue → Branch → Implementation → Commit → Push → Pull Request → Review → Squash Merge → Delete Branch.
6. AI usage is documented in AI_Log.md, and the issue is verified before it is marked complete.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Aaron Draplin; the headline idea is bold, honest, hand-built guidance for Yemeni students — badge-grade craft.

Colour tokens (light mode)

No blue, indigo, or violet anywhere. Colour proportion is roughly 70% kraft/paper, 20% ink, 10% orange + mustard combined.

Typography

• Headings (Latin): Alfa Slab One, 700 weight, all-caps for Latin kickers and section stamps, tight leading 0.95–1.05.
• Headings (Arabic): IBM Plex Sans Arabic, 700, leading 1.25–1.35.
• Body: IBM Plex Sans Arabic.
• Headline sizes: clamp(40px, 9vw, 96px) hero; clamp(28px, 5vw, 48px) section titles; clamp(20px, 3vw, 28px) card titles.
• Letter-spacing: 0.02em on Latin caps, 0 on Arabic.
• Scale: 1.25 modular — 40/32/26/20/16/14/12, with a mobile floor of 14px for body and 40px for hero.
• Line-height: 1.55 body, 1.25 headings, 1.35 Arabic headings.
• Numerals: tabular for RIASEC scores and percentages.

Shape language

• 8px radius on cards; 999px pills for filter chips and CTA buttons.
• 2px solid ink borders (never hairlines) on panels and inputs.
• 4px offset hard shadow in ink at 12% opacity instead of soft blur.
• Corner stamps and starburst badges mark milestones (assessment complete, result saved).
• Hard edges and stamped corners throughout; no glass, no gradient, no soft blob.

Layout

• Poster-like vertical rhythm on a 12-column grid, with a visible 1px ink rule between major sections and a 2px rule under the header.
• RTL-first: content flows right-to-left, navigation sits on the right on desktop, and the logo/wordmark anchors the top-right corner.
• Hero is a full-bleed kraft field with an oversized stacked headline on the right two-thirds and a stamped badge cluster on the left third.
• Specialisation catalogue: 3-up card grid on desktop, 2-up on tablet, 1-up on mobile, each card a ruled panel with a top stamp bar.
• The 18-item assessment is a single-column, one-question-per-screen flow with a fixed progress rail on the right edge descending vertically, so it reads naturally in RTL.
• Results use a 6-segment RIASEC ring (SVG) with labelled ruled rows beneath, not a chart library.

Imagery

• Thick-line vector pictograms for the six RIASEC types — a wrench, a magnifier, a pen, a handshake, a chart, a compass — drawn with 3px ink strokes on kraft.
• Halftone-treated photographic cutouts of Yemeni students and classrooms at 40% opacity behind the hero headline block.
• No stock-photo gloss, no 3D renders, no gradient blobs.
• A repeating topographic-line texture in muted ink at 8% opacity along section dividers.

7. Signature Design Concept

The public entry — Landing — is composed as a stamped kraft poster.

A full-bleed kraft ground (#E7DECB) carries a 3px ink rule at the very top. In the top-right corner sits a stamped "مشارك / MASARAK" badge. The dominant element is the oversized stacked Arabic headline "اكتشف مسارك" in IBM Plex Sans Arabic 700 at clamp(48px, 11vw, 120px), running right-to-left across the full width and bleeding slightly past the left edge on desktop. Beneath it, a single 2px ink rule and a one-line subhead in 18px muted type state the scope of work: the project exists and is complete, and the work is developing its interfaces to meet user needs.

On the left third, a cluster of three rotated circular stamps — RIASEC, 18 سؤالاً, نتيجة فورية — in primary orange and mustard overlaps the headline block by 24px but never covers any glyph. The primary CTA "ابدأ الاستكشاف" is a solid orange pill pinned to the bottom-right of the headline block with a 4px hard ink shadow; the secondary text link "تصفح التخصصات" sits beside it.

Below the hero, a ruled scope-and-roles panel states the project's completeness and the scope of work, and describes the two working roles. A repository reference block links to https://github.com/Bito-Tech/msarak. A specialisations ticker strip runs as the only permitted marquee.

On mobile the stamps collapse to a single horizontal row below the CTA, and the headline wraps to three lines without clipping. At 375px, 768px, and 1280px, every headline, wordmark, label, number, card text, and control stays entirely inside the viewport and its container; only imagery, decoration, and the ticker may cross an edge.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the oversized stacked Arabic headline "اكتشف مسارك" on the kraft ground, with the stamped Masarak badge in the top-right and the three rotated circular stamps (RIASEC, 18 سؤالاً, نتيجة فورية) overlapping the headline block on the left third.
• Input → transformation → outcome thesis: as the visitor arrives, the headline and its 2px ink rule settle into place with a simple 8px upward fade over 240ms, triggered once; the stamps land with a 2px downward snap; the specialisations ticker begins its horizontal pass. The outcome is a composed, readable poster in which the scope statement, the two role descriptions, and the workspace entry are all legible and reachable.
• Motion vocabulary: sturdy and mechanical — 120–180ms ease-out on hover and focus, no bounce, no spring; stamps land with a 2px downward snap; section reveals are simple 8px upward fades over 240ms, triggered once; the ticker is the only marquee.
• Composed first frame: kraft ground, 3px ink rule at the very top, stamped badge top-right, the full headline set right-to-left across the width, the 2px rule and 18px muted subhead beneath it, the three rotated stamps on the left third, and the orange pill CTA with its 4px hard ink shadow pinned bottom-right of the headline block.
• Reduced-motion state: under prefers-reduced-motion the ticker stops entirely and wraps into ruled rows; the fades and snaps resolve immediately to their final positions; the poster remains fully composed and every item is whole and readable.

9. Non-Functional Requirements

NFR-01 — Arabic RTL and responsive UI (explicit) The interfaces are Arabic-first and RTL, and responsive across viewports. Content flows right-to-left; navigation sits on the right on desktop; the wordmark anchors the top-right. Rationale: the platform's stated MVP scope includes Arabic RTL and responsive UI, and its audience is Arabic-reading.

NFR-02 — Readable text and controls stay whole at every viewport (explicit) At 375px, 768px, and 1280px, headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled, rotated, overlapped, or cut as the creative direction asks, as long as they cover no readable text or control. Moving and scrollable content may cross an edge by design and is judged by whether it actually moves or scrolls and whether every item becomes fully readable as it passes. Under prefers-reduced-motion it stops and shows whole items, wrapping into rows or sitting in a horizontally scrollable row (overflow-x: auto). Where any direction or requirement asks readable text or a control to be cropped, clipped, covered, or run off an edge, it is kept whole and the gesture is carried by imagery or decoration instead; for readable text and controls this rule takes precedence.

NFR-03 — Motion restraint and reduced-motion support (explicit) Interaction motion stays within 120–180ms ease-out with no bounce or spring; no motion over 300ms on interaction; section reveals are 240ms and triggered once. Marquees are permitted only for the specialisations ticker strip and stop entirely under prefers-reduced-motion, wrapping into ruled rows.

NFR-04 — Preserve the existing technology stack (explicit) The work stays on Laravel 12, PHP 8.2+, MySQL 8.4.x, Eloquent, Blade, Tailwind CSS, JavaScript/Fetch, Laravel session authentication (sessions, cookies, CSRF, password hashing), Vite, Node.js 24.x, Composer 2.x, npm, PHPUnit/Laravel Tests, Git, and GitHub. React, Vue, SPA, Laravel Breeze, Laravel Sanctum, JWT, API tokens, SQLite, and MariaDB are excluded. Rationale: these are the project's stated technologies and exclusions.

NFR-05 — Static specialisation catalogue (explicit) Specialisation data remains in resources/data/specializations.json; there is no database table for it and no admin CRUD over it.

NFR-06 — Server-side RIASEC processing (explicit) RIASEC score calculation is performed on the server.

NFR-07 — Non-diagnostic framing (explicit) The platform is exploratory guidance, not a psychodiagnostic tool, and it does not produce binding academic or professional decisions. Interface copy and result presentation must not imply diagnosis or a binding decision.

NFR-08 — Automated tests and build checks before merge (explicit) php artisan test, npm run build, and scripts/verify-project.bat run and pass before merge.

NFR-09 — Repository and secret hygiene (explicit) No direct push to main; no .env commit; no secrets; composer.lock and package-lock.json tracked; no composer/npm update in setup; no credentials in the repository; .env local only; no root MySQL for runtime.

NFR-10 — AI usage documented and understood (explicit) AI-generated code must be understood by the person submitting it, and AI usage is documented in AI_Log.md.

NFR-11 — Local runtime and health check (explicit) The application runs locally at http://127.0.0.1:8000 with a /up health check.

NFR-12 — Accessible contrast and legibility (required_inference) The kraft/ink palette is applied so that body and display type keep strong contrast in light mode, and tabular numerals are used for RIASEC scores and percentages so that dense result rows stay legible in RTL. Rationale: the accepted goal is interfaces that meet user needs, and the direction specifies strong contrast and tabular numerals for exactly these values.

10. Tech Stack

Preserved from the source, first:

• Backend: Laravel 12 (monolith)
• PHP runtime: PHP 8.2+
• Database: MySQL 8.4.x
• ORM: Eloquent
• Frontend: Blade
• Styling: Tailwind CSS
• Client logic: JavaScript / Fetch
• Auth: Laravel Session + Cookies + CSRF, password hashing
• Build tool: Vite
• Node: Node.js 24.x
• PHP packages manager: Composer 2.x
• JS packages manager: npm
• Testing: PHPUnit / Laravel Tests
• Version control: Git
• Collaboration: GitHub
• Routing: routes/web.php
• Specialisation data: resources/data/specializations.json (static; no database table; no admin CRUD)
• RIASEC processing: server-side

Excluded: React, Vue, SPA, Laravel Breeze, Laravel Sanctum, JWT, API tokens, SQLite, MariaDB.

Tooling requirements: Git 2.x, PHP 8.2+, Composer 2.x, Node.js 24.x, npm, MySQL 8.4.x.

Setup scripts: check-environment.bat, setup-database.bat, setup-project.bat, verify-project.bat, start-project.bat.

Fonts (per creative direction): Alfa Slab One for Latin headings; IBM Plex Sans Arabic for Arabic headings and body.

11. Assumptions and Constraints

Hard constraints

• C-01 (explicit) The project already exists and is complete; the work is limited to developing the interfaces (UI/UX) and is not a rebuild of the project.
• C-02 (explicit) The interfaces developed must meet the needs of the user.
• C-03 (explicit) The work is carried out against the repository at https://github.com/Bito-Tech/msarak.
• C-04 (explicit) Out of MVP scope for Masarak: admin dashboard, admin statistics, CRUD specializations, public API, standalone mobile app, psychometric diagnostics, binding academic/professional decisions.
• C-05 (explicit) Excluded technology: React, Vue, SPA, Laravel Breeze, Laravel Sanctum, JWT, API tokens, SQLite, MariaDB.
• C-06 (explicit) The generic indigo/blue-on-white SaaS template look is forbidden for this project.
• C-07 (explicit) No blue, indigo, or violet anywhere in the palette; no Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body; no soft blurred drop shadows, glassmorphism, gradient blobs, or frosted panels; no grids of identical hover-lift cards with 16px+ rounded corners; no centred hero with headline, subtext, and a single button in the middle of the viewport; no stock-photo gloss, 3D renders, or clip art as imagery; no bouncy spring easing, particle effects, or motion over 300ms on interaction.
• C-08 (explicit) Readable text and controls stay whole at 375px, 768px, and 1280px, and no other element covers any part of them.

Assumptions (narrow and labeled)

• A-01 (required_inference) The Developer and the Owner are distinct people in the accepted persona catalog; the Owner is identified in the source as أيمن, whose listed role is Frontend & UX. This SRD treats the Owner as the decision-making participant for priorities, verification, and approval, and does not assert any permission differentiation between the two roles.
• A-02 (required_inference) Identity continuity is application-owned and is established anonymously on first use, then verified on return. It exists so that review findings, improvement items, priorities, verification outcomes, and approvals stay bound to the correct participant and can be resumed. It does not create differentiated permissions or role-based visibility.
• A-03 (required_inference) The repository is provider-owned. Repository browsing, issues, pull requests, reviews, and actions are used through the provider's own surfaces and are not re-implemented here.
• A-04 (required_inference) The local development environment is reachable at http://127.0.0.1:8000 with /up as the health check, per the project's quick reference.
• A-05 (required_inference) The Masarak student-facing journeys — browsing and comparing specialisations, the 18-item four-option exploratory assessment, saved answers during assessment, server-side RIASEC scoring, non-diagnostic interpretive feedback, multiple recommendations, stored previous results, and resuming exploration — are existing product behaviour of the complete project and are the subject matter of the interface work, not new capabilities introduced by this engagement.
• A-06 (required_inference) The specialisations ticker strip on the Landing page is the only permitted marquee, per the creative direction.

Presentation and technology defaults [Default — not specified by user]

• The exact wording of interface copy beyond the direction's specified strings ("اكتشف مسارك", "ابدأ الاستكشاف", "تصفح التخصصات", "مشارك / MASARAK", "RIASEC", "18 سؤالاً", "نتيجة فورية") is not specified by the user and is written to match the plain-spoken, warm register of the direction.
• The exact breakpoint values beyond 375px, 768px, and 1280px are not specified by the user.
• The exact implementation of the review-status and confirmation stamps beyond the direction's specification (SVG, 2px ink stroke, rotated −8° to 6°) is not specified by the user.

12. Glossary

• Masarak (مشارك) — The existing, complete academic and career guidance platform for Yemeni high-school students and anonymous visitors. Arabic-first and RTL.
• bronze-msarak — The project name for this UI/UX development engagement on top of Masarak.
• UI/UX Developer (مطوّر الواجهات) — The accepted persona who reviews the current interfaces and implements the UI/UX improvements inside the existing project.
• Project Owner / Decision-Maker (مالك المشروع / صاحب القرار) — The accepted persona who directs improvement priorities, verifies user-need fit, and approves the final interface design.
• RIASEC — The six-type vocational interest model (Realistic, Investigative, Artistic, Social, Enterprising, Conventional) used by Masarak to explore inclinations. Rendered as a 6-segment hand-drawn SVG ring with 3px ink strokes and orange/mustard fills.
• Exploratory assessment — Masarak's 18-item, four-option assessment. It is exploratory guidance, not a psychodiagnostic instrument.
• Non-diagnostic interpretive feedback — The clear, interpreted result and recommendation output that Masarak produces, which does not diagnose and does not constitute a binding academic or professional decision.
• Specialisation catalogue — The static set of academic specialisations held in resources/data/specializations.json. It has no database table and no admin CRUD.
• Current UI — The destination where the existing Masarak interfaces are opened and reviewed before improvements are implemented.
• Design Workspace — The primary working destination where UI/UX improvements are implemented, priorities are directed, and the design is approved.
• Preview — The destination where developed interfaces are previewed and verified against user needs before approval.
• Improvement item — A recorded UI/UX improvement bound to a target interface, carrying a priority, an implementation state, and a design approval state.
• Confirmed state — The forest-green (#2F4A3C) treatment reserved strictly for "result confirmed / recommendation saved" states, including an approved design.
• Pre-merge checks — php artisan test, npm run build, and scripts/verify-project.bat, run before merge.
• Accepted workflow — Issue → Branch → Implementation → Commit → Push → Pull Request → Review → Squash Merge → Delete Branch, on a protected main branch.