AriaML Document Appearance

AriaML Document Appearance Definition

Appearance in AriaML allows for grouping style resources within a <g> container. This enables the separation of styles from page metadata (stored as JSON-LD) and provides the ability to make all or part of the appearance dynamic across fluid navigation contexts via the nav-slot attribute. Furthermore, AriaML facilitates a cleaner decoupling between semantics and appearance through volatile classes.

1. The `<g>` Grouping Element

The <g> (Group) element is the universal structural container. it is used to organize resources and define thematic boundaries.

Implicit Role: none. It has no default semantic value.
Visual Behavior: display: contents. It does not generate a rendering box and does not affect the layout.
Semantic Mutation: If the element receives a labeling attribute (aria-label, aria-labelledby), its role becomes group.
Specific Attributes:
theme: Defines the theme identifier for all descendants.
media-theme: An indication to assist in automatic theme selection.
media: Conditions the activation of the group via a Media Query.
nav-slot: Identifies the block for dynamic replacement operations.

2. The Extended `<style>` Element

In AriaML, <style> is the unique vector for CSS, icon data, and dynamic classes.

2.1 Control Attributes

theme: Thematic attachment identifier. Prevails over parent inheritance if no conflict exists.
media-theme: An indication to assist in automatic theme selection.
src: URL of an external resource (CSS or JSON).
preload: Instruction for high-priority caching.
media: Conditions the application of the resource.

2.2 Data Types (`type`)

Styles: text/css (default).
Volatile Classes: volatile-classes+json or application/volatile-classes+json.
System Icons: icons+json or application/icons+json.

3. Grouping and Thematic Hierarchy

3.1 Neutral Grouping

A <g> element without a theme attribute structures the document without breaking the thematic inheritance chain of its parents.

3.2 Thematic Grouping

An <g theme="A"> element establishes thematic authority over its descendants.

Inheritance: Descendant <style> tags inherit theme "A".
Uniqueness Rule: It is forbidden to define a different theme attribute within an established thematic group.
Conflict Resolution: Any discordant resource is invalidated (state set to disabled).

3.3 Automatic Selection (Auto-Theme)

In the absence of a saved user preference, the media attribute associated with a theme attribute (on a <g> or <style> element) is used to determine the default theme. The rendering engine activates the first theme whose Media Query matches the system environment.

4. Volatile Classes (Mutable States)

Volatile classes inject utility classes without modifying the semantic structure.

Format: JSON object { "selector": "classes" }.
Lifecycle: Application is tied to the node's activation. If the theme or media condition changes, the engine automatically removes the classes injected by the resource that has become inactive.

5. Interface Control (Viewport & Browser Color)

System parameters are managed via CSS by extracting computed variables from the <aria-ml> root element:

--browser-color: Defines the browser interface color (address bar, etc.).
--viewport: Defines the configuration of the display surface.

6. Server-Side HTML Compatibility

AriaML ensures backward compatibility and search engine indexing:

The server can deliver a document with volatile classes already applied and icons present in the <head>.
The client engine is idempotent: it synchronizes the final state and cleans up server-side injections if the theme changes.

Standard Structure Example (Auto-selection)

<aria-ml>
  <g id="static">
      <style type="icons+json" preload>
        [{
            "rel": "icon",
            "href": "https://flavi1.github.io/aria-ml/src/icon/32.png",
            "sizes": "32x32"
        },
        {
            "rel": "icon",
            "href": "https://flavi1.github.io/aria-ml/src/icon/300.png",
            "sizes": "192x192 300x300"
        }]
      </style>
      <style src="css/style.css"></style>
  </g>
  <g nav-slot="appearance">

    <g theme="dark" media-theme="(prefers-color-scheme: dark)">
      <style>aria-ml { --browser-color: #0f172a; --viewport: "width=device-width, initial-scale=1" }</style>
      <style type="volatile-classes+json">
        { "main": "bg-slate-900 text-white" }
      </style>
    </g>

    <g theme="light" media-theme="(prefers-color-scheme: light)">
      <style>aria-ml { --browser-color: #ffffff; }</style>
      <style type="volatile-classes+json">
        { "main": "bg-white text-black" }
      </style>
    </g>

  </g>
</aria-ml>

Next : AriaML Behavior Sheets

Aria Markup Language