SolidOS technical implementation of new UI

[timea-solid]

The NLnet grant allows us to improve SolidOS UI. Before going into technical solutions, I list the requirements.

High-level requirements are:

• longevity (W3C standards)
• accessibility (WCAG 2.2 compliant)
• reusability
• developer adoption (use in React/Vue/Svelte/etc.)

The longevity requirement is undebatable.

Accessibility is a requirement by the grant, which involves using HTML5 and ARIA.

Reusability:

• solid-ui was always envisioned as an HTML elements library dedicated to Solid functionality. Example: a list build based on a given predicate to more complex widgets like a login window. These HTML elements will have styles that can be themed to look like the app they are used in.

• solid panes are mini applications, such as profile dashboard, file explorer, and contacts. They use solid-ui HTML elements and add more HTML functionality where needed. They also have their own style elements, for extra elements it implements. For example, the QR code in the profile card. Like solid-ui, the entire pane's style will be able to be themed to look like the app they are used in.

Developer adoption:

• to make it easy for developers to reuse solid-ui HTML elements and maybe an entire pane, they need to be easy to add into their existing frameworks (React/Vue/Svelte/etc.) or use in simple HTML.

[timea-solid]

Proposed solution

For CSS:

• introduction of Shadow DOM
• reusable CSS custom properties for theming

This is a W3C-approved workaround for the “Shadow DOM blocks CSS” problem which offers full flexibility.

Why Shadow DOM?

• isolates component CSS (no leaking into other parts of your app)
• allows strict accessibility markup without interference

Why custom CSS properties?

• this is the theme system
• defines SolidOS brand colors, fonts, icon pack, spacing, elevation
• theme is centrally adjustable

Example:

Every solid-ui component exposes theme hooks via CSS variables.

Example in <solid-button>:

:host {
  --solid-button-bg: var(--solid-color-primary);
  --solid-button-color: white;
  --solid-button-radius: 6px;
  --solid-button-padding: 0.5rem 1rem;
}

A developer’s app can override them at any global scope:

/* App-specific theme overrides */
solid-button {
  --solid-button-bg: #ff6600;
  --solid-button-radius: 20px;
}

Or globally:

:root {
  --solid-color-primary: #ff6600;
  --solid-font-family: 'Roboto', sans-serif;
}

This is safe and supported inside Shadow DOM because custom properties pierce Shadow DOM boundaries.

Further technical proposal:

To achieve the usability and developer experience requirements, I propose to use the standard Web Components(https://www.webcomponents.org/specs).
With this, solid-ui becomes a “Solid Design System”: Accessible, Themed Web Components

Advantages:

• web components are framework-agnostic and native browser technology.
• solid-ui HTML elements would look like:

<solid-button>
<solid-icon name="trash">
<solid-select>
<solid-autocomplete>
<solid-table>
<solid-login>
<solid-profile-card>
<solid-cv-widget>
<solid-preferences-panel>

• easy to use for developers. They can simply import them in JavaScript like import '@solidos/ui/button'; or in HTML like <solid-button intent="primary">Save</solid-button> or <solid-profile-pane webId="..."></solid-profile-pane>
• each pane is converted into a Web Component and imported dynamically by Mashlib
• Web Components help enforce accessibility by default so developers can’t break it accidentally.

Prototype implementation

Look at the code and how it changes in Profile-pane: SolidOS/profile-pane#141
See how it looks now, deployed on test server: https://timea.pivot-test.solidproject.org:3000/profile/card#me

[chunt007]

I really like the responsive design choices as far as CSS. The curved edges make a huge difference!

Placement of the vCard saves space.

How much website real estate/negative space do you believe is necessary for the new user/onboarding experiences?

Do you think that the Contact "Login to chat with me" part should be merged with the top part? Make it one big contact card? It may save more space. For example, Facebook seems to imply that when a user visits a profile, they have to login in to continue to connect with said person. Just a thought. But overall it definitely feels like feels more professional pod experience already!!! 😊

[CxRes]

Hi @timea-solid, Great to see you back and working on Solid OS!

I would like you to think hard before committing to the Web Components route. For context, read Ryan Carniato's blog post https://dev.to/ryansolid/web-components-are-not-the-future-48bh. If you are not aware, Ryan authored the Solid.js framework (unrelated to Solid) whose internals are copied by literally every front-end framework on the planet (React, Svelte, Vue, Angular amongst others).

[timea-solid]

Thank you @CxRes for sharing!
I carefully considered the shared experiences from the article and it made me go back to the native HTML elements step. My previous proposal is wrong in the implementation of panes (our mini-applications).

A revised technical proposal is as follows:

Have Solid-ui as a “Solid Design System”

1. Use for most of the elements, native HTML elements wrapped in a solid flavour.
   Example for a Solid button:

class SolidButton extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = // load custom css
    this._button = shadow.querySelector('button');
  }

  static get observedAttributes() {
    return ['disabled'];
  }

  attributeChangedCallback(name, _, value) {
    if (name === 'disabled') {
      this._button.disabled = value !== null;
    }
  }

  focus() {
    this._button.focus();
  }
}

customElements.define('solid-button', SolidButton);

This can be used as

<solid-button>Save</solid-button>

<solid-button disabled>
  Disabled
</solid-button>

2. Create custom elements where needed (using Web Components).

• for example: for an autocomplete that queries from Wikipedia on skills or languages, which we have now.
  The alternative to Web Components is to create everything in javascript ourselves. This is what solid-ui HTML element intended but it is missing a lot of functionality.

• in any case, this needs to be prototyped first to see how it would hold in practice.

Solid panes such as Profile Pane

• our mini-applications, such as profile pane, would than make use of solid-ui elements and either use a framework like React or any other to implement everything else.

Other code stays the same

• solid-pnaes is the one who decides which panes are loaded and where they are rendered

CSS (in theory - this also still needs to be prototyped)

• the theme lives at the application root which is mashlib for us
• the theme is expressed as CSS custom properties (variables, as shown above/before)
• solid-ui design tokens are the contract: a documented, stable set of CSS variables that components agree to use.
• solid-ui components never hardcode colors, fonts, spacing.
• panes do not define themes; they consume them.

[CxRes]

I believe the best bet for panes is to build a <solid-pane-container> web-component that extends web-fragments. Web-fragments shall allow each pane to run in its own process, decoupling the fate of each component from Solid OS itself. Even if a pane performs poorly or outright crashes, this will not affect the remainder of a Solid OS instance. It also means that each pane can use its own framework/libraries.

Additionally, this container can serve as an open standard for panes for use with Solid OS. It can provide a standardized mechanism for interacting with the graph created by RDFlib.js. You can also explore if you want to limit the access of a component to a certain part of the linked data graph (I prefer that architecture, but it may not feasible with RDFlib or desirable for expedited querying).

[timea-solid]

@CxRes very interesting idea! Thanks again for sharing!
I like more and more the whole concept of custom HTML elements, style like solutions. This originates in how RDF forms and Jeff's Web Components were conceived.
This fits quite well in what pane-registry was, awkwardly, trying to achieve technically. I see Web Fragments as a mature version of that initial thought. So, all these to say, this is a first viable solution I read about for our dynamic pane registration problem! So IEI!
The dynamic pane registration goal did not make it in the current NLnet grant and was left for a followup grant. However, I will proceed with a CSS solution, having in mind the Web Fragments for the future. Or at least don't choose some solution that would hinder us from implementing Web Fragments if we want to. A prototype would be nice to have ;)

[melvincarvalho]

Hi @timea-solid, the longevity and accessibility focus makes sense, and the design tokens in global.css look well-structured.

One question on direction: I’m seeing Shadow DOM + lit-html across components. Do you see a supported path for panes/components that stick to Light DOM + conventional styling (still consuming the same tokens), or is Shadow DOM the expected baseline going forward? My preference would be to keep a non–Shadow DOM route viable for ease of debugging and integration.

[timea-solid]

The idea as of now is to have Web Components in solid-ui for UI elements that are more complex than native HTML elements.
Web Components works on shadow DOM underneath.
The panes will stay as they are but start making use of solid-ui elements, as it was intended.
What integration scenarios do you have in mind where Web Components would not work? Regarding debugging, why wouldn't debugging work with Web Components?

[melvincarvalho]

Thanks for clarifying.

On integration: external CSS generally can’t reach into Shadow DOM, so consumers are effectively limited to the exposed theming surface (CSS custom properties, and any parts you choose to expose). That's fine if the token/parts surface is comprehensive.

On debugging: event retargeting across shadow boundaries can make tracing a bit trickier, and you have the extra step of inspecting shadow roots. Manageable, but it adds friction.

My preference is to keep a lightweight Light DOM path viable for simpler elements where it’s practical, but I appreciate you thinking it through.