@halogen-ui/eslint-config 0.1.0

package/LICENSE.md

@@ -0,0 +1,102 @@
+# Halogen License Agreement
+
+Copyright © 2026 Nick Jacoy. All rights reserved.
+
+Halogen is **source-available commercial software**. The source is published so
+that it can be read, evaluated and audited before purchase — publication is not
+a grant of the right to use it. Use in a project requires a valid license.
+
+## 1. Definitions
+
+- **"Software"** — the Halogen design system, comprising the `@halogen-ui/react`,
+  `@halogen-ui/tokens` and `@halogen-ui/eslint-config` packages and their source,
+  documentation and generated assets.
+- **"Licensee"** — the individual or single legal entity that has purchased a
+  license.
+- **"Product"** — an application, website or service built by the Licensee in
+  which the Software is used as a component of a larger work.
+
+## 2. Evaluation
+
+Without purchasing a license, you may download, read, run and evaluate the
+Software, including building and running it locally. You may not use it in a
+Product, whether or not that Product is distributed, sold or made public.
+
+## 3. Grant of license
+
+Upon purchase, the Licensee is granted a perpetual, worldwide, non-exclusive,
+non-transferable license to:
+
+a. use the Software in an unlimited number of Products;
+b. modify the Software and use the modified version in those Products;
+c. distribute the Software **as part of** a Product, in compiled or bundled
+   form, to that Product's end users;
+d. make copies as reasonably required for backup and development.
+
+The license covers the Licensee and its employees and contractors, acting on the
+Licensee's behalf.
+
+## 4. Restrictions
+
+The Licensee may not:
+
+a. redistribute, publish, sublicense, sell, rent or lend the Software on its
+   own, or in any form where the Software — rather than a Product built with
+   it — is the substance of what is conveyed;
+b. use the Software to create or contribute to a competing design system,
+   component library, UI kit or template that is distributed to third parties;
+c. remove or obscure copyright, license or attribution notices;
+d. share license credentials or a purchased copy outside the Licensee.
+
+Publishing a fork, a re-skin, or a repackaged subset of the Software to a public
+registry or repository is prohibited under (a) and (b), and this remains true
+however the files were obtained.
+
+## 5. Third-party components
+
+The Software depends on and, in the case of fonts, redistributes third-party
+material licensed separately by its authors — including Radix UI, `clsx`,
+`class-variance-authority`, `tailwind-merge` and `lucide-react` (MIT), and the
+Geist and Geist Mono typefaces (SIL Open Font License 1.1, whose text ships at
+`fonts/LICENSE-Geist-OFL-1.1.txt`). Nothing in this Agreement limits or replaces
+your rights and obligations under those licenses.
+
+## 6. Ownership
+
+The Software is licensed, not sold. All title and intellectual property rights
+in the Software remain with the copyright holder. Rights not expressly granted
+here are reserved.
+
+## 7. Warranty disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+Halogen makes strong accessibility and contrast claims and tests them
+extensively. Those tests are evidence, not a warranty: conformance of *your*
+Product is your responsibility.
+
+## 8. Limitation of liability
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE. Total liability shall not exceed the amount paid for
+the license.
+
+## 9. Termination
+
+This license terminates automatically if the Licensee materially breaches it and
+does not cure the breach within 30 days of notice. On termination the Licensee
+must cease using the Software in new Products; Products already distributed are
+unaffected.
+
+## 10. Governing law
+
+This Agreement is governed by the laws of the State of California, United
+States, without regard to its conflict-of-laws rules.
+
+---
+
+Licensing questions: https://github.com/njacoy/halogen-design-system

package/README.md

@@ -0,0 +1,36 @@
+# @halogen-ui/eslint-config
+
+The four rules that make [Halogen](https://github.com/njacoy/halogen-design-system)'s
+guarantees hold in *your* code, not just inside the library.
+
+```bash
+pnpm add -D @halogen-ui/eslint-config
+```
+
+```js
+// eslint.config.js
+import { recommended } from '@halogen-ui/eslint-config';
+
+export default [
+  recommended,
+  // ...the rest of your flat config
+];
+```
+
+`recommended` turns all four on as errors. The raw `plugin` is also exported if
+you would rather wire the rules yourself.
+
+## The rules
+
+| Rule | Catches |
+| --- | --- |
+| `no-arbitrary-values` | `p-[13px]`, `text-[15px]` — a value invented to dodge a missing token |
+| `no-primitive-colors` | reaching past the semantic layer into the raw palette |
+| `no-aria-label-on-generic` | `aria-label` on a `span`, `div`, `kbd` — ARIA forbids naming a roleless element, so the name is silently dropped |
+| `no-gradient-on-controls` | gradients on interactive controls, where they break the state vocabulary |
+
+Each one exists because the mistake it catches **compiles cleanly and looks
+right**. A dead utility produces no CSS and no error; a dropped `aria-label` is
+valid HTML that no screen reader ever announces. A typechecker cannot see either.
+
+ESLint `>=9` (flat config) is a peer dependency.

package/index.js

@@ -0,0 +1,47 @@
+/**
+ * Halogen — the enforcement rules, shipped.
+ *
+ * These travel with the kit rather than living in the source repo, because a
+ * design system's guarantees are only worth something inside the buyer's
+ * codebase. Without them, Halogen is a folder of components that will drift
+ * into a folder of one-offs within a year.
+ */
+import { createRequire } from 'node:module';
+
+import noAriaLabelOnGeneric from './rules/no-aria-label-on-generic.js';
+import noArbitraryValues from './rules/no-arbitrary-values.js';
+import noGradientOnControls from './rules/no-gradient-on-controls.js';
+import noPrimitiveColors from './rules/no-primitive-colors.js';
+
+/* Read from the manifest rather than written here twice.
+ *
+ * ESLint puts plugin meta into its cache keys and its error output, so a
+ * hardcoded version does not fail — it silently reports the wrong number from
+ * the first release onward, and stale cache entries are the kind of bug nobody
+ * traces back to a string literal. createRequire rather than a JSON import
+ * attribute, which is still gated behind a flag on some runtimes a consumer
+ * might be linting under. */
+const { name, version } = createRequire(import.meta.url)('./package.json');
+
+export const plugin = {
+  meta: { name, version },
+  rules: {
+    'no-aria-label-on-generic': noAriaLabelOnGeneric,
+    'no-arbitrary-values': noArbitraryValues,
+    'no-gradient-on-controls': noGradientOnControls,
+    'no-primitive-colors': noPrimitiveColors,
+  },
+};
+
+/** Recommended flat config. Spread into your eslint.config.js. */
+export const recommended = {
+  plugins: { halogen: plugin },
+  rules: {
+    'halogen/no-aria-label-on-generic': 'error',
+    'halogen/no-arbitrary-values': 'error',
+    'halogen/no-gradient-on-controls': 'error',
+    'halogen/no-primitive-colors': 'error',
+  },
+};
+
+export default { plugin, recommended };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@halogen-ui/eslint-config",
+  "version": "0.1.0",
+  "description": "Halogen's enforcement rules. Ships to consumers — the system's guarantees travel with it.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "rules",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/njacoy/halogen-design-system.git",
+    "directory": "packages/eslint-config"
+  },
+  "homepage": "https://github.com/njacoy/halogen-design-system#readme",
+  "bugs": {
+    "url": "https://github.com/njacoy/halogen-design-system/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eslint-config",
+    "design-system",
+    "tailwindcss",
+    "halogen"
+  ],
+  "scripts": {}
+}

package/rules/no-arbitrary-values.js

@@ -0,0 +1,139 @@
+/**
+ * Halogen — `no-arbitrary-values`.
+ *
+ * Arbitrary values are the crack that drains a design system.
+ *
+ * Replacing Tailwind's theme stops `p-7` from compiling, but `p-[28px]` still
+ * works — arbitrary values bypass the theme entirely. One of them is harmless.
+ * Two hundred of them, added one reasonable exception at a time over a year, is
+ * a codebase where the token layer describes nothing that is actually on screen.
+ *
+ * That is the failure this rule exists to prevent, and it is why the rule ships
+ * to buyers rather than staying in the repo: the guarantee is only worth
+ * something if it survives contact with their codebase.
+ */
+
+/** `p-[28px]`, `bg-[#fff]`, `w-[calc(100%-1rem)]`, including under modifiers. */
+const ARBITRARY = /(^|:)-?[a-z][a-z0-9-]*-\[[^\]]+\]/;
+/**
+ * An arbitrary *variant* — a selector, not a value: `[&>svg]:size-4`, and also
+ * `aria-[invalid=true]:border-x`, where the brackets sit mid-token. Reported
+ * separately because the fix is different: Tailwind almost always has a named
+ * variant already (`aria-invalid:`), and reaching for a raw selector usually
+ * means a component boundary is in the wrong place.
+ */
+const ARBITRARY_VARIANT = /\[[^\]]+\]:/;
+
+const CLASS_CALLEES = new Set(['cn', 'cva', 'clsx', 'classNames', 'twMerge', 'tw']);
+const CLASS_ATTRS = new Set(['className', 'class']);
+
+/**
+ * A string that is *shaped* like a class list, wherever it happens to sit.
+ *
+ * The call-site check below is necessary and was not sufficient. A component can
+ * hold its classes in a plain lookup map and interpolate them into `className`
+ * later, and the rule saw nothing:
+ *
+ *   const ASPECT = { wide: 'aspect-[21/9]' };   // <- invisible
+ *   <div className={ASPECT[aspect]} />
+ *
+ * That is not a hypothetical. `ContentCard` shipped exactly this, and the sole
+ * arbitrary value in the entire library sat in it, unreported, while the rule
+ * that exists to forbid arbitrary values passed clean.
+ *
+ * The shape test is strict on purpose: EVERY whitespace-separated segment must
+ * look like a utility — lowercase, no sentence punctuation. Prose fails it on
+ * the first capital letter or bare word, so a `why:` field describing a token
+ * is not mistaken for a class list. A string only gets reported if it also
+ * contains an arbitrary value, so passing the shape test alone costs nothing.
+ */
+const UTILITY_SEGMENT = /^-?(?:[a-z0-9][a-z0-9-]*(?:-\[[^\]]+\])?:)*-?[a-z0-9][a-z0-9./-]*(?:\[[^\]]+\])?[a-z0-9%./-]*!?$/;
+
+function looksLikeClassList(raw) {
+  const segments = raw.trim().split(/\s+/).filter(Boolean);
+  if (segments.length === 0) return false;
+  return segments.every((s) => UTILITY_SEGMENT.test(s));
+}
+
+/** True when this string literal is somewhere that becomes a class name. */
+function inClassContext(node, sourceCode) {
+  let current = node;
+  for (let i = 0; i < 12 && current; i++) {
+    const parent = sourceCode.getAncestors
+      ? current.parent
+      : current.parent;
+    if (!parent) return false;
+
+    if (parent.type === 'JSXExpressionContainer' && parent.parent?.type === 'JSXAttribute') {
+      return CLASS_ATTRS.has(parent.parent.name?.name);
+    }
+    if (parent.type === 'JSXAttribute') {
+      return CLASS_ATTRS.has(parent.name?.name);
+    }
+    if (parent.type === 'CallExpression') {
+      const callee = parent.callee;
+      const name = callee?.name ?? callee?.property?.name;
+      if (CLASS_CALLEES.has(name)) return true;
+    }
+    // A `*.variants.ts` file is class definitions top to bottom.
+    current = parent;
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow Tailwind arbitrary values. Every value must come from a Halogen token.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          /** Files whose every string is treated as classes, e.g. `*.variants.ts`. */
+          treatAllStringsAsClasses: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      arbitrary:
+        '"{{ value }}" is an arbitrary value. Halogen is tokens-only: use a token from the scale, or add one deliberately if the scale is genuinely missing a step.',
+      arbitraryVariant:
+        '"{{ value }}" is an arbitrary variant. Express the relationship with a component or a documented variant instead of an ad-hoc selector.',
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] ?? {};
+    const patterns = options.treatAllStringsAsClasses ?? ['\\.variants\\.(ts|tsx|js)$'];
+    const filename = context.filename ?? context.getFilename();
+    const alwaysClasses = patterns.some((p) => new RegExp(p).test(filename));
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    function check(node, raw) {
+      if (typeof raw !== 'string' || !raw.includes('[')) return;
+      if (!alwaysClasses && !inClassContext(node, sourceCode) && !looksLikeClassList(raw)) return;
+
+      for (const token of raw.split(/\s+/)) {
+        if (!token) continue;
+        if (ARBITRARY_VARIANT.test(token)) {
+          context.report({ node, messageId: 'arbitraryVariant', data: { value: token } });
+        } else if (ARBITRARY.test(token)) {
+          context.report({ node, messageId: 'arbitrary', data: { value: token } });
+        }
+      }
+    }
+
+    return {
+      Literal(node) {
+        check(node, node.value);
+      },
+      TemplateElement(node) {
+        check(node, node.value?.cooked);
+      },
+    };
+  },
+};

package/rules/no-aria-label-on-generic.js

@@ -0,0 +1,79 @@
+/**
+ * Halogen — `no-aria-label-on-generic`.
+ *
+ * `aria-label` is prohibited on an element with no ARIA role.
+ *
+ * A `<span>`, a `<div>`, a `<kbd>` — none of these have an implicit role, and
+ * ARIA forbids naming a roleless element. Assistive technology is free to ignore
+ * the attribute entirely, which it does. The label is simply thrown away.
+ *
+ * Nothing complains. The attribute is valid HTML, TypeScript accepts it, the
+ * element renders, and a reader hears nothing where a name was intended. It is
+ * the exact failure mode this system keeps producing: **written, plausible,
+ * silently discarded.**
+ *
+ * This rule exists because it happened twice in one afternoon — `Kbd` naming a
+ * shortcut, and `Breadcrumb` naming the gap in a collapsed trail. Both were
+ * caught by axe in a browser, and only because the showcase happened to render
+ * them. A component whose labelled state is not on the review page would have
+ * shipped.
+ *
+ * The fix is always the same: a visually-hidden span with the text in it, which
+ * works on any element. Or give the element a real role, if it has one.
+ */
+
+/**
+ * Elements with no implicit ARIA role, or whose role prohibits naming.
+ *
+ * Deliberately not exhaustive — this is the set that actually gets reached for.
+ * `<p>` is included: its `paragraph` role also prohibits a name.
+ */
+const ROLELESS = new Set([
+  'span', 'div', 'kbd', 'code', 'p', 'em', 'strong', 'small',
+  'b', 'i', 's', 'u', 'sub', 'sup', 'pre', 'blockquote', 'label',
+]);
+
+const NAMING_ATTRS = new Set(['aria-label', 'aria-labelledby']);
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow aria-label on elements with no ARIA role, where it is prohibited and ignored.',
+    },
+    schema: [],
+    messages: {
+      prohibited:
+        '`{{ attr }}` on <{{ element }}> is prohibited: the element has no ARIA role, so assistive technology discards the name. Use a visually-hidden <span className="sr-only"> with the text, or give the element a role.',
+    },
+  },
+
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        const name = node.name?.name;
+        if (typeof name !== 'string' || !ROLELESS.has(name)) return;
+
+        // An explicit role makes naming legal again — `<div role="group">` is a
+        // real group and may be named.
+        const hasRole = node.attributes.some(
+          (attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'role',
+        );
+        if (hasRole) return;
+
+        for (const attr of node.attributes) {
+          if (attr.type !== 'JSXAttribute') continue;
+          const attrName = attr.name?.name;
+          if (typeof attrName === 'string' && NAMING_ATTRS.has(attrName)) {
+            context.report({
+              node: attr,
+              messageId: 'prohibited',
+              data: { attr: attrName, element: name },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-gradient-on-controls.js

@@ -0,0 +1,60 @@
+/**
+ * Halogen — `no-gradient-on-controls`.
+ *
+ * Gradients belong on heroes, feature surfaces, promotional panels, progress
+ * fills and decorative fields. They do not belong on buttons, inputs, tables,
+ * navigation, badges, icons or borders.
+ *
+ * The reason is not taste. A gradient has no single color, so no contrast
+ * figure can be computed for text sitting on it — every assertion in the system
+ * would have to become "at the worst stop", which is exactly the treatment
+ * `GradientSurface` exists to contain. Spread across controls, the guarantee
+ * that any label meets a known ratio simply stops being true.
+ */
+const GRADIENT = /(^|:)gradient-(ember|solar|dusk|glow|ground)\b/;
+
+/** Files where a gradient is legitimate: marketing surfaces and the two components that own them. */
+const DEFAULT_ALLOW = [
+  'GradientSurface',
+  'Progress',
+  '/marketing/',
+  '\\.stories\\.',
+];
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Disallow brand gradients on controls and product chrome.' },
+    schema: [
+      {
+        type: 'object',
+        properties: { allow: { type: 'array', items: { type: 'string' } } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      gradient:
+        '"{{ value }}" puts a gradient on a control. Gradients have no single color, so no contrast figure can be computed for text on them. Use <GradientSurface> for brand moments, or a solid surface token here.',
+    },
+  },
+
+  create(context) {
+    const allow = [...DEFAULT_ALLOW, ...(context.options[0]?.allow ?? [])].map((p) => new RegExp(p));
+    const filename = context.filename ?? context.getFilename();
+    if (allow.some((r) => r.test(filename))) return {};
+
+    function check(node, raw) {
+      if (typeof raw !== 'string') return;
+      for (const token of raw.split(/\s+/)) {
+        if (token && GRADIENT.test(token)) {
+          context.report({ node, messageId: 'gradient', data: { value: token } });
+        }
+      }
+    }
+
+    return {
+      Literal(node) { check(node, node.value); },
+      TemplateElement(node) { check(node, node.value?.cooked); },
+    };
+  },
+};

package/rules/no-primitive-colors.js

@@ -0,0 +1,61 @@
+/**
+ * Halogen — `no-primitive-colors`.
+ *
+ * Primitive color utilities (`bg-orange-base`, `text-neutral-500`) exist for
+ * marketing surfaces, where a designer is composing a brand moment and the
+ * semantic layer would only get in the way.
+ *
+ * In product UI they are a theme bug waiting to happen: `text-neutral-500` is a
+ * fixed gray in both themes, so it reads correctly in dark and washes out in
+ * light. The semantic layer exists precisely so a component never has to know
+ * which theme it is in.
+ *
+ * Default scope is the component library itself, which must be semantic-only.
+ */
+const PRIMITIVE_PREFIXES = [
+  'neutral', 'orange', 'coral', 'amber', 'yellow', 'peach', 'pink', 'teal',
+  'success', 'warning', 'error', 'heat',
+];
+const COLOR_UTILITIES = ['bg', 'text', 'border', 'outline', 'ring', 'fill', 'stroke', 'decoration', 'divide'];
+
+const PATTERN = new RegExp(
+  `(^|:)(${COLOR_UTILITIES.join('|')})-(${PRIMITIVE_PREFIXES.join('|')})-`,
+);
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Disallow primitive color utilities in product UI.' },
+    schema: [
+      {
+        type: 'object',
+        properties: { allow: { type: 'array', items: { type: 'string' } } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      primitive:
+        '"{{ value }}" is a primitive color and does not change between themes. Use a semantic token (bg-surface-*, text-ink-*, border-line-*) so the component works in both.',
+    },
+  },
+
+  create(context) {
+    const allow = (context.options[0]?.allow ?? []).map((p) => new RegExp(p));
+    const filename = context.filename ?? context.getFilename();
+    if (allow.some((r) => r.test(filename))) return {};
+
+    function check(node, raw) {
+      if (typeof raw !== 'string') return;
+      for (const token of raw.split(/\s+/)) {
+        if (token && PATTERN.test(token)) {
+          context.report({ node, messageId: 'primitive', data: { value: token } });
+        }
+      }
+    }
+
+    return {
+      Literal(node) { check(node, node.value); },
+      TemplateElement(node) { check(node, node.value?.cooked); },
+    };
+  },
+};