When to use it
Write the constitution once, at the start of a product or before a major rebuild, and change it rarely. Every feature spec inherits from it, so a rule stated here never has to be repeated. If a feature needs to break a rule, the constitution changes first, in writing, with a reason.
It works with GitHub Spec Kit, where the constitution is the first artifact, and with OpenSpec, where it sits beside the living spec. See Spec Kit and OpenSpec for how we choose.
How to fill it in
Keep it short and testable. A rule belongs here only if it applies to every feature and someone could write a check for it. Replace every [placeholder]. Where we show an example value, it is an example only. Set your own budgets from your users’ devices and networks.
- Product and scope: two sentences on what the product is and which parts of it the frontend covers.
- Non-negotiables: fill in each section. Delete a section only if it truly doesn’t apply.
- Rules matrix: one row per market or audience whose rules change the interface. Your compliance team confirms each row.
- Definition of done: the checks every change must pass. This list becomes your CI gates.
- Change log: date and reason for every change to this file.
The template
# Constitution: [Product name]
Version: [1.0] · Owner: [role, not a person's name] · Last changed: [YYYY-MM-DD]
## 1. Product and scope
[Two sentences: what the product is, who uses it, and which surfaces this frontend covers.]
## 2. Accessibility
- Standard: WCAG 2.2 AA on every page and state, in every theme.
- Keyboard: every action reachable and operable by keyboard, with a visible focus.
- Motion: prefers-reduced-motion disables all non-essential motion.
- Testing: automated checks on every change, plus a manual screen-reader pass on new interactive UI.
## 3. Performance budget
Measured at the 75th percentile on [reference device] over [reference network].
| Metric | Budget |
|---|---|
| Largest Contentful Paint (LCP) | [e.g. ≤ 2.5 s] |
| Interaction to Next Paint (INP) | [e.g. ≤ 200 ms] |
| Cumulative Layout Shift (CLS) | [e.g. ≤ 0.1] |
| JavaScript per route (compressed) | [e.g. ≤ 150 KB] |
A change that exceeds a budget does not merge.
## 4. Privacy
- No third-party request or storage key outside the inventory in [link to inventory].
- Nothing outside the "necessary" group before consent.
- Every form field mapped to a purpose. No purpose, no field.
- Personal data never in URLs, logs or analytics events.
## 5. Security
- Content Security Policy: default-src 'self'; scripts by hash or nonce; other origins listed with a reason.
- Headers: HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, frame protection.
- Sessions: HttpOnly, Secure, SameSite cookies. Idle timeout [X] min, absolute timeout [X] h.
- Dependencies: lockfile required; new packages reviewed; known-vulnerability scan on every change.
- Secrets: none in client code or the repository.
## 6. Browsers and devices
| Target | Support |
|---|---|
| Browsers | [e.g. last 2 versions of Chrome, Edge, Firefox, Safari] |
| Mobile | [e.g. iOS Safari [X]+, Android Chrome [X]+] |
| Smallest viewport | [e.g. 320 px wide] |
| Reference device for budgets | [device model or profile] |
## 7. Brand rules
- Tokens: components use semantic tokens only. No raw values in components.
- Themes: [list every brand and theme the product supports].
- Copy: [voice rules or a link to them]. Copy lives in content files, not components.
## 8. Rules matrix
Confirmed by: [compliance or legal role] on [YYYY-MM-DD]. This matrix is not legal advice.
| Market or audience | Rule | UI requirement | Spec reference |
|---|---|---|---|
| [Market A] | [Rule] | [What the interface must do] | [feature spec ID] |
| [Market B] | [Rule] | [What the interface must do] | [feature spec ID] |
## 9. Definition of done
A change merges only when all of these pass:
- [ ] Its acceptance criteria pass as automated tests
- [ ] Security checks: headers, CSP, dependencies, secrets
- [ ] Privacy checks: no unlisted request or storage key
- [ ] Accessibility checks against WCAG 2.2 AA
- [ ] Within the performance budget
- [ ] Reviewed by a senior engineer who did not write it
## 10. Change log
| Date | Change | Reason | Approved by (role) |
|---|---|---|---|
| [YYYY-MM-DD] | Initial version | — | [role] |
---
Based on the frontend constitution template by Tacet Works (tacetworks.com/templates/constitution/), CC BY 4.0.
Licence
This template is published under Creative Commons Attribution 4.0. You can copy, adapt and use it commercially. Keep the attribution line at the end of the file.
Next steps
Each feature then gets its own spec, using the feature spec template, and each release reports against both in a trace report. If you would like the constitution written with you, that is the first part of a Spec Sprint.