diff --git a/packages/site-demo/content/menu.yml b/packages/site-demo/content/menu.yml index dbb701a0be..112403731b 100644 --- a/packages/site-demo/content/menu.yml +++ b/packages/site-demo/content/menu.yml @@ -24,4 +24,6 @@ - Size - Spacing - Brand -- Partners +- Partners: + - Extensions: + - Design Documentation diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/Search.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/Search.png new file mode 100644 index 0000000000..6fd48f7fb1 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/Search.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/birthdays.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/birthdays.png new file mode 100644 index 0000000000..a2ae6f1059 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/birthdays.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/comment.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/comment.png new file mode 100644 index 0000000000..daac2de5e8 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/comment.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/contact-form.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/contact-form.png new file mode 100644 index 0000000000..3fca0c24e1 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/contact-form.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/dialog.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/dialog.png new file mode 100644 index 0000000000..df5d3f2413 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/dialog.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/display-image-widget.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/display-image-widget.png new file mode 100644 index 0000000000..621e4f00f4 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/display-image-widget.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/example-steps.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/example-steps.png new file mode 100644 index 0000000000..33590ab431 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/example-steps.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/form.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/form.png new file mode 100644 index 0000000000..9194eeded2 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/form.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/layout.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/layout.png new file mode 100644 index 0000000000..414679c32b Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/layout.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/progress.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/progress.png new file mode 100644 index 0000000000..4a15fb87d1 Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/progress.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/survey.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/survey.png new file mode 100644 index 0000000000..43df542cdb Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/survey.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/assets/widget.png b/packages/site-demo/content/partners/extensions/design-documentation/assets/widget.png new file mode 100644 index 0000000000..0bcf9110ea Binary files /dev/null and b/packages/site-demo/content/partners/extensions/design-documentation/assets/widget.png differ diff --git a/packages/site-demo/content/partners/extensions/design-documentation/index.mdx b/packages/site-demo/content/partners/extensions/design-documentation/index.mdx new file mode 100644 index 0000000000..c168e610a7 --- /dev/null +++ b/packages/site-demo/content/partners/extensions/design-documentation/index.mdx @@ -0,0 +1,317 @@ +# Extension publisher’s design documentation + +**The Extension publisher’s design documentation is a guide designed to help partners create their own extensions. Its goal is to assist designers, developers, and project managers in building extensions that perfectly fit into the LumApps environment.** + +**This documentation contains the best practices for creating extensions, with examples. It also contains instructions on how to use the LumApps Design System.** + +## Introduction + +### Lumapps layout + +A LumApps platform is composed of one or more sites. A site is made up of different elements including pieces of content which are built with widgets, cells and rows. + + + +In LumApps, a piece of content relies on a web-grid format. This grid is created with both rows and cells that are customizable by end-users: they can change the spacing, the borders, the background, etc. There is no limitation on the number of rows.  + +A maximum of four cells can be added into a row. A LumApps page can be composed of an infinite number of rows. Cells populate rows. A maximum of four cells can be added into a row. + +Read the [documentation](https://docs.lumapps.com/docs/support-l7827412063137893) to learn more about the LumApps layout and widgets behavior. + +### Widgets + +Widgets are elements displaying specific information within a piece of content. They are added inside cells. The widget width depends on the width of the cell containing the widget. A cell can contain multiple widgets. + +A widget has three parts: a header, a body and a footer. + + + +The header and footer are optional. The header can be used to display a title and an icon. The footer can be used to display a link and an icon. The body contains the core of the widget such as information and interactive items. + +Widgets also have styles that define the color, typography, spacing, etc. There is a default widget style, but a widget can also have a custom style. This custom style can be reused.   + +## Building a user experience + +The aim of this section is to help you understand how to design the user experience and the user interface of your extension project. + +### Defining user needs + +The first thing to consider before creating your extension is to make sure you understand the user needs. It is important to design an experience that is going to be useful.  + +Answer the following questions to understand your users and discover their needs: +- Who will use the widget? +- Why would they use it?  +- When will they use it? +- Where will they use it? + +From those answers, you can shape personas. Personas are fictional characters that represent the different user types who might use your extension. By reviewing your persona’s goals and needs, you can determine what the use cases of the extension are. Make an exhaustive list of all possible use cases, then define which ones have the highest values for the users. + +Decide what needs to be displayed in the widget body based on the main use cases. + +
+ Best Practice +

+ In your list of personas, don't forget the contributor. Those users are important because they pick and configure widgets in pieces of content and templates. +

+
+ +### Create a user flow + +User flows are diagrams that display the complete path users take when using a feature. The user flow maps out every step, human and machine interactions, from the entry point to the final interaction. + +[Miro](https://miro.com/) is an example of a helpful tool that helps shape a user flow. + +#### Steps + +Creating a user flow requires you to first imagine how the main use case is addressed by the extension. Split the path into the different steps users need to perform to complete the use case. +Quick and easy processes always deliver a better user experience. You may have to try different paths to find the best possible solution. + +
+
+ Example +

For a survey widget, users have to go through four different steps:

+
    +
  1. Read information to get context,
    2. +
  2. Pick a choice amongst different propositions,
    3. +
  3. Submit their choice,
    4. +
  4. Receive a confirmation that their choice has been taken into account.
    5. +
+
+ +
+ +#### Interactions + +For each step, imagine what interactions users could perform and think of all the information that needs to be displayed. + +Interactions can go from the users to the system and from the system to the users. + +- **User input** is requested by the system to address the use case. You can now imagine how users will interact with their interface to give information. + +
+
+ Example +

+ A registration form asks the user to provide a way to contact them. The user must select a contact method amongst a list of choices (phone, email, chat…). The user then needs to type in their personal information. +

+
+ +
+ +- **System tasks** can be triggered by the user. Imagine how the users will interact with the system and describe how the system will respond. + +
+
+ Example +

+ A widget displays images. When creating content, the contributor can choose between three different previews: landscape, portrait, and square. The user must define their preference in the widget settings. +

+
+ +
+ +#### Information + +The system can display information to the user such as media or text, in a more or less structured way. + +
+
+ Example +

A widget shows a list of users having their birthday today.

+
+ +
+ +As you need to cover all the main use cases, you should have detailed user flows which give you a good overview of how users will use your extension. + +**“But how to deliver a great user experience?”** + +As you create your widget's user experience, you might be wondering how to optimize it for the best user experience. + +- Re-read carefully the list of user needs and make sure they are fully addressed.  + +- Put yourself in your user’s shoes. Associate the personas with user flows and ask yourself if the user will have any issues.  + +- Try to optimize the flow by getting rid of unnecessary steps and interactions.  + +### User Interface components + +LumApps has its own design system, it provides UI components that can be used by extension publishers. Design consistency improves the overall usability of the extension.  + +Explore [LumApps' design system](/) to discover elements that will help you create your experience. + +#### User input + +User inputs enable users to fill in information and define preferences. User inputs are generally used in forms. Components should provide users a way to correctly add requested information.  + +
+
+ Example +

+ In a survey widget, the user must choose between three options. Radio button  components are appropriate as they display all options and restrain users in selecting only one choice. +

+
+ +
+ +A list of possible components: + +- [Autocomplete](/product/components/autocomplete/) +- [Checkbox](/product/components/checkbox/) +- [Date picker](/product/components/date-picker/) +- [Radio button](/product/components/radio-button/) +- [Select](/product/components/select/) +- [Slider](/product/components/slider/) +- [Text field](/product/components/text-field/) +- [Uploader](/product/components/uploader/) + +
+ Best practice +

+ Component labels, placeholders, and helpers should be clear and adapted to the level of understanding of your audience. +

+
+ +#### Interaction with the system + +Users can interact with the system through multiple components. Some components enable users to do very simple actions while others give users the ability to perform complex tasks. + +**Simple interactions** require only a click to be triggered. It allows users to define a preference or to action a: + +- [Switch](/product/components/switch/) +- [Buttons](/product/components/button/) +- [Link](/product/components/link/) +- [Tabs](/product/components/tabs/) +- [Link preview](/product/components/link-preview/) + +**Advanced interactions** that enables detailed position: + +- [Slider](/product/components/slider/) + +**Interactions feedback** informs users an interaction is in progress or has been completed successfully or unsuccessfully: + +- [Notification](/product/components/notification/) +- [Progress](/product/components/progress/) +- [Progress tracker](/product/components/progress-tracker/) +- [Skeleton](/product/components/skeleton/) + +#### Display information +Components that present media, simple information and advanced information. + +**Media** Display medias, images and videos + +- [Avatar](/product/components/avatar/) +- [Image-block](/product/components/image-block/) +- [Lightbox](/product/components/lightbox/) +- [Thumbnail](/product/components/thumbnail) +- [Thumbnail mosaic](/product/components/mosaic/) +- [Slideshow](/product/components/slideshow/) + +**Simple information.** Simple text based information + +- [Notification](/product/components/notification/) +- [Popover](/product/components/popover/) +- [Tooltip](/product/components/tooltip/) + +**Advanced information.** Display structured and or complex information such as rich text: + +- [Table](/product/components/table) +- [Comment block](/product/components/comment-block/) +- [User block](/product/components/user-block/) +- [Dialog](/product/components/dialog/) + +#### Structure interfaces + +Creating a structured interface requires assembling all the UI components in a logical and effective way to create each step of the user flow. A great user experience is achieved when users reach their goal without issues or hesitation. + +
+
+ Example +

+ In a form widget, the user is supposed to fill in a text field. Help the user fill the form quickly by using placeholders. Placeholders give a short hint that describes the expected value of an input field. +

+
+ +
+ +**Dialogs** + +Your widget will generally contain all your UI components. However, when space limitations due to narrow widget framing is an issue, you can use a dialog for interactions and information. Dialogs are displayed over the screen and increase user focus. + +
+
+ Example +

+ The user must write a comment for a request refusal. From the widget, a dialog is displayed when the user clicks on the refuse button. The dialog enables the user to focus on the task they have to complete. +

+
+ +
+ +
+ Best Practice +

Use dialogs when the user needs to execute complex tasks or be aware of important information.

+
+ +Inside a dialog, [tabs](/product/components/tabs/) enable structured information and interactions. The user clicks on tabs to access another section. + +The stepper dialog is a container used to complete a complex creation process. A [progress tracker](/product/components/progress-tracker/)conveys user progress through a sequence of steps. Each step of the process can contain multiple UI components. + +
+
+ Example +

+ A stepper dialog enables the user to create a new request, and the user must complete four steps to create and send their request. Each step is composed of text fields. +

+
+ +
+ +
+ Best Practice +

Stepper dialogs should be used for complex creation with multiple possibilities and settings.

+
+ +A [toolbar](/product/components/toolbar/) can be used to display information and actions related to the context. + +
+
+ Example +

A toolbar with a search field and filter can be very useful for widgets listing lots of users.

+
+ +
+ +Information can be structured inside a container by creating sections. They are separated by [divider](/product/components/divider/). Each section has a subtitle, and can also embed a subsection. + +[Expansion panel](/product/components/expansion-panel/) uses the principle of progressive disclosure to implement large amounts of content in a small space through progressive disclosure. + +#### Test and iterate + +After completing the design and development phases, ensure your extension widget meets high-quality standards through Quality Assurance and Usability testing. + +**Quality assurance** + +Take on the role of an end user and use your widget. The Playground is a local application that allows you to preview your widget and test every possible use case to try to identify bugs and errors. + +**Usability testing** + +Put your extension widget in the hands of an end user and ask them what they think about it. The usability test can reveal the strengths and weaknesses of your project. Insights learned from test sessions enable you to operate in iterations to improve your extension widget. + +
+ Best Practice +

Conducting test sessions with five different users helps to detect up to 90% of the problems within your project.

+
+ +A lot of different methods exist to run a usability test. There is no right or wrong method, use the one that best meets your requirements. + +Usability test methods include: + +- [Guerilla testing](https://uxdesign.cc/guerrilla-testing-what-it-is-and-when-to-use-it-500cc5d2f9b3) A method where a small team tests in real-world situations with real users, often in public places. It's quick, low-cost, and helps spot usability issues or gather feedback + +- [Lab usability testing](https://www.teced.com/services/usability-testing-and-evaluation/lab-usability-testing/) Within a usability testing session, a participant recruited based on specific criteria engages in typical tasks using your interface. A facilitator oversees and manages the test conditions to identify and understand usability issues and their root causes. + +- [Unmoderated remote testing](https://maze.co/guides/usability-testing/remote/) The participant and the researcher are in separate locations. This practice is facilitated by tools, such as [Maze](https://maze.co/) During a remote testing session, the participant is recorded while completing a test. The tool collects data and generates insights that you can put into action right away. + +- [A/B testing](https://www.uxpin.com/studio/blog/ab-testing-in-ux-design-when-and-why/)(split testing) is used to compare two versions of an interface to see which performs better. It helps determine which version is more effective in achieving a specific goal, by showing both versions to different groups of users and analyzing their responses. + diff --git a/packages/site-demo/src/components/layout/MainContent/MainContent.scss b/packages/site-demo/src/components/layout/MainContent/MainContent.scss index 914e39d325..f95c657786 100644 --- a/packages/site-demo/src/components/layout/MainContent/MainContent.scss +++ b/packages/site-demo/src/components/layout/MainContent/MainContent.scss @@ -53,10 +53,11 @@ background-color: $lumx-color-dark-L5; } - & > ul { + & > ul, + & > ol { margin-left: $lumx-spacing-unit-huge * 2; + li p {margin-block-end: 1em;} } - & > h2, & > h3, & > h4 { @@ -69,6 +70,7 @@ & > h4, & > p, & > ul, + & > ol, & > div, & > pre, & > img, diff --git a/packages/site-demo/src/style/components/_custom-doc-styles.scss b/packages/site-demo/src/style/components/_custom-doc-styles.scss new file mode 100644 index 0000000000..43ea116495 --- /dev/null +++ b/packages/site-demo/src/style/components/_custom-doc-styles.scss @@ -0,0 +1,29 @@ +.highlighted-block { + display: flex; + flex-direction: column; + padding: $lumx-spacing-unit * 1.5 $lumx-spacing-unit * 2; + background: lumx-color-variant('green', 'L5'); + color: lumx-color-variant('green', 'N'); +} + +.example-block { + display: flex; + flex-direction: column; + background: lumx-color-variant('blue', 'L5'); + color: lumx-color-variant('blue', 'N'); + + &__inner { + display: flex; + flex-direction: column; + padding: $lumx-spacing-unit * 1.5 $lumx-spacing-unit * 2; + + & > ul, + & > ol { + margin-left: $lumx-spacing-unit-huge * 2; + } + } + + &__image { + margin: 8px; + } +} diff --git a/packages/site-demo/src/style/index.scss b/packages/site-demo/src/style/index.scss index cc5be5eeb5..92ad025e28 100644 --- a/packages/site-demo/src/style/index.scss +++ b/packages/site-demo/src/style/index.scss @@ -1,5 +1,6 @@ /** DEMO THEME - LUMAPPS */ @import "@lumx/core/src/scss/lumx"; +@import "./components/custom-doc-styles"; /* ========================================================================== Base