ssagov / genesys

A prototyping toolkit using Visual Studio Code aimed at designers. Only HTML knowledge required.

⚝ Genesys

Design in the Browser Prototyping

Genesys Website: https://ssagov.github.io/genesys/

Genesys provides a simple way to make rich, accessible, interactive prototypes using a declarative language (HTML). It enables designers and UI developers to quickly create a low to high-fidelity prototypes, or even production-ready user interfaces.

Genesys provides support for most major design systems like Bootstrap, Material Design, Foundation, Ionic, Tailwind, Tachyons, et. al.) and you can add any others.

Additional features include multi-lingual support, automated walk-throughs, on-screen comments, A/B testing, conditional logic, animation, and more, all through markup.

Note that Genesys allows you to create and test fully accessible, Section 508-compliant prototypes.

Demo

• Genesys Demo

Requirements

• Microsoft Visual Studio Code
• Genesys Extension for Visual Studio Code
• Design in the Browser Extension for Visual Studio Code
• Any modern browser (Chrome, Edge, Safari, etc.)

Getting Started

1. Download the latest Genesys archive package from this repository. Select that big green button labelled Code above, then select Download ZIP. Finally, extract the Zip file contents wherever you want.
2. Start Visual Studio Code and select File > Open Folder... and then select Genesys from the location you extracted it to.
3. In VSCode, select the Extensions panel, search for and install the Genesys extension and the Design in the Browser extension from the Microsoft Extensions Marketplace.
4. Optional: Download and install Git in order to enable version control.

Once you have everything installed, you're ready to go. Start with our tutorials.

Tutorials

• Getting Started
  • Creating Your First Prototype
  • Using the Genesys Toolbar
  • Adding Tables Quickly
  • Adding Notes & Walkthroughs
  • Design Tips when using VSCode
• Flow Diagrams
  • Create a Flow Diagram
• Static Wireframes
  • Create a Static Wireframe
• Interactive Prototyping
  • Create a Click-Thru Prototype
  • Add Data Persistence
  • Add Conditional Logic
  • Add User Roles
• Multi-Lingual Prototyping
  • Adding Multiple Languages
• Collaboration & Version Control
  • Using Version Control
• Prototyping with UEF
  • Using UEF Snippets
  • Adding Sub-Navigation
• Advanced Topics
  • Adding Analytics
  • Adding Animation
  • Adding Realistic Data
  • Creating Prototype Walkthroughs
  • Creating a Site Map
  • Measuring Perceived Usability
  • Publishing Prototypes
  • Recording User Test Sessions
  • Starting with an Existing Page
  • Using Master Page Components
  • Using Virtual Pages

Features

Built-in Design Systems
Including Material Design, Bootstrap, Microsoft Fluent, U.S Web Design Standards, Salesforce Lightning, and more. Add your own as well.

Accessibility Checking
Integrated accessibilty checking of your prototypes through ANDI and Lighthouse.

Real-Time Collaboration
Integrated Kanban board, whiteboard and application sharing through LiveShare.

Single Source of Truth
No more approximations of designs. Prototypes are 100% accurate and responsive, since they are built in the browser.

Version Control
Explore and version designs with the integrated industry-standard Git version control system. View a visual history of design changes.

Annotations & Walkthroughs
Easily add and view designer comments or fully automated design walkthroughs right in your prototypes.

Roles, States and Conditional Logic
Multiple user roles, use cases, and conditional logic within a single prototype.

Multi-Lingual
Switch between multiple language designs within the same prototype.

Quick Mockups
Integrated drag & drop mockups with the embedded Draw.io application and prototyping stencils. (SVG Mode)

Master Page Components
Define UI components once and reuse them on multiple pages as Master Page Components.

Variables & Data Persistence
Easily pass user entered data from page to page.

Charting & Diagramming
Create sustainable charts, diagrams, and user flows with integrated Mermaid support.

Animation
Add animation to any element with predefined keywords.

A/B Testing
Easily add simple A/B testing on page content, components, or entire page designs, right within a single prototype.

UX Analytics
Built-in support for collecting UX-specific analytics via Google Analytics and the AutoTrack plugin

Realistic Data
Rapidly create realistic, fake data specific in your designs with the integrated Faker extension.

UX Measurements
Integrated support for industry standard SEQ, SUS, and TLX feedback.

Design Systems Support

Genesys provides built-in support for the following design systems and frameworks for building prototypes:

• Atlassian Design
• Basscss
• Bootstrap 3/4/5
• Bulma
• Foundation
• Ionic UI
• Material Design
• Material Design Lite
• Materialize
• Microsoft Fabric
• PaperCSS
• Semantic UI
• Tachyons
• Tailwind
• Turret
• User Experience Framework
• UI Kit
• U.S. Web Design Standards

Additionally, Genesys contains built-in support for WebSlides and Reveal.js for creating web-based presentations.

Contributing

Feel free to contribute to this project by suggesting a new feature or modification, or to discuss issues.

• Open an issue for any features, modifications, or issues you want to bring up.
• Have a look at the contributing guidelines before submitting a pull request (PR).

Maintainer

• Craig Cecil

Acknowlegements

Thanks to the following people and projects for producing the great open-source software that powers much of Genesys:

• Lea Verou (Mavo.js)
• Afshin Mehrabani (Intro.js)
• Andi Kent (PolyPage.js)
• John Cotter (ANDI)

License

This project uses the Apache 2.0 license.

genesys's Issues

Update Reveal.js to 4.2.0

Integrate HyperScript

Integrate the open-source HyperScript library into Genesys, allowing flexible, markup-based logic and interactivity.

https://hyperscript.org/

Add Ability to Toggle Thru Multiple Designs on Single Page

Add the ability to toggle thru multiple designs of a UI element or entire page by selecting a surfaced design toggle.

Build on the simple concept described here: https://css-tricks.com/body-toggle/

The last item in the design toggle (dropdown? popup? design number?) could be an option to show all designs at the same time.

Add an item to the Genesys Toolbar to show/hide clickable alternative design indicators.

Add Link Checker to Genesys Toolbar

Checks all links on current page.

Use https://github.com/WickyNilliams/LinkChecker

Add Virtual Keyboard

Integrate a virtual keyboard into the Genesys toolbar. This will allow the prototype page to display a virtual keyboard that appears from the bottom of the page and allows the designer to more accurately see how a virtual keyboard will affect a page design.

https://github.com/hodgef/simple-keyboard

Add 'Design Tips when using VS Code' tutorial

Add a tutorial for design tips when using VS Code, including:

• Using the Problems tab to find and fix issues
• Squiggly yellow line: What does it mean?

Add Eye Tracking Functionality

Add a Genesys toolbar toggle to turn eye tracking on/off.

The Eye Tracking functionality can be supplied via the Brown University's open-source WebGazer.js module.

Will need to add eye tracking data storage and playback controls.

Add Visual Page Design and Figma Import

Consider adding visual page design and Figma import capabilities via the Builder.io extension for VS Code.

https://marketplace.visualstudio.com/items?itemName=Builder.Builder

Add Background Toggle

When HTML elements don’t have backgrounds, it can be difficult to visualize their bounds and/or accurately measure the distance between them and other elements. Developers might want to better visualize bounds when dealing with optical imbalance (i.e. when something “looks off” even though it’s not), margin collapse (when certain margins are ignored), various issues with display:/float:/position:, and more.

Applying backgrounds means applying a semi-transparent background to all HTML elements in order to better visualize their bounds and spacings.

See https://css-tricks.com/web-development-bookmarklets/#applying-a-background-to-everything for more info.

Add Help to Genesys Toolbar

Add a Help icon to the Genesys toolbar, which when selected displays the Tutorials index from the repo in a new browser window/tab.

Add Color Picker to Toolbar

See https://css-tricks.com/web-development-bookmarklets/#color-widget-bookmark for more info.

Update Annotations (Comments) Design

Use a slide-out panel to show notations, each linked to their respective element.

Add USWDS intelligence to 'Generate Specifications'

Remove the 'Generate Specifications' functionality and toolbar button, since:

• This functionality is incomplete, only supports the UEF design system, and is generally not used

Update Genesys Toolbar to use Absolute Sizing Units

Currently, the toolbar uses relative sizing of the overall toolbar height and relative sizing on icons and text, based on the page it is used on. This needs to be changed to absolute units for optimal display and UX.

Add Markdown Support

Add the ability to author content using Markdown within prototypes, using either the Web Component (https://md-block.verou.me/) or the Markdown-Tag library (https://github.com/MarketingPipeline/Markdown-Tag).

Add Content to Tutorial for 'Click-Through Prototype'

Add content to https://github.com/SSAgov/genesys/blob/main/tutorials/04-Interactive-Prototyping/01-Create-a-Click-Thru-Prototype.md

This should show how to quickly prototype an application flow.

Add Plugin System

Refactor genesys.js so that it supports a robust plugin system for extensibility.

Add 'Powered by Genesys' Footer

Update the footer to all Genesys-built web pages so that it says 'Powered by Genesys' with links to the GitHub repo and a link for Feedback.

Update Mermaid.js

Update the Mermaid.js library to the latest version. This may clear up the two console errors that appear due to this library.

Update Inspector Code

Update the Inspector code to reflect the standalone version's functionality.

Add Built-in Markdown Viewer/Editor

Add a built-in Markdown viewer/editor (using a best-in-class open-source component) to the Genesys Toolbar.

This toolbar button should open a dialog that allows the designer to view two specific Markdown files for the current prototype page:

• Given a page name of pagename.html

The designer can create two specifically-named Markdown files:

• pagename-notes.md (for designer/developer notes)
• pagename-feedback.md (for reviewer feedback)

These two files can be viewed/edited via a toggle in the Markdown dialog that opens from the Genesys Toolbar button.

Add Fullscreen Toggle

Might be useful to add a fullscreen toggle to the Genesys toolbar.

See https://blog.bitsrc.io/building-fullscreen-web-apps-dfc2286b7049

Add New Tutorial for 'Iterative Page Prototyping'

Describe and show how to iterate on a single page of a prototype, going from pure text and placeholder content to a fleshed-out layout prototype. Include how to create button clicks to navigate pages and how to create dynamic forms.

Add Presentation Cursor

Add a Genesys toolbar toggle to show/hide a cursor outline/sun effect when presenting prototypes to reviewers. This will make the cursor much easier to follow.

Add Ninja Keys (Keyboard Shortcuts interface)

For those designers who don't want to display the Genesys toolbar, add the Ninja Keys keyboard shortcuts interface. This essentially cleans the UI of the prototyped page to only the design that the designer created. Pressing CTRL+K will bring up the shortcut interface to allow access to Genesys functionality, such as switching to Low-Fidelity, Checking Accessibility, etc.

https://ninja-keys-demo.vercel.app/

Improved README for Novice/First-Time Users

Be much more specific in all instructions (e.g., "to download, select the green Code button near the top of the page")

Be more explicit in the ordering of the README contents and instructions.

Add a link to the Tutorials index in the repo for direct access to this info.

Update Design Tips

Update design tips (https://github.com/SSAgov/genesys/blob/main/tutorials/01-Getting-Started/05-Design-Tips-for-VSCode.md) to include:

• Adding unknown words to your VS Code dictionary
• Using the Problems view
• Indicators that something is wrong (yellow squiggly underlines, red text, etc.)

Add Dyslexia Mode to Genesys Toolbar

Integrate the Page Tools bookmarklet into the Genesys Toolbar. Don't forget to include the new Dyslexia Simulator within Page Tools.

Enhance UIScript Functionality

Replace the existing UILang, with the following UIScript fork which contains support for more events and actions:

https://github.com/teletrade/uiscript

Fix DevTools Errors

Fix all JS errors flagged by DevTools.

Add New 'Create Simple UEF Page' tutorial

This should be a very small page tutorial, intended to get the user's feet wet with Genesys.

May also want to include a screencast of this tutorial being completed.

Refactor Genesys Toolbar Menu for Improved Accessibility

Use the role="menu" and role="menuitem" ARIA attributes for better Genesys Toolbar accessibility.

Add User Session Recording & Replay

Integrate the open-source rrweb (https://github.com/rrweb-io/rrweb) to add this functionality. Extend the Genesys toolbar with appropriate icons for this.

Add Boilerplate Configurations Page

Single browser page where the designer picks they options they want (Design System, A/B Testing, Analytics, UX Measurements) and then we write out the starting HTML page boilerplate, which they can then copy and paste.

Update Gremlins.js

Update the included Gremlins.js auto-testing library to the latest version.

https://github.com/marmelab/gremlins.js/

Update Intro.js to version 4.0

https://github.com/usablica/intro.js/releases/tag/v4.0.0

Add UI Lang Library, Docs, Demo, Tutorial

The open-source uilang library provides the ability to use English-like syntax for interactive behaviors.

Here's an example of a uilang statement:

clicking on ".try-it" toggles class "hidden" on ".info-box"

This will allow designers to quickly add interactivity to prototypes without the need for writing JavaScript code.

http://uilang.com/

Add this functionality to the /demo, /docs, and /tutorials

Host the library within the /components/interaction/uilang directory.

Add Contributors Info

Add a list of contributors (people, open source repos) that helped form Genesys, with links to each.

Add GitHub Pages Content

Add GitHub Pages content for this project. Use the existing standalone website content for this, making it public.

Update Intro.js to version 4.3

Add New Tutorial for 'Adding Interaction with Natural Language'

This tutorial will describe how to use UIScript within Genesys.

Examples to show include:

• Hooking up button interactions
• Displaying different content based on Radio Button selection

Note that this issue is dependent on #41

Create UEF Modals Tutorial

https://github.com/SSAgov/genesys/tree/main/tutorials/07-Prototyping-with-UEF

Explain where to place the modal code, and how to display the modal.

Add Toolbar button for toggling designMode

Also, show a ‘Edit Mode’ notification on the page to signify to the user that they can directly edit the page.

Add Mavo Source Map Files

Add the two Mavo source map files. This will remove the two DevTools warnings related to this.

Fix XRay Component

Update the XRay code to use HTTPS.

Update Genesys Logo in Toolbar & Docs

Update the Genesys logo used in the toolbar and documentation to match the logo in the README file.

Update 'Adding Interactions with Natural Language' Information

Add the reference to the snippet and code to link to the uilang.js library.

Refactor Functions for Readability

Use the RORO pattern for this: https://www.tinyblog.dev/blog/2020-07-13-javascript-roro-pattern/