#1031: Custom Functions (@function)

Visit on Github.

Opened Dec 18, 2024

こんにちは TAG-さん!

I'm requesting a TAG review of Custom Functions (@function)

"A custom function can be thought of as an advanced custom property, which instead of being substituted by a single fixed value provides its substitution value based on function parameters and local variables." (From the spec.)

  • Explainer¹: https://css.oddbird.net/sasslike/mixins-functions/ (Also explains mixins, which is not in scope for this review.)
  • Specification: https://drafts.csswg.org/css-mixins-1/#defining-custom-functions
  • WPT Tests: N/A
  • User research: https://css.oddbird.net/sasslike/mixins-functions/#author-interest
  • Security and Privacy self-review²: <details><summary>tl;dr: nothing to report, expand for details.</summary><ul><li>2.1 What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary? <br>A: It doesn't expose anything. It's both defined and used within CSS.</li></li><li>2.2 Do features in your specification expose the minimum amount of information necessary to enable their intended uses? <br>A: Yes. (Nothing.)</li></li><li>2.3 How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them? <br>A: N/A</li></li><li>2.4 How do the features in your specification deal with sensitive information? <br>A: N/A</li></li><li>2.5 Do the features in your specification introduce new state for an origin that persists across browsing sessions? <br>A: No.</li></li><li>2.6 Do the features in your specification expose information about the underlying platform to origins? <br>A: No.</li></li><li>2.7 Does this specification allow an origin to send data to the underlying platform? <br>A: No.</li></li><li>2.8 Do features in this specification enable access to device sensors? <br>A: No.</li></li><li>2.9 Do features in this specification enable new script execution/loading mechanisms? <br>A: No.</li></li><li>2.10 Do features in this specification allow an origin to access other devices? <br>A: No.</li></li><li>2.11 Do features in this specification allow an origin some measure of control over a user agent's native UI? <br>A: No.</li></li><li>2.12 What temporary identifiers do the features in this specification create or expose to the web? <br>A: None.</li></li><li>2.13 How does this specification distinguish between behavior in first-party and third-party contexts? <br>A: N/A.</li></li><li>2.14 How do the features in this specification work in the context of a browser's Private Browsing or Incognito mode? <br>A: As normal / not applicable.</li></li><li>2.15 Does this specification have both "Security Considerations" and "Privacy Considerations" sections? <br>A: Not yet. </li></li><li>2.16 Do features in your specification enable origins to downgrade default security protections? <br>A: N/A.</li></li><li>2.17 How does your feature handle non-"fully active" documents? <br>A: N/A.</li></li><li>2.18 What should this questionnaire have asked? <br>A: N/A.</li></ul></details>
  • GitHub repo: https://github.com/w3c/csswg-drafts/tree/main/css-mixins-1
  • Primary contacts:
    • @mirisuzanne, CSSWG Invited Expert, original proposal author and spec editor.
    • @tabatkins, Google, spec editor.
    • @andruud, Google, working on the feature in Chromium.
  • Organization/project driving the specification: Chromium
  • Multi-stakeholder support³:
  • Status/issue trackers for implementations⁴: https://issues.chromium.org/issues/325504770

Further details:

  • I have reviewed the TAG's Web Platform Design Principles
  • Relevant time constraints or deadlines: Q1 2025.
  • The group where the work on this specification is currently being done: CSSWG
  • The group where standardization of this work is intended to be done (if different from the current group): CSSWG
  • Major unresolved issues with or opposition to this specification: https://github.com/w3c/csswg-drafts/issues/10954 (not opposition, but could lead to removal of the using keyword and associated behavior.)
  • This work is being funded by: N/A

Discussions

Log in to see TAG-private discussions.

Comment by @LeaVerou Dec 23, 2024 (See Github)

There has been some CSS WG discussion around dropping using and just using the local context where the function is used, yet this explainer still includes it. Is it not removed or is the explainer outdated?

Comment by @mirisuzanne Dec 30, 2024 (See Github)

It's likely the explainer is out of date - although I'm not sure there were any resolutions or decisions, only some conversation in the github threads.

Comment by @andruud Jan 3, 2025 (See Github)

I think it's reasonable to keep using in the explainer until https://github.com/w3c/csswg-drafts/issues/10954 is resolved.

The discussion in that issue does seem to converge on using being dropped, though.

Comment by @LeaVerou Jan 11, 2025 (See Github)

I think it's reasonable to keep using in the explainer until w3c/csswg-drafts#10954 is resolved.

The discussion in that issue does seem to converge on using being dropped, though.

It seems like it's going to resolve imminently, so could you ping us when it resolves so we could review then?

Comment by @andruud Jan 14, 2025 (See Github)

Yes, will do.

Comment by @andruud Feb 5, 2025 (See Github)

@LeaVerou It's now resolved, and the spec has been updated.

Comment by @LeaVerou Feb 5, 2025 (See Github)

@andruud Awesome. I’m no longer in the TAG (my term expired a few days ago), but my advice to the current TAG is that this is sorely needed functionality for authors, and there are no architectural issues with it.

Discussed Mar 1, 2025 (See Github)

Xiaocheng: this feature is a pretty big extension to CSS>. right now we have big functions in CSS ... e.g. calc, trigonometry functions, etc... so how about introducing custom functions so that we odn't need to grow this list infinitely long? I think the solution is good. Developer demand is there. I don't see an architectural conflict with other areas... I support Lea's opinion.

Martin: we should encourge them to move the explainer...

Dan: custom mathematical functions? What's the scope?

Martin: it's not running arbitrary JS. I'ts saying I've got an alias that does calc and log etc., which you can already do in CSS, and just ball them up into a uniform, reusable unit. If the primitives don't exist, you can't add them, except where CSS is already capable.

Dan: just trying to think about high security aspects of the web

Martin: this is like var(--foo), in which you are definining an expansion of what you can already do. No new capabilities are enabled.

Dan: can we set this proposed closed and I'll ready through it before the plenary?

Martin: should these be 'functions' or 'macros'.

Xiaocheng: specified as functions... there is a distinction.

Martin: comparing to Rust ... Macros do the same thing. Are these macros rather than functions?

Xiaocheng: i feel Marcos is probably more confusing... the entire CSS custom property thing is like a macro...

Martin: suggest we ask the question.

Action: Dan to read through it before plenary and we set it to proposed close and close at the plenary, Xiaocheng to draft closing comment.

Comment by @xiaochengh Mar 27, 2025 (See Github)

Hi @andruud, the TAG discussed it but didn't reach consensus. Feedbacks:

  1. Regarding privacy and security:
    1. Thank you for responding to the security & privacy questionnaire. In response to the question about "do you have a security & privacy" section, you've said "not yet". We'd like to encourage you to write that, even if it is minimal.
    2. We suggest thinking about any possible security & privacy implications - especially if the proposal could increase potential for CSS-based fingerprinting or CSS injection.
    3. If the answer to these questions is "no", it's still worth documenting.
    4. If the answer is "maybe," then please specify mitigations.
  2. Regarding the explainer:
    1. We prefer the explainer to be put next to the relevant spec (like this one) instead of in a personal repo
    2. The explainer could be made clearer. It currently includes both functions and mixins, which is confusing, and the mixins part seems incomplete (though it's out of the scope of this review)
  3. An interesting question: have you considered naming it "Custom Macros"? Since the entire CSS custom variable mechanism is built on top of token substitution, which is how macros work. This is even more explicit with @function
Discussed Apr 1, 2025 (See Github)

Xiaocheng: Would like to add #1031 (custom functions) … CSS feature where you can define a function for certain calculations … is built on top of CSS custom properties … think it can be closed without any concerns … they didn't like alternatives (CSS custom macros) Hadley: Do you think Martin would agree? Xiaocheng: Let's leave a comment in Slack Matthew: Could leave propose: closing, agree that Martin should have the opportunity Hadley: If Martin agrees, go ahead and close it

Discussed Apr 1, 2025 (See Github)

Xiaocheng: Proposed close last time. Waiting for a response from Dan and Martin, who didn't say anything.

Jeffrey: Martin replied in the last hour. ""

Jeffrey: There's disagreement about whether explainers should be disposable.

Xiaocheng: Explainer is a collection of initial thoughts, so it's early. They put mixins and functions in the same explainer because they're related. Did we say we don't want people to do repeated work on explainers.

Jeffrey: There's a variety of opinions. I think explainers should move into specs as the specs are being finished. I think Martin disagrees.

Xiaocheng: I'll draft a comment to close the issue and ask them to improve the explainer.

Comment by @andruud Apr 10, 2025 (See Github)
  1. The spec has had privacy and security sections for quite some time already, although it was indeed missing at the time this issue was filed. We have thought about this, without finding any issues. I'll bring it up for discussion internally again, though.
  2. Yes, the explainer intentionally includes mixins because it's relevant for understanding the greater problem space. So perhaps it was incorrect to consider mixins fully out of scope for this review.
  3. I see what you mean. To my knowledge, this is the first time it has been proposed. "Macro" can mean different things depending on your background, though: in C/C++, it's a preprocessor thing that can substitute anything, at any level (<dashed-function>s, and more generally arbitrary substitution functions, can not: they only exist in the value space); LISP macros work differently, and are more integrated with the language; and MS Excel Macros are something else entirely. At least to me, it's not obvious that the term "macro" would meaningfully help the author in understanding what's going on; "CSS macros" would likely be subtly different from any existing definition of "macro". Of course "CSS functions" has the same problem, but my point is that "macro" isn't an obvious improvement.
Comment by @xiaochengh Apr 25, 2025 (See Github)

Hi @andruud, the TAG discussed the feature and are satisfied with it.

We would also like to see the explainer improved, as it seems to mostly serve early exploration purposes and are mixed with the mixins feature. The TAG prefers a dedicated explainer that's put next to the relevant spec, which is not only for TAG reviews, but also serves as an official explainer for everyone who reads the spec.