Unified home is a single page application that delivers a dynamic landing page for any application on Unified Shell. Unified Home uses the Quarry dashboard framework, leveraging widgets that can be contributed by any application team. Examples of applications implementing their home experience through unified home include Experience Cloud home (/home) and Journey Optimizer home (/journey-optimizer/home). The internal name for Unified Home is Pueblo, which is how it is referred to in this document.

A Pueblo widget is a UI component that is delivered by the Pueblo application for any home experience. It provides value to the end user by ensuring that their landing experience is relevant and efficient, such as by providing faster ways to jump into work, the ability to view recent activity, or learn content from Experience League. A pueblo widget should fit into the quarry dashboard framework, meaning that it should be wrapped in a quarry dashboard widget and should adhere to the spectrum design guidelines for widgets.

A good home experience can transform how a customer uses your product. It can help a user to jump back into their work where they left off, figure out where to start when they receive access to a new product, or learn about upcoming adobe events and promotions. REFERENCE THE UNIFIED HOME TECH TALK AND POWERPOINT.

The recommended approach to widget creation is to contribute your widget to the shared pueblo-widgets package in quarry. Contributing a widget to @quarry-connected gives your widget DXUE visibility and means that the widget can be used by both unified home and any other application that may need it.

• https://git.corp.adobe.com/exc/pueblo - Contains the code for the home application which runs at multiple routes (/home, /journey-optimizer/home). Pueblo is built on the quarry dashboard framework and imports widgets from multiple places including @quarry-connected/pueblo-widgets.
• https://git.corp.adobe.com/frontend/quarry - Quarry contains the dashboard framework leveraged in pueblo and the package where new widgets should be contributed.

1. Join the #pueblo Slack channel.
2. Clone the pueblo repository and fork the quarry repository.
3. Setup your local dev by following the steps for each repo. Instructions for pueblo are here and instructions for quarry are here.

New widgets that will be used by pueblo should live in @quarry-connected as part of the pueblo-widgets folder.

To speed up the development process in @quarry-connected, we've included a script to generate the minimum files required for a new widget in the pueblo-widgets package.

cd packages/@quarry-connected/pueblo-widgets
yarn generate

The script will create new files for your widget in the src, tests, stories, and docs folders.

Quarry-connected uses a storybook running within shell as its local environment. To test your widget in pueblo, simply yarn link the quarry connected package to the pueblo repo and run it locally.

Discuss deploying!!!

• File a JIRA ticket in the <JIRA Project> setting <components>, <domain> and a detailed description of the task with relevant epic links and documentation links. If it is a bug, clearly outline the steps to reproduce it.
• All code changes should:
  • Adhere to our lint by running yarn lint.
  • Be accessible (meets all WCAG 2.1 standards)
  • Be internationalized (localized into all languages that Pueblo and Unified Shell support).
  • Support both light and dark themes, as switched from the profile menu in the Unified Shell.
  • Include 90% test coverage.
  • Use @adobe/exc-app to log metrics to EIM including error information.
  • Include a storybook entry for each variation of the widget.
  • Include appropriate documentation updates.
• Once you have created a new widget or made a change that adheres to these code standards, issue a pull request for your changes. Make sure the pull request title matches the "JIRA-ID: Jira issue title."
• Code reviewers will be automatically assigned to your PR. You are encouraged to tag any additional repository maintainers via the github @name notification mechanism.

The pueblo team (@symanovi @doten) are the codeowners of the pueblo-widgets package in quarry and therefore an approving review is required before any code can be merged. That being said, a member from your scrum team should always review and approve the pull request first.

Once you have added a new widget, you should edit the codeowners document in quarry with the path to your component, i.e. /packages/@quarry-connected/pueblo-widgets/my-widget @team-for-my-widget

As a contributor, it is your responsibility to add new tests for your feature. Test coverage for the pueblo-widgets component in quarry should not dip below 90%.

Integration tests for pueblo are written in cypress and leverage spa-pipeline's automation framework. The tests live in the pueblo repo and test the home pages and widgets of applications running on pueblo. Once your widget has been committed to quarry, published, and imported into pueblo for use on a home page, it is up to you to write integration tests that test the widget.

Widgets should be built in a way that optimizes performance and avoids a cumulative layout shift on load. If your widget needs to make network calls, build the widget in such a way that it will not block the page load (i.e. ghost loading or add a spinner/loading state to the widget). If your widget needs to block page load entirely (e.g. the widget conditionally shows based on a network call) discuss with the #pueblo team what the best options are.

Synthetic checks in New Relic monitor the health of this service. When your application goes live on pueblo, you should work with a #pueblo team member to ensure that scripts are added to New Relic to monitor the availability of your widgets and home page.

PR reviews and test automation are expected to catch most of the issues with your change. However, by experience, we know that every new change will bring potential instability to the service. The unified shell team will be on-call for pueblo it is possible the on-call engineers may not be fully aware of your change. In case of a production issue or a CSO, contributors agree to support the on-call engineers when the problem is likely related to their change.

Documentation should be added to the docs folder for any new widget or widget modification. If you use the generate script, a mdx file for you to modify will automatically be created for your component.

If you need help, please ask your question in the #pueblo slack channel or reach out to the code owners yourself. If your question is better asked in person, please join the Unified Shell office hours on Thursdays at 9AM PST. Reach out in #unified-shell if you need to be invited to the meeting.

This is a live document. Suggestions, improvements to the guidelines, processes outlined here are always welcome! Please issue a pull requests to make changes to this document.