@seanyeh77/eslint-plugin-ui 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hsiu-An Yeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. 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.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { ESLint, Linter, Rule } from "eslint";
+declare const rules: {
+  'no-raw-color': Rule.RuleModule;
+  'no-tailwind-defaults': Rule.RuleModule;
+  'no-native-controls': Rule.RuleModule;
+  'no-nested-card': Rule.RuleModule;
+  'one-primary-button': Rule.RuleModule;
+  'verb-labels': Rule.RuleModule;
+  'danger-confirm': Rule.RuleModule;
+};
+declare const plugin: ESLint.Plugin & {
+  configs: Record<string, Linter.Config>;
+};
+export { plugin as default, rules };

package/dist/index.js

@@ -0,0 +1,368 @@
+import tsParser from "@typescript-eslint/parser";
+// package.json
+var name = "@seanyeh77/eslint-plugin-ui";
+var version = "0.3.0";
+// src/index.ts
+const valueOf = (n) => n.value;
+const COLOR = /#[0-9a-fA-F]{3,8}\b|\brgba?\(|\bhsla?\(|\boklch\(/;
+const URL_REF = /url\(\s*['"]?#[^)]*\)/g;
+const NAMED = /^(black|white|red|green|blue|yellow|orange|purple|pink|gray|grey|brown|cyan|magenta|navy|teal|maroon|olive|lime|aqua|fuchsia|silver|gold|indigo|violet|crimson|tomato|coral|salmon|khaki|beige|ivory|lavender|tan|darkgray|darkgrey|lightgray|lightgrey|darkblue|lightblue|darkred|darkgreen|lightgreen)$/i;
+const COLOR_KEY = /color|background|fill|stroke|border|outline|shadow/i;
+const ARBITRARY = /-\[(#|rgba?\(|hsla?\(|oklch\()/;
+function tagName(el) {
+	const n = el.name;
+	if (n.type === "JSXIdentifier") return n.name ?? "";
+	if (n.type === "JSXMemberExpression") return n.property?.name ?? "";
+	return "";
+}
+function attr(el, name) {
+	return el.attributes.find((a) => a.type === "JSXAttribute" && a.name?.name === name);
+}
+function literal(a) {
+	if (!a?.value) return a ? true : void 0;
+	if (a.value.type === "Literal") return a.value.value;
+	if (a.value.type === "JSXExpressionContainer" && a.value.expression?.type === "Literal") return a.value.expression.value;
+}
+function textOf(el) {
+	return el.children.map((c) => {
+		const n = c;
+		if (n.type === "JSXText") return n.value ?? "";
+		if (n.type === "JSXExpressionContainer" && n.expression?.type === "Literal") return String(n.expression.value);
+		return "\0";
+	}).join("").trim();
+}
+const TW_COLOR = new RegExp(`^(bg|text|border(?:-[trblxyse])?|ring(?:-offset)?|inset-ring|outline|divide(?:-[xy])?|fill|stroke|from|via|to|placeholder|decoration|caret|accent|shadow|inset-shadow|drop-shadow|text-shadow)-(?:(?:slate|gray|zinc|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|[1-9]00|950)|white|black)(?:/(?:[\\d.]+|\\[[^\\]]+\\]|\\([^)]+\\)))?$`);
+const TW_RADIUS = /^rounded(?:-[trblse]{1,2})?(?:-(?:xs|xl|2xl|3xl|4xl))?$/;
+const TW_SHADOW = /^(?:shadow|drop-shadow|inset-shadow)(?:-(?:2xs|xs|md|lg|xl|2xl|inner))?$/;
+const CLASS_FNS = "cn|clsx|cx|cva|twMerge|twJoin|tv|classnames";
+const hasJsxClassAncestor = (n) => {
+	for (let p = n.parent; p; p = p.parent) {
+		const a = p;
+		if (a.type === "JSXAttribute") return a.name?.name === "className" || a.name?.name === "class";
+	}
+	return false;
+};
+const CLASS_CALL = new RegExp(`^(${CLASS_FNS})$`);
+const isClassValue = (n) => {
+	let innerKey;
+	for (let c = n, p = n.parent; p; c = p, p = p.parent) {
+		const a = p;
+		if (a.type === "JSXAttribute") return a.name?.name === "className" || a.name?.name === "class";
+		if (a.type === "CallExpression") return CLASS_CALL.test(a.callee?.name ?? "");
+		if (a.type === "BinaryExpression" || a.type === "SwitchCase") return false;
+		if (a.type === "MemberExpression" && a.computed && a.property === c) return false;
+		if (a.type === "Property" && a.key === c) return hasClassCallParent(p);
+		if (a.type === "Property") {
+			const k = keyName(a.key);
+			innerKey ??= k;
+			if (k === "defaultVariants") return false;
+			if ((k === "compoundVariants" || k === "compoundSlots") && innerKey !== "class" && innerKey !== "className") return false;
+		}
+	}
+	return false;
+};
+const hasClassCallParent = (prop) => {
+	const obj = prop.parent;
+	if (obj?.type !== "ObjectExpression") return false;
+	let up = obj.parent;
+	while (up?.type === "ArrayExpression") up = up.parent;
+	return up?.type === "CallExpression" && CLASS_CALL.test(up.callee?.name ?? "");
+};
+const keyName = (k) => {
+	const key = k;
+	return key?.type === "Identifier" ? key.name : typeof key?.value === "string" ? key.value : void 0;
+};
+const TOKEN_HINT = {
+	text: "text-ink, text-ink-muted, text-accent-text, text-danger-text, text-on-accent",
+	bg: "bg-surface, bg-surface-sub, bg-accent, bg-accent-soft, bg-danger-soft",
+	border: "border-line, border-line-strong, border-accent"
+};
+const twClasses = (v) => v.split(/\s+/).filter(Boolean).map((c) => c.slice(c.lastIndexOf(":") + 1).replace(/^!|!$/g, ""));
+const noTailwindDefaults = {
+	meta: {
+		type: "suggestion",
+		docs: { description: "Disallow Tailwind's default palette, radii and shadows: use the design system's token classes." },
+		schema: []
+	},
+	create(context) {
+		const check = (node, v) => {
+			for (const c of twClasses(v)) {
+				const color = TW_COLOR.exec(c);
+				if (color) {
+					const kind = color[1].startsWith("border") ? "border" : color[1];
+					context.report({
+						node,
+						message: "{{c}} is Tailwind's palette, not a design-system color. Use a token class: {{hint}}.",
+						data: {
+							c,
+							hint: TOKEN_HINT[kind] ?? `${color[1]}-ink, ${color[1]}-accent, ${color[1]}-line`
+						}
+					});
+				} else if (TW_RADIUS.test(c)) context.report({
+					node,
+					message: "{{c}} is not a design-system radius. Use rounded-sm, rounded-md or rounded-lg.",
+					data: { c }
+				});
+				else if (TW_SHADOW.test(c)) context.report({
+					node,
+					message: "{{c}} is not a design-system shadow. Use shadow-card, shadow-overlay or shadow-sm.",
+					data: { c }
+				});
+			}
+		};
+		return {
+			"JSXAttribute[name.name=/^(className|class)$/] Literal"(node) {
+				const v = valueOf(node);
+				if (typeof v === "string" && isClassValue(node)) check(node, v);
+			},
+			"JSXAttribute[name.name=/^(className|class)$/] TemplateElement"(node) {
+				if (isClassValue(node)) check(node, node.value.cooked ?? "");
+			},
+			[`CallExpression[callee.name=/^(${CLASS_FNS})$/] TemplateElement`](node) {
+				if (!hasJsxClassAncestor(node) && isClassValue(node)) check(node, node.value.cooked ?? "");
+			},
+			[`CallExpression[callee.name=/^(${CLASS_FNS})$/] Literal`](node) {
+				if (hasJsxClassAncestor(node)) return;
+				const v = valueOf(node);
+				if (typeof v === "string" && isClassValue(node)) check(node, v);
+			}
+		};
+	}
+};
+const noRawColor = {
+	meta: {
+		type: "problem",
+		docs: { description: "Colors come from tokens: var(--ink) or cssVar(\"ink\"), never a hex, rgb() or hsl() value." },
+		schema: []
+	},
+	create(context) {
+		const check = (node, value, key = "") => {
+			if (COLOR.test(value.replace(URL_REF, "")) || COLOR_KEY.test(key) && NAMED.test(value.trim())) context.report({
+				node,
+				message: "Hard-coded color \"{{v}}\". Use a token: var(--ink-muted) in CSS, cssVar(\"ink-muted\") from @seanyeh77/tokens in style props, or a component prop.",
+				data: { v: value.slice(0, 40) }
+			});
+		};
+		return {
+			"JSXAttribute[name.name=\"style\"] Literal"(node) {
+				const v = valueOf(node);
+				if (typeof v !== "string") return;
+				let p = node.parent;
+				let isValue = true;
+				for (let c = node; p && p.type !== "Property"; c = p, p = p.parent) {
+					const m = p;
+					if (m.type === "MemberExpression" && m.computed && m.property === c) return;
+					if (!(m.type === "ConditionalExpression" && m.test !== c || [
+						"LogicalExpression",
+						"TSAsExpression",
+						"TSSatisfiesExpression",
+						"TSNonNullExpression"
+					].includes(m.type))) isValue = false;
+				}
+				if (!p) return;
+				const key = p.key;
+				if (key === node) return;
+				check(node, v, isValue ? String(key?.name ?? key?.value ?? "") : "");
+			},
+			"JSXAttribute[name.name=/^(className|class)$/] Literal"(node) {
+				const v = valueOf(node);
+				if (typeof v === "string" && ARBITRARY.test(v)) context.report({
+					node,
+					message: "Arbitrary color in \"{{v}}\". Use the token classes of @seanyeh77/tokens/tailwind.css: bg-surface, text-ink-muted.",
+					data: { v: v.slice(0, 40) }
+				});
+			},
+			"JSXAttribute[name.name=\"style\"] Property > TemplateLiteral > TemplateElement"(node) {
+				check(node, String(valueOf(node).raw));
+			},
+			"JSXAttribute[name.name=/^(fill|stroke|color|stopColor|floodColor)$/] Literal"(node) {
+				const v = valueOf(node);
+				if (typeof v === "string") check(node, v, "color");
+			}
+		};
+	}
+};
+const REPLACE = {
+	select: "Select (or MultiSelect)",
+	table: "DataTable",
+	dialog: "Dialog",
+	progress: "ProgressBar"
+};
+const INPUT_REPLACE = {
+	checkbox: "Checkbox",
+	radio: "RadioGroup",
+	date: "DatePicker",
+	search: "SearchField",
+	file: "FileUpload",
+	color: "AccentPicker"
+};
+const noNativeControls = {
+	meta: {
+		type: "problem",
+		docs: { description: "Use the design-system component instead of a native control it replaces." },
+		schema: []
+	},
+	create(context) {
+		return { JSXOpeningElement(node) {
+			const el = node;
+			const name = tagName(el);
+			if (REPLACE[name]) context.report({
+				node,
+				message: "Native <{{n}}>: use {{c}} from @seanyeh77/ui.",
+				data: {
+					n: name,
+					c: REPLACE[name]
+				}
+			});
+			if (name === "input") {
+				const t = literal(attr(el, "type"));
+				if (typeof t === "string" && INPUT_REPLACE[t]) context.report({
+					node,
+					message: "<input type=\"{{t}}\">: use {{c}} from @seanyeh77/ui.",
+					data: {
+						t,
+						c: INPUT_REPLACE[t]
+					}
+				});
+			}
+		} };
+	}
+};
+const noNestedCard = {
+	meta: {
+		type: "problem",
+		docs: { description: "No Card inside a Card: one shadow per block." },
+		schema: []
+	},
+	create(context) {
+		return { JSXElement(node) {
+			const el = node;
+			if (tagName(el.openingElement) !== "Card") return;
+			for (let p = el.parent; p; p = p.parent) if (p.type === "JSXElement" && tagName(p.openingElement) === "Card") {
+				context.report({
+					node,
+					message: "Card inside a Card gives two shadows. Use one Card and split it with headings, or place the Cards side by side."
+				});
+				return;
+			}
+		} };
+	}
+};
+const onePrimary = {
+	meta: {
+		type: "suggestion",
+		docs: { description: "At most one primary button per section." },
+		schema: []
+	},
+	create(context) {
+		const SECTIONS = /* @__PURE__ */ new Set([
+			"Card",
+			"Dialog",
+			"Drawer",
+			"section",
+			"form",
+			"SettingsSection"
+		]);
+		return { JSXElement(node) {
+			const el = node;
+			if (tagName(el.openingElement) !== "Button" || literal(attr(el.openingElement, "variant")) !== "primary") return;
+			let section = el.parent;
+			while (section && !(section.type === "JSXElement" && SECTIONS.has(tagName(section.openingElement)))) section = section.parent;
+			if (!section) return;
+			const walk = (n) => {
+				if (!n || typeof n !== "object") return [];
+				if (Array.isArray(n)) return n.flatMap(walk);
+				const e = n;
+				if (typeof e.type !== "string") return [];
+				if (e.type === "ConditionalExpression") {
+					const a = walk(e.consequent);
+					const b = walk(e.alternate);
+					return [...walk(e.test), ...b.length > a.length ? b : a];
+				}
+				const own = [];
+				if (e.type === "JSXElement") {
+					if (e !== section && SECTIONS.has(tagName(e.openingElement))) return [];
+					if (tagName(e.openingElement) === "Button" && literal(attr(e.openingElement, "variant")) === "primary") own.push(e);
+				}
+				for (const k in e) if (k !== "parent" && k !== "loc" && k !== "range") own.push(...walk(e[k]));
+				return own;
+			};
+			const primaries = walk(section);
+			if (primaries.length > 1 && primaries.includes(el) && primaries[0] !== el) context.report({
+				node,
+				message: "A second primary Button in this section. Keep one primary (the main action) and make the others secondary."
+			});
+		} };
+	}
+};
+const VAGUE = /^(確定|確認|好|好的|OK|Ok|ok|Submit|submit|送出|是|否|Yes|No)$/;
+const rules = {
+	"no-raw-color": noRawColor,
+	"no-tailwind-defaults": noTailwindDefaults,
+	"no-native-controls": noNativeControls,
+	"no-nested-card": noNestedCard,
+	"one-primary-button": onePrimary,
+	"verb-labels": {
+		meta: {
+			type: "suggestion",
+			docs: { description: "Button labels say what happens: 儲存, 刪除 api-gateway, 發布. Not 確定 or OK." },
+			schema: []
+		},
+		create(context) {
+			return { JSXElement(node) {
+				const el = node;
+				if (tagName(el.openingElement) !== "Button") return;
+				const t = textOf(el);
+				if (VAGUE.test(t)) context.report({
+					node,
+					message: "Button label \"{{t}}\" does not say what happens. Use the verb of the action: 儲存, 刪除, 發布.",
+					data: { t }
+				});
+			} };
+		}
+	},
+	"danger-confirm": {
+		meta: {
+			type: "problem",
+			docs: { description: "A danger Button is confirmed: pass confirm, or confirmed inside the confirm dialog." },
+			schema: []
+		},
+		create(context) {
+			return { JSXOpeningElement(node) {
+				const el = node;
+				if (tagName(el) !== "Button" || literal(attr(el, "variant")) !== "danger") return;
+				if (!attr(el, "confirm") && !attr(el, "confirmed")) context.report({
+					node,
+					message: "Danger Button without confirmation. Add confirm={{ title: \"刪除 …？\" }}, or confirmed when it is the button inside the confirm Dialog."
+				});
+			} };
+		}
+	}
+};
+const plugin = {
+	meta: {
+		name,
+		version
+	},
+	rules,
+	configs: {}
+};
+plugin.configs.recommended = {
+	name: "@seanyeh77/ui/recommended",
+	files: ["**/*.{jsx,tsx}"],
+	plugins: { ui: plugin },
+	languageOptions: {
+		parser: tsParser,
+		parserOptions: { ecmaFeatures: { jsx: true } }
+	},
+	rules: {
+		"ui/no-raw-color": "error",
+		"ui/no-tailwind-defaults": "error",
+		"ui/no-native-controls": "error",
+		"ui/no-nested-card": "error",
+		"ui/danger-confirm": "error",
+		"ui/one-primary-button": "warn",
+		"ui/verb-labels": "warn"
+	}
+};
+export { plugin as default, rules };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@seanyeh77/eslint-plugin-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "ESLint rules for SeanYeh's design system: token colors only, design-system components instead of native controls, no card in a card, one primary button, verb labels.",
+  "license": "MIT",
+  "author": "Hsiu-An Yeh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanyeh77/ui-design-system.git",
+    "directory": "packages/eslint-plugin-ui"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9",
+    "typescript": ">=4.8.4 <7"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.72.1"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p .",
+    "test": "vitest run --config vitest.config.ts"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.