Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(eslint-plugin): add @astryx/no-physical-properties rule (warn) for RTL (#4437)

nynexman4464fdcae1d735bf
diff --git a/.changeset/lint-no-physical-props.md b/.changeset/lint-no-physical-props.md
new file mode 100644
index 0000000000..9d6c2ab5ee
--- /dev/null
+++ b/.changeset/lint-no-physical-props.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Add `@astryx/no-physical-properties` ESLint rule that flags physical left/right CSS properties inside `stylex.create()` and suggests the CSS logical equivalent for RTL support.
+
+- KEY-BASED: `marginLeft`/`marginRight`, `paddingLeft`/`paddingRight`, `borderLeft`/`borderRight` (+ their `Width`/`Style`/`Color` longhands), `left`/`right` → `insetInlineStart`/`insetInlineEnd`, and the four physical corner radii → their diagonal-aware logical names (`borderTopLeftRadius` → `borderStartStartRadius`, etc.).
+- VALUE-BASED: `textAlign: 'left'|'right'`, `float: 'left'|'right'`, and `clear: 'left'|'right'` (the key stays, only the physical value is flagged).
+- Scoped strictly to `stylex.create()` — physical identifiers used elsewhere are ignored.
+
+Shipped at `warn` in both the `strict` and `recommended` tiers until the RTL Phase 4 (Calendar/Slider/Table) physical-property migration lands; it will be flipped to `error` afterward.
+
+@nynexman4464
diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.js
index 2b9cb2184b..113b0b25c5 100644
--- a/internal/eslint-plugin-astryx/index.js
+++ b/internal/eslint-plugin-astryx/index.js
@@ -24,6 +24,7 @@ import noClassnameClobberRule from './no-classname-clobber.js';
import noHardcodedAnchorRule from './no-hardcoded-anchor.js';
import noRawParagraphRule from './no-raw-paragraph.js';
import noBorderShorthandRule from './no-border-shorthand.js';
+import noPhysicalPropertiesRule from './no-physical-properties.js';
import noReactNamespaceHooksRule from './no-react-namespace-hooks.js';
import copyrightHeaderRule from './copyright-header.js';
import noRawConsoleCliRule from './no-raw-console-cli.js';
@@ -240,6 +241,7 @@ const plugin = {
'no-hardcoded-anchor': noHardcodedAnchorRule,
'no-raw-paragraph': noRawParagraphRule,
'no-border-shorthand': noBorderShorthandRule,
+ 'no-physical-properties': noPhysicalPropertiesRule,
'no-react-namespace-hooks': noReactNamespaceHooksRule,
'require-base-props': requireBasePropsRule,
'require-ref-prop': requireRefPropRule,
@@ -267,6 +269,12 @@ plugin.configs.strict = {
'@astryx/no-hardcoded-anchor': 'error',
'@astryx/no-raw-paragraph': 'error',
'@astryx/no-border-shorthand': 'error',
+ // Deliberately 'warn' even in the strict tier (not 'error'): the core
+ // package still has known un-migrated Phase-4 physical properties
+ // (Calendar radii, Slider positioning, Table gradients) that would break CI
+ // if this were an error. Ship at warn until RTL Phase 4 (Calendar/Slider/
+ // Table) migration lands; flip to error afterward.
+ '@astryx/no-physical-properties': 'warn',
'@astryx/no-react-namespace-hooks': 'error',
'@astryx/require-base-props': 'error',
'@astryx/require-ref-prop': 'error',
@@ -292,6 +300,9 @@ plugin.configs.recommended = {
'@astryx/no-hardcoded-anchor': 'warn',
'@astryx/no-raw-paragraph': 'warn',
'@astryx/no-border-shorthand': 'warn',
+ // Warn now, flip to error after RTL Phase 4 (Calendar/Slider/Table)
+ // physical-property migration lands.
+ '@astryx/no-physical-properties': 'warn',
'@astryx/no-react-namespace-hooks': 'error',
'@astryx/require-base-props': 'warn',
'@astryx/require-ref-prop': 'warn',
diff --git a/internal/eslint-plugin-astryx/no-physical-properties.js b/internal/eslint-plugin-astryx/no-physical-properties.js
new file mode 100644
index 0000000000..658eba78a2
--- /dev/null
+++ b/internal/eslint-plugin-astryx/no-physical-properties.js
@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file no-physical-properties.js
+ * @description Disallow physical left/right CSS properties (and physical
+ * left/right VALUES) inside stylex.create(). Physical properties don't flip
+ * under RTL; the CSS logical-property equivalents (inline-start/inline-end,
+ * start/end) do, so they're required for correct right-to-left rendering.
+ *
+ * Two kinds of violation are detected:
+ * 1. KEY-BASED — the object key is itself a banned physical property
+ * (e.g. `marginLeft`, `borderRightColor`, `left`, `borderTopLeftRadius`).
+ * The suggested fix renames the key to the logical equivalent.
+ * 2. VALUE-BASED — the key is fine, but a specific physical VALUE is used
+ * (e.g. `textAlign: 'left'`, `float: 'right'`, `clear: 'left'`). The
+ * suggested fix replaces only the value; the key is left alone.
+ *
+ * SEVERITY: shipped at `warn` in BOTH the `strict` and `recommended` tiers
+ * (see index.js). The core package still has known un-migrated Phase-4
+ * physical properties (Calendar radii, Slider positioning, Table gradients)
+ * that would break CI if this were an `error`. Ship at warn until RTL Phase 4
+ * (Calendar/Slider/Table) migration lands; flip to error afterward.
+ *
+ * AUTOFIX: this rule is fixable (`meta.fixable: 'code'`).
+ * - VALUE-BASED fixes are always safe: only the value literal is replaced.
+ * - KEY-BASED fixes rename the key token, but ONLY when the logical key is not
+ * already present in the same style object. If BOTH the physical and logical
+ * key are present, renaming would produce a duplicate property (and the two
+ * silently collide — last one wins in LTR), so instead of autofixing we
+ * surface a distinct `physicalKeyConflict` message for a human to resolve.
+ */
+
+/**
+ * Physical property KEYS → their CSS logical equivalent.
+ * When one of these appears as an object key inside stylex.create(), flag it
+ * and suggest the logical rename.
+ *
+ * The corner-radius mappings are diagonal-aware: a physical corner is named
+ * <vertical><horizontal>, while the logical corner is named <block><inline>.
+ * top-left → start(block) start(inline) → borderStartStartRadius
+ * top-right → start(block) end(inline) → borderStartEndRadius
+ * bottom-left → end(block) start(inline) → borderEndStartRadius
+ * bottom-right → end(block) end(inline) → borderEndEndRadius
+ */
+const PHYSICAL_KEY_MAP = {
+ // Margin
+ marginLeft: 'marginInlineStart',
+ marginRight: 'marginInlineEnd',
+ // Padding
+ paddingLeft: 'paddingInlineStart',
+ paddingRight: 'paddingInlineEnd',
+ // Border side shorthands
+ borderLeft: 'borderInlineStart',
+ borderRight: 'borderInlineEnd',
+ // Border side longhands (left)
+ borderLeftWidth: 'borderInlineStartWidth',
+ borderLeftStyle: 'borderInlineStartStyle',
+ borderLeftColor: 'borderInlineStartColor',
+ // Border side longhands (right)
+ borderRightWidth: 'borderInlineEndWidth',
+ borderRightStyle: 'borderInlineEndStyle',
+ borderRightColor: 'borderInlineEndColor',
+ // Inset
+ left: 'insetInlineStart',
+ right: 'insetInlineEnd',
+ // Corner radii (diagonal-aware: vertical+horizontal → block+inline)
+ borderTopLeftRadius: 'borderStartStartRadius',
+ borderTopRightRadius: 'borderStartEndRadius',
+ borderBottomLeftRadius: 'borderEndStartRadius',
+ borderBottomRightRadius: 'borderEndEndRadius',
+};
+
+/**
+ * Property KEYS whose physical left/right VALUES should be flagged. The key
+ * itself is fine — only the specific physical value literal is a violation.
+ * Maps `key → { physicalValue → logicalValue }`.
+ */
+const PHYSICAL_VALUE_MAP = {
+ textAlign: { left: 'start', right: 'end' },
+ float: { left: 'inline-start', right: 'inline-end' },
+ clear: { left: 'inline-start', right: 'inline-end' },
+};
+
+function isInsideStylexCreate(node) {
+ let current = node;
+ while (current) {
+ if (
+ current.type === 'CallExpression' &&
+ current.callee?.type === 'MemberExpression' &&
+ current.callee.object?.name === 'stylex' &&
+ current.callee.property?.name === 'create'
+ ) {
+ return true;
+ }
+ current = current.parent;
+ }
+ return false;
+}
+
+function getStaticValue(node) {
+ if (!node) return null;
+ if (node.type === 'Literal' && typeof node.value === 'string') {
+ return node.value;
+ }
+ return null;
+}
+
+/**
+ * Does the given ObjectExpression already contain a Property whose key is
+ * `keyName`? Handles both identifier keys (`marginLeft`) and string-literal
+ * keys (`'marginLeft'`).
+ */
+function objectHasKey(objectExpression, keyName) {
+ if (!objectExpression || objectExpression.type !== 'ObjectExpression') {
+ return false;
+ }
+ return objectExpression.properties.some((prop) => {
+ if (prop.type !== 'Property') return false;
+ const name = prop.key?.name ?? prop.key?.value;
+ return name === keyName;
+ });
+}
+
+const rule = {
+ meta: {
+ type: 'problem',
+ fixable: 'code',
+ docs: {
+ description:
+ 'Disallow physical left/right CSS properties and values inside ' +
+ 'stylex.create(). Use the CSS logical equivalents ' +
+ '(inline-start/inline-end, start/end) for RTL support.',
+ category: 'Best Practices',
+ recommended: true,
+ },
+ messages: {
+ physicalKey:
+ 'Use `{{logical}}` instead of `{{physical}}` for RTL support.',
+ physicalValue:
+ 'Use `{{prop}}: \'{{logical}}\'` instead of ' +
+ '`{{prop}}: \'{{physical}}\'` for RTL support.',
+ physicalKeyConflict:
+ '`{{physical}}` conflicts with `{{logical}}` already set on this ' +
+ 'style object — remove `{{physical}}`.',
+ },
+ schema: [],
+ },
+ create(context) {
+ return {
+ Property(node) {
+ if (!isInsideStylexCreate(node)) return;
+
+ const propName = node.key?.name || node.key?.value;
+ if (!propName) return;
+
+ // KEY-BASED: the object key is itself a physical property.
+ const logicalKey = PHYSICAL_KEY_MAP[propName];
+ if (logicalKey) {
+ // Guard: if the logical key is ALSO present in the same object,
+ // renaming would create a duplicate/silent collision. Ambiguous
+ // which value the author meant — surface a distinct message, no fix.
+ if (objectHasKey(node.parent, logicalKey)) {
+ context.report({
+ node: node.key,
+ messageId: 'physicalKeyConflict',
+ data: {
+ physical: propName,
+ logical: logicalKey,
+ },
+ });
+ return;
+ }
+
+ // Preserve the original key's quoting: a string-literal key is
+ // replaced with a quoted string; an identifier key stays unquoted.
+ // All logical names are valid identifiers.
+ const isStringLiteralKey =
+ node.key.type === 'Literal' && typeof node.key.value === 'string';
+ const newKeyText = isStringLiteralKey
+ ? `'${logicalKey}'`
+ : logicalKey;
+
+ context.report({
+ node: node.key,
+ messageId: 'physicalKey',
+ data: {
+ physical: propName,
+ logical: logicalKey,
+ },
+ fix(fixer) {
+ return fixer.replaceText(node.key, newKeyText);
+ },
+ });
+ return;
+ }
+
+ // VALUE-BASED: the key is fine, but the value may be physical.
+ const valueMap = PHYSICAL_VALUE_MAP[propName];
+ if (valueMap) {
+ const value = getStaticValue(node.value);
+ if (value !== null && valueMap[value]) {
+ const logicalValue = valueMap[value];
+ context.report({
+ node: node.value,
+ messageId: 'physicalValue',
+ data: {
+ prop: propName,
+ physical: value,
+ logical: logicalValue,
+ },
+ fix(fixer) {
+ return fixer.replaceText(node.value, `'${logicalValue}'`);
+ },
+ });
+ }
+ }
+ },
+ };
+ },
+};
+
+export default rule;
diff --git a/internal/eslint-plugin-astryx/no-physical-properties.test.mjs b/internal/eslint-plugin-astryx/no-physical-properties.test.mjs
new file mode 100644
index 0000000000..0eff0a09b7
--- /dev/null
+++ b/internal/eslint-plugin-astryx/no-physical-properties.test.mjs
@@ -0,0 +1,260 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file no-physical-properties.test.mjs
+ */
+
+import {RuleTester} from 'eslint';
+import rule from './no-physical-properties.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ ecmaVersion: 2022,
+ sourceType: 'module',
+ },
+});
+
+/** Wrap a style-object body in a stylex.create() call. */
+function inStylex(body) {
+ return `
+ import * as stylex from '@stylexjs/stylex';
+ const styles = stylex.create({
+ base: { ${body} },
+ });
+ `;
+}
+
+ruleTester.run('no-physical-properties', rule, {
+ valid: [
+ // Logical margin/padding are fine
+ {code: inStylex(`marginInlineStart: 8`)},
+ {code: inStylex(`paddingInlineEnd: 12`)},
+ // Logical inset is fine
+ {code: inStylex(`insetInlineStart: 0`)},
+ // Logical border longhands are fine
+ {code: inStylex(`borderInlineStartWidth: 1, borderInlineEndColor: 'red'`)},
+ // Logical corner radii are fine
+ {code: inStylex(`borderStartStartRadius: 4, borderEndEndRadius: 4`)},
+ // textAlign with a logical value is fine
+ {code: inStylex(`textAlign: 'start'`)},
+ // float/clear with logical values are fine
+ {code: inStylex(`float: 'inline-start'`)},
+ {code: inStylex(`clear: 'inline-end'`)},
+ // textAlign with a non-physical value (center) is fine
+ {code: inStylex(`textAlign: 'center'`)},
+ // Block-direction properties are never physical — fine
+ {code: inStylex(`marginTop: 4, paddingBottom: 8`)},
+ // SCOPING: physical key on a plain object OUTSIDE stylex.create — fine
+ {code: `const x = { left: 5, marginLeft: 10, borderTopLeftRadius: 4 };`},
+ // SCOPING: physical VALUE on a plain object outside stylex — fine
+ {code: `const x = { textAlign: 'left', float: 'right' };`},
+ // SCOPING: `left`/`right` as ordinary variable names — fine
+ {code: `const left = 5; const right = 10; const sum = left + right;`},
+ ],
+ invalid: [
+ // --- KEY-BASED: margin (autofix renames the key) ---
+ {
+ code: inStylex(`marginLeft: 8`),
+ output: inStylex(`marginInlineStart: 8`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'marginLeft', logical: 'marginInlineStart'}},
+ ],
+ },
+ {
+ code: inStylex(`marginRight: 8`),
+ output: inStylex(`marginInlineEnd: 8`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'marginRight', logical: 'marginInlineEnd'}},
+ ],
+ },
+ // --- KEY-BASED: padding ---
+ {
+ code: inStylex(`paddingLeft: 8`),
+ output: inStylex(`paddingInlineStart: 8`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'paddingLeft', logical: 'paddingInlineStart'}},
+ ],
+ },
+ {
+ code: inStylex(`paddingRight: 8`),
+ output: inStylex(`paddingInlineEnd: 8`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'paddingRight', logical: 'paddingInlineEnd'}},
+ ],
+ },
+ // --- KEY-BASED: border side shorthands ---
+ {
+ code: inStylex(`borderLeft: '1px solid red'`),
+ output: inStylex(`borderInlineStart: '1px solid red'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderLeft', logical: 'borderInlineStart'}},
+ ],
+ },
+ {
+ code: inStylex(`borderRight: '1px solid red'`),
+ output: inStylex(`borderInlineEnd: '1px solid red'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderRight', logical: 'borderInlineEnd'}},
+ ],
+ },
+ // --- KEY-BASED: border side longhands (width/style/color) ---
+ {
+ code: inStylex(`borderLeftWidth: 1`),
+ output: inStylex(`borderInlineStartWidth: 1`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderLeftWidth', logical: 'borderInlineStartWidth'}},
+ ],
+ },
+ {
+ code: inStylex(`borderLeftStyle: 'solid'`),
+ output: inStylex(`borderInlineStartStyle: 'solid'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderLeftStyle', logical: 'borderInlineStartStyle'}},
+ ],
+ },
+ {
+ code: inStylex(`borderLeftColor: 'red'`),
+ output: inStylex(`borderInlineStartColor: 'red'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderLeftColor', logical: 'borderInlineStartColor'}},
+ ],
+ },
+ {
+ code: inStylex(`borderRightWidth: 1`),
+ output: inStylex(`borderInlineEndWidth: 1`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderRightWidth', logical: 'borderInlineEndWidth'}},
+ ],
+ },
+ {
+ code: inStylex(`borderRightStyle: 'solid'`),
+ output: inStylex(`borderInlineEndStyle: 'solid'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderRightStyle', logical: 'borderInlineEndStyle'}},
+ ],
+ },
+ {
+ code: inStylex(`borderRightColor: 'red'`),
+ output: inStylex(`borderInlineEndColor: 'red'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderRightColor', logical: 'borderInlineEndColor'}},
+ ],
+ },
+ // --- KEY-BASED: inset left/right ---
+ {
+ code: inStylex(`left: 0`),
+ output: inStylex(`insetInlineStart: 0`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},
+ ],
+ },
+ {
+ code: inStylex(`right: 0`),
+ output: inStylex(`insetInlineEnd: 0`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'right', logical: 'insetInlineEnd'}},
+ ],
+ },
+ // --- KEY-BASED: string-literal key preserves quoting on rename ---
+ {
+ code: inStylex(`'left': 0`),
+ output: inStylex(`'insetInlineStart': 0`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},
+ ],
+ },
+ // --- KEY-BASED: corner radii (verify the diagonal mapping) ---
+ {
+ code: inStylex(`borderTopLeftRadius: 4`),
+ output: inStylex(`borderStartStartRadius: 4`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderTopLeftRadius', logical: 'borderStartStartRadius'}},
+ ],
+ },
+ {
+ code: inStylex(`borderTopRightRadius: 4`),
+ output: inStylex(`borderStartEndRadius: 4`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderTopRightRadius', logical: 'borderStartEndRadius'}},
+ ],
+ },
+ {
+ code: inStylex(`borderBottomLeftRadius: 4`),
+ output: inStylex(`borderEndStartRadius: 4`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderBottomLeftRadius', logical: 'borderEndStartRadius'}},
+ ],
+ },
+ {
+ code: inStylex(`borderBottomRightRadius: 4`),
+ output: inStylex(`borderEndEndRadius: 4`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'borderBottomRightRadius', logical: 'borderEndEndRadius'}},
+ ],
+ },
+ // --- KEY-BASED CONFLICT: both physical + logical present → no autofix ---
+ {
+ code: inStylex(`marginLeft: 8, marginInlineStart: 4`),
+ // Fix is skipped: `output: null` asserts the code is left unchanged.
+ output: null,
+ errors: [
+ {messageId: 'physicalKeyConflict', data: {physical: 'marginLeft', logical: 'marginInlineStart'}},
+ ],
+ },
+ // Conflict also detected when the logical key is a string literal.
+ {
+ code: inStylex(`left: 0, 'insetInlineStart': 10`),
+ output: null,
+ errors: [
+ {messageId: 'physicalKeyConflict', data: {physical: 'left', logical: 'insetInlineStart'}},
+ ],
+ },
+ // --- VALUE-BASED: textAlign (autofix replaces the value only) ---
+ {
+ code: inStylex(`textAlign: 'left'`),
+ output: inStylex(`textAlign: 'start'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'textAlign', physical: 'left', logical: 'start'}},
+ ],
+ },
+ {
+ code: inStylex(`textAlign: 'right'`),
+ output: inStylex(`textAlign: 'end'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'textAlign', physical: 'right', logical: 'end'}},
+ ],
+ },
+ // --- VALUE-BASED: float ---
+ {
+ code: inStylex(`float: 'left'`),
+ output: inStylex(`float: 'inline-start'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'float', physical: 'left', logical: 'inline-start'}},
+ ],
+ },
+ {
+ code: inStylex(`float: 'right'`),
+ output: inStylex(`float: 'inline-end'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'float', physical: 'right', logical: 'inline-end'}},
+ ],
+ },
+ // --- VALUE-BASED: clear ---
+ {
+ code: inStylex(`clear: 'left'`),
+ output: inStylex(`clear: 'inline-start'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'clear', physical: 'left', logical: 'inline-start'}},
+ ],
+ },
+ {
+ code: inStylex(`clear: 'right'`),
+ output: inStylex(`clear: 'inline-end'`),
+ errors: [
+ {messageId: 'physicalValue', data: {prop: 'clear', physical: 'right', logical: 'inline-end'}},
+ ],
+ },
+ ],
+});
+
+console.log('All tests passed!');