Architecture Decision Records (ADRs)

What is an ADR?

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system's architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions ("any decision record").

Adopted ADRs

General

• 2023-11-29: Git branch names should only consist of ticket numbers, lowercase
  Across all practices, it's important to maintain naming conventions for branches to make it easier for PMs, Architects, and devs to manage commits, comments, and JIRA tickets. Consistency will reduce time to find relevant code and to onboard new team members more quickly. Branch names should be in the following format: proj-123 Where proj indicates the project abbreviation code in Jira and the 123 corresponds to the Jira ticket number where the task was requested. This is done for two main reasons: Branches can easily be traced back to their initial request via the ticket number. Branch names will meet the Pantheon MultiDev requirements of being lowercase and 11 characters or less. Team members have a clear and consistent guide to naming branches. Specific code will be easier to find. Projects will have greater tracking fidelity between Jira and Git. Any branch can be turned into a Pantheon MultiDev environment. You can't create branches from Jira because it doesn't allow low-case names. You don't have to follow the convention for big epics such as Drupal core major updates, etc. If you need a second PR with revisions on the same issue then add -n (where n is the number of the iteration). Only do this once your original PR is merged or closed. And update Jira ticket description to include the new branch name. None
• 2024-01-05: Use a standard Pull Request Title format
  Use a standard method for titling Pull Requests. Pull Requests take on the following format for the titles, matching a similar structure to the commit messaging standard. Body is optional. Title: JIRA-ID: Brief description of the feature(s) in the present tense Example: ABC-123: Update the environment to use PHP 14.3 This is for a few reasons... It's important to reference the JIRA issue so that it's easy to track back to the original request and get an understanding of the context of the change. Adopting the same format as our commit message standard will keep team members on the same page when it comes to git commits and reviewing pull requests. More work when creating a Pull Request. Do not revert and redo Pull Requests if they end up being in the incorrect format You are in a rush to fix the site.
• 2024-02-28: All committed code undergoes code review process
  All code that is being merged into the main or master branch of the repository and is being deployed to one of the main level environments: dev, test, or production (live) needs to undergo code review process and be submitted through the pull request on GitHub repository. The review is performed by the architect or technical lead of the project. The review is conducted through the GitHub interface. The reviewer leaves the comments in GitHub on the code with suggestions or requested edits, the developer needs to be tagged on the corresponding Jira issue and the issue needs to be assigned back to the developer. Once edits are resolved the architect conducts another review and approves the PR, then they merge the PR to the main (master) branch and notify the developer that the issue has been merged. Create a pull request per Jira issue and ensure no code written by a non-architect / non-tech lead will be merged without code review performed by tech lead or architect. Code review helps to reduce technical debt and encourages knowledge sharing. Consistent code review should lead to code that has undergone better testing before being submitted and should enhance the capabilities of team members while improving the overall quality and cohesiveness of the codebase. More operational time is required before the deployment. An architect or technical lead is required to be on the project. Client projects that require more than one reviewer Architects (Tech leads) review their code Emergency situations where the architect/tech lead is not available and we cannot postpone the merge Code Review vs. QA Processes and Expectations
• 2024-03-06: Projects should include software version documentation and config
  To minimize the chance of incorrectly QA'd code getting into production, and ease debugging, it is important that development happens with tooling as close to production as can be achieved with the config options provided by your local development environment provider. Project READMEs should specify the tooling versions to be used in production for things like PHP, Database software, Caching layer, Search software, and Node. These versions should then be reflected in the configuration files for any local development and host configuration files committed to the repo for the project. Whenever these versions change, the README and configuration files should be updated to match. Local development environments should mirror the hosted website environment as closely as possible. Initial project setup should involve updating README and matching local development configurations with the hosting environment, and any updates to the hosting environment should involve updating README and local development configuration as well. This is done for two main reasons: Prevent bugs caused by differences in the hosting environment and local setup. Ensure debugging is happening in an environment that matches production to avoid rework. Project startup takes slightly longer. Documentation must be updated when the hosting environment changes. Architects must take responsibility for this. When client-dictated hosting configurations are not replicable with configuration options provided by default by your local development environment provider (ddev, lando, etc.) When setting up local environment is not possible / prohibited by the contract
• 2024-03-13: Git commit messages should follow a standard convention
  Commits should be in the following format: JIRA code (uppercase): brief description of the revision in the present tense. Commits should have a detailed, yet brief, message about the changes. The following are examples of good commit messages: Changes the header navigation order Adds paragraphs module Tweaks the search api's html preprocessor Theme adjustments to the Homepage Hero The following are examples of bad commit messages: Navigation Changes ← In what way? Module Installation ← What module? Search Adjustments ← What adjustments CSS Tweaks ← What was changed and where? NOTE: Where possible, please try to make small, atomic, commits as opposed to one large commit with illogical groupings of work. Commits should follow the below example: PROJ-123: My atomic commit message in present tense Where PROJ is the project abbreviation code and 123 is the ticket number from Jira. To ensure an orderly commit history, make it easy to match commits with their entry in our project management tools, and ease complex revision management operations; it is important that all commits begin with the issue code from JIRA. This method creates a clean commit log where development can be traced, and makes referencing previous work easier if it needs completed on another project. It results in more consistent, professional histories should a project need to be handed off to another developer or agency. Uppercase vs Lowercase was discussed at length. Uppercase matches Jira, while Pantheon branches have to be lowercase. Ultimately uppercase was decided as the standard since that matches Jira and that's the point of the number. The colon was added because sometimes devs would forget to add the space and it made searching very difficult. It is also a good breakpoint if commits need to be imported to a spreadsheet. Development progress can be more easily traced. Previous work will be easier to reference if it needs to be completed on another project. Finding specific code will be easier and faster for all team members. Gives a professional impression to our work. Don't go through amending commit messages to fix the standard, as it could break git history and have git conflicts. Projects that have been using lowercase until this ADR should continue with their conventions. < >
• 2024-03-20: Code repositories should use "main\" as the default branch name
  We use main rather than master as the default branch name for all new code repositories. Use main as the base branch name for code repositories instead of master. The team would be able to safely assume that the default branch is main and wouldn't need to look it up in the repository settings. Many platforms and organizations are adopting more neutral terms like main for their base branch names due to concerns regarding the historical connotations associated with the term master in version control systems. This decision reflects our sensitivity to diverse perspectives and aligns with prevailing industry practices. Requires to have CI to convert branch names from main to master on platforms that require master as branch Team Adjustment: Some initial adjustments are required for team members accustomed to using master. Existing projects already set the base branch as master. Project requirements mandate using master as default branch name

Accessibility

• 2024-09-05: Don't include buttons in clickable cards
  Clickable cards should not include buttons or links within them. Do not include buttons within a clickable card (unless the button is purely decorative). Stacking links on top of another can lead to confusion. When one link is nested within another, it creates ambiguity for both users and web browsers. Potential pushback: Some clients might push back against this, insisting on their personal preferences. We will need to educate them on why this approach is better for accessibility. Possible design reevaluation: Before moving on to implementation, we need to ensure that cards are designed appropriately. Otherwise, we may need to conduct a design reevaluation during the implementation phase, potentially impacting timelines. The button is purely decorative. Contextual menus that contain additional actions. Cards and Card Sections
• 2024-09-19: Use <button> and <a> tags appropriately
  <button> and <a> tags appropriately > It may seem harmless to use <a> and <button> tags interchangeably but to use them in their correct context provides accessibility benefits. Use <a> tags for links only. Use <button> tags to trigger actions like toggling elements on/off, opening and closing content, or submitting forms. It's ok to style links to look like buttons. The issue is when using <a> tags for toggling elements because we have to use javascript to prevent default behavior which leads to issues when javascript is disabled in addition to screen readers misidentifying the element. No need for additional javascript to prevent default behavior of <a> tags. <button> tags provide accessibility features for screen readers, such as aria properties to communicate the current state of elements. There should be no exceptions. If for some reason <button> tags can't be used it is better to use a <div> with the attributes tabindex=0 and role=button. < >
• 2025-02-06: Avoid auto-playing videos & slideshows
  Autoplaying videos and slideshows cause numerous accessibility concerns. Though only a clear pause button is technically required for accessibility, we've found that there are still additional concerns that make auto-playing not worth it. Avoid auto-playing videos and slideshows in projects. Autoplaying videos and slideshows can be distracting for users, increase cognitive load, slow page speed, cause motion sickness, create frustration, and trigger seizures (if there are flashing lights). On mobile, they can also use up data and get cut off. Potential pushback: Some clients might push back against our recommendations, insisting on their personal preferences. We will need to educate them on why this approach is better for accessibility. If the client insists against our recommendation, then we can: Add an autoplaying video as long as there's a clearly visible pause button, and ideally no flashing lights. Add an autoplaying slideshow as long as there's a clearly visible pause button, and ideally at least a 5-7 second delay before each slide of a slideshow auto-advances. Why Autoplay Is an Accessibility No-No A Step-By-Step Guide To Building Accessible Carousels Usability Guidelines For Better Carousels UX
• 2025-02-06: Don't use color alone to convey information
  Not all users can perceive or distinguish colors the same way, which can create barriers to understanding and navigating websites. To ensure our sites are accessible to all users, we must avoid relying solely on color to convey information. Do not rely solely on color to convey information. Relying solely on color to convey information creates accessibility barriers for many users. Colorblind and low vision users may struggle to distinguish color differences, high contrast modes may reduce or eliminate color distinctions, and screen readers do not communicate colors to non-sighted readers. Potentially more complex designs: Designs may be slightly more complex to accommodate multiple ways of conveying the same information. Color can still be used to enhance visuals, as long as it is used in conjunction with other cues such as text labels or underlines. Sometimes color differences convey very minor amounts of context, or just add visual interest, which is not a huge loss to the user if not perceived. Web Content Accessibility Guidelines': Use of colour Examples/Patterns
• 2025-08-07: Do not override the browser's default focus indicator
  Focus indicators are visual cues that highlight the currently focused element on a webpage, guiding users who navigate with keyboards or assistive technologies. By default, browsers provide built-in focus indicators that are already accessible when left unmodified. Overriding these indicator styles can negatively impact accessibility and usability if not styled correctly. Other than applying outline-offset styles, do not style default focus indicators. We have opted not to customize default focus states at this time because ensuring consistent focus styles for every link and interactive element would require significant effort. Factors such as light, dark, high-contrast modes, etc., and other accessibility considerations would all need to be addressed and thoroughly tested. Different browsers handle focus states in various ways, so the quality of focus indicators can vary. Safari, in particular, is known for having less effective focus indicators compared to other browsers. Default focus styles may not match your theme. Adding outline-offset styles to improve legibility of the focus outline. Small adjustments like outline-offset can enhance aesthetics without sacrificing functionality. If a third-party plugin or module has removed default focus styles for its components, you should re-add them. WCAG Focus Visible

Drupal

• 2024-05-01: Use the Environment Indicator module with standard color configuration on all of our modern Drupal projects
  In our default Drupal installation, we have predefined settings for the Environment Indicator module. It is important to have it enabled on all of our client projects. It is also critical to have consistency for the environment indicator values to avoid confusion, unintended mistakes, and misconfiguration. On our support projects we configure environment settings to match our default installation during the new support project intake process. All client sites will have the Environment Indicator module installed and configured. Environment colors will be configured as follows: Environment Colors Suggestedfg_color Suggestedbg_color Live White on Red #fff #ec0914 Staging Black on Yellow #010101 #f5c000 Development / Multi-dev White on Blue #fff #007fad Local White on Green #fff #007a5a All Drupal websites our team works on have one or more environments. At a minimum, there will be a production and a local development environment. Most projects will have production, staging, development, and local environments. Developers often access different environments at the same time. Since making content or configuration changes in the wrong environment can have unintended consequences, it is important to distinguish environments easily and have a consistent color scheme across all projects. Errors will be reduced as all screenshots by authenticated users will indicate the environment. All non-live existing sites should be configured to use the standard scheme. Teams deviating from the recommended colours will need to check the accessibility of their custom colours. Support intake process will require this setup. Standard environment colours may conflict with those existing before this ADR site configuration, so each team will need to decide whether colours should be changed on existing sites. We don't have access and client permissions to install and configure new modules on the website.
• 2024-05-22: Store Composer patches locally rather than referencing them directly from drupal.org
  The use of remote patches applied by composer results in risk to the project due to the possibility of the remote file changing or ceasing to exist. The use of local patches speeds project build because the patch already exists locally, and eliminates the possibility of the patch changing or ceasing to exist unexpectedly. Contents of remote patches can potentially change leading to unexpected build issues. Detailed guidance can be found on our wiki page on composer patches. All patches to be applied by composer should be downloaded and placed in the /patches directory in the project root to be referenced by composer. Drupal patch files for contributed modules should be named according to the following convention <'--.patch' > Drupal is one of our most common use cases for composer patches. As drupal.org moves to handling code collaboration in gitlab, remote patches become more complicated. Decreased install speed and risk from downloading remote patches. Increased repo size. None
• 2024-07-10: Store Composer Patches configuration in composer.patches.json
  Defining patches in a separate composer.patches.json file will make it easier for the developer to add and maintain patch definitions as they won't need to search for the patch section of composer.json, and it will also reduce clutter in composer.json. New projects using composer should start with a composer.patches.json file with no patches defined in it. To make this change, move the patches item in composer.json to composer.patches.json, and replace the patches item in composer.json with the following: patches-file: composer.patches.json, We will define patches in a separate file called composer.patches.json rather than composer.json. In composer, patches can be defined either in the main composer file or in a separate file which is referenced in the main composer file. Patches are the only commonly directly edited section of a composer.json file, so making that section easy to find improved productivity. All projects have a common composer structure with patches easy to refer to. Projects not using Composer need not concern themselves with this until a change to the patches is made. Projects with no patches can opt to have no patches file until patches are needed.
• 2024-08-07: In views displays use entity display modes instead of fields
  When displaying entities in views use entity display modes, not fields. When building views, use entity display modes instead of field configuration when possible. If existing view modes don't line up with the intended style or content availability create a new view mode to avoid affecting existing pages. View queries are faster and better optimized when the view queries the whole entity instead of adding joins to the field tables. It's also easier to theme a display mode that can be reused across the site components outside the view's context than re-theming fields for one particular scenario. Having view mode templates keeps the theme clean and organized, and it's easy to see which template is being used. Therefore, using display modes in views improves site performance and decreases the time required for theming. Developers cannot use field overrides in the view and will have to write preprocess functions or override in the template. Aggregation options inside of the view are limited and may require a hook to achieve distinct results. For GROUP BY functionality, the option force fields usage must be used. Usage of fields will significantly simplify the solution. When the site exists and is already using fields. Core-provided views such as content. Table-formatted views.
• 2024-12-11: Leverage view modes when rendering entities
  When rendering entities in layout builder or blocks leverage view mode over fields when possible. When possible, render entities within layout builder blocks and reusable blocks using the view modes instead of rendering individual fields. If fields are rendered as the layout builder blocks, they lose consistent core classes that can be reused for front-end development. When the fields are wrapped in the view mode then front-end developer has access to the view mode template overrides and the fields are rendered consistently regardless of where the entity in this particular view mode is going to be used. It becomes an atomic component that looks styled independently of Layout Builder section or theme region. This promotes front-end code reusability, allows for cleaner themes and reduces effort needed for styling. It also allows to produce predictable results for the editors since components they are placing are semantically and functionally atomic. Potentially increased amount of templates in the theme to accommodate all of the view modes. Cleaner Layout Builder UI (less fields are exposed to the editor) You need to place just one field and it's not going to be reused anywhere else, it's used only once and it doesn't make sense to create view mode just for that e. g. Body field on the nodes.
• 2024-08-21: Place form fields in the same order that they are rendered in the default view mode
  To ease site building activities, the order of fields in the form and the display should match unless there is a documented reason for them not to. Always check form fields order and reorder to match the default view mode order. When form fields are ordered randomly, it makes it difficult for content editors to find the desired field to fill and/or update when needed. A better editorial experience. We do not need to go and check old projects. If there is a compelling reason not to and it is documented in the project README.
• 2024-11-29: Lock entity language on edit forms
  When setting up a multilingual site it is important to have a consistent original language for the entities instead of allowing editors to select the original language. This allows for consistency in the translation and makes implementation of custom functionality related to translations easier. Disable language field in the form mode, set original default language for every translatable entity to be the default language of the website. The majority of our clients come to us with the website content being generated in a single language, and then this content is being translated to the other languages. Disabling language select on the node allows for less editorial mistakes -- when editors may select the wrong language by accident or instead of translating an existing node / page they may create a new one in a different language breaking multilingual connection between pieces of content. Disabling the language select allows to set the language to a default value and assure consistency throughout the content of the website. This leads to the simplification of back-end translation-related functionality and migration of the content. This also allows to have fallback language in case of certain content items not having a translation in a particular language. To disable the select, keep the Show language selector on create and edit pages checkbox off in content type settings and set the default language to be site's default language. /assets/drupal-show-language-selector.png alt=Drupal admin interface showing the Show language selector checkbox width=684 height=auto /> Drag language select field into the disabled section of the form mode. /assets/drupal-language-select-field.png alt=Drupal admin interface showing the language select field' checkbox width=684 height=auto /> Editors will not be able to control the original language of the entity. Sites with multiregional editorial teams where single default content language doesn't make sense from the semantic perspective and single fallback language cannot be established.
• 2025-04-17: Use kala-drupal-project as default installation when starting all new Drupal projects
  It is important that all new Drupal projects that Kalamuna undertakes start from our current best practices. This ensures that as we improve our practice, we can capture these improvements in one place, and all new projects will adopt them. It also ensures that any deviations from our normal practice have been made intentionally for a reason. These practices are maintained in our kala-drupal-project repository. It has all the modules and configurations we frequently use in Drupal projects. A standardized directory structure. The kala-project recipe to create the initial configuration for the project. Essential contrib modules. The base GitHub actions with the build and deploy processes. All new Drupal projects will use the kala-drupal-project as the starting point to create new projects. We must establish a standardized approach to starting new Drupal projects within the organization. Currently, there are multiple ways of initiating new Drupal projects, leading to inconsistency in the setup, dependencies, and configurations across projects. To streamline the process, we aim to standardize the way new Drupal projects are initiated by using a predefined starter template. The kala-drupal-project is a repository that contains a set of pre-configured, best-practice components that our team has developed and tested for creating Drupal projects. It includes configurations, modules, libraries, and best practices that our team frequently uses across various projects. It will continue to be maintained and updated as new best practices come into play. Consistency: Every new project will have a consistent baseline, reducing discrepancies and improving maintainability. Speed: Developers can get up and running quickly with a project template that already includes most of the necessary configurations, modules, and tools. Best Practices: Projects will automatically incorporate the best practices and configurations that the team has established and tested. Easier Maintenance: With all projects starting from the same template, maintaining updates, security patches, and configuration changes becomes easier and less error-prone. Existing Projects: This ADR does not apply to any projects that already exist or are in progress. Current and ongoing projects can continue to use their existing setup and configurations. There is no requirement to migrate or reconfigure these projects to adopt the kala-drupal-project template. Special Circumstances: Projects with unique requirements that cannot be met by the kala-drupal-project template may also be exempt. In such cases, a separate decision can be made to define the setup for those projects.
• 2025-04-17: Use QuickSilver to automate build steps on Pantheon
  Use QuickSilver automation scripts committed to Kalamuna default installation to automate post code sync workflow on Pantheon. On Pantheon, after the code sync workflow is complete, we need to run certain commands to import configuration, perform database updates, and clear caches. Those commands can be automated with the QuickSilver scripts and workflows already set up in the Kalamuna Drupal installation. Alternatively, they can be installed on the legacy projects by copying them from the current version of the Kalamuna Drupal installation. This deploy script should be enabled on code sync, not on deploy. In the pantheon.yml file, the setup would look like this: workflows: sync_code: after: - type: webphp description: Import configuration from .yml files script: private/scripts/quicksilver/quicksilver-deploy-tools/postdeploy.php Configuration import, database updates, and cache clearing are the repetitive tasks that can be automated to avoid human error and speed up the deployment process. Pantheon provides QuickSilver integration that allows to automate those tasks. You don't need to run the commands manually. In rare cases the commands will fail to run if Pantheon is experiencing an outage or configuration is not importable. When deploying we must remember to safely import configuration, a step that is not required when pushing code to dev or multidev. Legacy project that doesn't use configuration management.
• 2025-05-01: Live site configurations must always be integrated into deployments
  Actions such as block placement on the live site can cause the configuration to change on the live environment. Always ensure these changes are evaluated, applied as needed, and tested before deploying to the live site. During a deployment cycle, synchronize any uncommitted changes in the active configuration from a site's live environment down to the integration branch and test it with the incoming code changes so that any configuration changes that were made on the live site during the release cycle are captured and not lost during deployment. In Drupal, settings and site structure are kept separate from content. This allows configuration changes to be captured in code, which makes it easy to rollback any unwanted changes, or QA configuration changes on a separate environment before they're pushed up to the production server. All of our configurations are captured in version control, and any configuration changes that we make are to be done through synced configurations. Sometimes changes to configuration on live are unavoidable (e.g. client circumstance, block placement). To avoid conflicts, the live configuration is to be brought down to the integration branch and tested prior to deployments. See the process documentation on how best to synchronize the configuration. The need to integrate and test live config changes will slow deployments. There is no need to import live configuration that is undesirable or that already exists in the incoming code.

Frontend

• 2024-06-11: SCSS/CSS nesting max levels
  Nesting styles allow for less code repetition and cleaner code that is easier to read and quicker to write. However, too many nested levels can make code more difficult to read and make selectors too specific to override. Max 4 levels of nesting. This does not include pseudo-classes, pseudo-elements and media queries. For example in Drupal node page it can be structured below: The first level is node/view class The second level is wrapper class The third level is field class The fourth level is children of field class Code block example: .node--type-blog.node--view-mode-featured { .node__content { margin-top: 1rem; margin-bottom: 1rem; } .field--name-field-image { border-right: 24px solid color(primary-3); box-sizing: border-box; background: $blue-gradient; height: 100%; img { max-blend-mode: multiply; filter: grayscale(100%); } @include breakpoint($m-break) { flex: 0 1 50%; max-width: 50%; } } } It is convenient to keep endlessly nesting CSS selectors but too many levels makes code hard to read and makes selectors too specific and hard to override. Code that is easier to read. Styles that can be easier overridden when needed. Media queries Pseudo-classes Pseudo-elements Old projects that already have the over nested code in place.
• 2024-06-25: Use vanilla Javascript instead of jQuery
  We should use vanilla JavaScript rather than jQuery. When possible, use vanilla JavaScript instead of jQuery on projects. This allows us to gain higher performance and less overhead by not having to load the jQuery library. Drupal and WordPress are moving away from jQuery. Plain JavaScript is preferable due to its better performance and modern features. The advancement of JavaScript has diminished the value of numerous advantages previously associated with jQuery, such as cross-browser compatibility and simplified code writing. The potential for an increase in development time due to the inability to rely on predefined jQuery functions. Legacy code: If a project is already using jQuery, it might be beneficial to continue using it for the sake of consistency.
• 2024-07-09: Use local fonts instead of 3rd Party hosted fonts
  We no longer use 3rd party hosted fonts and install fonts locally instead. Store fonts locally instead of using 3rd-party hosted fonts such as on Google Fonts. Using 3rd party hosted fonts such as through Google Fonts is against the law in Europe because of GDPR (General Data Protection Regulation). Eliminates the need to rely on 3rd party services that could be unavailable. Extra step to download fonts. Taking time to go through the setup process which is outlined in the wiki. Old project already using Google Fonts for websites not based in Europe. Set fonts locally
• 2024-07-09: Use of SASS partials instead of one big sass file
  Use SASS partials to organize your CSS into logical manageable chunks. Partials should be used to organize stylesheets to make things more modular and easier to maintain. Example: // main.scss @import 01-base/_all; @import 00-starter/_all; @import 02-atoms/_all; @import 03-molecules/_all; @import 04-organisms/_all; @import 05-layouts/_all; @import 06-misc/_all; The larger a stylesheet grows, the harder it is to maintain. By splitting large stylesheets into smaller chunks, it allows codebases to become more maintainable in the long run because things are easier to find, and the smaller focused files are easier to read and understand. The potential for overuse: There is a risk of overusing partials, which can lead to too many small files, making the project structure overly complex and difficult to manage. Legacy code: If a project is not using SASS partials, it might be beneficial to stick with the current structure, since it could be a massive undertaking to change everything. Small codebases: For smaller projects like a single-page site, the overhead of creating and maintaining multiple SASS partials might not be worth it. A single stylesheet might be more efficient. Sass Basics - Partials
• 2024-09-03: Appropriate use of CSS Units
  By necessity, any stylesheets will include a combination of different units when specifying sizes of things. However, it is important to use the proper units for the proper uses. rem Rems are the most frequently used unit, and is usually the right answer if one of the units below do not match the use. They are relative to the base font size of the window (which should never be overridden). Use anytime you need a specific width, such as the size of the gutter around the page or between columns. Can be used to specify the minimum and maximum width of elements, such as making sure a logo does not get too big, or a card does not get too small. Use for breakpoints (now preferred to ems, since browser compatibility issues have been resolved). Useful for defining heading and paragraph font sizes. px No one should ever use px. They are no longer a thing, since no devices actually lock browser units to physical screen pixels. While browsers define virtual pixels, they are basically translating them into 1/16th of a rem, so we might as well use rems instead in most situations. pt No one should ever use pt. It's only used in printing, not web development. em Ems should be used when the spacing should change along with the font size. A good example of this is that headings should always have a relative amount of space above them that gets bigger the bigger the heading gets. By using ems, we do not need to remember to change the absolute spacing between elements like paragraphs when the font size changes. In addition to vertical space between elements, it should also be used for horizontal spacing between inline elements (such as placing an icon the appropriate distance from text). It should also be used for padding inside and border radius of buttons that should scale with the text. (Padding in things like inside of and between cards/columns should use rems, so everything lines up vertically down the page nicely.) x.x Unitless numbers are used for the line-heights of text elements. For example 1.2 for headings and 1.5 for body text for maximum readability. While usually equivalent to the em units when applied to a single element, unitless line heights are recommended due to the fact that child elements will inherit the raw number value, rather than the computed value. [source] % Percentages are used to specify how much of the available space that an element should use. Almost always 100%, since things like column width are now usually specified using grids with fr units. Sometimes you might need to define a horizontal percentage using flexbox. fr Fractional units that allow you to define how much relative space each column in a grid should take. Used now instead of percentages, since you don't need to account for the size of column gaps. vh/vw Used to size things in relation to the size of the viewport. Usually 100vw or 100vh to take up the full width, but watch out, since some OS/browser combinations include the scrollbars as part of that space, so content may overflow the window and create additional scrollbars. Sometimes vh is used as the min-height of the page so content takes up enough space to ensure that the footer is at the bottom of the screen. vw unit can be used for responsive scaling that changes based on screen width such as inside calc and clamp functions. Other units A bunch of offshoots of vh/vw units like dvh, lvh, svh, svb, svh, svi, svmax, svmin, svw, lvb, lvh, lvi, lvmax, lvmin, lvw, dvb, dvh, dvi, dvmax, dvmin, dvw, vi and vb. Who knows what they do and how to use them, but they are supported by most browsers. deg, s, etc. Used for css animations and transformations. We only use s for time length instead of ms. Using the proper units will ensure accessibility especially as users have control over font size. Traditional units such as pixels are outdated and don't make much sense because browser units no longer map on physical pixels. Browser support for many common units such as rems have become complete and we are no longer stuck using some units for browser support (such as ems in media queries). Newer units such as fr have been introduced to make relative sizing without precise percentage computations possible. Using the same units within a project and across projects ensures uniform code. Using the right units leads to less regressions and layout bugs especially as other things change. When users do things like change the font size things like spacing will scale with and it will ensure the text stays legible. Some developers will be annoyed that they can't use the units that they prefer and have been using for a while. QA needs to be inline with the ADR to ensure correct units are being used. Existing projects (more important to remain uniform within a project, so long as it isn't creating layout bugs or accessibility issues.) When we use certain frameworks that might prefer different units that we should match. < >
• 2024-10-15: Minimize :not() CSS pseudo-class usage
  :not() CSS pseudo-class usage > Overuse of the :not() selector may cause specificity issues and, is harder to understand what is going on in the code. Avoid using the :not() pseudo-class selector in CSS whenever possible, opting for more specific and direct selectors instead. The :not() selector often leads to complex and hard-to-maintain stylesheets with specificity issues if overly used or not scoped properly. Specificity challenges: In many cases, using :not() might require adjusting specificity, which could complicate the cascade. Readability issues: Needs more time to figure out the target element. When inheriting the codebase, with complex css. However, the usage MUST be scoped and specified as much as possible. When using css frameworks and libraries, again, the usage MUST be scoped and specified as much as possible. < block resources > How :not() chains multiple selectors :not() Specificity < endblock resources >
• 2025-04-29: Do not set background color and text color for blocks that would be used in Layout Builder
  Setting text and background color in blocks may lead to issues when these blocks are placed in layout builder. Blocks within layout builder should not have a set background color and text color, they should inherit their colors either from the layout builder section (if specified) or the body element. Most of the time, this is redundant code. It may result in unneeded additional frontend fixes. Layout Builder sections may have dark background colors which require lighter text colors for the blocks within them. Setting text colors for the blocks makes overriding them by the section style harder and requires more time. N/A Old projects. There is no need to go back and update them. Specific components that have decorative design elements. These would need their styles to be adapted to different sections.

Wordpress

• 2024-07-12: All hard-coded labels and outputs should be wrapped in internationalization tags and refer to the site's custom text-domain
  Even if a site is not slated to be translated, all hard-coded strings, labels, and outputs (including patterns, blocks, templates, etc.) in PHP and JavaScript should be wrapped in internationalization tags to future-proof the site. A custom text domain should also be established. To prepare the theme to leverage internationalization functions, first have a proper text-domain in the theme header: /* * Theme Name: A Kala Theme * Author: Kalamuna * Text Domain: kalapress-project * Domain Path: /languages */ Then use that text domain with the appropriate internationalization function throughout the theme. For example: <?php echo _e('The default label for the front end.', 'kalapress-project' ); ?> If HTML is needed then it should be escaped using the appropriate function for the use case: <h1><?php esc_html_e( 'Title', 'kalapress-project' )?</h1> Clients sometimes decide later in the life cycle of the site to add translations for one or more additional languages. Having to go back through old code is more costly and time-consuming than simply providing for it while the code is being written. Additionally, sometimes text labels exist in a template part like the footer that needs to be made available for translation. Learning curve: Developers might not know which internationalization functions to use, as well as other functions like sprintf() and /* translators ...*/ comments depending on the functionality requested. This ADR only applies to output generated by code written by Kalamuna, not anything provided via plugins like Gravity Forms where the entire output is controlled by the plugin.
• 2024-07-19: All custom blocks should have a block preview
  Include a preview for all custom native and ACF blocks so that when you hover over the block in the block inserter, a preview is displayed. /assets/wordpress-custom-blocks-preview.png alt=The block preview thumbnail for a custom Cards Grid block. width=250 height=auto /> Block previews are needed for custom blocks. The preview can be generated by passing your block's attribute values or by using an image as the block preview. A preview for a block helps editors see what the block will look like before they insert it into a post. Adding a preview can require additional work and extra steps. Older blocks: You don't have to add previews to existing blocks. Block Attributes example
• 2024-07-26: Fonts should be loaded through theme.json
  Use theme.json to register fonts, to ensure that font files are properly enqueued throughout the site. Fonts should be added to theme.json settings in settings.typography.fontFamilies. You can either reference an existing font family, such as a system font, or use the font-face declaration for custom fonts by using the src parameter to add a link to the font file. Loading fonts through theme.json ensures that the font files are properly enqueued for both the editor and front end of the site. This approach also simplifies font management. Extra step to download fonts. None. Set fonts locally (WordPress) Theme.json Typography options 10up Loading Fonts using theme.json
• 2024-08-09: Blocks and patterns should not have the project name in the Title
  Because all blocks and patterns should be in a category with a title that reflects the project name, the project name is not needed in the title. Shorter names are also easier to identify for editors while inserting content. Blocks and patterns should not have the project name in the Title. With proper categorization, adding the project name to the block or pattern title becomes redundant. Additionally, sometimes the project name is too long and the inserter truncates it before the editor can see the actual description. For example, Super Long Project N... Blocks may be harder to find outside of the inserter without the project name in the title. Could be a title conflict with a block added by a plugin (e.g. FAQ) that would necessitate changing the title in some way to make the difference between them clear. None.
• 2025-09-05: Local wp-config.php or its analog should disable wp_mail()
  On occasion a local environment will send the This site has encountered a fatal error email notice to a client if they are listed as the admin. Add the following function to the controlling wp-config.php, wp-config-local.php, or whatever the controlling file is in the local environment before pulling the database: // Disable Outgoing WordPress Emails function wp_mail() { // } Clients have received this email in the past, generating confusion and churn explaining that it's not their live site. The need to test email functionality in a local environment is almost non-existent. Most local setups do not enable mail by default but some, like sites with WP Mail SMTP or Local by Flywheel, do. If this step is not taken prior to completely activating the theme and database, there is the risk of a crash and subsequent client notification. Local environments will not be able to use mail functionality. We need to test mail sending on a local. Disable emails sending from WordPress in Development

License and Conditions

While Kalamuna publishes these Architecture Decision Records (ADRs) in the spirit of open source under Creative Commons BY-SA 4.0, we do not provide any warranty or guarantee of their accuracy or applicability to your specific use case.