From 97d28fddd68c655aeb0a451f33c80a57cf6bdfca Mon Sep 17 00:00:00 2001 From: nim Date: Thu, 16 Sep 2021 17:01:42 +0530 Subject: [PATCH] changed link wording, added icon size, changed formatting for code bits Signed-off-by: nim --- developer_manual/design/atomiccomponents.rst | 28 +++++++++++++------- developer_manual/design/foundations.rst | 14 +++++----- developer_manual/design/layout.rst | 6 ++--- developer_manual/design/layoutcomponents.rst | 28 ++++++++++++++------ 4 files changed, 48 insertions(+), 28 deletions(-) diff --git a/developer_manual/design/atomiccomponents.rst b/developer_manual/design/atomiccomponents.rst index b888e3aa0..12590cfeb 100644 --- a/developer_manual/design/atomiccomponents.rst +++ b/developer_manual/design/atomiccomponents.rst @@ -77,10 +77,12 @@ 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 `_. +`Action menu Vue component `_. For Android and iOS, the action menu is generally opened as a bottom sheet. +.. _Input fields: + Input fields ------------ @@ -111,7 +113,7 @@ Although not always necessary, it is generally a good idea to have a default ite 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 `_. +`Dropdown Vue component `_. .. _Checkboxes and radio buttons: @@ -128,7 +130,9 @@ Checkboxes and radio buttons 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. `Link to checkbox and radio button Vue components `_. +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. + +`Checkbox and radio button Vue components `_. Pickers ------- @@ -143,7 +147,9 @@ 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. `Link to datetime picker Vue component `_. +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. + +`Datetime picker Vue component `_. .. _Color picker: @@ -155,7 +161,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. `Link to color picker Vue component `_. +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. + +`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. @@ -191,7 +199,7 @@ Examples of modals are: * Move or copy dialog in Files * the file picker in Mail and Talk -`Link to the modal Vue component `_. +`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 `_. @@ -210,7 +218,7 @@ 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 `_. +`Avatar Vue component `_. .. _Progress bars and meters: @@ -230,7 +238,7 @@ Progress bars shows progress for a potentially lengthy process such as uploading 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 `_. +`Progess bar Vue component `_. .. _User bubbles: @@ -243,7 +251,7 @@ User bubbles 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 `_. +`User bubble Vue component `_. .. _Tooltips: @@ -273,7 +281,7 @@ The empty content state provides feedback that a view is empty, e.g. a new folde 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. -`Link to empty content component `_. +`Empty content component `_. .. _Skeleton screens: diff --git a/developer_manual/design/foundations.rst b/developer_manual/design/foundations.rst index 8a830d720..3a7956ce9 100644 --- a/developer_manual/design/foundations.rst +++ b/developer_manual/design/foundations.rst @@ -37,7 +37,7 @@ Background color Nextcloud apps have a light and a dark theme, with appropriately chosen colors for all elements. -* On web: var(--color-main-background) +* On web: ``var(--color-main-background)`` * Android: uses default Material Design colors * iOS: `systemBackground `_ * Desktop: default Qt guidelines @@ -58,7 +58,7 @@ Text color This is the main color for the text in light theme, and in dark theme. -* On web: var(--color-main-text) +* On web: ``var(--color-main-text)`` * Android: uses default Material Design color "high emphasis" * iOS: `label `_ (in UITextView, leave the default textColor) * Desktop: default Qt guidelines @@ -77,7 +77,7 @@ This is the main color for the text in light theme, and in dark theme. In addition, a softer color is used for secondary text like sublines, timestamps, and similar. -* On web: var(--color-text-maxcontrast) +* On web:``var(--color-text-maxcontrast)`` * Android: uses default Material Design color "medium emphasis" * iOS: `secondaryLabel `_ * Desktop: `default Qt guidelines `_ @@ -106,9 +106,9 @@ While interface elements like buttons are colored differently depending on their * On web: - * var(--color-success) - * var(--color-warning) - * var(--color-error) + * Success colour: ``var(--color-success)`` + * Warning colour: ``var(--color-warning)`` + * Error colour: ``var(--color-error)`` * Android: Material Design guidelines * iOS: `Apple HIG colors `_ @@ -144,7 +144,7 @@ Icons .. image:: ../images/material-icons.png :alt: Material icons -Icons can be used to communicate the intent of an action, or to provide visual interest to the screen. We use monochrome icons on all platforms: `Material Design icons (default filled) `_ for web, Android, Windows and Linux, and `SF Symbols (default weight, scale and variant) `_ for iOS and macOS. +Icons can be used to communicate the intent of an action, or to provide visual interest to the screen. We use monochrome icons on all platforms: `Material Design icons (20 px default filled) `_ for web, Android, Windows and Linux, and `SF Symbols (default weight, scale and variant) `_ for iOS and macOS. This is except for the icon of the app itself, which can be a custom icon. diff --git a/developer_manual/design/layout.rst b/developer_manual/design/layout.rst index a9a8cdffc..ecd7d45af 100644 --- a/developer_manual/design/layout.rst +++ b/developer_manual/design/layout.rst @@ -26,7 +26,7 @@ Navigation → Content → Sidebar This layout is used in Files, Calendar, Deck, and Tasks. -This layout has the [app navigation] on the left, the [main content] in the middle, and a [sidebar] on the right. The main content depends on the navigation, and the sidebar which is closed by default contains details of an item in the main content. +This layout has the :ref:`Navigation` on the left, the :ref:`Content` in the middle, and a :ref:`Sidebar` on the right. The main content depends on the navigation, and the sidebar which is closed by default contains details of an item in the main content. For example, in the Files app, the files in the main content varies based on what is selected in the navigation. The sidebar would open when the user wants to see the details of a file. @@ -52,7 +52,7 @@ Special case: list in navigation :alt: Talk layout -Another variation of this layout is where the [list] of entries take up the left space instead of navigation, as seen in Talk. It shows the list of chats on the left, and the main content contains the messages in a chat, while opening the right sidebar shows the details of a chat like the description and participants. Talk also collapses the left list and right sidebar during a video call, so that the entire screen is taken up by just the call. +Another variation of this layout is where the :ref:`List` of entries take up the left space instead of navigation, as seen in Talk. It shows the list of chats on the left, and the main content contains the messages in a chat, while opening the right sidebar shows the details of a chat like the description and participants. Talk also collapses the left list and right sidebar during a video call, so that the entire screen is taken up by just the call. Navigation → List → Content --------------------------- @@ -64,7 +64,7 @@ Navigation → List → Content This layout is used in Mail and Contacts. -In this layout, the 3 levels of hierarchy are shown by default. On the left there is the [app navigation], right next to it is a [list] of entries for the navigation chosen, and the main content is for the entry selected in the list. +In this layout, the 3 levels of hierarchy are shown by default. On the left there is the :ref:`Navigation`, right next to it is a :ref:`List` of entries for the navigation chosen, and the main content is for the entry selected in the list. A good example of this layout is in the Mail app. The left navigation section contains the different inboxes and categories. The list then shows the emails of the selected inbox or folder and the main content shows the contents of the email which is currently open. diff --git a/developer_manual/design/layoutcomponents.rst b/developer_manual/design/layoutcomponents.rst index bacd79fe6..3fe470e56 100644 --- a/developer_manual/design/layoutcomponents.rst +++ b/developer_manual/design/layoutcomponents.rst @@ -13,7 +13,11 @@ Navigation :alt: Contacts navigation -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: +The left navigation provides a way for users to move around different sections of your app. + +`Vue component for the app navigation `_. + +The navigation consists of 4 main elements: * Main action button @@ -58,7 +62,9 @@ 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. `Link to navigation entries Vue component `_. +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. + +`Navigation entries Vue component `_. New item element ^^^^^^^^^^^^^^^^ @@ -74,7 +80,7 @@ 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 `_. +`New item Vue component `_. .. _Settings: @@ -87,11 +93,15 @@ 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. `Link to the settings Vue component `_. +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. + +`Settings Vue component `_. Also see: :ref:`Modal` -List items +.. _List: + +List item ---------- @@ -105,7 +115,7 @@ 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 `_. +`List item Vue component `_. .. _Content: @@ -140,7 +150,9 @@ Spacing between elements in your app should be in multiples of 4px. 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. `Link to sidebar Vue component `_. +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. + +`Sidebar Vue component `_. Commonly used tabs in the sidebar are: @@ -151,7 +163,7 @@ Details .. image:: ../images/sidebar-details.png :alt: Details tab in Calendar sidebar -The details tab contains information about the entry it refers to, which is often editable using various input fields. The details included here will depend upon your app. For example, the details tab in the sidebar of the Calendar app contains information about the selected event, like location, description, and status. Also see [input fields] in the atomic components section for more details about the various input fields that can be used here. +The details tab contains information about the entry it refers to, which is often editable using various input fields. The details included here will depend upon your app. For example, the details tab in the sidebar of the Calendar app contains information about the selected event, like location, description, and status. Also see :ref:`Input fields` in the atomic components section for more details about the various input fields that can be used here. Activity ^^^^^^^^