diff --git a/developer_manual/design/atomiccomponents.rst b/developer_manual/design/atomiccomponents.rst deleted file mode 100644 index a8f225aff11..00000000000 --- a/developer_manual/design/atomiccomponents.rst +++ /dev/null @@ -1,300 +0,0 @@ -Atomic components -================= - -.. _Buttons: - -Buttons -------- - -`Buttons Vue component `_. -`Penpot buttons `_ - -Buttons are used to initiate actions in your app. This may be a primary action, or it may be used to confirm an action in a dialog, or simply be used for any major action in your app. - -There are generally different types of buttons for different purposes: - -.. image:: ../images/button-primary-secondary.png - :alt: Primary button "Move" and secondary button "Copy" in Files - -* Primary buttons are used to indicate the main action ("Start call" button in Talk, "Move" in Files). The primary buttons are stylized in Nextcloud blue by default or the theming color when themed. These should only be used sparingly and ideally only for 1 visible action at a time. -* Secondary buttons are used for actions that have lesser weight than the primary action ("Today" button in Calendar, "Copy" in Files) - -.. image:: ../images/button-tertiary.png - :alt: Tertiary button "Mark as read" in desktop tray menu - -* Tertiary buttons, which are the buttons without a background, can be used for other actions in your app which are important, but not the main focus. These buttons are usually combined with a primary or secondary button. For example, "Mark as read" is a tertiary button used alongside a secondary button - -.. image:: ../images/button-icon-only.png - :alt: Mute, video, screenshare and 3-dot buttons in Talk video call - -* The icon-only buttons can be used if the action is frequently used and the icon is easily recognizable, and therefore does not require any text to support it (mute/video/screenshare actions in Talk, and the 3-dot menu icon) - -.. image:: ../images/button-success.png - :alt: Success button "Join call" in Talk - -* Success buttons are used for a positive action ("Join call" button in Talk) - -.. image:: ../images/button-danger.png - :alt: Danger button "Remove email" in Mail - -* Danger buttons are used to signify a potentially dangerous or negative action ("Remove account" button in the confirmation dialog when you want to remove an account in Mail, or "Delete conversation" in Talk conversation settings) - -.. _Action menu: - -Action menu ------------ - -`Action menu Vue component `_. -`Penpot action menu `_ - -.. image:: ../images/action-menu.png - :alt: Files action menu - - -The action menu contains commonly used actions associated with an item. Each entry in the action menu has some text accompanied by a suitable icon. In some cases, the action menu may also contain: - -.. image:: ../images/action-menu-checkbox.png - :alt: Checkbox in action menu in Mail - -* checkboxes to quickly toggle a state, like in Mail - -.. image:: ../images/action-menu-radio-button.gif - :alt: Radio button in action menu in Files link sharing - -* radio buttons to select from a few options, like chat notifications in Talk - -.. image:: ../images/action-menu-new-item.gif - :alt: Add new mailbox in Mail action menu - -* new entry elements to quickly add items, like add a new mailbox in Mail - -.. image:: ../images/action-menu-second-level.gif - :alt: Second level of actions in action menu to configure custom permissions for link shares in Files - -* a second level of actions, like to configure custom permissions for link shares in Files - -Some commonly used actions in the action menu are favoriting, renaming, downloading and deleting. Delete should always be at the last position as to not be confused with other actions. - -It is important to keep the action menu simple and its length at a minimum. Too many entries in the action menu can lead to confusion and people not finding what they are looking for. - -.. image:: ../images/action-menu-icon.png - :alt: Action menu with a paperclip icon for attachments in Talk - -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. - -For Android and iOS, the action menu is generally opened as a bottom sheet. - -.. _Input fields: - -Input fields ------------- - -`Input field Vue component `_. -`Penpot text fields `_ - -.. _Text input: - -Text input -^^^^^^^^^^ - -.. image:: ../images/talk-text-input.png - :alt: Talk text input - -.. image:: ../images/text-input-label.png - :alt: Text input with label in settings - -Text inputs are usually used for free-form inputs. Make sure that the label for a text input field is simple and clear. It may also be a good idea to use placeholder text in the field. - -.. _Dropdowns: - -Dropdowns -^^^^^^^^^ - -`Dropdown Vue component `_. -`Penpot dropdowns `_ - -.. image:: ../images/dropdown-find-as-you-type.gif - :alt: Dropdown menu in Files sharing - -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. - -.. _Checkboxes and radio buttons: - -Checkboxes and radio buttons -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -`Checkbox and radio button Vue components `_. -`Penpot checkboxes and radio buttons `_ - -.. image:: ../images/checkboxes-settings.png - :alt: Checkbox in Talk settings - -.. image:: ../images/radiobuttons-settings.png - :alt: Radio buttons in Mail 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. - -Pickers -------- - -.. _Datetime picker: - -Datetime picker -^^^^^^^^^^^^^^^ - -`Datetime picker Vue component `_. - -.. image:: ../images/files-date-picker.png - :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. - -.. _Color picker: - -Color picker -^^^^^^^^^^^^ - -`Color picker Vue component `_. - -.. image:: ../images/colour-picker.gif - :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. - -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: - -Tags ----- - -.. image:: ../images/mail-tags.png - :alt: Mail tags - - -Tags are used by users to manage their items. They can be colored for easy identification, but make sure to use subtle colors if colored tags are a main part of the UI, as seen in Mail. - -.. _Modal: - -Modal ------ - -`Modal Vue component `_. -`Penpot modals `_ - -.. image:: ../images/deck-card-modal.png - :alt: Deck card modal - - -A modal is an element on top of the main UI, and interaction with the main element is disabled. - -The modal is used when there is a specific task or information that the user needs to focus on. Modals are a good idea if the showing some information on the main UI would clutter the UI too much, and the information does not necessarily depend on the UI. Modals are also used for confirmation when performing dangerous tasks such as permanent deletion. - -Examples of modals are: - - -* Settings modal found in Talk and Mail -* the modal view for a card in Deck -* 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 `_. - - -.. _Avatar: - -Avatar ------- - -`Avatar Vue component `_. -`Penpot avatars `_ - -.. image:: ../images/avatar-talk.gif - :alt: Avatars in Talk - -An avatar is used when referring to any user and displays their photo or initials. The avatar component also shows a menu for that user when clicked. - -When using an avatar it is usually accompanied by the name of the user as well, and sometimes it can also show the status of the user, although not always necessary. Statuses can be useful when the user is interacting with another user and is expecting a response, for example when @mentioning someone else in Talk, or in any sharing view. - -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. - -.. _Progress bars and meters: - -Progress bars and meters ------------------------- - -`Progress bar Vue component `_. - -.. image:: ../images/progress-bar.png - :alt: Desktop syncing progress bar - - -Progress bars shows progress for a potentially lengthy process such as uploading, downloading, or syncing. When using a progress bar it can also be a good idea to have a text-based indication of the progress, such as percentage or time remaining, and make sure to provide feedback when the process has been completed. - -.. 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. - -.. _User bubbles: - -User bubbles ------------- - -`User bubble Vue component `_. -`Penpot user bubbles `_ - -.. image:: ../images/talk-user-bubble.png - :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. - -.. _Counter bubbles: - -Counter bubbles ---------------- - -`Counter bubble Vue component `_. -`Penpot counter bubbles `_ - -.. image:: ../images/talk-counter-bubble.png - :alt: Talk counter bubble - -In Talk, it is used for showing which chats are unread and if you or your group is mentioned. - -.. _Empty content: - -Empty content -------------- - -`Empty content component `_. -`Penpot empty content `_ - -.. image:: ../images/empty-content.png - :alt: Bookmarks 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. The wording on the empty content view should be friendly and helping people out of the situation, for example in the Bookmarks app. - -.. _Skeleton screens: - -Skeleton screens ----------------- - -.. image:: ../images/skeleton-screen-talk.png - :alt: Talk skeleton screen - :scale: 50% - -While the app is loading, it is best to show a skeleton view of the apps probable contents as loading feedback. A good example for this is Talk on web as well as Files and Talk on Android. diff --git a/developer_manual/design/components.rst b/developer_manual/design/components.rst new file mode 100644 index 00000000000..f874da11933 --- /dev/null +++ b/developer_manual/design/components.rst @@ -0,0 +1,391 @@ +========== +Components +========== + +These are usage guidelines for common components used across Nextcloud. For a full list of components go to the `Nextcloud Vue component library `__. + +.. _Buttons: + +Buttons +------- + +Buttons `(NcButton) `__ are used to initiate actions in your app. This may be a primary action, or it may be used to confirm an +action in a dialog, or simply be used for any major action in your app. + +- Primary buttons have a background of the primary color and are used to indicate the main action for a flow or screen. Use primary buttons for positive actions like creating and joining. + + - Do not use primary buttons for negative actions like deleting and exiting. + - Ideally use only one visible primary button on a screen. + +- Tertiary buttons, which are the buttons without a background, can be used for other actions in your app which are important, but not the main focus. Use tertiary buttons when an action is + low-priority or dismissive, like going back to a previous step. + + - Do not use tertiary buttons for important actions like signing up or for permanent destructive actions like deleting. + +- Icon-only buttons can be used for simple actions with a widely recognized icon, and as an entry point for an action menu. + + - Always use outlined Material Symbols for icons. + - Do use generally accepted icons for icon-only buttons like a star icon for favoriting. + +.. image:: ../images/buttons.png + :alt: Primary, secondary and tertiary buttons used in the Talk dashboard + +.. _List item: + +List item +--------- + +List items `(NcListItem) `__ are the rows of a content list such as conversations in Talk, messages in Mail, +and boards in Deck. + +- List items are flexible, always having a leading avatar or icon, a name, and an action menu on the right, and optionally a preview line, a timestamp or a counter bubble. + +- Single-line list items show only the name and suit dense, navigation-like lists. Use them when the name alone is enough to identify the row. +- Two-line list items show a name or title on the first line and a preview or metadata on the second line. Use them for messages, conversations, and notes where extra information helps the user. + +.. image:: ../images/list-item.png + :alt: List items used for conversations in Talk + +.. _Counter bubbles: + +Counter bubbles +--------------- + +Counter bubbles `(NcCounterBubble) `__ are small badges that show a number count next to an item, often in the +navigation. A counter bubble is not interactive. + +- Filled primary bubbles can be used to highlight counters that may need attention like direct mentions. +- Outlined bubbles can be used for less important counters. + +.. image:: ../images/counter-bubble.png + :alt: Unread counter in Mail + +.. _Avatars: + +Avatars +------- + +Avatars `(NcAvatar) `__ represent a user, group, or contact. They show the user's profile picture when available, the user's +initials otherwise, and a generic icon for non-users like external email addresses or integrations. An avatar should almost always sit next to a display name. + +- User avatars are the default and automatically show the user's profile picture and status. Use them whenever you have a real Nextcloud user. +- Non-user avatars represent external email addresses, guests, and integrations. For example, external recipients in Mail and guests in Talk. +- 32px as the default size for avatars, but they can be as small as 24px in dense lists, , and as large as 44-64px in headers and profile cards. Keep the size consistent within a single list or row. + +- Avoid placing an avatar alone in flowing text without a name next to it. For inline mentions of a user inside a sentence, use a User bubble. + +.. image:: ../images/avatar.png + :alt: List of avatars in a Talk conversation + + +.. _Chips: + +Chips +----- + +Chips `(NcChip) `__ are small, compact labels for short pieces of metadata like tags, categories, selected values inside an input, +or filter options above a list. Do not use chips for triggering major actions, use a button instead. + +- Removable chips have a small close button and represent a value that can be removed. Use them inside multi-value inputs like recipient pickers, tag editors, and label fields. +- Filter chips toggle a filter on or off and visually indicate when they are active. Use them for small filter sets above a list, like "Unread" or "Flagged" in Mail. +- Colored chips work well for user-defined labels like tags and calendar categories. +- When there are many options or a lack of space, consider using a dropdown instead. + +.. image:: ../images/chip.png + :alt: Tag in Mail + + +.. _User bubbles: + +User bubbles +------------ + +User bubbles `(NcUserBubble) `__ represent a user inside flowing content like chat messages, comments, and text documents. + +.. image:: ../images/user-bubble.png + :alt: User bubbles when you at-mention in Talk + +.. _Note card: + +Note card +--------- + +Note cards `(NcNoteCard) `__ are persistent inline message boxes that can be used to provide additional information about an +element, communicate state, warn the user, or surface a problem. They come in four types: info, success, warning, and error. + +- Info note cards explain context or share a tip. Use them for helpful additional information like "Your date of birth is needed for age verification". +- Success note cards can show persistent positive information like "Your software is up-to-date". +- Warning note cards can be used to indicate an unfavorable but non-blocking state or guide users through a risky operation. For example, Talk shows a "High-performance backend is not installed" + warning to indicate it may result in connectivity issues for participants in a call. +- Error note cards mark a real problem in the current view, like "Could not connect to mail server". + +.. image:: ../images/notecard.png + :alt: Warning note card in Talk + +.. _Dropdown: + +Dropdown +-------- + +Dropdowns `(NcSelect) `__ let the user pick one or more values from a list. They support search, free-text entry, and loading +options on the fly. + +- Single-select dropdowns let the user pick one value. + + - If your dropdown has many options, do add an option to search. For example, it is possible to search for a time zone. + - Do not use them for a small number of mutually exclusive options. A radio group is clearer in that case. + +- Multi-select dropdowns allow several values and show each selection as a chip inside the input. Use them for things like selecting multiple users and tags. + + - Do let the user type and add their own option whenever applicable, for example while adding recipient email addresses to an email. + +.. image:: ../images/dropdown.png + :alt: Single-select dropdown in calendar settings + + +.. _Input fields: + +Input fields +------------ + +Input fields allow the user to enter text, numbers, passwords, and more. Input fields often have labels, helper text, and errors. + +- Use text inputs `(NcTextField) `__ for single-line text like names, titles, subjects, search queries, and + URLs. +- Use the password input `(NcPasswordField) `__ for passwords which obscures the text being typed and has a + reveal-password button. +- A text area `(NcTextArea) `__ is for multi-line input like descriptions, notes, plain-text email bodies, and + card details. +- Every input field should have a label. The default is a floating label which appears floating at the border when the input is active or filled. Use external labels when there are many inputs in a + column. +- When something is wrong with the text the user has entered, for example an invalid email address format, show an error state together with a short helper message that tells the user how to fix it. +- Do use a leading icon when it helps identify the field (a magnifying glass for search, or an envelope for email), and a trailing button for inline actions like clearing, copying, or revealing a + password. + +- Do choose the right text type (email, URL, search) so mobile keyboards adapt and the browser can help. + +.. image:: ../images/text-fields.png + :alt: Text fields and text area while creating a Talk conversation + +Formattable text area +^^^^^^^^^^^^^^^^^^^^^ + +Use the rich text content `(NcRichContenteditable) `__ when the user may want to enter text with formatting via +markdown syntax. This can be used for messages, comments, and long descriptions. To display the results of the text entered in this text area, use the ``NcRichText`` component which renders the +formatted text. + +.. image:: ../images/richcontent.png + :alt: Message input in Talk + +.. _Pickers: + +Pickers +------- + +Pickers are specialized inputs that open a popover or modal to choose a structured value like a date, a timezone, a color, an emoji, or a file. + +Datetime picker +^^^^^^^^^^^^^^^ + +The datetime picker can be used to enter a date and time for scheduling events, setting reminders, and selecting dates of birth. + +- Use the native picker `(NcDateTimePickerNative) `__ as a default. It uses the browser's native + date and time controls and is more accessible than a custom one. +- Use the custom picker `(NcDateTimePicker) `__ when the user benefits from seeing a calendar + persistently, like for selecting a slot while booking an appointment. +- Do use a sensible default date and time, for example, a user setting their work hours may benefit from a default of 9:00 AM as their starting availability and 5:00 PM as ending availability. + +.. image:: ../images/datetime-picker.png + :alt: Date time picker for setting an event time + +Timezone picker +^^^^^^^^^^^^^^^ + +The timezone picker `(NcTimezonePicker) `__ is a specialized dropdown preloaded with all named timezones. + +- Do use it only when a timezone is needed. Often the user's default home timezone may be sufficient for the action. + +.. image:: ../images/timezone-picker.png + :alt: Timezone picker in Calendar + + +Color picker +^^^^^^^^^^^^ + +The color picker `(NcColorPicker) `__ opens a small popover with a preset color palette. It can be used for +setting colors for various items like Deck boards, calendars, and tags. The color picker should color a specific item, not large areas of the UI. + +- Use the default Nextcloud palette so colors stay consistent across different Nextcloud apps. +- Enable the advanced fields (hex, RGB) only when fine control matters, for example, for personal theming. + +.. image:: ../images/color-picker.png + :alt: Color picker for selecting an event color in Calendar + +Emoji picker +^^^^^^^^^^^^ + +The emoji picker `(NcEmojiPicker) `__ opens a popover for choosing an emoji, with search, skin-tone selection, +and a recently-used row. + +- Do use it for user-generated content like reactions in Talk, conversation icons, and user-created pages in Collectives. +- Do not use it as a generic icon picker for navigation entries or system items. Those use Material Symbols. + +.. image:: ../images/emoji-picker.png + :alt: Emoji picker in Talk + +File picker +^^^^^^^^^^^ + +The file picker `(NcFilePicker) `__ opens a modal of the user's files on Nextcloud. It supports filtering by +file type, picking one or several items, and choosing folders. + +- Use the file picker when the user can attach a file from their Nextcloud. Also let the user upload a file from their local filesystem. +- The file picker can also be useful for moving or copying files. +- Do filter by file type when only certain formats are valid. +- Do label the primary button with a verb that matches the action like "Attach", "Insert", or "Choose". + +.. image:: ../images/file-picker.png + :alt: File picker for copying a file + +.. _Checkboxes and toggles: + +Checkboxes and toggles +-------------------------------------- + +Checkboxes and toggles `(NcCheckboxRadioSwitch) `__ are selection controls that share a +single component. + +- Checkboxes allow users to select multiple options from a list. for example, per-folder share permissions. +- Toggles (switches) are used for enabling and disabling a single setting. + + + +.. image:: ../images/checkboxes.png + :alt: Checkboxes in Files sharing + + +.. image:: ../images/toggles.png + :alt: Toggles while creating a Talk conversation + + +Radio groups +^^^^^^^^^^^^ + +Radio buttons allow users to select exactly one option from a defined radio group `(NcRadioGroup) `__ . It also has a button variant which displays the options as buttons. When there are many options, use a dropdown instead. + +.. image:: ../images/radio-group.png + :alt: Radio group Mail settings + + +.. _Action menus: + +Action menus +------------ + +Action menus `(NcActions) `__ are command menus attached to a trigger button. The trigger opens a popover with a list of +actions like "Rename", "Move", "Share", or "Delete". + +- The most common trigger for an action menu is an action button with a three-dot icon. In some apps the button uses a specific icon; for example, a paperclip icon is used for Talk's attachment menu. +- In lists where one or two actions are common and the rest are rare, the common actions can be shown inline, with the remaining actions in the menu. + +- Do keep menus short. A long list of unrelated commands is hard to scan. Split it up or group it. +- Do put destructive actions like "Delete" or "Remove" last and separated from the rest of the menu. +- Do not use an action menu to pick an item from a list, use a dropdown instead. + +.. image:: ../images/action-menu.png + :alt: Action menu in Talk + +.. _Empty content: + +Empty content +------------- + +Empty content `(NcEmptyContent) `__ is a message used when a view has no items to show. It has an icon, a heading, a short +description, and an optional button. + +- Do use helpful wording. "Drop files here to upload" is better than "No items". +- Do show a button with a helpful next step whenever possible like "Create event" and "Add a card". +- Do not use an empty content element while content is still loading. Use a skeleton screen while loading and the empty state only once the load finishes with nothing. +- Do not use empty content for error states. If the loading failed, show a recoverable error message with a retry option. + +.. image:: ../images/empty-content.png + :alt: Empty content in Collectives + +.. _Modals: + +Modals +------ + +Modals are overlays that demand the user's focused attention. In the component library there are two components: a dialog +`(NcDialog) `__ used for confirmations and short forms, and a modal +`(NcModal) `__ for custom content like viewers and slideshows. These components are used when there is a specific task or +information that the user needs to focus on. + +- The dialog component is commonly used for confirming a permanent action. Do use descriptive buttons for proceeding like "Save", "Move file", "Delete file". +- Do not use generic words in the buttons like "OK", especially when the action is destructive. +- Choose an appropriately sized dialog for your flow. if the dialog contains only small input fields, use a small dialog. +- Avoid opening a modal over another modal. + +.. image:: ../images/modal-calendar-settings.png + :alt: Modal containing settings for a calendar + +.. _Navigation: + +Navigation +---------- + +The app navigation `(NcAppNavigation) `__ is the left column of an app. It contains the +primary structure of the app like the list of mailboxes, boards, calendars, or folders. + +- A prominent "new" button `(NcAppNavigationNew) `__ is always at + the top of the navigation and carries out the most common create action for the app. For example, "New message" in Mail, "New event" in Calendar, "New conversation" in Talk. +- There can also be a search field at the top + (`NcAppNavigationSearch `__ ) which allows the user to search + through the items of the navigation. +- The body of the navigation is a flat list of items + (`NcAppNavigationItem `__). Each item can have a small action + menu at the end for actions like "Rename" or "Mark all as read", or a counter (for example, unread email count in Mail). +- Do group items under section headings + (`NcAppNavigationCaption `__) if there are many items or + different categories of items like "Calendars", "Meeting proposals", and "Appointment schedules" in Calendar. +- The bottom of the navigation is reserved for the settings entry + (`NcAppSettingsDialog `__) that opens the app's settings dialog. + +.. image:: ../images/navigation.png + :alt: Navigation in Files + +.. _Settings: + +Settings +-------- + +The settings dialog (`NcAppSettingsDialog `__) holds an app's per-user +preferences and opens from the cog at the bottom of the app navigation. + +- Inside the dialog, settings are organized into sections + (`NcAppSettingsSection `__) on the left. Each section should cover + one topic. If there are more than around ten sections, consider reorganizing them and removing some settings. +- Under each section are form boxes (`NcFormBox `__) containing the actual settings, so that settings look and feel the same + across every Nextcloud app. +- Settings can be grouped into a form group (`NcFormGroup `__) with an appropriate label. +- If the app has no per-user preferences to offer, the settings dialog can be omitted entirely. + +.. image:: ../images/settings.png + :alt: Settings in Talk + + +.. _Sidebar: + +Sidebar +------- + +The sidebar (`NcAppSidebar `__) can be used to show supporting information and actions for +an item. For example, Files uses a sidebar to show information about the selected file such as activity and comments. + +- The sidebar usually contains a header (`NcAppSidebarHeader `__) with + the title of the associated item and some metadata, and tabs + (`NcAppSidebarTab `__) for the various groups of information or actions. +- Do not use more than 3 tabs in the sidebar, the names of the tabs then start getting cut off. + +.. image:: ../images/sidebar.png + :alt: Sidebar for a folder in Files diff --git a/developer_manual/design/foundations.rst b/developer_manual/design/foundations.rst index 0e601372309..55ef59ee292 100644 --- a/developer_manual/design/foundations.rst +++ b/developer_manual/design/foundations.rst @@ -2,210 +2,191 @@ 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, for example Android, it would be a good idea to keep those in mind while designing your app. +.. _Colors: -For web apps, there is the `Vue library `_ and the `Penpot design kit `_. - -Color ------ - -`Penpot colors `_ - -Primary color -^^^^^^^^^^^^^ - -.. figure:: ../images/colour-primary.svg - :alt: Nextcloud primary color swatch showing blue #0082C9 - - #0082C9 - -While this is the primary color associated with Nextcloud and can be used to draw attention to an element, it is best to limit the usage of this to primary actions and other important elements. - -.. note:: - The primary color can be customized by admins through theming, but the default experience will be Nextcloud blue. If the primary color is themed to something very light like a shade of yellow, the text or header icons will be inverted to dark automatically. +Colors +------ -* On web: ``var(--color-primary-element)`` -* Android: uses default Material Design colors -* iOS: `systemFill `_ -* Desktop: `default Qt guidelines `_ +Primary colors +^^^^^^^^^^^^^^ -Background color -^^^^^^^^^^^^^^^^ +- ``--color-primary-element``: Primary colors are to be used for positive action buttons and active states. Otherwise use the primary color sparingly in the UI. Do not use the primary color for body + text. +- ``--color-primary-element-light``: Use the secondary color for less important buttons and highlighting elements in the UI. Do not use the secondary color for body text. .. list-table:: + :header-rows: 1 - * - .. figure:: ../images/colour-main-background.svg - :alt: Light theme background color swatch showing white #FFFFFF - - Background for light theme: #FFFFFF - - - .. figure:: ../images/colour-dark-theme-main-backgroud.svg - :alt: Dark theme background color swatch showing dark grey #181818 - - Background for dark theme: #181818 + * - Light theme + - Dark theme + * - .. image:: ../images/color-primary-light.png + :alt: Color swatch: --color-primary (Light) + - .. image:: ../images/color-primary-dark.png + :alt: Color swatch: --color-primary (Dark) + * - .. image:: ../images/color-primary-element-light-light.png + :alt: Color swatch: --color-primary-element-light (Light) + - .. image:: ../images/color-primary-element-light-dark.png + :alt: Color swatch: --color-primary-element-light (Dark) -Nextcloud apps have a light and a dark theme, with appropriately chosen colors for all elements. +Text colors +^^^^^^^^^^^ - -* On web: ``var(--color-main-background)`` -* Android: uses default Material Design colors -* iOS: `systemBackground `_ -* Desktop: `default Qt guidelines `_ - -Text color -^^^^^^^^^^ +- ``--color-main-text``: Most text that is not inside a component is the main text color. +- ``--color-text-maxcontrast``: Use this color for sublines, captions and any other kind of supporting text. .. list-table:: + :header-rows: 1 - * - .. figure:: ../images/colour-main-text.svg - :alt: Light theme text color swatch showing near-black #222222 - - Text in light theme: #222222 - - - .. figure:: ../images/colour-dark-theme-main-text.svg - :alt: Dark theme text color swatch showing light grey #D8D8D8 - - Text in dark theme: #D8D8D8 - -This is the main color for the text in light theme, and in dark theme. + * - Light theme + - Dark theme + * - .. image:: ../images/color-main-text-light.png + :alt: Color swatch: --color-main-text (Light) + - .. image:: ../images/color-main-text-dark.png + :alt: Color swatch: --color-main-text (Dark) + * - .. image:: ../images/color-text-maxcontrast-light.png + :alt: Color swatch: --color-text-maxcontrast (Light) + - .. image:: ../images/color-text-maxcontrast-dark.png + :alt: Color swatch: --color-text-maxcontrast (Dark) +Background colors +^^^^^^^^^^^^^^^^^ -* 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 `_ +- ``--color-main-background``: The background of the main content should be this color. +- ``--color-background-darker``: This can be used as a background color for containers inside the main content when visual contrast would be useful. Use sparingly to not overwhelm the UI. .. list-table:: + :header-rows: 1 + + * - Light theme + - Dark theme + * - .. image:: ../images/color-main-background-light.png + :alt: Color swatch: --color-main-background (Light) + - .. image:: ../images/color-main-background-dark.png + :alt: Color swatch: --color-main-background (Dark) + * - .. image:: ../images/color-background-dark-light.png + :alt: Color swatch: --color-background-dark (Light) + - .. image:: ../images/color-background-dark-dark.png + :alt: Color swatch: --color-background-dark (Dark) + +Border colors +^^^^^^^^^^^^^ - * - .. figure:: ../images/colour-text-maxcontrast.svg - :alt: Light theme secondary text color swatch showing grey #767676 - - Secondary text in light theme: #767676 - - - .. figure:: ../images/colour-dark-theme-text-maxcontrast.svg - :alt: Dark theme secondary text color swatch showing medium grey #8C8C8C - - Secondary text in dark theme: #8C8C8C - - -In addition, a softer color is used for secondary text like sublines, timestamps, and similar. - - -* On web:``var(--color-text-maxcontrast)`` -* Android: uses default Material Design color "medium emphasis" -* iOS: `secondaryLabel `_ -* Desktop: `default Qt guidelines `_ - -Status and indicators -^^^^^^^^^^^^^^^^^^^^^ +- ``--color-border``: Use this color for borders of elements like cards, and for separator lines. +- ``--color-border-maxcontrast``: Use this color when there is a stronger contrast needed. .. list-table:: + :header-rows: 1 + + * - Light theme + - Dark theme + * - .. image:: ../images/color-border-light.png + :alt: Color swatch: --color-border (Light) + - .. image:: ../images/color-border-dark.png + :alt: Color swatch: --color-border (Dark) + * - .. image:: ../images/color-border-maxcontrast-light.png + :alt: Color swatch: --color-border-maxcontrast (Light) + - .. image:: ../images/color-border-maxcontrast-dark.png + :alt: Color swatch: --color-border-maxcontrast (Dark) + +Status colors +^^^^^^^^^^^^^ - * - .. figure:: ../images/color-info.svg - :alt: Info status color swatch showing blue #006AA3 - - Info: #006AA3 - - - .. figure:: ../images/color-success.svg - :alt: Success status color swatch showing green #46BA61 - - Success: #46BA61 +- ``--color-info``: This color is used for denoting informational elements like info cards. +- ``--color-success``: Used for positive actions like a "Join call" button, and for indicating an action is successful. +- ``--color-error``: This color is used to indicate a destructive action like "Delete conversation" and when an action has failed. +- ``--color-warning``: This is used to warn the user about an action that may be dangerous. - - .. figure:: ../images/color-error.svg - :alt: Error status color swatch showing red #E9322D +.. list-table:: + :header-rows: 1 + + * - Light theme + - Dark theme + * - .. image:: ../images/color-info-light.png + :alt: Color swatch: --color-info (Light) + - .. image:: ../images/color-info-dark.png + :alt: Color swatch: --color-info (Dark) + * - .. image:: ../images/color-success-light.png + :alt: Color swatch: --color-success (Light) + - .. image:: ../images/color-success-dark.png + :alt: Color swatch: --color-success (Dark) + * - .. image:: ../images/color-warning-light.png + :alt: Color swatch: --color-warning (Light) + - .. image:: ../images/color-warning-dark.png + :alt: Color swatch: --color-warning (Dark) + * - .. image:: ../images/color-error-light.png + :alt: Color swatch: --color-error (Light) + - .. image:: ../images/color-error-dark.png + :alt: Color swatch: --color-error (Dark) + +Assistant colors +^^^^^^^^^^^^^^^^ - Error: #E9322D +- ``--color-element-assistant``: A special color used for elements using AI. Using this color informs the user that the info they are seeing may be AI-generated or that they are interacting with an + AI. - - .. figure:: ../images/color-warning.svg - :alt: Warning status color swatch showing amber #ECA700 +.. list-table:: + :header-rows: 1 - Warning: #ECA700 + * - Light theme + - Dark theme + * - .. image:: ../images/color-element-assistant-light.png + :alt: Color swatch: --color-element-assistant (Light) + - .. image:: ../images/color-element-assistant-dark.png + :alt: Color swatch: --color-element-assistant (Dark) -Interface elements associated with a status like info, success, error, or warning may also be colored to communicate the action better. +.. _Typography: -While interface elements like buttons are colored differently depending on their action, the color of the text in that element is almost always either of the main text colors, that is light or dark. +Typography and wording +---------------------- +Fonts +^^^^^ -* On web: +- To ensure compatibility with different platforms, Nextcloud apps always use the native system font. +- Use bold font weight for emphasis and unread items +- Do not use italics or upper case as they are less legible. - * Info color: ``var(--color-info)`` - * Success color: ``var(--color-success)`` - * Warning color: ``var(--color-warning)`` - * Error color: ``var(--color-error)`` +Font sizes +^^^^^^^^^^ -* Android: Material Design guidelines -* iOS: `Apple HIG colors `_ +- ``--defalut-font-size``\ (15px): For body text +- ``--font-size-small`` (13px): For nonessential information +- Other than those 2 font sizes, 20px is also often used for headings, and 24px for titles. - * success: systemGreen - * error: systemRed +Wording +^^^^^^^ -* Desktop: `default Qt guidelines `_ +- Wording guidelines have been moved to :doc:`the writing section `. -Typography ----------- +.. _Borders: -`Penpot typography `_ +Borders +------- -To ensure compatibility with different platforms, Nextcloud apps always use the native system font. +Border radii +^^^^^^^^^^^^ -For legibility, make sure that the text in your content uses: +- ``--border-radius-small`` (4px): Used for small elements like tags and cards. +- ``--border-radius-element`` (8px): Standard border radius used for buttons. navigation items and more. +- ``--border-radius-container`` (12px): Used for larger elements such as dialogs. +- ``--border-radius-pill`` (100px): Used to convert any small element into a pill-shape. -* **Bold** for emphasis -* A line height between 130% and 150% -* The default tracking of the font -* No *italics* or UPPER CASE as these text styles are less legible +.. _Element sizes and spacing: -The text sizes for the different platforms are: +Element sizes and spacing +------------------------- +- ``--default-grid-baseline``\ (4px): This is the base multiplier for all spacing. Use whole number multiples of this variable for all spacing, never raw numbers. +- ``--default-clickable-area``\ (34px): This should be the minimum width and height of most clickable elements like buttons, inputs, cards, etc. +- ``--clickable-area-small``\ (24px): This can be used for smaller elements like chips, or when there is limited space. -* Web: 16px 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 `_ +.. _Icons: Icons ----- -`Penpot 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 Symbols (not Material Icons, and 20 px default outlined) `_ 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. Most use an app icon from Material Symbols as well though to keep consistency. - -Make sure to: - -* Not overuse icons -* When possible, use text together with icons so it’s clear what they refer to -* For special cases like warnings, combine the icon with color to enhance its visibility - -Naming ------- - -To be immediately understandable, we choose app names which are generic and easily translatable. Additionally, they are short and easily fit in the top navigation without being cut off. - -Files, Contacts, Calendar, and Mail do not need further explanation, which is why we recommend to choose a self-explanatory app name. - -Further good examples of this: Notes, Bookmarks, Maps, Forms, Tasks, Music. - -Wording -------- - -The wording and language in your app sets the tone and approachability of your app. - - -* Nextcloud should always be written out, and only with a capital N. Not "NextCloud" or "Nc". -* Be friendly and approachable, not condescending. -* Use understandable language, not technical jargon. For example, "link" is much better than "URL", and explaining errors is better than showing error codes. -* Don’t write in ALL CAPS, as it is not as readable and comes off as shouting and aggressive. Also use Sentence case and not Capital Case, with the exception of product names like Nextcloud Talk, Nextcloud Hub, etc. -* We are a community, so better write "We are happy to announce" instead of "I am happy to announce". -* If your app content is empty, it can be helpful to add an engaging message. "Add or import your first bookmark!" is much nicer than "No bookmarks yet". -* Try to avoid using "my" or "your" like in "My files" or "Your files", instead using "All files". For longer sentences where it cannot be avoided, use "your", never "my". -* Use gender neutral language. This `international guide to gender-inclusive writing `_ contains info and examples on gender neutral wording for different languages. -* Use full names instead of only first names while addressing the person using your app. -* For any "Delete" action, give context to what it will delete, like "Delete conversation" or "Delete user" so that it is clear specifically for this destructive action. -* Keep language short and concise, and keep in mind that it should be easily translatable. -* Make sure to spellcheck anything you write. +Icons can be used to communicate the intent of an action, or to provide visual interest to an element. On the browser always use Material Symbols (outlined, 20px). +- Never use a custom icon except for the icon of the app itself. Still, most apps use an app icon from Material Symbols to keep consistency. +- When possible, use text together with icons so it’s clear what they refer to. +- Elements that contain AI-generated content should have a clear indication that they are AI-generated in the form of a written disclaimer or by the use of the Assistant icon ('creation' in Material Symbols) in the Assistant color. diff --git a/developer_manual/design/index.rst b/developer_manual/design/index.rst index 6b86074652e..969e22bf553 100644 --- a/developer_manual/design/index.rst +++ b/developer_manual/design/index.rst @@ -1,13 +1,12 @@ -============================== -Interface & interaction design -============================== +====== +Design +====== .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - introduction - writing - foundations - layout - layoutcomponents - atomiccomponents + introduction + foundations + writing + components + layout diff --git a/developer_manual/design/introduction.rst b/developer_manual/design/introduction.rst index bd9962fe835..89b9105e6b0 100644 --- a/developer_manual/design/introduction.rst +++ b/developer_manual/design/introduction.rst @@ -1,28 +1,31 @@ -.. _navigation: - ============ Introduction ============ -Nextcloud design and brand standards are used to maintain the identity of Nextcloud apps. -If you're a developer who wants to create or contribute to a Nextcloud app, following this guide will make sure your app looks like it belongs to the Nextcloud family. +Nextcloud design and brand standards are used to maintain the identity of Nextcloud apps. If you’re a developer who wants to create or contribute to a Nextcloud app, following this guide will make +sure your app looks like it belongs to the Nextcloud family. -Each Nextcloud app is unique and different, but there are a couple of standards that are used in everything. -All Nextcloud apps are built keeping some basic principles in mind. +Each Nextcloud app is unique and different, but all Nextcloud apps are built keeping some basic principles in mind. +- Software should be quick and easy to use. Show only the most important elements. Secondary elements can be showed on hover or via an “Advanced” function. +- Nextcloud apps are built for everybody. Use a friendly tone with simple sentences. Make sure your app is responsive and runs on all browsers and devices. +- Accessibility: Make sure to regularly test accessibility, for example with `Lighthouse `__, `WAVE `__, and `Google + Accessibility Scanner `__. Aim for WCAG Level AA. You can learn more about accessibility standards in + the `W3 website `__ +- Software should work. Only put features into main branch when they are complete. It is better to not have a feature instead of having one that works poorly. +- Software should get out of the way. Do things automatically instead of offering configuration options. When people ask for a setting, find out what the root of the problem is and fix that instead. + Also read `Choosing our Preferences `__. +- People’s data is sacred. Provide undo for most operations and optionally a confirmation for bigger more complex operations, but be careful about confirmations `as they might be + dismissed `__. +- People deserve to know when they are interacting with AI. AI-generated items must have an indication that they were AI-generated and in many places in Nextcloud this is done through the use of the + color and iconography. +- The state of the application should be clear. If something loads, provide feedback. Reactions should be quick, ideally under 100ms as per `response time + limits `__. +- The state of the application should be clear. If something loads, provide feedback. +- Regularly reset your installation to see what the first-run experience is like, and improve it. +- Ideally do `usability testing `__ to know how people use the software. Testing with 5 users is enough to identify most of your problems. -* Software should be quick and easy to use. Show only the most important elements. Secondary elements can be showed on hover or via an "Advanced" function. -* Nextcloud apps are built for everybody. Use a friendly tone with simple sentences. Make sure your app is responsive and runs on all browsers and devices. -* Accessibility: Make sure to regularly test accessibility, for example with `Lighthouse `_\ , `WAVE `_\ , and `Google Accessibility Scanner `_. Aim for WCAG Level AA. You can learn more about accessibility standards in the `W3 website `_ -* Software should work. - Only put features into main branch when they are complete. It is better to not have a feature instead of having one that works poorly. -* Software should get out of the way. - Do things automatically instead of offering configuration options. When people ask for a setting, find out what the root of the problem is and fix that instead. - Also read `Choosing our Preferences `_. -* People’s data is sacred. Provide undo for most operations and optionally a confirmation for bigger more complex operations, but be careful about confirmations `as they might be dismissed `_. -* The state of the application should be clear. If something loads, provide feedback. Reactions should be quick, ideally under 100ms as per `response time limits `_\. -* The state of the application should be clear. If something loads, provide feedback. -* Regularly reset your installation to see what the first-run experience is like, and improve it. -* Ideally do `usability testing `_ to know how people use the software. Testing with 5 users is enough to identify most of your problems. +For further UX principles, read `Alex Faaborg from Mozilla `__, and the `GNOME Human Interface Guidelines `__ -For further UX principles, read `Alex Faaborg from Mozilla `_\ , and the `GNOME Human Interface Guidelines `_ +This guide mainly serves as guidelines for designing for Nextcloud on the browser. For Android, closely follow the latest `Material Design guidelines `__ and for iOS, the +`Apple Human Interface Guidelines `__. diff --git a/developer_manual/design/layout.rst b/developer_manual/design/layout.rst index 40c43989d79..f88797d7505 100644 --- a/developer_manual/design/layout.rst +++ b/developer_manual/design/layout.rst @@ -1,74 +1,15 @@ +====== Layout ====== -These layout guidelines mainly focus on our web interface. On Android and iOS we closely follow the platform guidelines, namely `Material Design `_\ , and `Apple Human Interface Guidelines `_. - -While deciding how you want your app to look, there are a number of factors to consider: - - -* Consistency with other Nextcloud apps -* Responsiveness for different browsers, browser sizes and devices -* Typical interface patterns in other similar apps in the market - -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: -`Penpot empty template `_ - -* Navigation → content → sidebar (and a couple of variations of it, e.g. without the sidebar) -* Navigation → list → content - -Navigation → Content → Sidebar ------------------------------- - -`Penpot Files layout `_ - -.. image:: ../images/files-layout.png - :alt: Files layout - - -This layout is used in Files, Calendar, Deck, and Tasks. - -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. - -On mobile, the content is shown by default. The navigation and sidebar are expandable using icons on the sides. - - - -Special case: no sidebar -^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. image:: ../images/activity-layout.png - :alt: Activity layout - - -Typically, a sidebar is used to show more information about an item. Sometimes this is not necessary as in the case of Activities. Then, the layout will have only a navigation and the main content. - -Special case: list in navigation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -`Penpot Talk layout `_ - -.. image:: ../images/talk-layout.png - :alt: Talk layout - - -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 ---------------------------- - - -.. image:: ../images/mail-layout.png - :alt: Mail layout - - -This layout is used in Mail and Contacts. +Generally most Nextcloud apps have a navigation on the left, and a content area, often depending on the typical layout patterns for other similar apps in the market. Some examples of common layouts: -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. +- Navigation → Content: This layout can be seen in Files, Talk, Calendar, Photos, and Deck. The main content depends on what is selected in the navigation. Often this type of layout has a sidebar as well, which contains details about an item in the main content. -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. + .. image:: ../images/files-layout.png + :alt: Files layout with navigation and content -On mobile, the list is shown by default. The navigation is expandable using an icon in the top left, and the content can be opened by selecting an entry from the list. Navigation back up from a content can be done via a "Back" arrow action in the top left, in place of the navigation icon. +- Navigation → List → Content: This layout can be seen in Mail, Contacts and Collectives. The selected item in the navigation determines what is shown in the list, and the selected item in the list determines the main content. For example in Collectives, the navigation contains the list of collectives, the list contains the list of pages inside the selected collective, and the main content contains the contents of the selected page. + .. image:: ../images/contacts-layout.png + :alt: Contacts layout with navigation, list and content diff --git a/developer_manual/design/layoutcomponents.rst b/developer_manual/design/layoutcomponents.rst deleted file mode 100644 index 7edb1907ba3..00000000000 --- a/developer_manual/design/layoutcomponents.rst +++ /dev/null @@ -1,198 +0,0 @@ -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 `_. - -Navigation ----------- - -`Vue component for the app navigation `_. - -`Penpot navigation items `_ - -.. image:: ../images/contacts-navigation.png - :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: - - -* Main action button -* Navigation entries -* New item element (optional) -* Settings menu (optional) - -Main action button -^^^^^^^^^^^^^^^^^^ - -`Navigation AppNew Vue component `_. - -`Penpot buttons `_ - -.. image:: ../images/mail-primary-action-button.png - :alt: Mail primary action button.png - - -For most apps, the first element in the navigation is the main action button. For example: - - -* Mail has a "New message" button to compose a new mail -* Contacts has a "New contact" button -* in Talk, you can create a new conversation -* in Calendar there is a "New event" button -* Forms has a "New form" action - -Navigation entries -^^^^^^^^^^^^^^^^^^ - -`Navigation entries Vue component `_. - -`Penpot navigation items `_ - -.. image:: ../images/mail-navigation-entries.png - :alt: Mail navigation entries - - -The different sections of your app would be organized by different navigation entries. For example, the Files app contains different categories of files in its navigation, and the Contacts app contains different groups and circles. When creating your navigation, make sure that the entries in this section: - - -* are easy to understand -* are frequently used -* are organized -* do not change positions frequently - -Top-level navigation entries ideally have a suitable icon left next to them. Optionally they may also have: - - -* 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. - -New item element -^^^^^^^^^^^^^^^^ - -`New item Vue component `_. - -.. image:: ../images/new-item-element.gif - :alt: Add new item element - - -Users can easily create a new item with a suitable name by using the new item element. This element can be used in the navigation, as in the case of Deck, or in the content. Other apps which use this: - - -* "Create a new group" in Contacts -* "Add mailbox" in Mail -* "New calendar" in Calendar - -.. _Settings: - -Settings -^^^^^^^^ - -`Settings Vue component `_. - -`Penpot modals `_ - -.. image:: ../images/talk-settings-modal.png - :alt: Talk settings modal - - -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, if they are not disabled by the user. -The global javascript function ``OCP.Accessibility.disableKeyboardShortcuts()`` can be used to check that. - -Also see: :ref:`Modal` - -.. _List: - -List item ----------- - -`List item Vue component `_. - -`Penpot list item `_ - -.. image:: ../images/list-item.gif - :alt: Talk list - - -List items can be used to display a collection of elements from which one can be selected. List items are seen in the left list of chats in Talk, as well as the list of messages in Mail and the list of contacts in Contacts. List items usually have an avatar or a descriptive icon, a main line and optionally a subline. A list item may also contain: - - -* 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 - -.. _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 `appContent Vue component `_ should be used for the content of your app. - -Views -^^^^^ - -Some apps offer different views on their content so people can pick a preference which should be remembered automatically. It is important to consider which should be the default one and whether to have different views at all, since most people do not change the default. - - -* Files (web, Android & iOS), Bookmarks: List view or grid view -* Calendar: Month view, week view, day view, list view / agenda -* Talk (web, Android & iOS): Speaker view and grid view in a call - -The content is also the section where you can quickly explain to people how to get started with your app, for example using an :ref:`Empty content` atomic component. - -Sizing -^^^^^^ - -For text-based apps like chat, mails, and other paragraphs of text, the width of the content should not go over a certain width to facilitate readability. In Nextcloud Text for example the width is limited to 650px and we do it similarly in Mail and Talk, even if the screen size is larger. - -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. - -Spacing between elements in your app should be in multiples of 4px. - -.. _Sidebar: - -Sidebar -------- - -`Sidebar Vue component `_. - -`Penpot 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. - -Commonly used tabs in the sidebar are: - - -Details -^^^^^^^ - -`Sidebar Tabs Vue component `_. - -`Penpot sidebar `_ - -.. 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 :ref:`Input fields` in the atomic components section for more details about the various input fields that can be used here. - -Activity -^^^^^^^^ - -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. - -If there is the possibility to restore earlier versions, this can be integrated using a 3-dot action menu on any past activity. - -Sharing -^^^^^^^ - -.. image:: ../images/sidebar-sharing.png - :alt: Proposed sharing tab in the sidebar - -The sharing tab allows users to share the selected item with others in different ways. An item can be shared with specific users or groups on the instance by simply selecting whom you want to share with. Another very simple way of sharing is through a share link, which can optionally also be configured using the "Advanced settings" option. diff --git a/developer_manual/html_css_design/icons.rst b/developer_manual/html_css_design/icons.rst index 62b0070876e..dd720092ab1 100644 --- a/developer_manual/html_css_design/icons.rst +++ b/developer_manual/html_css_design/icons.rst @@ -1,6 +1,6 @@ .. sectionauthor:: John Molakvoæ .. codeauthor:: John Molakvoæ -.. _icons: +.. _iconsold: ===== Icons diff --git a/developer_manual/images/action-menu.png b/developer_manual/images/action-menu.png index fa23b004726..defe0d6d127 100644 Binary files a/developer_manual/images/action-menu.png and b/developer_manual/images/action-menu.png differ diff --git a/developer_manual/images/avatar.png b/developer_manual/images/avatar.png new file mode 100644 index 00000000000..00a2626ffe5 Binary files /dev/null and b/developer_manual/images/avatar.png differ diff --git a/developer_manual/images/buttons.png b/developer_manual/images/buttons.png new file mode 100644 index 00000000000..a66d774548e Binary files /dev/null and b/developer_manual/images/buttons.png differ diff --git a/developer_manual/images/checkboxes.png b/developer_manual/images/checkboxes.png index 5567c21baaf..91d8108387d 100644 Binary files a/developer_manual/images/checkboxes.png and b/developer_manual/images/checkboxes.png differ diff --git a/developer_manual/images/chip.png b/developer_manual/images/chip.png new file mode 100644 index 00000000000..e7aec78c338 Binary files /dev/null and b/developer_manual/images/chip.png differ diff --git a/developer_manual/images/color-background-dark-dark.png b/developer_manual/images/color-background-dark-dark.png new file mode 100644 index 00000000000..18600593008 Binary files /dev/null and b/developer_manual/images/color-background-dark-dark.png differ diff --git a/developer_manual/images/color-background-dark-light.png b/developer_manual/images/color-background-dark-light.png new file mode 100644 index 00000000000..c471d51e197 Binary files /dev/null and b/developer_manual/images/color-background-dark-light.png differ diff --git a/developer_manual/images/color-border-dark.png b/developer_manual/images/color-border-dark.png new file mode 100644 index 00000000000..cb4cf865f33 Binary files /dev/null and b/developer_manual/images/color-border-dark.png differ diff --git a/developer_manual/images/color-border-light.png b/developer_manual/images/color-border-light.png new file mode 100644 index 00000000000..2d20751075e Binary files /dev/null and b/developer_manual/images/color-border-light.png differ diff --git a/developer_manual/images/color-border-maxcontrast-dark.png b/developer_manual/images/color-border-maxcontrast-dark.png new file mode 100644 index 00000000000..0dac56ad43b Binary files /dev/null and b/developer_manual/images/color-border-maxcontrast-dark.png differ diff --git a/developer_manual/images/color-border-maxcontrast-light.png b/developer_manual/images/color-border-maxcontrast-light.png new file mode 100644 index 00000000000..becb1fc8139 Binary files /dev/null and b/developer_manual/images/color-border-maxcontrast-light.png differ diff --git a/developer_manual/images/color-element-assistant-dark.png b/developer_manual/images/color-element-assistant-dark.png new file mode 100644 index 00000000000..d047057fc52 Binary files /dev/null and b/developer_manual/images/color-element-assistant-dark.png differ diff --git a/developer_manual/images/color-element-assistant-light.png b/developer_manual/images/color-element-assistant-light.png new file mode 100644 index 00000000000..0cf4949f532 Binary files /dev/null and b/developer_manual/images/color-element-assistant-light.png differ diff --git a/developer_manual/images/color-error-dark.png b/developer_manual/images/color-error-dark.png new file mode 100644 index 00000000000..8d16862bbde Binary files /dev/null and b/developer_manual/images/color-error-dark.png differ diff --git a/developer_manual/images/color-error-light.png b/developer_manual/images/color-error-light.png new file mode 100644 index 00000000000..8bd619e8f98 Binary files /dev/null and b/developer_manual/images/color-error-light.png differ diff --git a/developer_manual/images/color-info-dark.png b/developer_manual/images/color-info-dark.png new file mode 100644 index 00000000000..cf37677e25e Binary files /dev/null and b/developer_manual/images/color-info-dark.png differ diff --git a/developer_manual/images/color-info-light.png b/developer_manual/images/color-info-light.png new file mode 100644 index 00000000000..1aaa78b988e Binary files /dev/null and b/developer_manual/images/color-info-light.png differ diff --git a/developer_manual/images/color-main-background-dark.png b/developer_manual/images/color-main-background-dark.png new file mode 100644 index 00000000000..f6d7ce0498e Binary files /dev/null and b/developer_manual/images/color-main-background-dark.png differ diff --git a/developer_manual/images/color-main-background-light.png b/developer_manual/images/color-main-background-light.png new file mode 100644 index 00000000000..0bb1e6e0f62 Binary files /dev/null and b/developer_manual/images/color-main-background-light.png differ diff --git a/developer_manual/images/color-main-text-dark.png b/developer_manual/images/color-main-text-dark.png new file mode 100644 index 00000000000..0de389435a2 Binary files /dev/null and b/developer_manual/images/color-main-text-dark.png differ diff --git a/developer_manual/images/color-main-text-light.png b/developer_manual/images/color-main-text-light.png new file mode 100644 index 00000000000..038ecd46fcd Binary files /dev/null and b/developer_manual/images/color-main-text-light.png differ diff --git a/developer_manual/images/color-picker.png b/developer_manual/images/color-picker.png new file mode 100644 index 00000000000..ce1d7165f9d Binary files /dev/null and b/developer_manual/images/color-picker.png differ diff --git a/developer_manual/images/color-primary-dark.png b/developer_manual/images/color-primary-dark.png new file mode 100644 index 00000000000..9b71144531f Binary files /dev/null and b/developer_manual/images/color-primary-dark.png differ diff --git a/developer_manual/images/color-primary-element-light-dark.png b/developer_manual/images/color-primary-element-light-dark.png new file mode 100644 index 00000000000..dabc9a0e555 Binary files /dev/null and b/developer_manual/images/color-primary-element-light-dark.png differ diff --git a/developer_manual/images/color-primary-element-light-light.png b/developer_manual/images/color-primary-element-light-light.png new file mode 100644 index 00000000000..36cf9fafdd9 Binary files /dev/null and b/developer_manual/images/color-primary-element-light-light.png differ diff --git a/developer_manual/images/color-primary-light.png b/developer_manual/images/color-primary-light.png new file mode 100644 index 00000000000..e539c8e9b51 Binary files /dev/null and b/developer_manual/images/color-primary-light.png differ diff --git a/developer_manual/images/color-success-dark.png b/developer_manual/images/color-success-dark.png new file mode 100644 index 00000000000..841943b0686 Binary files /dev/null and b/developer_manual/images/color-success-dark.png differ diff --git a/developer_manual/images/color-success-light.png b/developer_manual/images/color-success-light.png new file mode 100644 index 00000000000..123920f351b Binary files /dev/null and b/developer_manual/images/color-success-light.png differ diff --git a/developer_manual/images/color-text-maxcontrast-dark.png b/developer_manual/images/color-text-maxcontrast-dark.png new file mode 100644 index 00000000000..ee85c698ec3 Binary files /dev/null and b/developer_manual/images/color-text-maxcontrast-dark.png differ diff --git a/developer_manual/images/color-text-maxcontrast-light.png b/developer_manual/images/color-text-maxcontrast-light.png new file mode 100644 index 00000000000..39ef5fbdb33 Binary files /dev/null and b/developer_manual/images/color-text-maxcontrast-light.png differ diff --git a/developer_manual/images/color-warning-dark.png b/developer_manual/images/color-warning-dark.png new file mode 100644 index 00000000000..33e02ba3417 Binary files /dev/null and b/developer_manual/images/color-warning-dark.png differ diff --git a/developer_manual/images/color-warning-light.png b/developer_manual/images/color-warning-light.png new file mode 100644 index 00000000000..95079e163d2 Binary files /dev/null and b/developer_manual/images/color-warning-light.png differ diff --git a/developer_manual/images/contacts-layout.png b/developer_manual/images/contacts-layout.png new file mode 100644 index 00000000000..3ea1c36ecbc Binary files /dev/null and b/developer_manual/images/contacts-layout.png differ diff --git a/developer_manual/images/counter-bubble.png b/developer_manual/images/counter-bubble.png new file mode 100644 index 00000000000..63d836e106e Binary files /dev/null and b/developer_manual/images/counter-bubble.png differ diff --git a/developer_manual/images/datetime-picker.png b/developer_manual/images/datetime-picker.png new file mode 100644 index 00000000000..39a0a03b74d Binary files /dev/null and b/developer_manual/images/datetime-picker.png differ diff --git a/developer_manual/images/dropdown.png b/developer_manual/images/dropdown.png new file mode 100644 index 00000000000..0977d2eee7d Binary files /dev/null and b/developer_manual/images/dropdown.png differ diff --git a/developer_manual/images/emoji-picker.png b/developer_manual/images/emoji-picker.png new file mode 100644 index 00000000000..7083482de14 Binary files /dev/null and b/developer_manual/images/emoji-picker.png differ diff --git a/developer_manual/images/empty-content.png b/developer_manual/images/empty-content.png index 969fd8f6ec7..e69d90a0b4d 100644 Binary files a/developer_manual/images/empty-content.png and b/developer_manual/images/empty-content.png differ diff --git a/developer_manual/images/file-picker.png b/developer_manual/images/file-picker.png new file mode 100644 index 00000000000..4bc08241ac1 Binary files /dev/null and b/developer_manual/images/file-picker.png differ diff --git a/developer_manual/images/files-layout.png b/developer_manual/images/files-layout.png index c4fc9c40b43..5dee5e2c22a 100644 Binary files a/developer_manual/images/files-layout.png and b/developer_manual/images/files-layout.png differ diff --git a/developer_manual/images/list-item.png b/developer_manual/images/list-item.png new file mode 100644 index 00000000000..0fe8ecfb472 Binary files /dev/null and b/developer_manual/images/list-item.png differ diff --git a/developer_manual/images/modal-calendar-settings.png b/developer_manual/images/modal-calendar-settings.png new file mode 100644 index 00000000000..67c6fe95b40 Binary files /dev/null and b/developer_manual/images/modal-calendar-settings.png differ diff --git a/developer_manual/images/navigation.png b/developer_manual/images/navigation.png index 48502fbdfca..856646cf453 100644 Binary files a/developer_manual/images/navigation.png and b/developer_manual/images/navigation.png differ diff --git a/developer_manual/images/notecard.png b/developer_manual/images/notecard.png new file mode 100644 index 00000000000..f25d09a6e6d Binary files /dev/null and b/developer_manual/images/notecard.png differ diff --git a/developer_manual/images/radio-group.png b/developer_manual/images/radio-group.png new file mode 100644 index 00000000000..396d8eb688b Binary files /dev/null and b/developer_manual/images/radio-group.png differ diff --git a/developer_manual/images/richcontent.png b/developer_manual/images/richcontent.png new file mode 100644 index 00000000000..bb5e90eefdd Binary files /dev/null and b/developer_manual/images/richcontent.png differ diff --git a/developer_manual/images/settings.png b/developer_manual/images/settings.png index 2e6827438c5..cbc7dba0ea8 100644 Binary files a/developer_manual/images/settings.png and b/developer_manual/images/settings.png differ diff --git a/developer_manual/images/sidebar.png b/developer_manual/images/sidebar.png new file mode 100644 index 00000000000..10d016d50d9 Binary files /dev/null and b/developer_manual/images/sidebar.png differ diff --git a/developer_manual/images/text-fields.png b/developer_manual/images/text-fields.png new file mode 100644 index 00000000000..2032d96849c Binary files /dev/null and b/developer_manual/images/text-fields.png differ diff --git a/developer_manual/images/timezone-picker.png b/developer_manual/images/timezone-picker.png new file mode 100644 index 00000000000..0420b4dc295 Binary files /dev/null and b/developer_manual/images/timezone-picker.png differ diff --git a/developer_manual/images/toggles.png b/developer_manual/images/toggles.png new file mode 100644 index 00000000000..681a61d3ad6 Binary files /dev/null and b/developer_manual/images/toggles.png differ diff --git a/developer_manual/images/user-bubble.png b/developer_manual/images/user-bubble.png new file mode 100644 index 00000000000..6ddd51d8ca7 Binary files /dev/null and b/developer_manual/images/user-bubble.png differ