- About the guidelines
- Getting Started
- Browser and Device Support
- HTML
- CSS
- JavaScript
- Accessibility
- Media
- Fonts
- Performance
- Deployment
- Localization
This is the KXB Frontiers Guidelines template. It is designed to help you and your team put together front-end development guidelines for your project.
Writing, reading and maintaining your guidelines should help you write more consistent, cohesive code more efficiently, produce a better quality front-end, and to make it easier for developers to get started in this codebase. We recommend making the guidelines a part of your codebase both in order to make changes to the guidelines visible and to make them easier to update.
You can use this section to add any other details about the nature of this document that are specific to your project.
We suggest using your project's README.md file for information about installing, running and configuring the application. The CONTRIBUTING.md file can be used to cover the development practices your team adopts when working on the project.
In this section, you can include the following:
- Which version control system is used for the front-end codebase (e.g., Git, Subversion, Mercurial). Include a link to your remote repository and any relevant information regarding hosting, access and administration.
- Details about the version control workflow your team is adopting. Will you be using Gitflow or feature branching? Will commits be squashed when merging into master?
- Any naming conventions your team is adopting. Will you name your branches using a particular syntax? Does your task management platform integrate with your VCS via prefixed commit messages?
- Details about how your team plans to do code reviews, if applicable.
- Information about deployment/integration to test and production environments. There is a separate section for deployment towards the end of the template in case this warrants a section of its own.
Include project management information in this section, like where issues are being tracked and how one gets access to the system. How should developers and others on the project write/structure bug reports and other issues? Is there anything else one ought to know about the project management workflow?
This section covers different tools you might be using as part of the project. We suggest agreeing on choosing a linter and code formatter that everyone will use in order to ensure a base level of consistency. You can include information about tools such as:
- task runners (such as Grunt or Gulp);
- dependency/package managers (such as npm, Bower or Composer);
- scaffolding tools (such as Yeoman);
- tools used to reinforce style (e.g. Editor Config, a linter such as ESLint, or a formatter like Prettier).
You can use this section for information about any additional documentation (or similar resources) related to the project, such as a design system or pattern library. Note where external documentation lives, who maintains it, and what happens when it is updated.
In this section, you can:
- Include a list explicitly covering all devices and browsers to support and to what extent. This can include details about graded support of specific components when applicable.
- Include suggestions on how to develop against older browsers (e.g. IE11), if applicable.
- Maintain a list of devices and browsers on which developers are expected to test their code as well as how and when such developer testing should take place.
- Document the smallest viewport size to support and any other similar constraints.
You can use this section to document the general principles your team follows when writing HTML:
- If your site needs to meet e.g. accessibility requirements due to universal design legislature, specify the success criteria and how to meet them. This can include information about apposite elements and attributes for your particular project and links to external resources that will help developers meet the success criteria (see the HTML section in the
/examples/example-bank.mdexample guidelines). - Are there any other standards or best practices your team has adopted or will adopt? If these are documented elsewhere, provide a link. Here are some examples:
- Does your CSS methodology place any requirements on how your HTML markup is written?
In this section, you can include the following:
- your HTML preprocessor (if applicable), such as HAML or Jade;
- your templating engine (if applicable), such as Mustache or Handlebars;
- information about the backend architecture's influence on the frontend markup (if applicable).
If you have chosen not to use a common formatter/linter for HTML code, coding style specifications can be made here. You can also specify under what (if any) circumstances are HTML comments acceptable and how such comments will look and e.g. stripped out before going to production.
If your team is using a framework like Bootstrap, Foundation or Bulma, provide a link to the documentation. Be sure to specify any ways in which your team's approach deviates from the standard framework.
You can also use this section to list other external stylesheets, like CSS bases (such as Normalize or resets.
If your team follows certain principles/guidelines or subscribes to a particular CSS authoring methodology, provide links to the documentation. If your team's methodology and conventions deviate in some way from the external documentation, be sure to document how (and why).
Examples of CSS Guidelines:
- Harry Roberts' CSS Guidelines
- PageUp People CSS Guidelines
- Gravity Department CSS Guidelines
- Mark Otto's Code Guide
Examples of CSS-authoring methodologies:
You can also provide details about specific CSS techniques or strategies your team uses, such as critical CSS.
If you have chosen not to use a common formatter/linter for your CSS, coding style specifications for e.g. spacing can be made here. You can also include more general CSS style guidelines, concerning:
- Ordering of declarations within a rule (e.g., https://smacss.com/book/formatting#grouping)
- Property values (e.g., when to use
px/rem/emvalues) - Constraints on available spacing and font sizes
- Use of CSS-in-JS
- Your team's commenting strategy
- How your team manages CSS TODOs
- You can use this section to describe the directory structure (and file import) conventions your team follows.
-
If your team using a pre-processor like Sass or Less provide links to documentation and guidelines (e.g., Sass Guidelines for Sass).
-
If your team using a post-processor like Prefixfree or Autoprefixer, include a link to the documentation and information regarding things like customization.
- If your project leverages a UI library (like jQuery, Vue or React) and/or framework (like Next.js or Nuxt.js), provide links to the documentation.
- Make note of polyfills/shims used in your project and any relevant documentation.
- Does your team use a module bundler like Webpack or Parcel? Where can developers get an overview of the project's dependencies?
If your team testing tools like Jasmine, Jest, Karma or Selenium, provide documentation links.
You can provide additional testing information as well, such as how to use tools like Storybook for manual testing, debugging in IDEs, etc.
- Is there a style guide or are there general principles your team should follow when writing JavaScript? Examples:
- Are there any further elaborations on JavaScript authoring style?
- Does your team employ a particular methodology for annotating code (e.g. JSDoc)? Are there any relevant tools complimenting it that developers should know about (e.g., Visual Studio Code's IntelliSense based on JSDoc annotations)?
- What accessibility requirements does the site need to meet?
- What tools are you using to check the accessibility of your site?
- Provide a short description of how your team handles:
- icons (e.g., inline SVG? Sprite sheet? Icon fonts?)
- responsive images (e.g., using
srcsetand<picture />)
- Is your team using any tools to optimize and serve images? Is there a DAM?
- How does your project load custom fonts?
- Do you use any tools to help implement web fonts (such as Font Squirrel)?
- Do you use a service to manage and serve custom fonts (such as Fonts.com or Typekit)?
- Do you use performance budgets? If so, what metrics are you using to determine budgets? Where are you keeping track of performance budgets?
- How are you measuring your project's speed (e.g., using a tool like Pingdom Speed Test or Google PageSpeed)?
- Do you use techniques decrease file size (such as Gzip and Image Optimization)?
- Do you use other performance-related tools in your workflow, like WebPagetest, BigRig or Speedcurve?
How is your front-end code integrated into a production environment?
If your website is served in different languages, consider what do you need to address when localizing for other languages and use this section to document it.