convert/docs/superpowers/specs/2026-07-31-ombrora-frontend-redesign-design.md

Ombrora Convert — frontend redesign (foundation)

Date: 2026-07-31

Goal

Redesign frontend/ into a modern, minimalist, dark-mode-capable, bilingual (FR/EN), SEO-friendly single page that embeds the existing file-conversion tool directly in the homepage, with reassurance elements built from real backend facts. This is Sub-project 1 of two: it delivers the shared shell (design system, i18n, dark mode, SEO fundamentals). A follow-up Sub-project 2 (programmatic per-format-pair landing pages, e.g. /fr/jpg-vers-png) is deliberately out of scope here — it needs this foundation to exist first, and needs its own content/routing spec.

Scope decisions (from brainstorming)

• One merged page, not two. Originally considered a marketing Home + separate /convertir tool page; changed after user feedback — the upload/convert flow is embedded directly in the homepage hero. There is nothing left for a separate tool route to do, so it's dropped.
• i18n via URL prefix, not a client-side toggle: /fr/ and /en/ are distinct, indexable, bilingual URLs connected by hreflang. Chosen over a single-URL toggle specifically because Google can only index one language per URL.
• Root / redirects to /fr/ or /en/ based on Accept-Language, defaulting to /fr/ if undetected — avoids duplicate content on / vs /fr/.
• Legal pages (mentions légales, confidentialité, CGU) are deferred. No real company/hosting/legal data exists yet to put in them; publishing placeholder legal text would be worse than not having the pages. Revisit once that content is ready.
• Reassurance claims are limited to what the backend actually guarantees today, verified in code, not invented:
  • Auto-deletion: src/config.js → retentionHours (RETENTION_HOURS env, default 1), enforced by src/cleanup.js (cron-driven in production per README.md).
  • Max file size: src/config.js → maxFileSizeMb (MAX_FILE_SIZE_MB env, default 100).
  • No account required: true today — POST /api/jobs requires no auth.
  • 100% online / nothing to install: true — browser upload, server-side conversion.
  • RGPD/hosting-location messaging was explicitly not requested by the user and is not included.
• Brand name: "Ombrora Convert" (per user), replacing the generic "file-converter"/"Convertisseur de fichiers" placeholder title.
• No SSR/prerendering in this sprint. The site remains a client-rendered Vite SPA; SEO relies on on-page tags, structured data, and Googlebot's JS rendering. Flagged as a known limitation, not a gap to silently fix — a candidate for Sub-project 2 if organic performance requires it.
• No new frontend test harness. frontend/ has no test setup today; adding one is a separate decision, not bundled into a redesign. Verification for this sprint is manual (npm run dev, both languages, both themes, multiple viewport widths).

Architecture

Dependencies (new, all pure JS — no native bindings, safe for o2switch)

Added to frontend/package.json:

• react-router-dom — routing.
• react-i18next, i18next, i18next-browser-languagedetector — i18n.
• @phosphor-icons/react — icon set (outline style, per design system below).

Routing

• frontend/src/main.jsx wraps App in a BrowserRouter.
• App.jsx becomes a route table:
  • / → redirect component: reads navigator.language, maps anything starting en to /en/, everything else (including undetected) to /fr/.
  • /:lang/ → HomePage (only fr/en accepted; anything else renders a NotFound, since there's no other route to fall back to).
• HomePage renders inside a shared Layout (header + footer), and is code-split via React.lazy (per stack guidance: lazy-load route-level components rather than importing everything upfront) — a single-page site doesn't gain much from this today, but it establishes the pattern Sub-project 2 needs when more routes exist.

i18n

• frontend/src/locales/fr.json, frontend/src/locales/en.json — flat key/value dictionaries for all UI strings (headline, reassurance bullets, format-family labels, button/label text, tool status messages).
• react-i18next initialized with the :lang route param as the single source of truth for the active language (via i18n.changeLanguage(lang) in a useEffect keyed on the param) — no separate persisted-locale state, so the URL and displayed language can never disagree.
• Language switcher in the header: a two-item control (FR/EN) that navigates to the sibling /:otherLang/ path, preserving no query/hash state (there is none to preserve).

Dark mode

• Toggle in the header, plus first-load detection of prefers-color-scheme. Per the design system's own guidance ("avoid dark mode by default"), the default is light — prefers-color-scheme: dark is honored as an initial value, not forced.
• Implementation: a data-theme="light"|"dark" attribute on <html>, set on mount from (in priority order) localStorage.getItem('theme') → matchMedia('(prefers-color-scheme: dark)') → "light". Toggling writes the explicit choice back to localStorage, which then wins on every subsequent load regardless of system preference.
• frontend/src/index.css currently already defines a CSS-variable token set with a prefers-color-scheme: dark media query (leftover from the Vite template scaffold, purple accent). This is replaced outright by the new token set (below), driven by [data-theme="dark"] attribute selectors instead of the media query alone, so the manual toggle can override system preference.

Design system

From ui-ux-pro-max --design-system "file conversion SaaS tool modern minimal trustworthy" (Flat Design × Minimal Single Column pattern):

• Typography: Plus Jakarta Sans (Google Fonts @import), replacing the current system-ui stack.
• Color tokens (light, with dark override for each):
  • --color-primary: #2563EB / dark #3B82F6
  • --color-accent: #D97706 (CTA — the upload/convert action)
  • --color-background: #F8FAFC / dark #16171d-class dark surface
  • --color-foreground: #0F172A / dark light-gray text
  • --color-muted, --color-border, --color-destructive: #DC2626 (error states — reuses the existing .error semantic role in FileCard.jsx)
• Icons: Phosphor, outline weight, never emoji — UploadSimple (dropzone), File/FileText (per-file cards), DownloadSimple (download link), plus one icon per reassurance bullet (e.g. a clock for auto-delete, a shield or lock for no-account).
• Effects: flat surfaces, no shadows/gradients, 150–300ms transitions, prefers-reduced-motion respected (transitions become instant when set).
• Accessibility: 4.5:1 minimum contrast in both themes, visible focus rings (not removed for aesthetics), all interactive controls ≥44×44px touch target.

Page structure (single page, FR content shown — EN mirrors via i18n keys)

1. Header — logo/wordmark "Ombrora Convert", language switcher (FR/EN), dark-mode toggle. Single row at every breakpoint (no nav items to overflow, so no hamburger menu needed).
2. Hero — headline + one-line description + the upload dropzone embedded directly in the hero (drag-and-drop via native HTML5 DnD events on a styled dropzone, or click to open the file picker — no drag-drop library needed).
3. Selected-files state (conditionally rendered, same trigger as today's pendingFiles.length > 0): per-file cards directly below the dropzone, each with the existing target-format <select>, quality slider (image formats), PNG compression slider, ICO size <select>, and PDF-compression checkbox+slider — same logic as current App.jsx, restyled into a card layout instead of an inline <li> row (today's single-row-per-file layout is what breaks on narrow viewports; this is a real layout fix, not cosmetic). "Convertir" button triggers the same handleConvert.
4. Submitted-jobs state — FileCard components (existing polling/download logic unchanged), restyled to match the new card visual language.
5. Reassurance strip — 4 items, icon + short label, sourced only from the verified facts above: auto-delete after 1h, no account required, 100% online/nothing to install, up to 100MB per file.
6. Supported-formats section — grouped by family, grid layout (1 col mobile → 2 tablet → 4 desktop):
   • Images: jpg, jpeg, png, webp, gif, tiff, avif, heic/heif, ico (all-pairs within the image set, plus HEIC/ICO as documented in src/converters/heic.js/ico.js, plus image→PDF from imageToPdf.js)
   • Documents: docx, txt, html, md, pdf, csv, xlsx (per src/converters/document.js's registered pairs)
   • Polices: ttf, otf, woff, dfont (per src/converters/font.js/dfont.js)
   • Ebooks: epub, fb2, lrf, mobi, pdb, rb, snb, tcr, azw3, pdf (per src/converters/ebook.js's EBOOK_FORMATS)
   • This list is hand-maintained in the frontend, not fetched live from GET /api/formats — that endpoint answers "given this one source format, what targets exist," which isn't the right shape for a "here's everything we support" marketing grid. Risk: it can drift from the registry if a converter is added/removed later without updating this section — accepted for this sprint (YAGNI a generated-list build step until the format catalog changes often enough to justify one).
7. Footer — reassurance recap (short form) + format-family recap + language switcher. No legal links (deferred, see above).

Responsive behavior

• Mobile-first, breakpoints 375 / 768 / 1024 / 1440px.
• Dropzone and per-file cards: full-width, stacked vertically on mobile; format/quality controls stack under the filename instead of the current single inline row.
• Formats grid: 1 → 2 → 4 columns across the breakpoints above.
• Header: fixed single-row layout at all sizes.
• All interactive elements (dropzone, toggle, language switcher, sliders, selects) sized for ≥44×44px touch targets.

SEO

• frontend/index.html: real <title> ("Ombrora Convert — Conversion de fichiers en ligne" / EN equivalent set dynamically per route — see note below), <meta name="description">, OpenGraph (og:title, og:description, og:type=website, og:locale), Twitter card tags.
• Per-language <title>/meta description and <link rel="alternate" hreflang="fr"> / hreflang="en" / hreflang="x-default" are set client-side per route via a small useEffect-based head manager (no new dependency — direct document.title/meta-tag DOM updates keyed on the :lang param), since this is a single static index.html shell shared by both language routes.
• JSON-LD SoftwareApplication schema injected on HomePage (name "Ombrora Convert", applicationCategory: "UtilitiesApplication", offers with price 0).
• frontend/public/robots.txt (allow all) and frontend/public/sitemap.xml (2 URLs: /fr/, /en/) added as static files.
• Existing PostHog snippet in index.html is untouched.

Out of scope (explicitly deferred)

• Sub-project 2: programmatic per-format-pair SEO landing pages, sitemap generation at scale, internal linking between them.
• Legal pages (mentions légales, confidentialité, CGU) — pending real company/hosting data.
• SSR/prerendering.
• A frontend automated test harness.
• RGPD/hosting-location trust messaging (not requested).

Testing

Manual only, per the "no new test harness" decision above:

• npm run dev in frontend/ (proxying /api to a locally running src/server.js/src/worker.js per existing vite.config.js proxy).
• Verify both /fr/ and /en/ render correctly, / redirects appropriately, language switcher round-trips.
• Verify dark-mode toggle, and first-load respecting prefers-color-scheme before any manual toggle has been made (test via OS-level dark mode with localStorage cleared).
• Verify upload → format/quality selection → convert → poll → download flow still works end-to-end (functional logic is carried over from App.jsx/FileCard.jsx/api.js, not rewritten).
• Verify responsive layout at 375/768/1024/1440px widths, particularly the per-file card controls and formats grid.
• Verify reassurance figures shown in the UI (1h, 100MB) match whatever RETENTION_HOURS/MAX_FILE_SIZE_MB actually resolve to in the running backend, rather than being hardcoded strings that could drift from .env — confirm during implementation whether these should be hardcoded copy (matching today's defaults) or fetched from a small backend config-exposure endpoint; hardcoding is the default assumption for this spec since no such endpoint exists today and adding one is a backend change beyond "frontend redesign," but flag this as a decision point for the implementation plan.