@carto/meridian-ds 5.1.4-alpha.f9cdbcf.347 → 5.2.0

package/CHANGELOG.md

@@ -2,11 +2,19 @@
 
 ## Unreleased
 
-- feat(dialog): export useScrollBorders hook for scroll-edge borders [sc-578988] [#564](https://github.com/CartoDB/meridian-ds/pull/564)
-- feat(ai-metadata): leaner MCP and shared design-system rules [#563](https://github.com/CartoDB/meridian-ds/pull/563)
-
 ## 5.0
 
+### 5.2.0
+
+- feat(dialog): export useScrollBorders hook for scroll-edge borders [sc-578988] [#564](https://github.com/CartoDB/meridian-ds/pull/564)
+- feat(button): `tooltip` on Button and SplitButton — shown on hover even while disabled, and linked as the button's description; with it set, the button renders inside a wrapper span [sc-579530] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(icon-button): logs a dev-only `console.error` when an IconButton has no accessible name — test setups that fail on `console.error` need a `tooltip` or `aria-label` on those buttons [sc-579530] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(eslint-rules): new `@carto/meridian-ds/eslint-rules` export — Meridian's design rules as `no-restricted-syntax` entries plus generated MUI restricted imports, for `.eslintrc` or flat config; `SPACING_STEPS` exported from `@carto/meridian-ds/theme` [sc-579313] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): leaner MCP — minified results, compact catalogs (`list_icons` is now plain text; `list_components` lists family members by name), `get_component` takes `names` and returns `example`/`moreExamples`/`propTypes` instead of `description`/`examples.stories` [sc-578601] [sc-578984] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): conventions absorb the generic design-review rules; decision trees point list filters at FilterDropdown [sc-578639] [sc-580037] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): Meridian's own rendering per curated story — `meridian_get_screenshot(storyId)` and new `meridian_get_anatomy(storyId)`, shipped in `dist/stories/` [sc-580343] [#568](https://github.com/CartoDB/meridian-ds/pull/568)
+- chore(stories): stories follow Meridian's design rules, enforced by lint [sc-579467] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+
 ### 5.1.3
 
 - fix(ai-metadata): allow fractional spacing steps; give design team ownership of design-system paths [sc-577069] [#558](https://github.com/CartoDB/meridian-ds/pull/558)

package/dist/bin/meridian-ds-mcp.js

@@ -36,6 +36,8 @@ var ICONS = [];
 var ICONS_TEXT = "";
 var TOKENS;
 var SCREENSHOTS = {};
+var STORY_REFS = {};
+var DIST_DIR = "";
 var CONVENTIONS = "";
 var VERSION = "0.0.0";
 var TOOLS = [
@@ -109,17 +111,32 @@ var TOOLS = [
   },
   {
     name: "meridian_get_screenshot",
-    description: "Path to a labeled reference image. name='icons' is a grid of every custom icon captioned with its import name \u2014 Read it to confirm an icon visually. Needs an image-capable runtime. Omit name to list the available screenshots.",
+    description: "Path to a reference image. name='icons' is a grid of every custom icon captioned with its import name. Any curated component's story id (e.g. 'components-alert--layout', from meridian_get_component's `example.id` or meridian_get_examples) returns Meridian's own rendering of that story at 1280\xD7800 \u2014 compare it with your build to tell an app composing a component wrong from Meridian rendering it wrong. Needs an image-capable runtime. Omit name to list the labeled screenshots.",
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
-          description: "Which screenshot to return (e.g. 'icons'). Omit to list the available ones."
+          description: "'icons', or a story id. Omit to list the labeled screenshots."
         }
       },
       additionalProperties: false
     }
+  },
+  {
+    name: "meridian_get_anatomy",
+    description: "Slot geometry of Meridian's own rendering of a story: each MUI component instance with its box, and its slots' boxes (e.g. Alert `icon`/`message`/`action`) relative to that instance, so they compare across widths. Matches meridian_get_screenshot for the same story id. Use it to measure where a component's parts should sit.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        storyId: {
+          type: "string",
+          description: "A curated component's story id, e.g. 'components-alert--layout'."
+        }
+      },
+      required: ["storyId"],
+      additionalProperties: false
+    }
   }
 ];
 var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLowerCase());
@@ -273,15 +290,43 @@ Fetch any with meridian_get_examples(storyId):
   }
   return md;
 }
+var SCOPE_HINT = {
+  element: " (cropped to the story root)",
+  page: " (full page, with portaled content)"
+};
 function getScreenshot(name) {
   const available = Object.keys(SCREENSHOTS);
+  const story = STORY_REFS[name];
+  if (story)
+    return {
+      path: path.join(DIST_DIR, story.image),
+      ...story.scope && { scope: story.scope },
+      hint: `Meridian's rendering of ${name} at 1280\xD7800${story.scope ? SCOPE_HINT[story.scope] : ""}. meridian_get_anatomy('${name}') gives its slot boxes.`
+    };
   const shot = name ? SCREENSHOTS[name] : void 0;
   if (!shot || !fs.existsSync(shot.path))
     return name ? {
-      error: `No screenshot named "${name}". Available: ${available.join(", ") || "(none \u2014 run `yarn metadata:screenshots` and rebuild)"}.`
+      error: `No screenshot named "${name}". Available: ${available.join(", ") || "(none \u2014 run `yarn metadata:screenshots` and rebuild)"}, or a curated component's story id (see meridian_get_examples).`
     } : { available };
   return { path: shot.path, count: shot.count, hint: shot.hint };
 }
+function getAnatomy(storyId) {
+  const ref = STORY_REFS[storyId];
+  if (!ref)
+    return {
+      error: `No reference rendering for "${storyId}". Use a curated component's story id (see meridian_get_examples).`
+    };
+  if (!ref.anatomy)
+    return {
+      error: `No anatomy captured for "${storyId}" yet; meridian_get_screenshot('${storyId}') still has its image.`
+    };
+  return {
+    storyId,
+    ...JSON.parse(
+      fs.readFileSync(path.join(DIST_DIR, ref.anatomy), "utf8")
+    )
+  };
+}
 function renderIcons() {
   const lines = ICONS.map(
     (i) => i.keywords?.length ? `${i.name}: ${i.keywords.join(", ")}` : i.name
@@ -303,6 +348,8 @@ function callTool(name, args) {
       return TOKENS ?? { error: "No tokens in this bundle." };
     case "meridian_get_screenshot":
       return getScreenshot(String(args.name ?? ""));
+    case "meridian_get_anatomy":
+      return getAnatomy(String(args.storyId ?? args.name ?? ""));
     case "meridian_get_component":
       if (Array.isArray(args.names))
         return args.names.map((n) => getComponent(String(n)));
@@ -322,7 +369,7 @@ var SERVER_INSTRUCTIONS = `Meridian Design System knowledge for writing React UI
 
 REQUIRED FIRST STEP: before writing or editing any Meridian UI, have the conventions in context and follow them for the rest of the session \u2014 the per-component data doesn't repeat those rules. Call meridian_get_conventions once, unless your context already has the "Meridian usage conventions" doc (e.g. a skill loaded it).
 
-Then: meridian_list_components to pick \u2192 meridian_get_component (\`names: [...]\` for several; includes the lead example) \u2192 meridian_get_examples only for other stories. Icons: meridian_list_icons. Exact token values: meridian_get_tokens.
+Then: meridian_list_components to pick \u2192 meridian_get_component (\`names: [...]\` for several; includes the lead example) \u2192 meridian_get_examples only for other stories. Icons: meridian_list_icons. Exact token values: meridian_get_tokens. Meridian's own rendering of a story, for design QA: meridian_get_screenshot(storyId) + meridian_get_anatomy(storyId).
 
 Component tiers \u2014 all real and importable; prefer any of them over a bare MUI equivalent: CURATED (most) have full guidance; LISTED (\`documented: false\`, with stories) have no curation \u2014 use the examples + .d.ts; KNOWN (\`documented: false\`, no stories) have only the .d.ts.
 
@@ -394,6 +441,8 @@ function load() {
       }
     ])
   );
+  DIST_DIR = path.dirname(bundlePath);
+  STORY_REFS = bundle.storyReferences ?? {};
   CONVENTIONS = bundle.conventions;
   VERSION = bundle.version;
   process.stderr.write(

package/dist/conventions.md

@@ -67,7 +67,7 @@ Meridian is the source of truth: when an existing codebase pattern contradicts M
 
 ## Styling
 
-- Use theme tokens, never hardcoded values: colors from the palette (`text.*`, `background.*`, `divider`, semantic `*.main`) and spacing from the theme scale (`theme.spacing(n)`, or `sx` numeric spacing like `px: 2` / `mt: 1.5`) — no raw hex/rgb or px. Margin, padding and offsets use steps `0.25, 0.5, 0.75, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8, 9, 12, 15` (2–120px); `width`/`height` may use any step (`spacing-step` in `@carto/meridian-ds/eslint-rules` lints it). Get the exact values — palette keys, spacing base, type ramp, `shape.borderRadius`, breakpoints, shadows — from `meridian_get_tokens`.
+- Use theme tokens, never hardcoded values: colors from the palette (`text.*`, `background.*`, `divider`, semantic `*.main`) and spacing from the theme scale (`theme.spacing(n)`, or `sx` numeric spacing like `px: 2` / `mt: 1.5`) — no raw hex/rgb or px. Margin, padding and gap use steps `0.25, 0.5, 0.75, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8, 9, 12, 15` (2–120px); `width`/`height` and positional offsets may use any step (`spacing-step` in `@carto/meridian-ds/eslint-rules` lints it). Get the exact values — palette keys, spacing base, type ramp, `shape.borderRadius`, breakpoints, shadows — from `meridian_get_tokens`.
 - Token details:
   - `sx` spacing keys (`m*`/`p*`/`gap`) resolve to the scale, but `top`/`right`/`bottom`/`left` don't (`top: 2` is 2px) — use `theme.spacing()` there.
   - In `styled()`, always use `theme.spacing()`. `style={}` isn't theme-aware — use `sx`.

package/dist/eslint-rules/index.cjs

@@ -177,11 +177,13 @@ const STYLE_STRING = (pattern) => `Literal[value=${pattern}]:not(JSXAttribute[na
 const NON_ZERO = "Literal[raw=/^[0-9.]+$/][raw!=/^0+(\\.0+)?$/]";
 const exactly = (...alternatives) => `/^(${alternatives.join("|")})$/`;
 const SPACING = "[mp][trblxy]?|(margin|padding)(Top|Right|Bottom|Left|X|Y|Inline|Block)?|gap|rowGap|columnGap";
-const OFFSET = "top|right|bottom|left|inset";
 const SPACING_KEY = exactly(SPACING);
-const OFFSET_KEY = exactly(OFFSET);
-const SPACING_OR_OFFSET_KEY = exactly(SPACING, OFFSET);
-const MERIDIAN_COMPONENT = exactly(...MERIDIAN_COMPONENTS);
+const MERIDIAN_IMPORT = /^@carto\/meridian-ds(\/|$)/;
+const CSS_WIDE = "inherit|initial|unset|revert|revert-layer";
+const PALETTE_VALUE = `/^(${CSS_WIDE}|currentColor|transparent|divider|[a-z]+\\.[A-Za-z0-9]+(\\.[A-Za-z0-9]+)?)$/`;
+const ICON = "/(Icon|Outlined|Rounded|Sharp|TwoTone)$/";
+const VISUAL_KEY = "/^(background|border|border(Top|Right|Bottom|Left)?(Color|Width|Style)?|borderRadius|boxShadow|opacity|outline|textTransform|textDecoration|fill|stroke)$/";
+const COLOR_KEY = "/^(color|bgcolor|backgroundColor)$/";
 const SX = ":matches(JSXAttribute[name.name='sx'], Property[key.name='sx'])";
 const STYLED_OR_STYLE = ":matches(CallExpression[callee.callee.name='styled'], CallExpression[callee.object.name='styled'], CallExpression[callee.callee.object.name='styled'], JSXAttribute[name.name='style'])";
 const SPACING_CALL = "CallExpression[callee.property.name='spacing']";
@@ -196,110 +198,138 @@ const WRAPPERS = [
   "TemplateLiteral > ConditionalExpression > "
 ];
 const under = (parent, nodes) => nodes.flatMap((node) => WRAPPERS.map((w) => `${parent} > ${w}${node}`));
-const meridianDesignRules = {
-  "spacing-step": {
-    selector: anyOf(
-      ...under(`${SX} Property[key.name=${SPACING_KEY}]`, [
-        ...signed(OFF_SCALE),
-        `ArrayExpression > ${OFF_SCALE}`,
-        `ObjectExpression > Property > ${OFF_SCALE}`
-      ]),
-      ...under(
-        `Property[key.name=${SPACING_OR_OFFSET_KEY}]`,
-        signed(OFF_SCALE).map((n) => `${SPACING_CALL} > ${n}`)
-      )
-    ),
-    message: `Spacing off the Meridian scale: margin, padding, gap and offsets use ${spacingSteps.SPACING_STEPS.join(", ")}.`
-  },
-  "px-spacing": {
-    selector: anyOf(
-      ...under(`Property[key.name=${SPACING_OR_OFFSET_KEY}]`, [
-        PX_STRING,
-        `ArrayExpression > ${PX_STRING}`,
-        `ObjectExpression > Property > ${PX_STRING}`
-      ]),
-      ...under(
-        `${STYLED_OR_STYLE} Property[key.name=${SPACING_OR_OFFSET_KEY}]`,
-        signed(NON_ZERO)
+const esqueryRegex = (re) => `/${re.source.replace(/\\?\//g, "\\x2F")}/`;
+function createMeridianDesignRules({
+  importSource = MERIDIAN_IMPORT
+} = {}) {
+  const source = esqueryRegex(importSource);
+  const forImported = (names, selector) => anyOf(
+    ...names.map(
+      (name) => `Program:has(ImportDeclaration[source.value=${source}] > :matches(ImportSpecifier, ImportDefaultSpecifier)[local.name='${name}']) ${selector(name)}`
+    )
+  );
+  const sxOf = (name) => `JSXOpeningElement[name.name='${name}'] > JSXAttribute[name.name='sx']`;
+  return {
+    "spacing-step": {
+      selector: anyOf(
+        ...under(`${SX} Property[key.name=${SPACING_KEY}]`, [
+          ...signed(OFF_SCALE),
+          `ArrayExpression > ${OFF_SCALE}`,
+          `ObjectExpression > Property > ${OFF_SCALE}`
+        ]),
+        ...under(
+          `Property[key.name=${SPACING_KEY}]`,
+          signed(OFF_SCALE).map((n) => `${SPACING_CALL} > ${n}`)
+        )
       ),
-      ...under(`${SX} Property[key.name=${OFFSET_KEY}]`, signed(NON_ZERO))
-    ),
-    message: "Raw px spacing: use the theme scale — `sx` spacing numbers (`px: 2`) or `theme.spacing(n)`. Numbers in `styled()`/`style` and `sx` offsets are px."
-  },
-  "filled-icon": {
-    selector: anyOf(
-      "ImportDeclaration[source.value=/^@mui.icons-material.(?!.*(Outlined|Rounded|Sharp|TwoTone)$)/]",
-      "ImportDeclaration[source.value='@mui/icons-material'][importKind!='type'] > ImportSpecifier[importKind!='type'][imported.name!=/(Outlined|Rounded|Sharp|TwoTone)$/]"
-    ),
-    message: "Filled MUI icon: import the Outlined variant."
-  },
-  "alpha-white-black": {
-    selector: "CallExpression[callee.name='alpha'] > MemberExpression[property.name=/^(white|black)$/][object.property.name='common']",
-    message: "`alpha()` on white/black: use the palette opacity shades `white[N]` / `black[N]`."
-  },
-  "hex-color": {
-    selector: STYLE_STRING(
-      "/(^|[\\s(,])#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\\b/"
-    ),
-    message: "Hardcoded hex color: use a palette token."
-  },
-  "rgb-color": {
-    selector: STYLE_STRING("/(^|[^a-z])rgba?\\(/"),
-    message: "Hardcoded rgb()/rgba() color: use a palette token."
-  },
-  "typography-style": {
-    selector: anyOf(
-      ...under(
-        `:matches(${SX}, ${STYLED_OR_STYLE}) Property[key.name=/^(fontSize|fontWeight|lineHeight|fontFamily)$/]`,
-        ["Literal"]
-      )
-    ),
-    message: "Hardcoded typography: use `<Typography variant>` (and `weight`), `sx={{ typography: 'body2' }}` or `...theme.typography.body2`."
-  },
-  "external-link": {
-    selector: "JSXOpeningElement[name.name='a'] > JSXAttribute[name.name='target'] > Literal[value='_blank']",
-    message: 'Raw `<a target="_blank">`: use Meridian `Link` with `external`.'
-  },
-  "system-props": {
-    selector: "JSXOpeningElement[name.name=/^(Box|Stack|Grid|Grid2|Container)$/] > JSXAttribute[name.name=/^(m|p)[trblxy]?$/]",
-    message: "MUI system props are deprecated: move spacing into `sx`, e.g. `<Box sx={{ px: 2 }}>`."
-  },
-  "data-name": {
-    selector: `JSXOpeningElement[name.name=${MERIDIAN_COMPONENT}] > JSXAttribute[name.name='data-name']`,
-    message: "`data-name` on a Meridian component overrides its own marker: set it on a wrapper, or drop it."
-  },
-  "literal-a11y-text": {
-    selector: anyOf(
-      ...["", "JSXExpressionContainer > "].map(
-        (wrapper) => `JSXAttribute[name.name=/^(aria-label|placeholder)$/] > ${wrapper}Literal[value=/[A-Za-z]/]`
-      )
-    ),
-    message: "Hardcoded `aria-label` / `placeholder`: translate it with the i18n layer, and keep test ids out of it."
-  },
-  "raw-shadow-radius": {
-    selector: anyOf(
-      "Property[key.name='boxShadow'] > Literal[value=/\\d/]",
-      "Property[key.name='borderRadius'] > Literal[value=/^\\d+(\\.\\d+)?px$/]"
-    ),
-    message: "Hardcoded shadow or radius: use `theme.shadows[n]` / `theme.shape.borderRadius`."
-  },
-  "styled-meridian": {
-    selector: `CallExpression[callee.name='styled'] > Identifier[name=${MERIDIAN_COMPONENT}]`,
-    message: "`styled()` of a Meridian component restyles it locally: use its props/variants, or raise the gap upstream in Meridian."
-  },
-  "visual-sx": {
-    selector: `JSXOpeningElement[name.name=${MERIDIAN_COMPONENT}] > JSXAttribute[name.name='sx'] Property[key.name=/^(color|bgcolor|background|backgroundColor|border|border(Top|Right|Bottom|Left)?(Color|Width|Style)?|borderRadius|boxShadow|opacity|outline|textTransform|textDecoration|fill|stroke)$/]`,
-    message: "Visual `sx` on a Meridian component overrides its design: keep `sx` to layout (spacing, size, position) and use its props/variants for the look."
-  },
-  "disabled-without-reason": {
-    selector: "JSXOpeningElement[name.name=/^(Button|IconButton|SplitButton)$/]:has(> JSXAttribute[name.name='disabled']:not([value.expression.value=false])):not(:has(> JSXAttribute[name.name=/^(tooltip|aria-describedby)$/]))",
-    message: "Disabled without a reason: pass `tooltip` (or `aria-describedby`) saying why it can’t be used."
-  },
-  "disabled-cursor": {
-    selector: "Property[key.name='cursor'] > Literal[value='not-allowed']",
-    message: "Don't tweak the cursor for disabled states: the component already styles them."
-  }
-};
+      message: `Spacing off the Meridian scale: margin, padding and gap use ${spacingSteps.SPACING_STEPS.join(", ")}.`
+    },
+    "px-spacing": {
+      selector: anyOf(
+        ...under(`Property[key.name=${SPACING_KEY}]`, [
+          PX_STRING,
+          `ArrayExpression > ${PX_STRING}`,
+          `ObjectExpression > Property > ${PX_STRING}`
+        ]),
+        ...under(
+          `${STYLED_OR_STYLE} Property[key.name=${SPACING_KEY}]`,
+          signed(NON_ZERO)
+        )
+      ),
+      message: "Raw px spacing: use the theme scale — `sx` spacing numbers (`px: 2`) or `theme.spacing(n)`. Numbers in `styled()`/`style` are px."
+    },
+    "filled-icon": {
+      selector: anyOf(
+        "ImportDeclaration[source.value=/^@mui.icons-material.(?!.*(Outlined|Rounded|Sharp|TwoTone)$)/]",
+        "ImportDeclaration[source.value='@mui/icons-material'][importKind!='type'] > ImportSpecifier[importKind!='type'][imported.name!=/(Outlined|Rounded|Sharp|TwoTone)$/]"
+      ),
+      message: "Filled MUI icon: import the Outlined variant."
+    },
+    "alpha-white-black": {
+      selector: "CallExpression[callee.name='alpha'] > MemberExpression[property.name=/^(white|black)$/][object.property.name='common']",
+      message: "`alpha()` on white/black: use the palette opacity shades `white[N]` / `black[N]`."
+    },
+    "hex-color": {
+      selector: STYLE_STRING(
+        "/(^|[\\s(,])#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\\b/"
+      ),
+      message: "Hardcoded hex color: use a palette token."
+    },
+    "rgb-color": {
+      selector: STYLE_STRING("/(^|[^a-z])rgba?\\(/"),
+      message: "Hardcoded rgb()/rgba() color: use a palette token."
+    },
+    "typography-style": {
+      selector: anyOf(
+        ...under(
+          `:matches(${SX}, ${STYLED_OR_STYLE}) Property[key.name=/^(fontWeight|fontFamily)$/]`,
+          [`Literal[value!=/^(${CSS_WIDE})$/]`]
+        ),
+        ...under(
+          `:matches(${SX}, ${STYLED_OR_STYLE}) Property[key.name='lineHeight']`,
+          [`Literal[value!=/^(${CSS_WIDE}|0|1|normal)$/]`]
+        ),
+        ...under(
+          `:matches(${SX}, ${STYLED_OR_STYLE}) Property[key.name='fontSize']:not(JSXOpeningElement[name.name=${ICON}] > JSXAttribute[name.name='sx'] Property)`,
+          [`Literal[value!=/^(${CSS_WIDE})$/]`]
+        )
+      ),
+      message: "Hardcoded typography: use `<Typography variant>` (and `weight`), `sx={{ typography: 'body2' }}` or `...theme.typography.body2`."
+    },
+    "external-link": {
+      selector: "JSXOpeningElement[name.name='a'] > JSXAttribute[name.name='target'] > Literal[value='_blank']",
+      message: 'Raw `<a target="_blank">`: use Meridian `Link` with `external`.'
+    },
+    "data-name": {
+      selector: forImported(
+        MERIDIAN_COMPONENTS,
+        (name) => `JSXOpeningElement[name.name='${name}'] > JSXAttribute[name.name='data-name']`
+      ),
+      message: "`data-name` on a Meridian component overrides its own marker: set it on a wrapper, or drop it."
+    },
+    "literal-a11y-text": {
+      selector: anyOf(
+        ...["", "JSXExpressionContainer > "].map(
+          (wrapper) => `JSXAttribute[name.name=/^(aria-label|placeholder)$/] > ${wrapper}Literal[value=/[A-Za-z]/]`
+        )
+      ),
+      message: "Hardcoded `aria-label` / `placeholder`: translate it with the i18n layer, and keep test ids out of it."
+    },
+    "raw-shadow-radius": {
+      selector: anyOf(
+        "Property[key.name='boxShadow'] > Literal[value=/\\d/]",
+        "Property[key.name='borderRadius'] > Literal[value=/^\\d+(\\.\\d+)?px$/]"
+      ),
+      message: "Hardcoded shadow or radius: use `theme.shadows[n]` / `theme.shape.borderRadius`."
+    },
+    "styled-meridian": {
+      selector: forImported(
+        MERIDIAN_COMPONENTS,
+        (name) => `CallExpression[callee.name='styled'] > Identifier[name='${name}']`
+      ),
+      message: "`styled()` of a Meridian component restyles it locally: use its props/variants, or raise the gap upstream in Meridian."
+    },
+    "visual-sx": {
+      selector: forImported(
+        MERIDIAN_COMPONENTS,
+        (name) => `${sxOf(name)} :matches(Property[key.name=${VISUAL_KEY}], Property[key.name=${COLOR_KEY}] Literal[value!=${PALETTE_VALUE}])`
+      ),
+      message: "Visual `sx` on a Meridian component overrides its design: keep `sx` to layout (spacing, size, position) and use its props/variants for the look."
+    },
+    "disabled-without-reason": {
+      selector: forImported(
+        ["Button", "IconButton", "SplitButton"],
+        (name) => `JSXOpeningElement[name.name='${name}']:has(> JSXAttribute[name.name='disabled']:not([value.expression.value=false])):not(:has(> JSXAttribute[name.name=/^(tooltip|aria-describedby)$/]))`
+      ),
+      message: "Disabled without a reason: pass `tooltip` (or `aria-describedby`) saying why it can’t be used."
+    },
+    "disabled-cursor": {
+      selector: "Property[key.name='cursor'] > Literal[value='not-allowed']",
+      message: "Don't tweak the cursor for disabled states: the component already styles them."
+    }
+  };
+}
+const meridianDesignRules = createMeridianDesignRules();
 const PROPS_TYPES = new Set(MERIDIAN_PROPS_TYPES);
 const replacedBy = (names) => names.flatMap((n) => PROPS_TYPES.has(n) ? [n, `${n}Props`] : [n]);
 const USE_MERIDIAN = "Import from @carto/meridian-ds/components instead.";
@@ -333,5 +363,6 @@ const meridianRestrictedImports = {
     message: USE_MERIDIAN
   }))
 };
+exports.createMeridianDesignRules = createMeridianDesignRules;
 exports.meridianDesignRules = meridianDesignRules;
 exports.meridianRestrictedImports = meridianRestrictedImports;