diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css index 7c316f3fee9..12b6d9ba94f 100644 --- a/_shared_assets/static/custom.css +++ b/_shared_assets/static/custom.css @@ -92,4 +92,8 @@ div#list-of-available-icons > blockquote > div > div > p { font-size: 90%; font-style: normal; text-align: center; +} + +.wy-nav-content { + max-width: max(800px, calc(100vw - 600px)) !important; } \ No newline at end of file diff --git a/developer_manual/basics/front-end/theming.rst b/developer_manual/basics/front-end/theming.rst index 3419d55c563..d3774533c45 100644 --- a/developer_manual/basics/front-end/theming.rst +++ b/developer_manual/basics/front-end/theming.rst @@ -6,13 +6,10 @@ Theming support The Nextcloud theming app offers some tools for app developers to ensure that apps also match the themed look. -CSS classes ------------ - -* **.nc-theming-main-background** Background in theming color -* **.nc-theming-main-text** Text in theming color -* **.nc-theming-contrast** Text in white/black color to be shown in front of the theming color +CSS variables +------------- +There are a lot of CSS variables available, see :ref:`cssvars`. JavaScript ---------- diff --git a/developer_manual/html_css_design/css.rst b/developer_manual/html_css_design/css.rst index 2dcbdf4dd3b..e5601f115ea 100644 --- a/developer_manual/html_css_design/css.rst +++ b/developer_manual/html_css_design/css.rst @@ -2,15 +2,12 @@ .. codeauthor:: John Molakvoæ .. _css: -==== -SCSS -==== +=== +CSS +=== -Nextcloud supports SCSS natively. -You can migrate your files by simply renaming your ``.css`` files to ``.scss``. -The server will automatically compile, cache and serve it. -The SCSS file is prioritized. Having two files with the same name and a ``scss`` & ``css`` extension -will ensure backwards compatibility with <12 versions as scss files will be ignored by the server. +While the recommended way to develop the user interface is using Vue with the Nextcloud provided components, +Nextcloud also provides CSS variables and classes to style components to have a consistent look. .. _cssvars: @@ -18,75 +15,225 @@ will ensure backwards compatibility with <12 versions as scss files will be igno CSS variables ============= -App developers should use CSS4 variables so you get the values which Nextcloud defines. This way you can be sure that the theming and accessibility app can dynamically adjust the values. - -A list of available variables is listed in the server repository: -https://github.com/nextcloud/server/blob/master/core/css/variables.scss - - -.. _cssicons: - -SCSS icon mixins -================ - -.. deprecated:: 25 - -Some SCSS mixins and functions are employed to add and manage SVG icons. - -These functions need to be used to add the icons via background-image. They create a list of every icon used in Nextcloud and create an associated list of variables. -This allows us to invert the colors of the SVGs when using the dark theme. - -.. code-block:: scss - - /** - * SVG COLOR API - * - * @param string $icon the icon filename - * @param string $dir the icon folder within /core/img if $core or app name - * @param string $color the desired color in hexadecimal - * @param int $version the version of the file - * @param bool [$core] search icon in core - * - * @returns string the url to the svg api endpoint - */ - @mixin icon-color($icon, $dir, $color, $version: 1, $core: false) - - // Examples - .icon-menu { - @include icon-color('menu', 'actions', $color-white, 1, true); - // --icon-menu: url('/svg/core/actions/menu/ffffff?v=1'); - // background-image: var(--icon-menu) - } - .icon-folder { - @include icon-color('folder', 'files', $color-black); - // --icon-folder: url('/svg/files/folder/000000?v=1'); - // background-image: var(--icon-folder) - } - -More information about the :ref:`svg color api `. - - -The ``icon-black-white`` mixin is a shorthand for the ``icon-color`` function but it generates two sets of icons with the suffix ``-white`` and without (default black). - - -.. code-block:: scss - - /** - * Create black and white icons - * This will add a default black version of and an additional white version when .icon-white is applied - */ - @mixin icon-black-white($icon, $dir, $version, $core: false) - - // Examples - @include icon-black-white('add', 'actions', 1, true); - - // Will result in - .icon-add { - @include icon-color('add', 'actions', $color-black, 1, true); - } - .icon-add-white, - .icon-add.icon-white { - @include icon-color('add', 'actions', $color-white, 1, true); - } - - +It is strongly recommended to use the Nextcloud provided CSS variables for styling components. +This way you can be sure that the theming and accessibility app can dynamically adjust the values. +Doing so also allows users to enforce dark or light theme, high contrast or other theming related options. + + +Primary color variables +----------------------- + +The primary color is the main accent color that can be configured by the administrator or the user (if user theming is enabled). + ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| Variable | Example | Usage | ++==============================================+==================+===========================================================================================+ +| ``--color-primary`` | ``#00679e`` | Primary color configured by user | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-text`` | ``#ffffff`` | Text color to be used on ``--color-primary`` | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-hover`` | ``#3285b1`` | Variant of ``--color-primary`` for hover effects | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-light`` | ``#e5eff5`` | Light variant of ``--color-primary`` used for secondary actions | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-light-text`` | ``#00293f`` | Text color to be used on ``--color-primary-light`` | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-light-hover`` | ``#dbe4ea`` | Variant of ``--color-primary-light`` for hover effects | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element`` | ``#00679e`` | Accessibility adjusted variant of ``--color-primary`` to be used on interactive elements | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-text`` | ``#ffffff`` | Text color to be used on ``--color-primary-element`` | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-text-dark`` | ``#f5f5f5`` | Less contrast version of ``--color-primary-element-text`` | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-hover`` | ``#005a8a`` | Variant of ``--color-primary-element`` for hover effects | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-light`` | ``#e5eff5`` | Light variant of ``--color-primary-element`` used for secondary actions | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-light-text`` | ``#00293f`` | Text color to be used on ``--color-primary-element-light`` | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--color-primary-element-light-hover`` | ``#dbe4ea`` | Variant of ``--color-primary-element-light`` for hover effects | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--primary-invert-if-bright`` | ``invert(100%)`` | Filter to invert icons placed on primary color backgrounds if the primary color is bright | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ +| ``--primary-invert-if-dark`` | ``invert(100%)`` | Filter to invert icons placed on primary color backgrounds if the primary color is dark | ++----------------------------------------------+------------------+-------------------------------------------------------------------------------------------+ + +Background variables +-------------------- + ++----------------------------------------------+-----------------------+-------------------------------------------------------------------------------------+ +| Variable | Example | Usage | ++==============================================+=======================+=====================================================================================+ +| ``--color-background-plain`` | ``#00679e`` | The background color of the ``body`` element | ++----------------------------------------------+-----------------------+-------------------------------------------------------------------------------------+ +| ``--color-background-plain-text`` | ``#ffffff`` | Text color to be used directly on the background (e.g. header menu) | ++----------------------------------------------+-----------------------+-------------------------------------------------------------------------------------+ +| ``--image-background`` | ``url('clouds.jpg')`` | Background image used on the ``body`` element (optional) | ++----------------------------------------------+-----------------------+-------------------------------------------------------------------------------------+ +| ``--background-image-invert-if-bright`` | ``invert(100%)`` | Filter to invert (bright) icons placed directly on the body background (app menu) | ++----------------------------------------------+-----------------------+-------------------------------------------------------------------------------------+ + +General color variables +----------------------- + ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Variable | Example | Usage | ++==============================================+================================================+===========================================================================================================+ +| ``--color-main-text`` | ``#222222`` | Main text color | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-text-maxcontrast`` | ``#6b6b6b`` | Brighter text color that still fulfills accessibility requirements | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-text-maxcontrast-background-blur`` | ``#595959`` | ``--color-text-maxcontrast`` for blurred background, see ``--color-main-background-blur`` | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-main-background`` | ``#fffff`` | Main background color | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-main-background-rgb`` | ``255,255,255`` | RGB variant of ``--color-main-background`` | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-main-background-blur`` | ``rgba(var(--color-main-background-rgb), .8)`` | Background color used for blurred background, see ``--filter-background-blur`` | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-background-hover`` | ``#f5f5f5`` | Background color for hover effects | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-background-dark`` | ``#ededed`` | Can be used e.g. to colorize selected table rows | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-background-darker`` | ``#dbdbdb`` | Should only be used for elements, not as a text background! Otherwise it will not work for accessibility. | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-border`` | ``#ededed`` | Default element border color | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-border-dark`` | ``#dbdbdb`` | Darker version of the border color | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-border-maxcontrast`` | ``#7d7d7d`` | Brightest possible border color for accessibility | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-placeholder-light`` | ``#e6e6e6`` | Color for input placeholders | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-placeholder-dark`` | ``#cccccc`` | Darker version of ``--color-placeholder-light`` | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-scrollbar`` | ``#33333344`` | Color for scrollbars | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-loading-light`` | ``#cccccc`` | Color for the loading spinner (the bright part of it) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-loading-dark`` | ``#444444`` | Color for the loading spinner (the dark part of it) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-box-shadow-rgb`` | ``77,77,77`` | Color for box shadow effects in RGB notation | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--color-box-shadow`` | ``rgba(var(--color-box-shadow-rgb), 0.5)`` | Color for box shadow effects | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--background-invert-if-dark`` | ``invert(100%)`` | Filter to invert (dark) icons (e.g. set if the color theme is dark) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--background-invert-if-bright`` | ``invert(100%)`` | Filter to invert (bright) icons (e.g. set if the color theme is bright) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +State colors variables +---------------------- + ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| Variable | Example | Usage | ++==============================================+=================+===========================================================================================+ +| ``--color-favorite`` | ``#a37200`` | Color to mark favorites, can be used to color e.g. a star icon for favorites | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-error`` | ``#db0606`` | Element color to show error state, this should not be used for text | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-error-rgb`` | ``219,6,6`` | RGB variant of ``--color-error`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-error-hover`` | ``#df2525`` | Element color for hover effects of ``--color-error`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-error-text`` | ``#c20505`` | Text color to show error state | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-warning`` | ``#a37200`` | Element color to show warning state, this should not be used for text | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-warning-rgb`` | ``163,114,0`` | RGB variant of ``--color-warning`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-warning-hover`` | ``#8a6000`` | Element color for hover effects of ``--color-warning`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-warning-text`` | ``#7f5900`` | Text color to show warning state | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-success`` | ``#2d7b41`` | Element color to show success state, this should not be used for text | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-success-rgb`` | ``45,123,65`` | RGB variant of ``--color-success`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-success-hover`` | ``#428854`` | Element color for hover effects of ``--color-success`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-success-text`` | ``#286c39`` | Text color to show success state | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-info`` | ``#0071ad`` | Element color to show info state, this should not be used for text | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-info-rgb`` | ``0,113,173`` | RGB variant of ``--color-info`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-info-hover`` | ``#197fb5`` | Element color for hover effects of ``--color-info`` | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ +| ``--color-info-text`` | ``#006499`` | Text color to show info state | ++----------------------------------------------+-----------------+-------------------------------------------------------------------------------------------+ + +Element structure variables +--------------------------- + ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Variable | Example | Usage | ++==============================================+================================================+===========================================================================================================+ +| ``--animation-quick`` | ``100ms`` | Animation time for snappy CSS transitions | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--animation-slow`` | ``300ms`` | Animation time for more complex transitions | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--breakpoint-mobile`` | ``1024px`` | Breakpoint for mobile responsive layout (e.g. if app navigation should be always visible) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--filter-background-blur`` | ``blur(25px)`` | Filter to be used on elements with background blur (e.g. app navigation) | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--font-face`` | ``system-ui, 'Segoe UI', Roboto, Oxygen-Sans`` | Font used for Nextcloud user interface | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--default-font-size`` | ``15px`` | Font size for normal text | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--default-line-height`` | ``24px`` | Line height for normal text, for accessibility this should always be ``calc(1.5 * var(--font-size))`` | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--default-grid-baseline`` | ``4px`` | Foundation of all spacing sizes used on Nextcloud which are multiples of the baseline size | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--border-radius`` | ``3px`` | Default border radius | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--border-radius-large`` | ``10px`` | Larger border radius | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--border-radius-rounded`` | ``28px`` | Even larger border radius for elements which should be look rounded | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--border-radius-pill`` | ``calc(var(--default-clickable-area) / 2)`` | Border radius for pill-style elements | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--default-clickable-area`` | ``44px`` | Default size (width and height) for interactive elements like buttons | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--header-height`` | ``50px`` | Height of the main app navigation bar | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--header-menu-item-height`` | ``44px`` | Height of entries in the main app navigation bar | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--navigation-width`` | ``300px`` | Width of the in-app navigation sidebar | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--sidebar-min-width`` | ``200px`` | Minimum width of the app sidebar on small screens | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``--sidebar-max-width`` | ``500px`` | Maximum width of the app sidebar on wide screens | ++----------------------------------------------+------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +.. _cssclasses: + +CSS classes +=========== + +There are some predefined classes for public use to ease developing an application for Nextcloud. + ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| CSS class | Usage | ++==============================================+================================================================================================================================================+ +| ``.hidden-visually`` | Hides an element visually from the page but keeps it in the accessibility tree | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.hidden`` | Hides an element completely from the page (also removed from the accessibility tree) | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.bold`` | Make content of the element bold emphasize | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.center`` | Center align the elements text | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.clear-left`` | Clear float left | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.clear-right`` | Clear float right | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.clear-both`` | Clear float on both | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.pull-left`` | Float left | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.pull-right`` | Float right | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``.inlineblock`` | Make an element an inline block | ++----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/go.php b/go.php index b942825f823..af8c9847b1d 100644 --- a/go.php +++ b/go.php @@ -48,10 +48,11 @@ 'admin-warnings' => '/admin_manual/configuration_server/security_setup_warnings.html', 'admin-workflowengine' => '/admin_manual/file_workflows/index.html', - 'developer-backports' => '/developer_manual/getting_started/development_process.html#bugfixes', - 'developer-code-integrity'=> '/developer_manual/app/code_signing.html', 'developer-manual' => '/developer_manual', - 'developer-theming' => '/developer_manual/core/theming.html', + 'developer-backports' => '/developer_manual/getting_started/development_process.html#bugfixes', + 'developer-code-integrity'=> '/developer_manual/app_publishing_maintenance/code_signing.html', + 'developer-css' => '/developer_manual/html_css_design/css.html', + 'developer-theming' => '/developer_manual/basics/front-end/theming.html', 'user' => '/user_manual', 'user-2fa' => '/user_manual/en/user_2fa.html',