ionbase-ui 0.17.0 → 0.18.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ionbase-ui",
-  "version": "0.17.0",
-  "description": "IonBase Design System \u2014 accessible React components, styles and design tokens in one package",
+  "version": "0.18.1",
+  "description": "IonBase Design System — accessible React components, styles and design tokens in one package",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,9 @@
     "./tokens-js": {
       "types": "./dist/tokens-js.d.ts",
       "default": "./dist/tokens-js.js"
-    }
+    },
+    "./stylelint-config": "./stylelint-config.js",
+    "./eslint-plugin": "./eslint-plugin/index.js"
   },
   "keywords": [
     "design-system",
@@ -34,7 +36,9 @@
     "ionbase"
   ],
   "files": [
-    "dist"
+    "dist",
+    "eslint-plugin",
+    "stylelint-config.js"
   ],
   "sideEffects": [
     "**/*.css"
@@ -53,17 +57,22 @@
   },
   "scripts": {
     "dev": "tsc --watch",
-    "build": "node scripts/sync-tokens.mjs && tsc --build --force && node scripts/copy-css.mjs && node scripts/verify-client-boundaries.mjs && node scripts/build-meta.mjs && node scripts/verify-meta.mjs",
+    "build": "node scripts/sync-tokens.mjs && tsc --build --force && node scripts/copy-css.mjs && node scripts/verify-client-boundaries.mjs && node scripts/verify-contrast.mjs && node scripts/build-meta.mjs && node scripts/verify-meta.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . && stylelint \"src/styles/*.css\"",
     "format": "prettier --check .",
     "icons:verify": "node scripts/verify-icons.mjs",
     "meta:build": "node scripts/build-meta.mjs",
-    "meta:verify": "node scripts/build-meta.mjs && node scripts/verify-meta.mjs"
+    "meta:verify": "node scripts/build-meta.mjs && node scripts/verify-meta.mjs",
+    "contrast": "node scripts/verify-contrast.mjs",
+    "contrast:list": "node scripts/verify-contrast.mjs --list"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "stylelint": "^16.0.0 || ^17.0.0",
+    "stylelint-declaration-strict-value": "^1.10.0",
+    "eslint": "^8.57.0 || ^9.0.0"
   },
   "dependencies": {
     "@react-stately/collections": "^3.13.1",
@@ -71,9 +80,20 @@
     "react-aria": "^3.34.0",
     "react-stately": "^3.48.0"
   },
-  "//devDependencies": "lucide-react is a devDependency, not a dependency: nothing in src/ imports it. It is here only so scripts/verify-icons.mjs can compare the installed icon set against the Figma page. Consumers pick their own icon library. There is deliberately NO dependency on @ionbase-ui/tokens \u2014 it is private and would publish as a version that does not exist on npm. Build ordering is expressed in turbo.json instead.",
+  "//devDependencies": "lucide-react is a devDependency, not a dependency: nothing in src/ imports it. It is here only so scripts/verify-icons.mjs can compare the installed icon set against the Figma page. Consumers pick their own icon library. There is deliberately NO dependency on @ionbase-ui/tokens — it is private and would publish as a version that does not exist on npm. Build ordering is expressed in turbo.json instead.",
   "devDependencies": {
     "lucide-react": "^1.27.0",
     "typescript": "^5.5.2"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    },
+    "stylelint-declaration-strict-value": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
   }
 }

package/stylelint-config.js

@@ -0,0 +1,144 @@
+/**
+ * IonBase stylelint config — the token rules, shipped.
+ *
+ *   // stylelint.config.js
+ *   export default { extends: ['ionbase-ui/stylelint-config'] };
+ *
+ * This exists because the premise of IonBase is that the code consuming it may
+ * be written by an agent with no developer reviewing the result. A rule that
+ * lives only in this repo protects only this repo; the app is where the drift
+ * actually happens, and a lint error naming the fix is the one form of guidance
+ * an agent reliably acts on.
+ *
+ * It is deliberately NOT a superset of stylelint-config-standard. That config
+ * is about CSS hygiene and is the consumer's choice; this one is about design
+ * tokens, and pairs with whatever else they already run.
+ *
+ * Requires `stylelint-declaration-strict-value` alongside `stylelint`. Both are
+ * optional peer dependencies — installed only by projects that opt in.
+ *
+ * REPO NOTE: the root stylelint.config.js extends this file directly rather
+ * than re-declaring the rules. One source, many pointers — the same reason
+ * CLAUDE.md is a pointer to AGENTS.md. If you edit rules, edit them here.
+ */
+
+/** Properties where a raw value is a theming bug rather than a style choice. */
+export const TOKENISED_PROPERTIES = [
+  'color',
+  'background-color',
+  'border-color',
+  'border-top-color',
+  'border-bottom-color',
+  'border-left-color',
+  'border-right-color',
+  'outline-color',
+  'font-size',
+  'font-family',
+  'font-weight',
+  'line-height',
+  'margin',
+  'margin-top',
+  'margin-bottom',
+  'margin-left',
+  'margin-right',
+  'padding',
+  'padding-top',
+  'padding-bottom',
+  'padding-left',
+  'padding-right',
+  'gap',
+  'border-radius',
+  'border-top-left-radius',
+  'border-top-right-radius',
+  'border-bottom-left-radius',
+  'border-bottom-right-radius',
+  'border-width',
+  'border-top-width',
+  'border-bottom-width',
+  'border-left-width',
+  'border-right-width',
+];
+
+/**
+ * Values that are not tokens and never should be.
+ *
+ * The forced-colors block is the important half: under Windows High Contrast
+ * every authored colour is remapped, and these system keywords are the only
+ * values that survive. A token there would be silently discarded.
+ */
+export const ALLOWED_RAW_VALUES = [
+  'inherit',
+  'transparent',
+  'currentColor',
+  'currentcolor',
+  '0',
+  'none',
+  'auto',
+  'normal',
+  '100%',
+  'max-content',
+  'min-content',
+  'Canvas',
+  'CanvasText',
+  'Highlight',
+  'HighlightText',
+  'GrayText',
+  'ButtonText',
+  'ButtonFace',
+  'LinkText',
+  'Field',
+  'FieldText',
+  'SelectedItem',
+  'SelectedItemText',
+];
+
+/** @type {import('stylelint').Config} */
+const config = {
+  plugins: ['stylelint-declaration-strict-value'],
+  rules: {
+    'color-no-hex': true,
+
+    // BEM. `.ion-button--primary-brand`, `.ion-tabs__item`.
+    'selector-class-pattern': null,
+
+    'scale-unlimited/declaration-strict-value': [
+      TOKENISED_PROPERTIES,
+      {
+        ignoreValues: ALLOWED_RAW_VALUES,
+        message:
+          'Raw CSS values are forbidden here. Use a design token — see `ionbase-ui/tokens` for the custom properties, or `ionbase-ui/meta/<Component>.json` for the tokens a given component consumes.',
+      },
+    ],
+
+    /*
+     * No raw colour inside a shadow.
+     *
+     * Shadows are the one property where geometry and colour share a value.
+     * The offsets (`0 0 0 2px`) are inert and never theme, so requiring them to
+     * be tokens would buy nothing — but a raw colour is a place dark mode has to
+     * be fixed by hand, once per occurrence. This bans the colour half only,
+     * which is why it is a disallowed-list rather than declaration-strict-value.
+     *
+     * Correct:  box-shadow: 0 0 0 2px var(--border-primary-strong);
+     *           box-shadow: var(--ion-shadow-button-raised);
+     * Rejected: box-shadow: 0 1px 2px rgb(0 0 0 / 40%);
+     */
+    'declaration-property-value-disallowed-list': {
+      'box-shadow': [/rgba?\(/i, /hsla?\(/i, /#[0-9a-f]{3,8}/i],
+    },
+  },
+
+  overrides: [
+    {
+      // Wherever a project keeps its own elevation ramp, that file is where raw
+      // shadow values are SUPPOSED to live — it is the one place dark mode has
+      // to touch. Everywhere else must reference the token.
+      files: ['**/elevation.css'],
+      rules: { 'declaration-property-value-disallowed-list': null },
+    },
+  ],
+
+  ignoreFiles: ['**/dist/**', '**/node_modules/**'],
+};
+
+export default config;