Files
gracesalmoun/docs/visual-refinement.md

122 lines
6.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Grace portfolio visual refinement
## Audit and preservation
The existing Next.js 14 App Router application was refined in place. The main
visual problem was the use of complete, vertical presentation boards as hero
and project imagery, together with overlapping bordered panels. The site now
uses isolated architectural renders, open alternating project layouts, quieter
rules, and a separate full-sheet viewer.
All five featured projects, additional projects, descriptions, roles, highlights,
years, locations, awards, experience, education, skills, software, metrics,
contact details, English/Arabic copy, PDF actions, theme controls, and routes are
retained. The English and Arabic dictionaries were compared programmatically
against their pre-edit snapshots, excluding the intentional image fields.
Original board alt text is retained in `sheetImageAlt`.
## Image architecture
- `Project.coverImage` is optional; the component falls back to the retained
legacy `image` field when a cover has not been assigned.
- `sheetImage` is the complete presentation board, loaded only when the viewer
opens. `additionalSheetImages` supports the second Bab Touma sheet.
- `coverOrientation` keeps tower renders portrait and wider scenes landscape.
- `getHeroImage()` selects `/images/site/grace-hero-main.webp` if it exists at
build time. Otherwise it uses `/images/site/grace-hero-fallback.webp`.
- The current hero fallback is a real **Marota City S160** exterior render,
cropped from the original board. Its visible caption and alt text identify
that project. Supply the preferred image and rebuild; if it depicts another
project, update the hero caption and alt text to identify that project.
- No stock imagery, generated imagery, fabricated image detail, or new
application dependencies were introduced.
All paths in this table are relative to `public/images/`.
| Project | Cover | Full board | Original crop, x/y/width/height |
| --- | --- | --- | --- |
| Marota City S160 | `projects/marota-s160-cover.webp` | `projects/marota-s160-board.webp` | `portfolio-pages/marota-city-s160.webp`: 139 / 799 / 593 / 852 |
| Marota City S174 | `projects/marota-s174-cover.webp` | `projects/marota-s174-board.webp` | `portfolio-pages/marota-city-s174.webp`: 90 / 1520 / 606 / 816 |
| Luxury Hotel | `projects/luxury-hotel-cover.webp` | `projects/luxury-hotel-board.webp` | `portfolio-pages/luxury-hotel.webp`: 91 / 798 / 1253 / 745 |
| Regal Pool | `projects/regal-pool-cover.webp` | `projects/regal-pool-board.webp` | `portfolio-pages/regal-pool.webp`: 998 / 2081 / 339 / 189 |
| Bab Touma Square | `projects/bab-touma-cover.webp` | `projects/bab-touma-board.webp` | Original portfolio page 10: 578 / 1309 / 724 / 463 |
`projects/bab-touma-perspectives-board.webp` contains the original page 10
perspectives, alongside the preserved plan board from page 9. The original
portfolio PDF and all legacy public image paths remain available.
The PDF embeds the same source-resolution page images as the existing extracted
pages; it does not contain higher-resolution individual renders.
## Owner image replacements
The missing preferred hero is `public/images/site/grace-hero-main.webp`.
All five covers now exist and work. Higher-resolution original renders are
recommended, especially **Regal Pool** (the available crop is only 339 × 189).
Replace the corresponding cover files with the owner's originals; preserve
their aspect ratio or update `coverOrientation`. The current crops have not
been artificially upscaled or reconstructed.
## Motion, navigation, and accessibility
Section-heading rules now use their own Reveal intersection state instead of a
page-load animation. Image reveals respect reading direction. Route entrances
use opacity and a 12px translation over 420ms. Reduced-motion preferences reveal
all content immediately and disable transforms.
The native dialog viewer provides full-sheet fit, detail zoom, original-image
links, localized controls, optional sheet navigation, Escape, focus return, and
body-scroll restoration. Without JavaScript, the sheet link opens the actual
image. Mobile navigation retains its focus trap and makes the background inert.
Mobile projects stack image before copy; desktop alternates the image and copy.
The full layout uses logical spacing for RTL/LTR. Contact values and links,
Lucide icons, light/dark themes, and language switching are retained.
## Domain and SEO
The default canonical origin is `https://gracesalamoun.com`. Known misspelled
and www production host overrides normalize to that origin. Other valid
environment origins remain supported. Canonical metadata, OpenGraph, Twitter,
JSON-LD, robots, and sitemap share this configuration. The social image uses the
resolved, existing hero asset rather than a missing preferred-file URL.
## Files
Updated in this refinement: `app/layout.tsx`, `app/portfolio.css`,
`components/home-page.tsx`, `components/project-card.tsx`,
`components/section-heading.tsx`, `components/site-shell.tsx`,
`components/mobile-nav.tsx`, `components/reveal.tsx`,
`data/portfolio/{types,shared,en,ar}.ts`, `data/seo.ts`,
`data/site-config.ts`, and `.gitignore`.
New source files: `components/project-sheet-viewer.tsx`,
`components/route-transition.tsx`, `data/portfolio-images.ts`,
`app/sheet-viewer.css`, and this report. New public assets: five covers, six
boards, and the hero fallback listed above.
The repository already had unrelated and earlier working-tree changes when
the task began; those were preserved. Local browser scripts, screenshots,
content snapshots, and verification output are under ignored `.artifacts/`.
## Validation
- TypeScript: `node node_modules/typescript/bin/tsc --noEmit --incremental false` passed.
- Production: `npm.cmd run build` passed, generating all 13 static pages.
- Lint: `npm.cmd run lint` reaches the interactive ESLint setup prompt; no ESLint
configuration or dependency exists, so a configured lint run is unavailable.
- English/Arabic factual-content preservation comparison passed.
- Browser review uses the built application in local Chromium. Screenshots and
the detailed checks are saved in `.artifacts/visual-report.json`.
- All 58 browser assertions passed with no runtime or console errors. Both
homepages were reviewed at 360, 390, 430, 768, 1024, 1280, 1440, and 1920px;
both resume routes were also checked at mobile and desktop sizes. No
horizontal overflow was found. Dialog fit/zoom/Escape/focus, mobile-menu
focus and inert background, route navigation, dark mode, viewport-driven
heading rules, and reduced motion were checked.
- Additional checks passed for language switching on the resume routes, the
four primary routes, both English redirects, the PDF, robots, and sitemap.
Supplemental section and project screenshots are in `.artifacts/detail-*.png`.
- Build warnings concern the existing webpack cache and stale Browserslist
database; they do not prevent compilation.