127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
# Tech Policies — Public Web Portals
|
||
|
||
These policies apply to **all** governmental body web portals in this repository. They define security, accessibility, quality, and operational standards.
|
||
|
||
---
|
||
|
||
## 1. Security
|
||
|
||
- **No secrets in repository**
|
||
No API keys, passwords, or tokens in source code, config files, or history. Use environment variables or a secure secrets store.
|
||
|
||
- **Dependency hygiene**
|
||
- Dependencies must be from trusted registries (npm/pnpm).
|
||
- Run vulnerability scanning (e.g. `pnpm audit`, Snyk) in CI; fix or document accepted risks.
|
||
- Prefer minimal dependency set; justify new dependencies in PRs.
|
||
|
||
- **Content Security Policy (CSP)**
|
||
Each portal must ship with a strict CSP (e.g. via Next.js headers). Nonces or hashes for inline scripts if required; avoid `unsafe-inline` where possible.
|
||
|
||
- **HTTPS only**
|
||
All environments (dev/staging/production) must use HTTPS. No mixed content.
|
||
|
||
- **Authentication**
|
||
Use the standardized OIDC/OAuth 2.0 flow. Session handling (e.g. httpOnly cookies, token storage) must follow the same security guidelines across portals.
|
||
|
||
---
|
||
|
||
## 2. Accessibility (WCAG 2.1 AA)
|
||
|
||
- **Compliance**
|
||
All user-facing content and flows must meet WCAG 2.1 Level AA unless a formal exception is documented.
|
||
|
||
- **Testing**
|
||
- Use automated tools (e.g. axe-core, Pa11y) in CI.
|
||
- Manual checks for keyboard navigation, screen reader, and zoom.
|
||
- Critical user journeys must have an accessibility sign-off before release.
|
||
|
||
- **Design**
|
||
Color contrast, focus indicators, and touch targets must meet WCAG. Use the shared design system’s accessible components.
|
||
|
||
---
|
||
|
||
## 3. Browser & Device Support
|
||
|
||
- **Browsers**
|
||
Support the current and previous major versions of:
|
||
Chrome, Firefox, Safari, Edge.
|
||
Exact versions and “current” definition are set in CI (e.g. browserslist).
|
||
|
||
- **Devices**
|
||
Responsive design required; mobile and tablet are first-class. Test on real or emulated devices for critical flows.
|
||
|
||
- **Progressive enhancement**
|
||
Core content and actions must work without JavaScript where feasible; enhance with JS for better UX.
|
||
|
||
---
|
||
|
||
## 4. Code Quality & Consistency
|
||
|
||
- **TypeScript**
|
||
Strict mode. No `any` except where explicitly typed and commented. Public APIs must be fully typed.
|
||
|
||
- **Lint & format**
|
||
- ESLint and Prettier configs are shared at repo root.
|
||
- CI fails on lint or format errors.
|
||
- No disabling rules without a documented exception.
|
||
|
||
- **Naming & structure**
|
||
- Same folder conventions across portals (e.g. `app/`, `components/`, `lib/`).
|
||
- Shared glossary for common terms (e.g. “user”, “session”, “portal”) to keep copy and code consistent.
|
||
|
||
---
|
||
|
||
## 5. Testing
|
||
|
||
- **Unit / component**
|
||
Vitest + React Testing Library. Critical business logic and shared components must have tests.
|
||
|
||
- **E2E**
|
||
Playwright. Critical user journeys (e.g. login, main flows) must have E2E tests. Same browser matrix as production support.
|
||
|
||
- **Coverage**
|
||
Minimum coverage thresholds (e.g. 80% for critical paths) enforced in CI. New code should not lower coverage without approval.
|
||
|
||
---
|
||
|
||
## 6. Documentation & Onboarding
|
||
|
||
- **Per-portal README**
|
||
Each portal must have a README with: purpose, how to run locally, required env vars, and links to TECH_STACK.md and TECH_POLICIES.md.
|
||
|
||
- **API contracts**
|
||
Document public APIs (OpenAPI or tRPC schema). Keep docs in sync with code.
|
||
|
||
- **Changelog / releases**
|
||
Document breaking changes and notable updates. Use a consistent format (e.g. keep a CHANGELOG or use release notes).
|
||
|
||
---
|
||
|
||
## 7. Performance & Reliability
|
||
|
||
- **Performance budgets**
|
||
Set and enforce budgets (e.g. LCP, FID, CLS) in CI where possible. No regression without approval.
|
||
|
||
- **Error handling**
|
||
User-facing errors must be handled gracefully; no raw stack traces or internal details exposed.
|
||
|
||
- **Logging & monitoring**
|
||
Use the same approach (e.g. structured logs, same log levels). No PII in logs.
|
||
|
||
---
|
||
|
||
## 8. Governance
|
||
|
||
- **Changes to TECH_STACK.md and TECH_POLICIES.md**
|
||
Changes apply to all portals. Update stack/policies via a process that includes impact review (e.g. ADR or tech lead sign-off).
|
||
|
||
- **Exceptions**
|
||
Any exception to these policies must be documented (what, why, expiry, owner) and reviewed periodically.
|
||
|
||
- **Review cycle**
|
||
Stack and policies should be reviewed at least annually and after major incidents or audits.
|
||
|
||
---
|
||
|
||
*These policies sit alongside TECH_STACK.md. Portals must comply with both.*
|