@contractspec/eslint-plugin-design-system 1.44.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+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/README.md

@@ -0,0 +1,45 @@
+# @contractspec/eslint-plugin-design-system
+
+Design-system enforcement rules for LSSM apps. Ships:
+
+- `prefer-design-system`: auto-rewrites known `@contractspec/lib.ui-kit-web` form/control imports to `@contractspec/lib.design-system` and flags intrinsic layout/form elements
+- `no-intrinsic-typography`: flag raw headings/paragraph/spans; use DS typography primitives
+- `design-import-boundary`: block forbidden design imports (default: native ui-kit in web)
+- `localAllowPatterns` option (prefer-design-system): allow local/relative imports (shadcn-style) to bypass DS replacement so teams can copy/paste components.
+
+`configs.recommended` enables all of the above.
+
+Usage:
+
+```js
+import dsPlugin from '@contractspec/eslint-plugin-design-system';
+
+export default [
+  dsPlugin.configs.recommended,
+  // or customize
+  // {
+  //   plugins: { 'design-system': dsPlugin },
+  //   rules: {
+  //     'design-system/prefer-design-system': [
+  //       'error',
+  //       {
+  //         intrinsicDisallowList: ['div', 'button'],
+  //         localAllowPatterns: ['^\\./components', '^@/components'],
+  //       },
+  //     ],
+  //     'design-system/no-intrinsic-typography': 'error',
+  //     'design-system/design-import-boundary': 'error',
+  //   },
+  // },
+];
+```
+
+
+
+
+
+
+
+
+
+

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@contractspec/eslint-plugin-design-system",
+  "version": "1.44.0",
+  "private": false,
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "test": "node ./tests/prefer-design-system.test.js"
+  },
+  "peerDependencies": {
+    "eslint": "^9.39.2"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2"
+  },
+  "license": "MIT",
+  "description": "Design-system ESLint rules (prefer-design-system) for LSSM apps",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/tools/eslint-plugin-design-system"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/index.js

@@ -0,0 +1,40 @@
+import preferDesignSystem from './rules/prefer-design-system.js';
+import noIntrinsicTypography from './rules/no-intrinsic-typography.js';
+import designImportBoundary from './rules/design-import-boundary.js';
+
+export const rules = {
+  'prefer-design-system': preferDesignSystem.rules['prefer-design-system'],
+  'no-intrinsic-typography': noIntrinsicTypography,
+  'design-import-boundary': designImportBoundary,
+};
+
+export const configs = {
+  recommended: {
+    plugins: {
+      'design-system': {
+        rules,
+      },
+    },
+    rules: {
+      'design-system/prefer-design-system': 'error',
+      'design-system/no-intrinsic-typography': 'error',
+      'design-system/design-import-boundary': 'error',
+    },
+  },
+};
+
+export default {
+  rules,
+  configs,
+};
+
+
+
+
+
+
+
+
+
+
+

package/src/rules/design-import-boundary.js

@@ -0,0 +1,73 @@
+// Prevent forbidden cross-surface imports (e.g., native ui-kit in web code).
+const DEFAULT_FORBIDDEN = [
+  {
+    path: '@contractspec/lib.ui-kit',
+    message:
+      'Do not import native ui-kit in web code. Use @contractspec/lib.design-system or @contractspec/lib.ui-kit-web.',
+  },
+];
+
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce design import boundaries (no native ui-kit in web; prefer design-system).',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          forbidden: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                path: { type: 'string' },
+                message: { type: 'string' },
+              },
+              required: ['path'],
+              additionalProperties: false,
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      forbiddenImport: '{{message}}',
+    },
+  },
+  create(context) {
+    const forbidden = context.options[0]?.forbidden || DEFAULT_FORBIDDEN;
+    const pathToMessage = new Map(
+      forbidden.map((f) => [f.path, f.message || `Import "${f.path}" is forbidden here.`])
+    );
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (pathToMessage.has(source)) {
+          context.report({
+            node: node.source,
+            messageId: 'forbiddenImport',
+            data: { message: pathToMessage.get(source) },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;
+
+
+
+
+
+
+
+
+
+
+

package/src/rules/no-intrinsic-typography.js

@@ -0,0 +1,67 @@
+// Flags intrinsic typography tags (headings, paragraph, spans, emphasis) in app/bundle code.
+const DEFAULT_BLOCKLIST = new Set([
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'span',
+  'strong',
+  'em',
+]);
+
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Use design-system typography primitives instead of intrinsic heading/paragraph/span tags.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allow: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      avoidIntrinsicTypography:
+        'Use design-system typography primitives instead of intrinsic <{{name}}>.',
+    },
+  },
+  create(context) {
+    const allow = new Set(context.options[0]?.allow || []);
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const name = node.name.name;
+        if (!name || name[0] !== name[0]?.toLowerCase?.()) return;
+        if (allow.has(name)) return;
+        if (!DEFAULT_BLOCKLIST.has(name)) return;
+
+        context.report({
+          node: node.name,
+          messageId: 'avoidIntrinsicTypography',
+          data: { name },
+        });
+      },
+    };
+  },
+};
+
+export default rule;
+
+
+
+
+
+
+
+
+
+
+

package/src/rules/prefer-design-system.js

@@ -0,0 +1,137 @@
+// Custom ESLint rule to enforce design-system-first imports and discourage
+// intrinsic layout/form elements in app/bundle code.
+const DEFAULT_REPLACEMENTS = {
+  '@contractspec/lib.ui-kit-web/ui/button': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/input': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/textarea': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/cta': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/link': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/empty-state': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/loader': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/label': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/select': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/checkbox': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/radio-group': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/form': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/card': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/stack': '@contractspec/lib.design-system',
+  '@contractspec/lib.ui-kit-web/ui/typography': '@contractspec/lib.ui-kit-web/ui/typography', // allow typography to pass through
+};
+
+const DEFAULT_INTRINSIC = new Set([
+  'div',
+  'section',
+  'main',
+  'header',
+  'footer',
+  'nav',
+  'span',
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'option',
+  'form',
+  'label',
+]);
+
+const preferDesignSystemRule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer design-system imports and avoid intrinsic layout/form elements in app/bundle code.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          replacementMap: { type: 'object' },
+          intrinsicDisallowList: { type: 'array', items: { type: 'string' } },
+          allowIntrinsic: { type: 'array', items: { type: 'string' } },
+          localAllowPatterns: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    fixable: 'code',
+    messages: {
+      preferDSImport:
+        'Use design-system import instead of "{{from}}". Prefer "{{to}}".',
+      avoidIntrinsic:
+        'Use design-system layout/typography primitives instead of intrinsic <{{name}}> in app/bundle code.',
+    },
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const replacementMap = {
+      ...DEFAULT_REPLACEMENTS,
+      ...(options.replacementMap || {}),
+    };
+    const intrinsicDisallowList = new Set(
+      options.intrinsicDisallowList || DEFAULT_INTRINSIC
+    );
+    const allowIntrinsic = new Set(options.allowIntrinsic || []);
+    const localAllowPatterns = (options.localAllowPatterns || []).map(
+      (p) => new RegExp(p)
+    );
+
+    return {
+      ImportDeclaration(node) {
+        const sourceValue = node.source.value;
+        const replacement = replacementMap[sourceValue];
+        if (!replacement) return;
+        if (!node.specifiers || node.specifiers.length === 0) return;
+        if (localAllowPatterns.some((re) => re.test(sourceValue))) return;
+
+        context.report({
+          node: node.source,
+          messageId: 'preferDSImport',
+          data: { from: sourceValue, to: replacement },
+          fix(fixer) {
+            return fixer.replaceText(node.source, `'${replacement}'`);
+          },
+        });
+      },
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const name = node.name.name;
+        if (!name || name[0] !== name[0]?.toLowerCase?.()) return;
+        if (allowIntrinsic.has(name)) return;
+        if (!intrinsicDisallowList.has(name)) return;
+
+        context.report({
+          node: node.name,
+          messageId: 'avoidIntrinsic',
+          data: { name },
+        });
+      },
+    };
+  },
+};
+
+export const rules = {
+  'prefer-design-system': preferDesignSystemRule,
+};
+
+export default {
+  rules,
+};
+
+
+
+
+
+
+
+
+
+
+