Documenting a Robust Frontend Convention for Small Teams
A concise convention should define structure, naming conventions, cascade, states, and validation steps using real-world examples and be maintained in the repository.
For frontend developers and web designers, "decision relevance" and "executable example" are crucial for "frontend conventions for small teams." A "paper document" serves as a cross-check.
Published: 3 min read · Author: Sebastian Geier
What must a frontend convention address for a small team to actually use it?
The file structure, naming conventions, CSS layers, component variants, browser target, and mandatory checks are documented. Pull requests reference specific examples and update the rule when a justified exception becomes permanent.
Practical scenario: "Paper document"
The team repeatedly discusses where component variants are stored. A short rule defines the filename, variant attribute, and test location based on an existing component; the review checklist refers directly to this example.
Decision relevance
Decision relevance – The rule prevents recurring ambiguity and is not merely a matter of personal preference.
Executable example – Permissible and problematic cases can be found in the actual project code.
Maintenance Path – Owner and change decision are named to keep the document and code together.
Paper Document
Paper Document – The manual is separate from the repository and is not considered during changes.
Rule Overload – Too many requirements slow down simple decisions and encourage workarounds.
Unresolved Exception – Deviations accumulate without resolution and form a second convention.
Executable example
Recurring review discussions and inconsistent sections are collected as candidates.
Each selected rule receives a rationale, a small code example, and a suitable automatic or manual check.
Rule violations and justified exceptions are regularly reflected in the documentation.
Maintenance Path
Control signal
Signal 1
Recurring review comments on already documented decisions.
Control signal
Signal 2
Convention rules without a current example or discernible audit trail.
Follows up on "Frontend Conventions for Small Teams"
Meaningfully combining utility classes and semantic classes Answers the next practical question: How to combine utility classes with semantic component classes without rule chaos?
Treat speed as a system requirement rather than as a later optimization. continues this line of thought with another question: How can website speed be made a binding system requirement from the outset?
If you want to practically implement "Frontend Conventions for Small Teams," you can refer to Robust Website Systems This resource focuses on "Design System and Component Boundaries" and "Decision Relevance."
Conclusion: Frontend Conventions for Small Teams
Small teams need a few visible decisions instead of comprehensive rule sets. Examples and reviews keep a convention alive.
Sources and Further Information
The primary sources define the technical framework for "Frontend Conventions for Small Teams."
CSS Custom Properties for Cascading Variables Level 1 – W3CThis specification provides the binding basis for inherited, replaced, and fallbacked CSS variables.
Baseline – web.devThe model maintained by the Web Platform Initiative makes the cross-browser availability of platform functions verifiable.
Key Thesis
Only recurring decisions are documented: file structure, naming scheme, CSS layers, component variants, browser target, and audit trail. Pull requests highlight deviations early and keep the examples up to date.
What This Is Not About
A convention is not a comprehensive style guide that doesn't reflect real-world decisions in the code.
What it's about
It documents a few recurring rules with examples, audit trails, and ownership where the team actually uses them.
Frontend Architecture & CSS
Using Design Tokens Effectively for Spacing, Typography, and Radii
"Frontend conventions for small teams" includes, as a separate audit step, the question: How do we integrate spacing, typography, and radii into a usable token system?
Frontend Architecture & CSS
Reduce frontend dependencies before they become a maintenance problem.
Supplements "Frontend Conventions for Small Teams" with a separate decision: According to which criteria should a team retain or remove frontend dependencies?
Insights Overview
All VELUNO Insights at a Glance
Further analyses on Website Systems, digital visibility, and robust working models.
Actionable Example: Implementation Path
The most frequently repeated review comments provide the best starting point. From these, three concrete rules with real-world project examples can be developed.