diff --git a/source/img/HIGPatternIconsAndText.png b/source/img/HIGPatternIconsAndText.png new file mode 100644 index 0000000..d1caf39 Binary files /dev/null and b/source/img/HIGPatternIconsAndText.png differ diff --git a/source/index.rst b/source/index.rst index 8aec641..987b45e 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,97 +1,98 @@ .. KDE HIG documentation master file, created by sphinx-quickstart on Tue Feb 6 13:29:47 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. KDE Human Interface Guidelines (Desktop Platform) ================================================= .. toctree:: :caption: Contents: :titlesonly: introduction/vision layout/index style/index components/index + patterns/iconandtext resources/contribute .. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` The Classic KDE Human Interface Guidelines (HIG) offer application designers and developers a set of recommendations for designing and developing user interfaces for QWidget-based, desktop-only applictions. Their aim is to improve the experience for users by making application interfaces more consistent and hence more intuitive and learnable. For applications which are supposed to run on both desktop and mobile systems, consult the [[../KirigamiHIG | Kirigami Human Interface Guidelines (HIG)]] Getting Started --------------- * :doc:`introduction/vision` - The overall vision and principles that guide the design and development of user interfaces for KDE software. * :ref:`Concept` - Creating a project vision, determining the users, and the scenarios of use. * :ref:`Organization` - Guidelines on how an application’s content and functionality are ordered and categorized. * :ref:`Architecture` Architecture of KDE * :ref:`Contribute` Contribute to the HIG]] Behaviour --------- This section contains guidelines for application behaviour. * :ref:`ViewingAndNavigation` Guidelines on controls and patterns to use for viewing, navigating and performing actions on application content. * :ref:`EditingAndManipulation` Guidelines on controls and patterns to use for selection and input. * :ref:`UserAssistance` Guidelines on tooltips, notifications, messages and help. * :ref:`Patterns` Patterns - Guidelines on how to use controls in different combinations to accomplish specific behaviors. Presentation ------------ Presentation deals with the visual design of the user interface. * :ref:`Layout` Guidelines regarding the placement and ordering of onscreen elements. Includes guidance on layout patterns, alignment, size and spacing. * :ref:`Style` Guidelines on the use of colour, icon design and the typography to communicate with a consistent visual vocabulary. * :ref:`Text` Guidelines for the written, language-based elements of the interface. Includes guidelines on wording, capitalization and localization. * :doc:`style/typography` Tools and Resources ------------------- The following tools and resources are offered to help with following these guidelines. * :ref:`ControlsList` A complete listing of all user interface controls and their guidelines in alphabetical order. * :ref:`MockupToolkit` Includes UI controls stencils, color swatches and fonts to help create the visual design your application. * :ref:`About` Learn more about the philosophy behind the KDE HIG. * [http://forum.kde.org/viewforum.php?f=285 Visual Design Group forum] - Ask for help and share your design ideas. Quick index for the new mobile-oriented HIG (work in progress) -------------------------------------------------------------- Drawers & FAB ^^^^^^^^^^^^^ * :ref:`GlobalDrawer` * :ref:`ContextDrawer` * :ref:`FloatingActionButton` * :ref:`QuickContentActions` Navigation ^^^^^^^^^^ * :ref:`ViewsByColumns` * :ref:`ContentsFilter` * :ref:`Views-by-tabs` Editing ^^^^^^^ * :ref:`RearrangeListItems` | Rearrange list's items]] App settings ^^^^^^^^^^^^ * :ref:`VBCtoSettings` | Views-by-columns approach applied to settings]] Cross-apps interactions ----------------------- * :ref:`SharingContents` | Sharing contents to an other app]] Complete app examples --------------------- * App store (to be applied to Muon Mobile) * E-mail client * Media player diff --git a/source/layout/units.rst b/source/layout/units.rst index c14d5e8..1b25f3d 100644 --- a/source/layout/units.rst +++ b/source/layout/units.rst @@ -1,210 +1,218 @@ Units & measurements ==================== - + Purpose ------- This pages gives an overview about different units used in KDE and Plasma Pixel ----- A (physical) pixel or dot is a physical point in a raster image, or the smallest addressable element in an all points addressable display -device. +device. .. caution:: Be careful not to confuse it with DPI independent pixels DPI - pixels per inch --------------------- Pixel density is the number of (physical) pixels or dots that fit into an inch. Different screens have different DPI. screen density = screen width (or height) in pixels / screen width (or height) in inches .. figure:: /img/Pixel.qml.png :scale: 50 % :alt: Different DPIs on desktop and mobile - + Different DPIs on desktop and mobile DPI is often used interchangeably with PPI, pixel per inch. .. hint:: - |designicon| Don't confuse this with the DPI setting in photoshop, krita, ... . For mockups you can just ignore this setting or choose a what ever value you like. + |designicon| Don't confuse this with the DPI setting in photoshop, krita, ... . For mockups you can just ignore this setting or choose a what ever value you like. PPI / DPI independent pixels ---------------------------- A DPI independet pixel is scaled to look uniform on any screen regardless of the DPI. A lot of platforms, eg iOS, Android, the Web, replaced the old (physical) px with a DPI px. So most the time you read about pixel/px they actually talk about DPI independent pixels. Qt (and QML) support DPI independent pixels in newer versions, but because KDE and Plasma support older versions of Qt too, one can not assume that pixels used in Qt or QML apps are DPI independent. .. figure:: /img/DPI.qml.png :scale: 50 % :alt: Different DPIs on desktop and mobile - + Different DPIs on desktop and mobile - + A rectangle defined with physical pixels and DPI independent pixels. .. hint:: |devicon| Except explicilty stated otherwise, all HIG pages, draft, mockups, ... pixels/px are always DPI independent pixels. DPI independent pixels in KDE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. hint:: - |devicon| As a developer, if you want to use DPI independent pixels use units.devicePixelRatio as a multiplier on physical pixels. Since units.devicePixelRatio is a float, make sure to round the results. Most of the time you want to floor it. + |devicon| As a developer, if you want to use DPI independent pixels use units.devicePixelRatio as a multiplier on physical pixels. Since units.devicePixelRatio is a float, make sure to round the results. Most of the time you want to floor it. Fonts ~~~~~ Since KDE allows the user to change the font settings any dimensions defined with px, no matter if they are DPI independent or not, make problems together with text. -.. figure:: /img/Font.qml.png +.. figure:: /img/Font.qml.png :scale: 50 % :alt: Using DPI independet pixel with different font setting - - Using DPI independet pixel with different font setting + + Using DPI independet pixel with different font setting base units in plasma -------------------- There are special base units in plasma: - units.smallSpacing - units.largeSpacing - units.gridUnit These are not only DPI independent but scale according to the font settings too. While designing, be careful not to rely on the ratio between units.smallSpacing and units.largeSpacing because these change depending on font setting +.. hint:: + |designicon| For mockup and design you can use these values: + + * units.smallSpacing = 4px + * units.largeSpacing = 18px + * units.gridUnit = 18px From design to code ------------------- For any mockup, please help the developers by specifying all measurements, either in the mockup itself or in an extra guide to the mockup. It is a lot of work and it is error prone for developers trying to measure everything from a mockup. Even if the mockup is in a file format that would allow exact measurements, don't expect the developer to know how to do it. .. container:: flex - + .. container:: - + .. figure:: /img/Design.qml.png - + *BAD* + There are no measures. - + .. container:: - + .. figure:: /img/Design_Good.qml.png - + *GOOD* + Try to be as detailed as necessary, but you don't have to provide measurement for objects that can be easily calculated. For example the size of the dark rectangle can be easily obtained. recomended spacings ~~~~~~~~~~~~~~~~~~~ If you design try to use the recomended values for margin and paddings, to ensure a uniform appearance. See `Placement and Spacing`_ for more details. .. figure:: /img/Margin.qml.png :alt: Use of base units - + Use of base units .. code:: qml :number-lines: Row { spacing: units.largeSpacing Rectangle { ... } Rectangle { ... } } .. code:: qml :number-lines: Row { spacing: 2 * units.smallSpacing Rectangle { ... } Rectangle { ... } } arbitrary px values ~~~~~~~~~~~~~~~~~~~ When needed, you can use arbitrary px values for your mockups. As a developer you need to use units.devicePixelRatio to make these values DPI independent. .. figure:: /img/Arbitrary.qml.png :alt: Use of arbitrary px values - + Use of arbitrary px values - + .. code:: qml :number-lines: Row { spacing: units.smallSpacing Rectangle { height: units.largeSpacing width: Math.floor(2 * units.devicePixelRatio) } Text { ... } } ratio ~~~~~ Sometimes the ratio between dimensions is more important then the actually values. .. figure:: /img/Ratio.qml.png .. code:: qml :number-lines: Grid { columns: 3 ... Repeater { model: 9 ... Rectangle { width: grid.width / 3 height: grid.height / 3 ... } } } diff --git a/source/patterns/iconandtext.rst b/source/patterns/iconandtext.rst new file mode 100644 index 0000000..c6770ff --- /dev/null +++ b/source/patterns/iconandtext.rst @@ -0,0 +1,23 @@ +Purpose +------- + +Combining icons and text can be used to identify data and actions in a +user interface. Examples include toolbar actions, file and folder +displays in a file manager, application listings, and notifications. The +layout should be consistent. + +Guideline +--------- + +.. image:: /img/HIGPatternIconsAndText.png + :alt: Alignment of text and icons. + +.. attention:: + Make sure to read about how :doc:`units and messurements ` are used for design and development. + +- Where icons are shown with text, use the layout guidelines above. +- For 16x16px icons and smaller, the 8px margins may be reduced to 4px. +- If Secondary Text is normally present, but is empty in a particular + instance, align the Primary Text to the vertical center. +- Where icons are shown without text, always provide tooltip text and + alternate text for accessibility. diff --git a/source/style/writing/index.rst b/source/style/writing/index.rst index 572fc75..b06611e 100644 --- a/source/style/writing/index.rst +++ b/source/style/writing/index.rst @@ -1,21 +1,20 @@ Writing ======= .. toctree:: - :caption: Contents: :titlesonly: :hidden: wording capitalization labels static localization Text includes all the written, language-based elements of the interface. This includes the labels used to represent the organizational model, the names of the input and navigational controls contained for Viewing and Navigation, and the alert messages and help text used for User Assistance. * :doc:`wording` * :doc:`capitalization` * :doc:`labels` * :doc:`static` * :doc:`localization`