..  include:: /Includes.rst.txt

..  _feature-styling-tokens:

==================================
Feature: The surface can be themed
==================================

Description
===========

The editing surface is styled from a set of CSS custom properties instead of
values written into the components. Every colour, distance, radius, duration and
width it uses is now a property declared on the custom element, and a site
overrides one by setting it on that element from its own stylesheet.

At the time this landed it was the only way the surface could be restyled at
all: it was drawn inside a shadow root, which no selector reaches, and a custom
property is the one thing that crosses that boundary.

..  note::
    The surface renders into the light DOM now, so custom properties are no
    longer the only interface — a site can also write ordinary rules against the
    surface's class names, and can have it carry its own. The properties below
    are unchanged and still work. See :ref:`configuration-component`.

..  code-block:: css

    modern-extbase-frontend-edit-profile {
        --frontend-edit-color-accent: #b8003c;
        --frontend-edit-measure: 60rem;
    }

The complete list is in :ref:`configuration-styling`.

What changed in the appearance
==============================

The surface was previously laid out but not styled — buttons were user agent
buttons at a different height than the controls beside them, and the error
colour was written three times in three files.

*   Buttons and controls share one box: the same height, border, radius and
    focus ring.
*   The file control of the profile image is a button like every other control,
    reading :guilabel:`Choose image` or :guilabel:`Replace image` rather than the
    browser's :guilabel:`Choose File` and its permanent
    :guilabel:`No file chosen` — which was untrue here, because the control is
    emptied the moment a file is read.
*   Every address and e-mail address is headed by its own type and first line,
    with the buttons that act on it on the same line. The heading is not a
    number: the records can be reordered, and a number would rename every entry
    below the one that moved.
*   A field is laid out as a row — label, value, and the action belonging to it
    — rather than as a stack, which makes a profile roughly a third shorter and
    puts the :guilabel:`Edit` button beside the value it edits. On a narrow
    column the value wraps back under its label.
*   Every button carries an icon, drawn inline in the extension's own JavaScript
    — no icon font, no request, and nothing for the Content Security Policy to
    permit. In the toolbar of a child record the text is hidden and the icon
    stands alone; the label is still announced by a screen reader.
*   Buttons carry emphasis. The one that commits a pending change —
    :guilabel:`Apply`, :guilabel:`Save all fields`, :guilabel:`Add` — is filled
    in the accent colour, and :guilabel:`Remove` is labelled in the danger
    colour and fills only under the pointer. Everything else is the plain
    button.
*   The surface is capped at :css:`--frontend-edit-measure`, so the
    :guilabel:`Edit` button of a value no longer sits at the far edge of a wide
    page.
*   A rejected control and its focus ring are drawn in one colour rather than
    two, so the field reads as wrong rather than as focused.
*   Labels, captions and the state badge are set quieter than the values they
    describe.
*   A dark colour scheme is provided for pages that follow the system setting.

Impact
======

An installation that has not styled the surface needs to do nothing.

The typeface is unchanged and is still inherited from the page: the extension
ships no font and cannot load one from another origin, because the Content
Security Policy it declares permits the installation's own origin only. See
:ref:`configuration-csp`.