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
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 nosniffX-Frame-Options: DENYReferrer-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
- 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.
- Wider browser support (Q6 note): reconsider support for older mobile browsers (e.g. iOS 14/15) once real visitor statistics exist.
- 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.
- Production headers: configure the same header set (NFR-SEC-01/02) on the production host (Operations).