# ASAT Website — `design.md` ## 1. Executive Overview The ASAT website is a premium digital portfolio, professional archive and engagement platform for **Arc. Shehu Ahmed Tukur (ASAT)**. Its primary purpose is to communicate three decades of architectural and development experience through selected work, philosophy, professional service, institutional contribution, thought leadership and carefully contextualized civic engagement. The design must communicate architectural discipline rather than resemble a generic corporate website or political campaign template. Core qualities: - purposeful; - architectural; - contemporary; - authoritative; - editorial; - restrained; - highly visual; - responsive; - accessible; - fast; - completely CMS-managed. The product consists of two major experiences: 1. **Public website** — React + Inertia SSR, SEO-focused, visually expressive and selectively animated using GSAP. 2. **CMS/admin** — React CSR application backed by secure Laravel APIs, optimized for editing workflows and complete content control. --- ## 2. Source-Content Principles ### Primary identity Present ASAT in this order: 1. architect; 2. development consultant; 3. practice leader; 4. institutional/professional contributor; 5. civic/public leader. ### Core statements **Hero:** > Functionality. Character. Integrity. Service. **Complementary:** > Architecture with Purpose. Design for Humanity. **Philosophy:** > Purpose defines function. Function informs form. Architecture serves humanity. ### Philosophy rule The dedicated philosophy source establishes **form follows function**. ### Verification-aware content CMS must track unresolved source items. Do not silently normalize conflicting facts. Known verification items include: - practice leadership: 1997 vs 2001; - Phoenix University chronology; - preferred professional suffix ordering; - missing graduation years/distinctions; - unprovided media, publication and social-profile details. --- ## 3. System Architecture ```text ┌─────────────────────────────┐ │ CDN / Edge │ │ TLS • Cache • Compression │ └──────────────┬──────────────┘ │ ┌──────▼──────┐ │ Nginx │ └───┬─────┬───┘ │ │ public/API PHP │ │ static assets/media │ │ ┌───────▼─────▼────────┐ │ Laravel Application │ │ routes • auth • CMS │ │ services • policies │ └───────┬──────────────┘ │ Inertia props │ API JSON + SSR │ ┌──────────────┴───────────────┐ │ │ ┌──────▼──────┐ ┌──────▼──────┐ │ Public React │ │ CMS React │ │ Inertia SSR │ │ CSR Admin │ └──────┬──────┘ └─────────────┘ │ ┌──────▼──────┐ │ Node SSR svc │ └─────────────┘ ┌────────────────┬────────────────┬─────────────────┐ │ MySQL 8 │ Redis │ Object Storage │ │ content/users │ cache/session │ images/docs │ │ revisions/etc. │ queues │ + CDN │ └────────────────┴────────────────┴─────────────────┘ ``` ### Responsibilities **Laravel** - route resolution; - authentication; - authorization; - CMS APIs; - validation; - workflow; - revision history; - content aggregation; - SEO payload; - cache invalidation; - scheduled publishing; - inquiry processing; - media orchestration. **React public app** - SSR-safe presentation; - responsive components; - interactive enhancement; - GSAP motion after hydration; - forms and lightweight client state. **React CMS** - complex editorial UI; - page builder; - media manager; - workflow controls; - RBAC administration; - search/filter/data tables. --- ## 4. Rendering Strategy ### SSR routes SSR all public content pages: - homepage; - architect biography; - works index; - project case studies; - philosophy; - development perspectives; - professional record; - insights; - insight detail; - contact; - CMS-created public pages. SSR output must contain real copy and semantic HTML, not loading shells. ### CSR areas Use CSR for: - CMS; - authenticated editing workflows; - highly interactive admin tables/editors; - noncritical public widgets after SSR. ### Hydration constraints - no random IDs/values unless stable and server-provided; - no viewport branching during render; - no direct `window/document` reads during SSR; - browser-only code in effects; - GSAP initializes after hydration; - deterministic date/text formatting; - stable section keys from database IDs/UUIDs. --- ## 5. Public Information Architecture ### `/` Homepage: identity, selected work, metrics, philosophy, professional journey, development perspectives, engagement. ### `/the-architect` Sections: - biography; - architectural education; - practice history; - design/development focus; - practice leadership; - teaching/mentorship; - professional service; - bridge from architecture to broader service; - selected timeline. ### `/selected-works` Filterable portfolio with category/location/status/year filters if sufficient content exists. ### `/selected-works/{slug}` Case study composition: 1. project hero; 2. identity metadata; 3. overview; 4. challenge/context; 5. architectural strategy; 6. outcome/impact; 7. project metrics; 8. drawings/images/gallery; 9. optional process diagrams; 10. related works; 11. next-project navigation. ### `/philosophy` Deep storytelling around: - form follows function; - purpose before visual expression; - Canonic method; - seven-stage process; - relationship between function, character, sustainability and human experience. ### `/perspectives` Three core development perspectives plus future CMS-managed perspectives. ### `/professional-record` Professional bodies, fellowships, board roles, public/institutional service, teaching and honours. ### `/insights` Taxonomy-driven articles/speeches/publications/media appearances. ### `/contact` Separate inquiry pathways. --- ## 6. Design Tokens Use CSS custom properties as the source of truth and map them into Tailwind. ```css :root { --color-navy-950: #0b1c30; --color-navy-900: #112945; --color-navy-800: #183756; --color-gold-700: #8f6b1f; --color-gold-600: #af872b; --color-gold-500: #c09338; --color-cream-50: #faf8f2; --color-cream-100: #f6f2e8; --color-slate-100: #e5e8ea; --color-ink: #14181d; --color-white: #ffffff; --radius-sm: .375rem; --radius-md: .75rem; --radius-lg: 1.25rem; --shadow-soft: 0 18px 60px rgb(8 18 32 / 0.08); --space-section: clamp(5rem, 10vw, 10rem); --container-wide: 92rem; --container-copy: 48rem; } ``` Exact official brand values remain CMS/design-token configurable once approved. --- ## 7. Typography ### Display serif Use a sophisticated serif with architectural/editorial character. Possible licensed/open alternatives should be evaluated for performance and visual fit rather than chosen blindly. ### Sans serif Use a neutral, highly readable grotesk/humanist sans for body and interface text. ### Scale ```text Display XL: clamp(3.2rem, 8vw, 8.5rem) Display L: clamp(2.8rem, 6vw, 6.5rem) H1: clamp(2.5rem, 5vw, 5rem) H2: clamp(2rem, 4vw, 3.75rem) H3: clamp(1.5rem, 2.5vw, 2.5rem) Body L: clamp(1.1rem, 1.4vw, 1.35rem) Body: 1rem–1.125rem Small: .875rem ``` Maintain comfortable line lengths, typically 55–75 characters for body content. --- ## 8. Grid & Spacing ### Desktop - 12-column grid; - max content width around 1440–1472px; - wide architectural imagery may bleed toward viewport edges; - text frequently occupies 4–7 columns rather than full width. ### Tablet - 8-column conceptual layout; - simplify asymmetry; - preserve generous margins. ### Mobile - 4-column conceptual layout; - single-column content flows; - 20–24px standard gutters; - large type remains expressive but controlled. Avoid filling every section with cards. Use scale, whitespace and editorial composition. --- ## 9. Navigation Design ### Desktop header - transparent/over-hero variant; - solid variant after scroll; - ASAT wordmark/monogram left; - primary navigation right/center; - restrained CTA if needed; - active route state; - optional mega-panel for selected works/insights if content volume justifies it. ### Mobile Use a full-screen or large overlay menu with: - clear close control; - keyboard focus trap; - scroll lock; - large tap targets; - staggered motion only when motion is allowed; - contact/social secondary links. --- ## 10. Homepage Detailed Design ### 10.1 Hero Composition: - full viewport media or architectural image field; - gradient/overlay only as needed for contrast; - fine plan/grid line overlay; - large H1 occupying an intentional editorial region; - supporting text below/adjacent; - two CTAs; - optional project/location caption. Motion: - image settles from mild scale; - line geometry draws in; - headline mask reveal; - supporting content stagger; - scroll indicator appears last. ### 10.2 Metric band Use strong typography with fine separators. Avoid dashboard-style cards. ### 10.3 Selected work feature Alternate large project compositions: - full-bleed image with metadata rail; - image left/copy right; - copy overlay on controlled dark field; - desktop pinned sequence for 2–4 featured works. ### 10.4 Philosophy statement Use oversized text and large breathing room. Possible composition: ```text PURPOSE defines FUNCTION FUNCTION informs FORM ARCHITECTURE serves HUMANITY ``` Animate connecting rules/terms subtly. ### 10.5 Canonic process Desktop: horizontal/pinned sequence allowed. Mobile: vertical stepper. ### 10.6 Journey Use year markers, short copy and occasional media. Avoid overly dense résumé formatting. ### 10.7 Perspectives Three large editorial panels with understated iconography/line diagrams. ### 10.8 Closing CTA Strong architectural image + simple invitation to explore works/contact. --- ## 11. Project Case Study Design Project pages should be the most visually immersive pages. ### Hero - full-width responsive image/video; - title; - location; - year/status; - project type; - concise project thesis. ### Metadata rail Can include: - client; - location; - scope; - status; - year; - scale/area; - services. ### Story blocks Use alternating text and visual layouts. ### Architectural drawing treatment Plans/elevations/sections should be shown crisply on quiet neutral backgrounds. Optional zoom/lightbox must be keyboard accessible. ### Gallery Support portrait/landscape/masonry-like editorial layouts without causing CLS. ### Desktop storytelling Use ScrollTrigger selectively for: - image crossfades; - pinned project metadata; - slow reveal of strategy/outcome; - plan line progression. Always render an ordinary document-flow version for reduced motion/mobile. --- ## 12. Motion Design Specification ### Motion personality Motion should feel like architectural drafting and spatial composition: - precise; - measured; - calm; - deliberate; - never playful for its own sake. ### Timing ranges - micro interaction: 150–250ms; - common reveal: 450–800ms; - editorial transition: 700–1200ms; - long scroll-linked sequences driven by scroll rather than fixed blocking duration. ### Easing Use restrained custom eases or GSAP standards. Avoid exaggerated bounce/elastic effects. ### ScrollTrigger patterns Recommended: - `start: 'top 85%'` for ordinary reveals; - one-time reveals for most content; - scrub only for truly spatial effects/parallax; - pin sparingly; - always account for responsive breakpoint behavior. ### Performance Animate primarily: - `transform`; - `opacity`; - clip paths only where tested; - SVG stroke-dash for lightweight line drawings. Avoid continuous animation of filters, large blurs or layout dimensions. --- ## 13. Section Renderer Architecture Public pages should compose CMS sections through a typed registry. Example conceptual structure: ```ts const sectionRegistry = { hero: HeroSection, rich_text: RichTextSection, image_text: ImageTextSection, stats: StatsSection, project_grid: ProjectGridSection, featured_project: FeaturedProjectSection, gallery: GallerySection, timeline: TimelineSection, values: ValuesSection, philosophy_process: PhilosophyProcessSection, perspectives: PerspectivesSection, quote: QuoteSection, cta: CtaSection, insights_feed: InsightsFeedSection, }; ``` Unknown section types must fail gracefully in production and log a meaningful warning without taking down the page. Use server-validated schemas for section payloads. --- ## 14. CMS Architecture ### Main navigation - Dashboard - Pages - Selected Works - Insights - Professional Record - Timeline - Perspectives - Media - Navigation - Inquiries - Redirects - Users & Roles - Site Settings - Activity / Revisions ### CMS layout Desktop: - collapsible left rail; - top bar with search/command palette, notifications, user menu; - main workspace; - contextual right rail for metadata/publish controls on editors. Mobile/tablet: - collapsible drawer; - sticky editor actions; - full-width field layouts. --- ## 15. CMS Page Editor ### Header Display: - page title; - status badge; - last saved; - preview; - save; - submit for review/publish depending permission; - overflow actions. ### Workspace Recommended three-zone model: 1. section navigator/order; 2. section form/editor; 3. settings/publishing sidebar. ### Section configuration All sections expose relevant fields plus standardized controls: - internal section name; - enabled state; - layout variant; - background theme; - anchor; - animation preset; - spacing size; - media focal point where relevant. ### Rich text Use a structured editor such as TipTap/ProseMirror ecosystem if introduced. Sanitize server-side. Restrict arbitrary embeds/styles. --- ## 16. CMS Project Editor Tabs or logical groups: 1. Overview 2. Story 3. Media 4. Metrics 5. Relationships 6. SEO 7. Publishing 8. Revisions Support gallery reordering, captions, alt text and focal points. --- ## 17. Media Library UX ### Grid/list views Provide: - thumbnail; - type; - dimensions; - file size; - upload date; - usage count; - alt status warning. ### Detail drawer Edit: - alt; - caption; - credit; - title; - focal point; - tags/folder; - SEO filename metadata if relevant. Never delete in-use media without explicit dependency warning. --- ## 18. CMS Animation Control Editors may select from safe presets, not author JS. Fields: - `animation_preset` - optional `animation_intensity`: subtle / standard - optional `animation_delay_group` where needed Do not expose arbitrary duration, easing or ScrollTrigger expressions to normal editors. Admin preview should reflect motion when previewing desktop but provide a reduced-motion toggle. --- ## 19. Content Model ### Page ```text id uuid title slug page_type status excerpt seo fields published_at scheduled_at created_by updated_by verification_status created_at updated_at ``` ### PageSection ```text id page_id type label sort_order enabled content_json layout_variant theme_variant animation_preset settings_json created_at updated_at ``` ### Project Fields defined in master prompt, plus structured media/metrics relationships. ### Post Support multiple content types with shared publishing/SEO workflows. ### ProfessionalRecord Types may include: - fellowship; - professional service; - board role; - teaching; - honour; - institutional role. ### TimelineEntry Store year/date range, title, summary, category, media and sort metadata. ### ContentRevision Store: - revisable type/id; - snapshot; - actor; - reason/action; - timestamp. --- ## 20. Search and Filtering CMS search must cover relevant entity text. Public search is optional until sufficient content exists, but architecture should not prevent it. Filters should use URL query state where practical for shareability and browser navigation. --- ## 21. Authentication / Authorization UX ### Login Simple, branded and security-focused. No public registration for CMS users. ### Password reset Use secure expiring tokens. ### 2FA Recommended for Super Admin and Administrator roles. ### Session controls Provide ability to terminate other sessions for privileged users if implemented. --- ## 22. SEO Architecture Laravel supplies a normalized SEO object to public pages. A typical payload: ```ts interface SeoPayload { title: string; description?: string; canonical: string; robots: string; openGraph?: { title?: string; description?: string; image?: MediaDto; type?: string; }; schema?: Record[]; } ``` SSR renders these tags on first response. --- ## 23. Accessibility Specification Target WCAG 2.2 AA. ### Public site - skip link; - landmarks; - correct headings; - alt text; - keyboard menus; - visible focus; - sufficient contrast; - form error association; - no motion dependency; - reduced motion; - no autoplay audio; - accessible galleries/lightboxes. ### CMS - fields have labels/instructions; - sortable sections include keyboard alternative to drag-and-drop; - dialogs use proper focus management; - toast messages are announced appropriately; - data tables remain understandable to assistive technology. --- ## 24. Responsive Requirements ### Mobile `<768` - stacked content; - simplified motion; - full-screen nav; - project metadata flows naturally; - no fixed-width media; - no horizontal overflow; - touch targets >=44px where practical. ### Tablet `768–1199` - adapt editorial asymmetry; - avoid desktop pinning unless tested; - two-column compositions where room permits. ### Desktop `>=1200` - full editorial grid; - selective parallax/pinning; - larger typographic scale; - persistent contextual layouts where useful. --- ## 25. Performance Architecture ### Critical path 1. CDN/Nginx responds quickly. 2. Laravel resolves cached content. 3. SSR service renders full initial React HTML. 4. critical CSS/fonts/media load. 5. hydration completes. 6. GSAP initializes after hydration. 7. noncritical modules/media lazy-load. ### Media Generate widths appropriate to design, e.g.: - 480 - 768 - 1024 - 1440 - 1920 - optional 2560 for large retina architecture imagery only. Use AVIF first where supported and WebP fallback. ### JS - avoid monolithic bundle; - lazy-load noncritical galleries/editors; - CMS and public builds should not unnecessarily share large admin libraries; - analyze bundles in CI/release process. --- ## 26. Security Architecture ### Content Rich text is sanitized server-side using an allowlist. ### Uploads - inspect MIME and extension; - random filenames; - never execute uploads; - restrict public document types; - virus-scanning integration point; - private/signed access where content is not public. ### CMS API - authenticated; - CSRF-protected for session auth; - policy checks; - rate limits on sensitive operations; - audit privileged actions. ### Headers Deploy strict CSP compatible with application requirements; avoid unsafe-inline except where cryptographic nonce/hash strategy justifies it. --- ## 27. Caching Cache: - published page payloads; - navigation; - settings; - featured project lists; - sitemap fragments. Use tag/key invalidation on publish/update. Do not serve stale preview/draft data through public caches. --- ## 28. Publication Workflow ### Author/editor flow 1. create/edit draft; 2. autosave/manual save; 3. preview via signed preview URL; 4. submit for review if role requires; 5. reviewer approves/rejects with notes; 6. publisher publishes immediately or schedules; 7. revision snapshot recorded; 8. public caches invalidate; 9. sitemap/search hooks update. --- ## 29. Error and Empty States Public: - branded 404; - graceful 500 fallback; - project/gallery empty states not visually broken. CMS: - actionable permission denied; - validation summaries; - network retry option; - empty content encouragement; - media processing states; - publication conflict handling. --- ## 30. Testing Architecture ### Unit Domain rules, services, helpers. ### Feature Laravel requests, policies, workflow, API behavior. ### Component Complex CMS controls/public reusable interactions. ### E2E Critical user flows across Chromium, Firefox and WebKit. Add console listeners that fail tests on hydration-related React errors for public SSR routes. --- ## 31. CI/CD Design Branches may follow organization convention, but pipeline must include: ```text checkout -> composer install -> npm install -> php lint/static analysis -> backend tests -> frontend lint/typecheck -> frontend tests -> production public/admin build -> SSR build -> Playwright -> artifact/package -> deploy -> migrate -> cache optimize -> restart workers/SSR -> health check ``` Deployment must be environment-aware and approval-gated for production where supported. --- ## 32. Operations Run: - Nginx; - PHP-FPM; - Laravel queue worker; - Laravel scheduler; - Inertia SSR process; - Redis; - MySQL; - CDN/object storage; - logs/error monitoring; - uptime monitoring; - automated database/object backups. Document restore procedures, not merely backup creation. --- ## 33. Initial Content Seed The initial database seed should include structured records for: ### Core identity Arc. Shehu Ahmed Tukur and approved professional designations. ### Values - Functionality - Character - Integrity - Discipline - Service ### Philosophy process - Understand - Analyse - Define Function - Develop Form - Integrate - Refine - Deliver ### Selected works - Lafia Airport Project - Abaji Trailer Park and Container Terminal - NASENI Renewable Energy Industrial Park - Phoenix University ### Perspectives - Planned Communities, Better Living - Resilient Infrastructure, Sustainable Communities - Productive Places, Sustainable Growth The seed is editable bootstrap content, not permanent code-level copy. --- ## 34. Acceptance Criteria ### Public site - SSR is functioning on every public content page. - No hydration errors. - Hero and primary content render without waiting for JS. - Navigation and pages work without animation support. - Core routes are responsive and keyboard accessible. - Motion is polished on capable devices and simplified appropriately elsewhere. ### CMS - all publishable frontend content can be modified; - admins can create/reorder sections; - projects and insights can be managed; - media can be uploaded/reused; - navigation/settings are editable; - preview/revisions/scheduling work; - RBAC restrictions work; - content verification warnings work. ### Quality - tests pass; - production build passes; - cross-browser E2E passes; - security baseline is implemented; - Core Web Vitals are measured and within target or exceptions documented; - deployment and rollback are documented. --- ## 35. Design North Star Every design and engineering decision should reinforce this idea: **The website itself should feel architected.** Its hierarchy should feel planned, its motion should feel measured, its grids should feel intentional, and its visual richness should arise from proportion, typography, imagery, line and space rather than decorative excess. The finished result should be memorable because it is disciplined—not because it is noisy.