Accessibility Theme Builder - Software Project Contribution and Onboarding

[andybs]

1. Describing The Contribution

Business Problem

While governments and businesses have embraced accessibility standards, the implementations are complex thereby yielding compliance challenges and shortcomings. However, the availability of a theme builder, which generates machine readable asset types to be used by design systems to publish products that are accessibly inclusive, could provide much needed assistance to designers, developers and testers. Such a tool could leverage a set of foundational services that can dynamically calculate accessibility constraints for a range of disabilities and disorders. The theme builder could systematically orchestrate, for a designer, the interrelationships between atomic design elements to yield design system themes that reduce accessibly inclusive complexities.

Proposed Solution

Since Atomic Design enables designers and developers to establish a round-trip workflow process that traverses from abstract concepts to concrete details; and given the challenges associated with risk compliance for people with disabilities (Visual, Motion, Motor, Auditory, Cognitive/Learning), what if:

• We applied Atomic Design concepts towards the development of accessibly compliant solutions, yielding consistency and scalability while mitigating regulatory risk?
• An atomic design system could allow us to apply reuse, scaling, Continuous Integration and Continuous Delivery in the creation of user experiences?
• We had design and development libraries that were associated with each other? If changes happened in one they would be pushed to the other.
• We could create an atomic design system that was rooted in accessibility, assuring all components met accessibility guidelines?
• We could update atomic elements and roll changes across all products in minutes rather than months or years?
• We could align desktop and mobile experiences?
• We could seamlessly deliver light and dark mode experiences that meet WCAG guidelines?
• We could provide on-demand, profile-aware experiences that addressed a user's specific accessibility needs?

Our solution is described in our online docs.

Tentative Roadmap

Our GitHub Repo Project Wiki provides a detailed roadmap of the project's short and long-term inititaives. Additionally, there is a list of open issues organized by a Kanban Board to help understand project backlog.

Current State

The A11y Theme Builder is comprised of two GitHub Repositories. According to the Project Roadmap, this asset was contributed as an Alpha release in March of 2023 by Discover Financial. It was then used in the FINOS GAAD Hackathon where international interest, coupled with enhancements, spawned the effort to consider transfering the tool out of Discover Incubation and into FINOS Labs Incubation.

Existing Materials

• [x] GitHub / GitLab Repository
  • [x] URL for the repository
    • [x] https://github.com/discoverfinancial/a11y-theme-builder
    • [x] https://github.com/discoverfinancial/a11y-theme-builder-sdk
  • [x] Project Name - ThemeBuilder & ThemeBuilderSDK
  • [x] @finos-admin has been given read-only permissions if private
• [x] Is Continuous Integration used? No, other than the docs website build
• [x] Was the project ever released? (yes)
  • [x] If so, are releases public? (yes)
  • [x] And what's the latest released version? 0.0.15 (only SDK, the app was not released)
• [x] Existing Project Documentation ( URL / microsite / PDF etc detail here)
  • [x] https://github.com/discoverfinancial/a11y-theme-builder/wiki
  • [x] https://discoverfinancial.github.io/a11y-theme-builder/
• [x] Does the name have a registered trademark? (no)
• [x] Is there a logo? (yes)
• [x] High-Level Presentation prepared for Technical Steering Committee (~15 mins)
• [x] Are meetings currently held for the project? (yes + details)
  • https://github.com/discoverfinancial/a11y-theme-builder/wiki/Communication#meetings
• [x] Are meeting minutes, agenda and attendance tracked? (yes + details)
  • https://github.com/discoverfinancial/a11y-theme-builder/wiki/Meeting-Minutes

Development Team

List of Maintainers and Contributors

Maintainers

• Reference Maintainers in the project wiki
• @codyzus (Nearform)
• @paulapaul (Nearform)

Confirmed contributors

Reference Contributors in the project wiki

Target Contributors

We are actively working to bring in additional collaborators starting with the participants from the GAAD Hackathon. The initial aim is to incorporate the Hackathon projects and extensions upstream into FINOS Labs.

In general we aim to bring together a broader community of contributors that include the various roles within the Design lifecycle. This would include developers who are responsible for devlopment of web and mobile front ends, as well as designers.

Pending questions

• [x] Name is requested to be "ThemeBuilder & ThemeBuilderSDK", so without the term "Accessibility" ? Please confirm
  • Accessibility Theme Builder & Accessibility Theme Builder SDK
• [x] I see that the SDK is released, but the app is not, please confirm. Any plans to also release the app on npmjs.com ? Any issue adding @finos as scope in both package.json files
  • The release of the App doesn’t make sense to be distributed as a module (Library) in NPM.
  • There is no issue with adding @finos as the scope.
• [x] Isn't https://github.com/discoverfinancial/a11y-theme-builder/wiki duplicative of https://discoverfinancial.github.io/a11y-theme-builder/ ? Would be easier (to manage and consume) to have only 1 web property for docs
  • The Wiki contains the project, plan, meeting minutes etc.
  • The site is primarily focused on product documentation for end users/contributors.
• [x] Please provide SVG version of the logo
• [x] Are current meetings open to the community? If not, would you be interested to? This may be a post-contribution effort, to ensure we can close the contribution by September
  • Yes, all meetings are public and documented in the wiki
• [x] Choose new domain name for website, ie a11y-theme-builder.finos.org ; after the deployment, existing URL should point to the finos one, see https://gist.github.com/domenic/1f286d415559b56d725bee51a62c24a7
  • That’s fine, as a FINOS project we are happy to follow and redirect to the format suggested.
• [x] Grant finos-admin ability to transfer the 2 repositories (or ask to transfer repos to finos-admin user
  • Can you transfer the repo?
• [x] The app contains quite some transitive dependencies, defined on code/src/ui/package.json and code/package.json ; would be great to try moving as many libraries as possible to devDependencies, in order to lower the (security and license) scanning surface; hopefully the Discover team can help there
  • We’re happy to work with you on managing the surface area, there may be some areas where we can improve.
• [x] Would you like a FINOS slack channel and/or mailing list? We suggest in the beginning to keep things on GitHub as much as possible and we can create these later if/when needed, but we can also do it now.
  • We would prefer to instantiate slack and mailing list up front.

Project Communication Channel(s)

• [x] Contributor to ask maintainers which communications channels they'd like to use:
  • Slack + Zoom
• Asynchronous
  • [x] GitHub Issues (public)
  • [x] GitHub Discussions (public)
  • [ ] FINOS Slack Channel (consisting of the above described contributors) (After OSFF)
• Synchronous
  • [ ] Recurring meetings (After OSFF)

Understanding FINOS Onboarding Requirements

As a project onboarding into FINOS, you will need to familiarize yourself and your contributor team with the following materials:

• FINOS overview (if necessary)
• FINOS Maintainers cheatsheet
• FINOS Project/Standards Governance
• FINOS Project Lifecycle

Record The Contribution (FINOS Infra)

• [x] (optional) Identify and Assign FINOS Strategic Advisor
• [x] Submit contribution to LF by opening a ticket via https://jira.linuxfoundation.org/browse/SS and marking contribution as "Exploratory"; attach a summary of the Business Problem and Proposed Solution (above) of the project.

2. Approval

The FINOS Technical Steering Committee (TSC) is responsible for approving FINOS project contributions; feel free to check their contribution principles.

If needed, the TSC will request a follow up either via GitHub Issue comments or by inviting project leads to one of their recurrent meetings.

Tasks (for FINOS Infra/TSC)

• [x] Prioritise this issue on the TSC Backlog
• [x] Assign this issue to @colineberhardt
• [x] Add the ready-for-tsc label
• [x] TSC to invite contributors to present their project
• [x] FINOS TSC approves/rejects the contribution
• [x] Ask @jgavronsky to mark contribution as "Engaged" within LF systems
• [x] Update the contribution status to "Engaged" by sending another email to LF Legal Representative with the name of the project and its new status.

TSC Findings / Report

TSC to enter findings summary here.

3. Preparing For Onboarding

Before the FINOS team can onboard your project, there are a few housekeeping items that need to be taken care of. These must be completed by the contributor, with help (if required) from the FINOS Infra.

Kick-off meeting

• [x] Set up kick-off meeting with project leads
• [x] Run kick-off meeting
  • [x] Walk through the checklist in part 1, ensure all the questions are answered and remove items that don't apply
  • [x] Write and send contribution proposal announcement (optional - see below)

Logo / Trademarks

• [x] Sign the project contribution agreement to allow FINOS to act on behalf of the contributor for accounts related to the project (e.g., GitHub, domain names, social media) and to optionally manage trademark assignment
• [x] https://github.com/discoverfinancial/a11y-theme-builder/blob/main/code/src/ui/public/tb-logo.svg
• [x] The codebase doesn’t include any patent or copyright that conflicts with FINOS Governance and bylaws. (Infra team to validate with FINOS Legal team if anything important is raised)

FINOS Project Blueprint

• [x] Discover transfers repositories to finos-admin
• [x] Apply project blueprint contents - see ODP docs
  • https://github.com/discoverfinancial/a11y-theme-builder-sdk/pull/89
  • https://github.com/discoverfinancial/a11y-theme-builder/pull/478
  • [x] README.md file contains the sections in the README Template
  • [x] Project FINOS badge in README (incubating)
  • [ ] OpenSSF Passing Badge (Optional)
  • [x] License in README
  • [x] Contributing in README
  • [x] CONTRIBUTING.md
  • [x] LICENSE (replace {} placeholders)
  • [x] Ensure that the proper project governance is in the CONTRIBUTING.md file
• [x] All incubating criteria are checked and documented below

Add documentation here

4. FINOS Onboarding

This is performed by FINOS Infra once the three previous stages are complete, with support from the contributor and the FINOS Infra team.

Maintainers, Contributors and CLAs

• [x] Identify other existing contributors (assuming there's a contribution history (eg Git history)
• [x] Check if maintainers and other contributors are all covered by FINOS CLA
• [x] Engage with FINOS Legal team to figure out what’s needed to cover all maintainers and contributors with FINOS CLA
• [x] Reach out to contributors and employers to coordinate CLA signatures
• [x] Invite GitHub usernames to GitHub FINOS Org
• [x] Create <project-name>-maintainers GitHub team and invite users

Validation (only if code is contributed)

• [x] Check GitHub repository transfer requirements:
  • [x] finos-admin has Admin to all repositories to transfer
  • [x] finos-admin ia allowed to transfer repositories out of the org
• [x] The codebase doesn’t have HIGH or CRITICAL CVEs across direct and transitive libraries
  • [x] The SDK only depends on the latest version of chroma-js , which is a zero-dependency library. There are no CVEs, therefore security scanning will most likely pass; regardless, it's probably good to contribute a GitHub Action to enable continuous scanning; take it from traderx
  • [x] App (CVE's found https://github.com/TheJuanAndOnly99/a11y-theme-builder/actions/runs/6174576156/job/16759478134#step:6:48)
• [x] The codebase doesn’t have any unfriendly licenses across direct and transitive libraries
  • [x] The SDK only depends on the latest version of chroma-js , which is released under BSD 3-Clause, so we're good here
  • [x] App https://github.com/TheJuanAndOnly99/a11y-theme-builder/actions/runs/6174576171
• [x] The codebase doesn’t include any patent or copyright that conflicts with FINOS Governance and bylaws (to be validated with FINOS Legal team)
• [x] All incubating criteria are met (review documentation provided above)

Code transfer

• [x] Transfer all code assets as GitHub repositories under github.com/finos
• [x] Rename main branch to main (instead of master)
• [x] Configure finos-admins (Maintain role) and finos-staff (Triage role) team permissions

Project Communication Channel(s)

• [ ] Link communication channels linked front-and-center in the project README.md

Repository setup

• [x] Enable EasyCLA
• [x] Add project to metadata
• [x] Add logo to FINOS landscape
  • [x] Create staging branch on finos/finos-landscape
  • [x] Merge finos/metadata changes on master (will udpdate landscape.yml in finos/finos-landscape)
  • [x] Create PR from staging branch on finos/finos-landscape
  • [x] Review Netlify preview
  • [x] Merge PR
• [x] Add project maintainers emails to finos-project-maintainers@finos.org list
• [x] Add project maintainers GitHub usernames to the project-maintainers Team
• [x] Ask @jgavronsky to mark contribution as "Active" within LF systems
• [ ] (best effort) Update release coordinates and code namespace to include finos
• [x] Check that CVE (and preferably static code analysis, if applicable) scanning is in place
• [x] Enable automated dependency update, using Renovate
• [x] Enable branch protection (Require a pull request before merging)

5. Announcement

(Lead: Project Lead and FINOS Infra team)

• [x] Update the contribution status to "Active" by sending another email to LF Legal Representative with the name of the project and its new status.
• [x] Lead maintainer works with FINOS marketing to send out announcement to announce@finos.org , checkout announcement template at the Contribution page
• [x] Notify FINOS marketing (@grizzwolf + finos-marketing internal Slack channel)

[TheJuanAndOnly99]

Thanks for your contribution @andybs ! We'll get back to you as soon as we can with next steps.

[ColinEberhardt]

Thanks @andybs looks like an interesting contribution. I've got a couple of questions ...

1. The documentation does a good job of describing the challenge you're addressing and the conceptual aspects of your solution. However, I'm struggling to find the more technical / specific aspects of your solutions. What exactly does it produce? React components? CSS? A design system landing page? The opening paragraph of your overview describes the output as 'machine readable asset types' - I'm not really sure what that means!
2. Are there aspects of this project that are financial services specific? While this isn't a pre-requisite for inclusion into FINOS, the project does need to generate sufficient interest from members. Tackling financial services problems is a good way to generate this interest.

Anyhow, this does look like a project with potential, and isn't something FINOS currently has within their landscape.

[andybs]

@ColinEberhardt Thank you for the feedback.

The documentation does a good job of describing the challenge you're addressing and the conceptual aspects of your solution. However, I'm struggling to find the more technical / specific aspects of your solutions. What exactly does it produce? React components? CSS? A design system landing page? The opening paragraph of your overview describes the output as 'machine readable asset types' - I'm not really sure what that means!

Theme Builder is an early implementation that includes two repositories

• Theme Builder: Front end for defining your atomic language and selection of design characteristics with previews that incorporate calculations based on Accessibility characteristics. For additional details see User Interface Overview
• Theme Builder SDK: Used by the ThemeBuilder but can also be incorporated into other tools and frameworks to support configuration and expression with Accessibility in mind. For additional information see the SDK Overview

Theme Builder aspires to be an extensible library can that will be able to support expression of the design across different models. Today this supports two models:

• Design Tokens (JSON) that can be imported into design tools such as Figma.
• CSS which maps to MUI which can be directly imported into existing frameworks (e.g. React)

Are there aspects of this project that are financial services specific? While this isn't a pre-requisite for inclusion into FINOS, the project does need to generate sufficient interest from members. Tackling financial services problems is a good way to generate this interest.

Accessibility is a requirement for all Financial Industry digital experiences. Here's a reference ADA Requirements for Banks

We hosted the GAAD Hackathon as partners with FINOS and other members to promote the need for improved tooling. Through this initiative we have garnered interest with existing and former members of FINOS who are interested in continuing to collaborate around the project at large.

We also have a number of the FINOS GAAD Hackathon winning integrations and extensions that we would like to work with the community to contribute to the existing code base within FINOS Labs. We're also continuing to work with the community to grow contributors through existing and potential members to FINOS as well as the extended community. One of which will be hosting at the Grace Hopper OSD highlighting accessibility and mentoring new contributors to grow the community.

If there are more detailed questions, I'd be happy to pull the team together for a quick call to discuss.

[mcleo-d]

Hey @ColinEberhardt - I have added this contribution to the TSC backlog. Can you please provide the Discover team with a date and time where they can discuss potential contribution approval with the TSC members.

[ColinEberhardt]

No problem @mcleo-d - can you please add the 'ready-for-tsc' label too

[ColinEberhardt]

@brunodom is looking at this contribution on behalf of the TSC

[brunodom]

On behalf of the TOC and after evaluating this contribution against our approval principles (as outlined in this e-mail thread), I am glad to approve the contribution!

[maoo]

Announcement sent, see https://groups.google.com/a/finos.org/g/announce/c/M-xC48AMZak/m/c9ptKnfCBAAJ

The contribution process is completed; there are few leftovers (see https://github.com/finos/a11y-theme-builder/issues) that are in progress but not blockers.

Congratulations to the Discover team, and thanks for contributing the Accessibility Theme Builder to FINOS!