[csswg-drafts] [css-properties-values-api] enhance `@property` with local persistence (#9585)

brandonmcconnell has just created a new issue for https://github.com/w3c/csswg-drafts:

== [css-properties-values-api] enhance `@property` with local persistence ==
## Abstract

Developers often need to ensure that user-selected styles are consistent across visits and tabs, such as theme settings. To streamline this process, I propose an extension to the existing `@property` rule with a new `persist` descriptor. This addition will empower CSS to persist user-defined styles without relying on JavaScript, enabling a seamless and more native experience for managing user preferences.

## 1. Introduction

Persistent user preferences are a staple in the realm of web personalization. The vision is to provide a frictionless experience where users' style preferences are remembered effortlessly. Currently, this is handled via JavaScript, which can be less efficient and more complex. By extending the `@property` rule with local persistence capabilities, we can leverage CSS to elegantly solve this challenge.

## 2. `@property` rule enhancement

### 2.1 Declaring a locally persistent property

- The `@property` rule is extended with a `persist` descriptor that determines whether the property should be read from and written to `localstyles`:

```css
@property --theme-color {
  syntax: '<color>';
  inherits: false;
  initial-value: #00FF00;
  persist: true;
}
```

### 2.2 Utilizing locally persistent properties

- Locally persistent properties can be used just like any other custom property:

```css
body {
  background-color: var(--theme-color);
}
```

- If a locally persistent property isn’t set, it falls back to its initial value or another specified value:

```css
body {
  background-color: var(--theme-color, #000000); /* Fallback to black if not set */
}
```

### 2.3 Resetting locally persistent properties

Resetting a locally persistent property to its initial value is as simple as setting its value to `initial`, which will cause it to default to the `initial-value` set in its `@property` definition if there is one.

```css
--theme-color:  initial;
```

## 3. JavaScript API interaction

### 3.1 Accessing locally persistent properties

```javascript
// would use either `document.localStyles` or `window.localStyles`

const themeColor = document.localStyles.getPropertyValue('--theme-color');
```

### 3.2 Modifying locally persistent properties

```javascript
document.localStyles.setProperty('--theme-color', '#00FF00');
```

### 3.3 Removing locally persistent properties

```javascript
document.localStyles.removeProperty('--theme-color');
```

## 4. Use cases

Extending the `@property` rule with local persistence would serve the following scenarios and likely countless others:

- Maintaining theme preferences across sessions and tabs without server-side storage.
- Saving accessibility settings like preferred text size or contrast modes for user convenience.

## 5. Gotchas/considerations

### 5.1 Third-party style isolation

A key consideration is ensuring that `localstyles` are protected from third-party manipulation. It's essential to implement mechanisms where these styles can be designated as private, potentially through a flag or a specific scope, to prevent external CSS from altering these user-specific preferences.

### 5.2 Privacy & security

It's crucial that `localstyles` respect user privacy and are safeguarded against CSS-based security vulnerabilities. Similar to the existing web storage APIs, `localstyles` would adhere to privacy settings and the same-origin policy.

## 6. Conclusion

By enhancing the `@property` rule with a `persist` descriptor, we can unlock a powerful, native way to persist user-defined styles. This change promotes a more efficient, consistent, and user-centric web experience.

I intentionally chose to use the descriptor `persist` and not `local`, so as not to confuse `local` with any meaning in holds in terms of global/local scope. An unrelated but similar PR I opened a while back re global "scope" can be found here: https://github.com/w3c/csswg-drafts/issues/7866

## 7. Request for comments

Feedback is sought on:

- The proposed syntax and functionality for the extended `@property` rule.
- Strategies to ensure the privacy of `localstyles`.
- Potential challenges and solutions for browser vendors in implementing this feature.

Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/9585 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Thursday, 9 November 2023 20:45:14 UTC