diff --git a/developer_manual/design/atomiccomponents.rst b/developer_manual/design/atomiccomponents.rst index 835e1f1ad..b888e3aa0 100644 --- a/developer_manual/design/atomiccomponents.rst +++ b/developer_manual/design/atomiccomponents.rst @@ -39,11 +39,9 @@ There are generally different types of buttons for different purposes: .. _Action menu: - Action menu ----------- - .. image:: ../images/action-menu.png :alt: Files action menu @@ -79,13 +77,13 @@ It is important to keep the action menu simple and its length at a minimum. Too In most cases the action menu is accessed through a 3-dot menu. In certain cases, it is better to use a specific icon instead of the generic 3-dot icon. For example in Talk a paperclip icon is used for accessing the action menu for attaching an item, and a heading icon is used in Text formatting bar for heading level selection. +`Link to the action menu Vue component `_. + For Android and iOS, the action menu is generally opened as a bottom sheet. Input fields ------------ -There are several types of inputs that your Nextcloud app can have. Some commonly used input fields are given here: - .. _Text input: Text input @@ -107,12 +105,14 @@ Dropdowns .. image:: ../images/dropdown-find-as-you-type.gif :alt: Dropdown menu in settings -Dropdowns allow the user to select one or more items from a list. Dropdowns can have predefined options from which the user can select one or more items, as seen in Contacts for selecting the type of a phone number. If there are not too many entries, you may also think about using a set of radio buttons or checkboxes instead. +Dropdowns allow the user to select one or more items from a list. Dropdowns can have predefined options from which the user can select one or more items, as seen in Contacts for selecting the type of a phone number. If there are not too many entries, you may also think about using a set of :ref:`checkboxes and radio buttons` instead. Although not always necessary, it is generally a good idea to have a default item already selected, especially when a dropdown menu is a key element which will be used a lot. This can be decided by a number of factors such as most selected item for that user, most recently selected item, etc. For example, when you add a new phone number in Contacts, the type "Home" is automatically set in the dropdown. Another variation of the dropdown allows the user to find their preferred option by typing it in, like in Mail where the "To" field in the composer allows you to type an email address, and as you type it shows a dropdown with the results matching the input. This kind of dropdown is useful for when there are many options and the user would already know what they are looking for. It can also be a good idea to allow new inputs if there are no matches. +`Link to dropdown Vue component `_. + .. _Checkboxes and radio buttons: Checkboxes and radio buttons @@ -126,9 +126,9 @@ Checkboxes and radio buttons :alt: Radio buttons in Mail settings -Checkboxes and radio buttons are very common input methods. They are most commonly used in the [action menu], [sidebar] and settings. +Checkboxes and radio buttons are very common input methods. They are most commonly used in the :ref:`action menu`, :ref:`sidebar` and :ref:`settings`. -They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline. +They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline. `Link to checkbox and radio button Vue components `_. Pickers ------- @@ -143,7 +143,7 @@ Datetime picker :alt: Files date picker -A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default. +A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default. `Link to datetime picker Vue component `_. .. _Color picker: @@ -155,7 +155,9 @@ Color picker :alt: Deck color picker -For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to. +For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to. `Link to color picker Vue component `_. + +In addition to these 2 pickers, there is also the `emoji picker `_ and the `timezone picker `_ which can be also be used in your app. .. _Tags: @@ -189,7 +191,9 @@ Examples of modals are: * Move or copy dialog in Files * the file picker in Mail and Talk -On Android and iOS, content which is in a modal would usually be shown as a full-screen overlay, like for example composing a new mail in `iOS Mail `_\. +`Link to the modal Vue component `_. + +On Android and iOS, content which is in a modal would usually be shown as a full-screen overlay, like for example composing a new mail in `iOS Mail `_. .. _Avatar: @@ -206,6 +210,8 @@ When using an avatar it is usually accompanied by the name of the user as well, When multiple people are working on or are assigned to the same element, like in Text, Office, a Deck card, or in the Files list for sharing, they are shown as overlapped. +`Link to the avatar Vue component `_. + .. _Progress bars and meters: @@ -222,7 +228,9 @@ Progress bars shows progress for a potentially lengthy process such as uploading .. image:: ../images/meter-settings.png :alt: Meter in Files for storage quota -The progress bar component is also sometimes used as a meter to visualize data as seen in the settings for Files to show the quota +The progress bar component is also sometimes used as a meter to visualize data as seen in the settings for Files to show the quota. + +`Link to progess bar Vue component `_. .. _User bubbles: @@ -233,7 +241,9 @@ User bubbles :alt: Talk user bubble -When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message. +When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message. + +`Link to user bubble Vue component `_. .. _Tooltips: @@ -246,7 +256,9 @@ Tooltips Tooltips are small elements which appear on hover and contain information about the element. Although not necessary for every action or item on the screen, tooltips are great for providing extra information or when an element is too small for the text contained in it. -Using many tooltips is not advised, and if your app does this, possibly consider instead using text labels for icons, reducing the number of actions, or if the info in the tooltip is needed at all. +Using many tooltips is not advised, and if your app does this, possibly consider instead using text labels for icons, reducing the number of actions, or if the info in the tooltip is needed at all. + +`The tooltip Vue component can be found here as a directive `_. .. _Empty content: @@ -259,9 +271,9 @@ Empty content The empty content state provides feedback that a view is empty, e.g. a new folder. This is to differentiate it from the state of loading, or having loaded and showing data. -Make sure that empty content views only show when the view is really empty, and not while it is loading – otherwise people will be shocked as to where their data is gone. +Make sure that empty content views only show when the view is really empty, and not while it is loading – otherwise people will be shocked as to where their data is gone. The wording on the empty content view should be friendly and helping people out of the situation, for example in the Bookmarks app. -The wording on the empty content view should be friendly and helping people out of the situation, for example in the Bookmarks app +`Link to empty content component `_. .. _Skeleton screens: diff --git a/developer_manual/design/foundations.rst b/developer_manual/design/foundations.rst index 284abd98b..8a830d720 100644 --- a/developer_manual/design/foundations.rst +++ b/developer_manual/design/foundations.rst @@ -2,7 +2,7 @@ Foundations =========== -There are several design elements that are common to all Nextcloud apps. If you are developing for a platform that has its own design specifications, it would be a good idea to keep those in mind while designing your app. +There are several design elements that are common to all Nextcloud apps. If you are developing for a platform that has its own design specifications, for example Android, it would be a good idea to keep those in mind while designing your app. Color ----- @@ -80,7 +80,7 @@ In addition, a softer color is used for secondary text like sublines, timestamps * On web: var(--color-text-maxcontrast) * Android: uses default Material Design color "medium emphasis" * iOS: `secondaryLabel `_ -* Desktop: default Qt guidelines +* Desktop: `default Qt guidelines `_ Status and indicators ^^^^^^^^^^^^^^^^^^^^^ @@ -110,14 +110,13 @@ While interface elements like buttons are colored differently depending on their * var(--color-warning) * var(--color-error) -* Android: * +* Android: Material Design guidelines * iOS: `Apple HIG colors `_ * success: systemGreen - * warning: * error: systemRed -* Desktop: * +* Desktop: `default Qt guidelines `_ Typography ---------- @@ -137,7 +136,7 @@ The text sizes for the different platforms are: * Web: 15px for main text and sublines, **20px bold** for headings * Android: 14sp for main text, 16sp for headings * iOS: values from `Dynamic Type Sizes, for size Large (Default) `_ -* Desktop: default Qt guidelines +* Desktop: `default Qt guidelines `_ Icons ----- diff --git a/developer_manual/design/layout.rst b/developer_manual/design/layout.rst index 8d0388b11..a9a8cdffc 100644 --- a/developer_manual/design/layout.rst +++ b/developer_manual/design/layout.rst @@ -10,7 +10,7 @@ While deciding how you want your app to look, there are a number of factors to c * Responsiveness for different browsers, browser sizes and devices * Typical interface patterns in other similar apps in the market -While the arrangement of components in your app is dependent on what your app does, most Nextcloud apps typically have 3 levels of hierarchy. Some commonly used layouts are: +The `content Vue component `_ wraps your entire app. While the arrangement of components in your app is dependent on what your app does, most Nextcloud apps typically have 3 levels of hierarchy. Some commonly used layouts are: * Navigation → content → sidebar (and a couple of variations of it, e.g. without the sidebar) diff --git a/developer_manual/design/layoutcomponents.rst b/developer_manual/design/layoutcomponents.rst index cd65fce6e..bacd79fe6 100644 --- a/developer_manual/design/layoutcomponents.rst +++ b/developer_manual/design/layoutcomponents.rst @@ -1,7 +1,7 @@ Layout components ================= -All Nextcloud apps are built using individual reusable components for consistency and efficiency. Currently, these components are written in Vue and can be found at the `nextcloud-vue repository on Github `_ with the documentation available at `the Nextcloud vue components style guide `_ +All Nextcloud apps are built using individual reusable components for consistency and efficiency. Currently, these components are written in Vue and can be found at the `nextcloud-vue repository on Github `_ with the documentation available at `the Nextcloud Vue components style guide `_. .. _Navigation: @@ -13,7 +13,7 @@ Navigation :alt: Contacts navigation -The left navigation provides a way for users to move around different sections of your app. The navigation consists of 4 main elements: +The left navigation provides a way for users to move around different sections of your app. The Vue component for the app navigation can be found `here `_. The navigation consists of 4 main elements: * Main action button @@ -58,7 +58,7 @@ Top-level navigation entries ideally have a suitable icon left next to them. Opt * a 3 dot action menu (seen in Mail) * a counter (seen in Contacts and Mail) -A sublevel of navigation is possible, but can lead to entries being hard to discover. It is only advised if there is actually a hierarchy like for folders in Mail or News. +A sublevel of navigation is possible, but can lead to entries being hard to discover. It is only advised if there is actually a hierarchy like for folders in Mail or News. `Link to navigation entries Vue component `_. New item element ^^^^^^^^^^^^^^^^ @@ -74,6 +74,8 @@ Users can easily create a new item with a suitable name by using the new item el * "Add mailbox" in Mail * "New calendar" in Calendar +`Link to new item Vue component `_. + .. _Settings: Settings @@ -85,9 +87,9 @@ Settings The user-specific settings for your app may be shown in a settings modal, which can be accessed through a settings entry at the bottom of the navigation. Try to keep the settings to a minimum, as too many configurable options can be a burden to the user. If no settings are needed for the app, that is great and the settings modal can be omitted. Within the modal, categorizing your settings can sometimes offer a better experience if you have a lot of settings. If this is required, the categories are placed in the left of the settings modal. -You can also include a "Help" as an entry in the settings of your app and provide some simple information about your app and how to use it. Some apps like Talk and Mail also include keyboard shortcuts. +You can also include a "Help" as an entry in the settings of your app and provide some simple information about your app and how to use it. Some apps like Talk and Mail also include keyboard shortcuts. `Link to the settings Vue component `_. -Also see: :ref:`Modal` +Also see: :ref:`Modal` List items ---------- @@ -103,12 +105,14 @@ List items can be used to display a collection of elements from which one can be * an :ref:`Action menu` which has commonly used actions for that type of item * a counter bubble: Talk for example uses an unread messages counter +`Link to list item Vue component `_. + .. _Content: Content ------- -The content section of your app takes up the most screen space, and is the core of what your app does. The content of every app is unique, but do make sure that it follows some basic rules like responsiveness, accessibility, and support in different languages so that it can be used by everyone. The layout of your content depends on what your app does, as the content of almost every Nextcloud app looks different. +The content section of your app takes up the most screen space, and is the core of what your app does. The content of every app is unique, but do make sure that it follows some basic rules like responsiveness, accessibility, and support in different languages so that it can be used by everyone. The layout of your content depends on what your app does, as the content of almost every Nextcloud app looks different. The `appContent Vue component `_ should be used for the content of your app. Views ^^^^^ @@ -129,19 +133,17 @@ For text-based apps like chat, mails, and other paragraphs of text, the width of For every clickable element in your interface, make sure it has a minimum clickable area of at least 44px by 44px (48px for Android). Anything smaller than this will make your app inaccessible and difficult for users to use your app on mobile as they might miss while trying to tap on the element. -While adding margins, padding and other spacing in your interface, use multiples of 4px. +Spacing between elements in your app should be in multiples of 4px. .. _Sidebar: Sidebar ------- -Details of a particular entry in your content, as well as some actions associated with it, are shown in the right sidebar. In apps where the sidebar is used, it only opens when required. The sidebar is never used in the 3-column layout (Navigation + list + content). It contains the main information and sometimes a preview of the selected item, as well as a maximum of 3 possible tabs: +Details of a particular entry in your content, as well as some actions associated with it, are shown in the right sidebar. In apps where the sidebar is used, it only opens when required. The sidebar is never used in the 3-column layout (Navigation + list + content). It contains the main information and sometimes a preview of the selected item, as well as a maximum of 3 possible tabs. `Link to sidebar Vue component `_. +Commonly used tabs in the sidebar are: -* Details -* Activity -* Sharing Details ^^^^^^^ @@ -154,8 +156,6 @@ The details tab contains information about the entry it refers to, which is ofte Activity ^^^^^^^^ -[screenshot of Android activity tab] - Major changes done to the selected item, as well as comments left by users, are shown in the activity tab. These details are shown by latest activity up top. If your app includes comment support, the "Write comment" input box should be placed here so it is nicely integrated.