@clay-design-system/tokens 0.10.0 → 0.14.0

package/stylelint-plugin/no-literal-values.js

@@ -0,0 +1,178 @@
+/**
+ * stylelint-plugin: clay-ds/no-literal-values
+ *
+ * Every size and color in component CSS comes from a token. Flags, in declaration values:
+ *   - length literals: px, rem, and em (em is allowed for letter-spacing only)
+ *   - hex colors (#fff, #1c1d21aa)
+ *   - color functions: rgb() / rgba() / hsl() / hsla()
+ *   - a fallback on a real token (any fallback — tokens always resolve): var(--clay-size-space-500, 20)
+ *   - a literal length/color default on a runtime custom property: var(--agent-visual-size, 160px)
+ *     (real token names are read from ../dist/tokens.css; without a build, any --clay-* counts)
+ *   - an unknown token: var(--clay-x) that tokens.css doesn't define, with no fallback and no declaration of
+ *     --clay-x in the same file — it resolves to nothing (e.g. a renamed or misspelled token)
+ *
+ * Allowed:
+ *   - 0 (with or without a unit), %, vw/vh/fr/deg/ms/s, unitless numbers (line-height, z-index, …)
+ *   - token unit conversion: calc(var(--clay-*) * Npx) / calc(Npx * var(--clay-*)), any N — also at the
+ *     end of a chain or after a group: var(--clay-a) * 2 * 1px, (var(--clay-a) - var(--clay-b)) * 1px
+ *   - runtime unit conversion: calc(var(--any-prop) * 1px), e.g. a height set from JS
+ *   - a literal multiplied by a plain number is still a literal: calc(2 * 416px) is flagged
+ *   - em in letter-spacing: calc(var(--clay-web-type-*-letter-spacing) * 1em) or a bare em value
+ *   - anything inside url(...) or a string
+ *
+ * Usage in .stylelintrc:
+ *   plugins: ['@clay-design-system/tokens/stylelint-plugin/no-literal-values.js']
+ *   rules:
+ *     'clay-ds/no-literal-values': true
+ */
+
+import { readFileSync } from 'node:fs'
+import stylelint from 'stylelint'
+
+const { createPlugin, utils } = stylelint
+
+const ruleName = 'clay-ds/no-literal-values'
+const messages = utils.ruleMessages(ruleName, {
+  length: (value, prop) => `Literal length "${value}" in "${prop}". Use ${lengthHint(prop)}.`,
+  color: (value, prop) =>
+    `Literal color "${value}" in "${prop}". Use a semantic --clay-color-* token (or --clay-effect-shadow-* for shadows).`,
+  tokenFallback: (fallback, name) =>
+    `Fallback "${fallback}" on token var(${name}, …). Tokens always resolve — drop the fallback.`,
+  literalDefault: (value, name) =>
+    `Literal default "${value}" in var(${name}, …). Default to a token instead.`,
+  unknownToken: (name) =>
+    `Unknown token var(${name}): tokens.css doesn't define it and this file doesn't declare it, so it resolves to nothing.`,
+})
+
+/** Which token family a literal length in `prop` most likely belongs to. */
+function lengthHint(prop) {
+  const p = prop.toLowerCase()
+  if (/^(font-size|line-height|letter-spacing)$/.test(p)) return 'a --clay-web-type-* token'
+  if (/radius/.test(p)) return 'a --clay-radius-* token'
+  if (/^(border|outline)(-(top|right|bottom|left))?(-width)?$/.test(p))
+    return 'a --clay-size-stroke-* token (1px → --clay-size-stroke-border)'
+  if (/shadow/.test(p)) return 'a --clay-effect-shadow-* token'
+  return 'a token: calc(var(--clay-size-space-*) * 1px), a layout token, or a component token'
+}
+
+/** Every custom property tokens.css defines; empty when the package isn't built yet. */
+const TOKEN_NAMES = (() => {
+  try {
+    const css = readFileSync(new URL('../dist/tokens.css', import.meta.url), 'utf8')
+    return new Set([...css.matchAll(/(--clay-[\w-]+)\s*:/g)].map((m) => m[1]))
+  } catch {
+    return new Set()
+  }
+})()
+const isToken = (name) => (TOKEN_NAMES.size ? TOKEN_NAMES.has(name) : name.startsWith('--clay-'))
+
+/** The innermost `var(` call (the last one in the string) with its balanced inner text. */
+function lastVarCall(value) {
+  const start = value.lastIndexOf('var(')
+  if (start === -1) return null
+  let depth = 1
+  let i = start + 4
+  for (; i < value.length && depth > 0; i++) {
+    if (value[i] === '(') depth++
+    else if (value[i] === ')') depth--
+  }
+  return { start, end: i, inner: value.slice(start + 4, i - 1) }
+}
+
+// After step 1 every var() is reduced to the placeholder VAR{--name}.
+const LENGTH = /(^|[^\w.#-])(-?\d*\.?\d+)(px|rem|em)\b/gi
+const HEX = /(^|[^\w&-])(#[0-9a-f]{3,8})\b/gi
+const COLOR_FN = /\b(rgba?|hsla?)\(/gi
+
+/**
+ * Is the length at value[start, end) a unit multiplier — `<operand> * Npx` or `Npx * VAR{…}` — whose
+ * operand holds a var? Token vars allow any N; other (runtime) vars only ±1. The left operand may be a
+ * VAR{…}, a (…) group containing one, or a numeric chain ending in one (VAR{a} * 2 * 1px).
+ */
+function isUnitConversion(value, start, end, num) {
+  const allowed = (name) => name.startsWith('--clay-') || Math.abs(num) === 1
+  const right = value.slice(end).match(/^\s*\*\s*VAR\{(--[\w-]+)\}/)
+  if (right) return allowed(right[1])
+  let left = value.slice(0, start)
+  for (;;) {
+    const star = left.match(/\*\s*$/)
+    if (!star) return false
+    left = left.slice(0, star.index).trimEnd()
+    const v = left.match(/VAR\{(--[\w-]+)\}$/)
+    if (v) return allowed(v[1])
+    if (left.endsWith(')')) {
+      let depth = 0
+      let i = left.length - 1
+      for (; i >= 0; i--) {
+        if (left[i] === ')') depth++
+        else if (left[i] === '(' && --depth === 0) break
+      }
+      const names = [...left.slice(i).matchAll(/VAR\{(--[\w-]+)\}/g)].map((m) => m[1])
+      return names.length > 0 && (names.some((n) => n.startsWith('--clay-')) || Math.abs(num) === 1)
+    }
+    const n = left.match(/-?\d*\.?\d+$/)
+    if (!n) return false
+    left = left.slice(0, n.index)
+  }
+}
+
+/** Length and color literals in a value whose var() calls are already placeholders. */
+function literals(value, prop) {
+  const found = []
+  for (const m of value.matchAll(LENGTH)) {
+    const [, lead, num, unit] = m
+    if (Number(num) === 0) continue
+    if (unit.toLowerCase() === 'em' && prop === 'letter-spacing') continue
+    const start = m.index + lead.length
+    if (isUnitConversion(value, start, start + num.length + unit.length, Number(num))) continue
+    found.push({ kind: 'length', word: `${num}${unit}` })
+  }
+  for (const m of value.matchAll(HEX)) found.push({ kind: 'color', word: m[2] })
+  for (const m of value.matchAll(COLOR_FN)) found.push({ kind: 'color', word: `${m[1]}()` })
+  return found
+}
+
+const ruleFunction = (primary) => {
+  return (root, result) => {
+    const validOptions = utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    })
+    if (!validOptions) return
+
+    // Custom properties this file declares itself (runtime props, local --clay-* hooks) are never unknown.
+    const declared = new Set()
+    root.walkDecls(/^--/, (decl) => declared.add(decl.prop))
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase()
+      const report = (message, word) =>
+        utils.report({ message, node: decl, result, ruleName, word })
+
+      // Strings and url() never carry design values.
+      let value = decl.value.replace(/url\([^)]*\)/gi, 'url()').replace(/(["'])(?:\\.|(?!\1).)*\1/g, '""')
+
+      // 1. var() fallbacks — report, then reduce each var(), innermost first, to VAR{--name}.
+      for (let call = lastVarCall(value); call; call = lastVarCall(value)) {
+        const { start, end, inner } = call
+        const comma = inner.indexOf(',')
+        const name = (comma === -1 ? inner : inner.slice(0, comma)).trim()
+        const fallback = comma === -1 ? '' : inner.slice(comma + 1).trim()
+        if (fallback && isToken(name)) report(messages.tokenFallback(fallback, name), fallback)
+        else if (fallback)
+          for (const { word } of literals(fallback, prop)) report(messages.literalDefault(word, name), word)
+        else if (TOKEN_NAMES.size && name.startsWith('--clay-') && !isToken(name) && !declared.has(name))
+          report(messages.unknownToken(name), name)
+        value = `${value.slice(0, start)}VAR{${name}}${value.slice(end)}`
+      }
+
+      // 2. No length or color literal may remain (unit conversions excepted, see isUnitConversion).
+      for (const { kind, word } of literals(value, prop)) report(messages[kind](word, decl.prop), word)
+    })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+
+export default createPlugin(ruleName, ruleFunction)

package/stylelint-plugin/reduced-motion.js

@@ -0,0 +1,57 @@
+/**
+ * stylelint-plugin: clay-ds/reduced-motion
+ *
+ * A file that animates must also handle reduced motion. If a file declares `@keyframes`, or an
+ * `animation` / `animation-name` other than `none`, it must contain a
+ * `@media (prefers-reduced-motion: …)` block — `reduce` (switch the motion off) or
+ * `no-preference` (only animate when allowed). Reported once per file, on the first animation.
+ *
+ * Usage in .stylelintrc:
+ *   plugins: ['@clay-design-system/tokens/stylelint-plugin/reduced-motion.js']
+ *   rules:
+ *     'clay-ds/reduced-motion': true
+ */
+
+import stylelint from 'stylelint'
+
+const { createPlugin, utils } = stylelint
+
+const ruleName = 'clay-ds/reduced-motion'
+const messages = utils.ruleMessages(ruleName, {
+  missing: (what) =>
+    `${what} animates, but this file has no @media (prefers-reduced-motion: …) block. Disable or gate the motion for users who ask for less.`,
+})
+
+const ruleFunction = (primary) => {
+  return (root, result) => {
+    const validOptions = utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    })
+    if (!validOptions) return
+
+    let firstMotion = null
+    let hasReducedMotion = false
+
+    root.walk((node) => {
+      if (node.type === 'atrule') {
+        const name = node.name.toLowerCase()
+        if (name === 'media' && /prefers-reduced-motion/i.test(node.params)) hasReducedMotion = true
+        if (!firstMotion && /-?keyframes$/.test(name))
+          firstMotion = { node, what: `@keyframes ${node.params}` }
+      } else if (node.type === 'decl' && !firstMotion) {
+        const prop = node.prop.toLowerCase()
+        if ((prop === 'animation' || prop === 'animation-name') && !/^\s*none\s*$/i.test(node.value))
+          firstMotion = { node, what: `"${node.prop}: ${node.value}"` }
+      }
+    })
+
+    if (firstMotion && !hasReducedMotion)
+      utils.report({ message: messages.missing(firstMotion.what), node: firstMotion.node, result, ruleName })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+
+export default createPlugin(ruleName, ruleFunction)

package/stylelint-plugin/require-layer.js

@@ -0,0 +1,66 @@
+/**
+ * stylelint-plugin: clay-ds/require-layer
+ *
+ * Design-system CSS sits in `@layer clay.components`, so unlayered consumer styles always win.
+ * Every top-level rule, declaration and at-rule must be inside an `@layer clay.components { … }`
+ * block. Allowed at the top level as well:
+ *   - @layer order statements (`@layer clay.tokens, clay.base, clay.components;`)
+ *   - @keyframes (Chrome needs scroll-driven keyframes outside a layer), @property, @font-face
+ *   - @view-transition (a document-level descriptor block; cascade layers don't apply to it)
+ *   - @import, @charset
+ *
+ * Page CSS (apps/pages) is unlayered by design — don't enable this rule there.
+ *
+ * Usage in .stylelintrc:
+ *   plugins: ['@clay-design-system/tokens/stylelint-plugin/require-layer.js']
+ *   rules:
+ *     'clay-ds/require-layer': true            // or [true, { layer: 'clay.components' }]
+ */
+
+import stylelint from 'stylelint'
+
+const { createPlugin, utils } = stylelint
+
+const ruleName = 'clay-ds/require-layer'
+const messages = utils.ruleMessages(ruleName, {
+  outside: (what, layer) => `${what} sits outside @layer ${layer}. Wrap it in @layer ${layer} { … }.`,
+  wrongLayer: (name, layer) => `@layer ${name} — design-system CSS belongs in @layer ${layer}.`,
+})
+
+const TOP_LEVEL_OK = new Set(['keyframes', 'property', 'font-face', 'view-transition', 'import', 'charset'])
+
+const ruleFunction = (primary, secondary) => {
+  return (root, result) => {
+    const validOptions = utils.validateOptions(
+      result,
+      ruleName,
+      { actual: primary, possible: [true] },
+      { actual: secondary, possible: { layer: [(v) => typeof v === 'string'] }, optional: true },
+    )
+    if (!validOptions) return
+    const layer = secondary?.layer ?? 'clay.components'
+
+    for (const node of root.nodes ?? []) {
+      if (node.type === 'comment') continue
+      if (node.type === 'atrule') {
+        const name = node.name.toLowerCase()
+        if (/-?keyframes$/.test(name) || TOP_LEVEL_OK.has(name)) continue
+        if (name === 'layer') {
+          if (!node.nodes) continue // order statement: @layer a, b;
+          if (node.params.trim() !== layer)
+            utils.report({ message: messages.wrongLayer(node.params.trim(), layer), node, result, ruleName })
+          continue
+        }
+        utils.report({ message: messages.outside(`@${node.name} ${node.params}`.trim(), layer), node, result, ruleName })
+        continue
+      }
+      const what = node.type === 'rule' ? `"${node.selector}"` : `"${node.prop}"`
+      utils.report({ message: messages.outside(what, layer), node, result, ruleName })
+    }
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+
+export default createPlugin(ruleName, ruleFunction)