Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/construction/frontend-shell/nfr-requirements/nfr-requirements.md
T
SluijsensandClaude Opus 5.5 069c7cb7eb Adds AI-DLC construction docs for the front-end shell feature
Functional design, NFR requirements, code generation plan and summary,
and build-and-test instructions with results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 17:05:03 +02:00

8.0 KiB
Raw Blame History

NFR Requirements — frontend-shell

Refines requirements NFR-01…NFR-06 into measurable criteria. Decisions: frontend-shell-nfr-requirements-plan.md ("Q"), frontend-shell-nfr-clarification-questions.md ("CQ"). Business rules (BR-*) are in business-rules.md.

Quality Gates Overview

graph LR
    Code["Code change"] --> Lint["pnpm lint"]
    Lint --> Test["pnpm test incl. PBT, axe, coverage"]
    Test --> Build["pnpm build incl. type check and sitemap"]
    Build --> Audit["pnpm audit:deps"]
    Audit --> LH["pnpm lighthouse on preview"]
    LH --> Ready["Release ready"]
    Check["pnpm check runs all steps"] -.-> Lint

    classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef gate fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef done fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;

    class Code done;
    class Lint,Test,Build,Audit,LH step;
    class Check gate;
    class Ready done;

Text alternative: pnpm check runs lint, tests (including property-based and accessibility tests), build, dependency audit and Lighthouse in that order; every step must pass before a release.

NFR-P Performance

ID Requirement Measure Source
NFR-P-01 Lighthouse Performance ≥ 90, mobile and desktop, on every route. Exception (temporary): home page on mobile ≥ 80, until responsive images come from the API/CMS and prerendering exists (measured 0.81–0.82). pnpm lighthouse against pnpm preview Q3 = B; code change Q1 = B
NFR-P-02 No layout shift from shell elements: images have width/height, fonts are self-hosted Lighthouse CLS ≤ 0.1 BR-SEO-10
NFR-P-03 The shell adds no network requests beyond bundled assets No third-party origins in the network log NFR-05
NFR-P-04 Router devtools are not in the production bundle Build output does not contain the devtools chunk SECURITY-09
NFR-P-05 Scroll handling is passive, and NavigationBar and BackToTop share useScrolledPast Code review NFR-05

NFR-A Accessibility

ID Requirement Measure Source
NFR-A-01 Lighthouse Accessibility = 100, mobile and desktop, on every route pnpm lighthouse Q3 = B
NFR-A-02 No axe-core violations in the component tests of the shell, placeholder, 404 and error pages pnpm test (vitest-axe) Q4 = A
NFR-A-03 jsx-a11y lint rules pass pnpm lint Q5 = A
NFR-A-04 Keyboard and screen-reader behaviour per BR-A11Y-01…07 and BR-TOP-03/06 Example-based tests + manual check with NVDA or VoiceOver at Build and Test NFR-01
NFR-A-05 Colour contrast per NFR-01. axe in jsdom cannot measure contrast, so Lighthouse covers it NFR-A-01 Q4 note

NFR-S SEO

ID Requirement Measure Source
NFR-S-01 Lighthouse SEO = 100 on indexed pages (currently /) pnpm lighthouse CQ1
NFR-S-02 Non-indexed pages are noindex on purpose. Lighthouse's "blocked from indexing" audit is the only allowed SEO failure there Lighthouse assertion per URL CQ1
NFR-S-03 sitemap.xml contains exactly the indexed pages; registry and route tree are in sync pnpm test (BR-SEO-07, PBT) + build output BR-SEO-06/07

NFR-SEC Security

ID Requirement Measure Source
NFR-SEC-01 Headers on preview:
  • CSP (below)
  • HSTS max-age=31536000; includeSubDomains
  • nosniff
  • X-Frame-Options: DENY
  • Referrer-Policy: strict-origin-when-cross-origin
Test on the header config + response check at Build and Test SECURITY-04
NFR-SEC-02 Production CSP: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'. style-src 'unsafe-inline' is justified: Chakra/Emotion inject runtime styles. Lighthouse Best Practices: no CSP violations in the console SECURITY-04
NFR-SEC-03 The dev server uses the same headers. Its CSP adds only Vite's needs: 'unsafe-inline' in script-src for the React Refresh preamble, and ws: in connect-src for HMR. These dev exceptions never reach preview or production. Header config test Q1 = A
NFR-SEC-04 The production CSP has no inline scripts. next-themes is removed (Q2 = A); JSON-LD is a non-executed data block. NFR-SEC-02 Q2 = A
NFR-SEC-05 pnpm audit:deps (--prod --audit-level high) passes: no high or critical advisories in packages that ship with the site. Advisories in dev-only tools are reported by pnpm audit:dev but do not block. pnpm check Q8 = A, SECURITY-10; code change Q2 = A
NFR-SEC-06 Dependencies are pinned by pnpm-lock.yaml; no unused dependencies; build tools in devDependencies Code review SECURITY-10
NFR-SEC-07 No secrets in front-end code; the e-mail address is never a literal (BR-EMAIL-01) Test: bundle does not contain the joined address NFR-04, BR-EMAIL-01
NFR-SEC-08 Error and 404 pages expose no internals (BR-ERR-02) Example-based test SECURITY-09/15

NFR-R Reliability

ID Requirement Measure Source
NFR-R-01 A render error in a page never blanks the site: the shell stays and ErrorPage shows Test with a throwing route FR-10
NFR-R-02 Errors are logged with console.error in every environment (BR-ERR-03). Central logging is out of scope (SECURITY-03 N/A until there is a back-end). Test Q11 (FD)

NFR-M Maintainability and Testing

ID Requirement Measure Source
NFR-M-01 Every testable property in business-rules.md has a fast-check property test. Failures print the seed and shrink. pnpm test PBT-02…08
NFR-M-02 100% statement and branch coverage of the pure functions: backToTopThreshold, visibleSocials, emailAddress, copyrightLine, canonicalUrl, sitemapXml, jsonLdScript. No global threshold; coverage is reported. Vitest coverage with per-file thresholds Q7 = A
NFR-M-03 ESLint (TypeScript, React Hooks, jsx-a11y) and Prettier pass pnpm lint, pnpm format:check Q5 = A
NFR-M-04 pnpm check runs lint, format check, tests, build, audit and Lighthouse, in that order, and fails on the first failing step. It runs locally at any time. Script Q8 = A, CQ1 = A
NFR-M-05 No duplicate styling: theme usage per BR-THEME-01…07 Code review NFR-02

NFR-B Browser Support

ID Requirement Source
NFR-B-01 Supported: the last 2 versions of Chrome, Edge, Firefox and Safari, and Safari on iOS 16+. Older browsers get the site without guarantees. Q6 = A
NFR-B-02 Features used must work in that set: color-mix(), :focus-visible, fetchpriority, prefers-reduced-motion, scrollTo behaviour instant. fetchpriority degrades gracefully. Q6 = A

Not Applicable

Category Rationale
Scalability Static site without a server; load is the host's concern
Availability / DR Depends on the future host (Operations phase)
Data protection / compliance No personal data processed by the shell; privacy statement is a placeholder page

Follow-ups Outside This Unit

  1. CI/CD: run pnpm check (including Lighthouse) automatically as the final step on every push or pull request, so a forgotten local check is caught early (CQ1). Hand-over to Deployment Setup in the Operations phase.
  2. Wider browser support (Q6 note): reconsider support for older mobile browsers (e.g. iOS 14/15) once real visitor statistics exist.
  3. Responsive images (code change Q1): the hero (and later portfolio) images should come in several widths from the API/CMS or an image service, used via srcset. Restores NFR-P-01 to 0.9 for the home page together with prerendering.
  4. Production headers: configure the same header set (NFR-SEC-01/02) on the production host (Operations).