(DRAFT) Create an initial CODE_CONVENTIONS.md and CODE_STYLE.md (Frontend)

[lgeggleston]

References

Related to discussion that occurred in our DSpace Developer Meeting on June 25, 2026 and July 02, 2026

Related to initial Code Conventions PR created for DSpace repo: DSpace/DSpace#12739

Description

This PR creates two documentation files in our codebase:

CODE_STYLE.md is a copy of the short Angular section in the existing Code Style Guide in the wiki.
CODE_CONVENTIONS.md is a draft of a new "coding best practices" guide for the frontend which could be used by developers or reviewers as a reference for code review. I added only a few guidelines so far, based on the overarching principles described in User Interface Guidelines & Accessibility.

Instructions for Reviewers

• Review the structure of these files and provide comment/suggestions for improvement. This was based on the initial structure in Create an initial CODE_CONVENTIONS.md to describe coding best practices. Move style guide to CODE_STYLE.md DSpace#12739, but if that doesn't work as well for dspace-angular we can absolutely change it.
• Review the current content of these files and provide comment/suggestions for improvement.
  • Question: Would it be appropriate/helpful to copy all of the detailed design & accessibility guidelines described in https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility? For now, I just included some top level principles and a link to this wiki page, because the rules are much more numerous than the starting-out conventions for the backend, and I'm not familiar with how many are suggestions vs. rules we really want enforced. However, if developers think it's useful to copy over everything, we can certainly do so (probably grouped by topic such as buttons, notifications, layout etc.)
  • Similar question re. spelling out any linting rules in the Style Guide - would we want to highlight a set of the existing ESLint rules?

[tdonohue]

Thanks @lgeggleston ! I finally had a chance to give this a closer read. Overall, I think it looks like a great start. I only had a few minor suggested improvements inline below. (These are just suggestions though, so if you disagree or other developers disagree, I'm also OK with how this is currently structured)

[tdonohue]

I think we may want to move this into its own section, so that we can have two guidelines under this Accessibility Guidelines header:

1. Align with WCAG (Web Content Accessibility Guideliens) AA criteria
   • (Put the existing content under this subheader)
2. Align with DSpace's User Interface Accessibility Guidelines
   • This new section should link to https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility#UserInterfaceDesignPrinciples%26Accessibility-UserInterfaceAccessibilityGuidelines

[tdonohue]

Per the discussion last week (above keeping the user interface guidelines in the wiki), I think we may want a new section here that says something like:

### Align with DSpace's User Interface Design Guidelines

And link that to https://wiki.lyrasis.org/spaces/DSDOC10x/pages/408945765/User+Interface+Design+Principles+Accessibility#UserInterfaceDesignPrinciples%26Accessibility-UserInterfaceDesignGuidelines

That way we have a reference back to the wiki page where these guidelines currently exist.