Skip to content

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

TypeScript

fix(core): replace null style overrides with explicit values, add lint rule (#547)

Cindy Zhangb2a333d5e1be
diff --git a/internal/eslint-plugin-xds/index.js b/internal/eslint-plugin-xds/index.js
index 811003527a..30d5102aa8 100644
--- a/internal/eslint-plugin-xds/index.js
+++ b/internal/eslint-plugin-xds/index.js
@@ -15,6 +15,7 @@
import booleanPropNamingRule from './boolean-prop-naming.js';
import presentationalComponentRule from './presentational-component.js';
import docblockExampleFormatRule from './docblock-example-format.js';
+import noStylexNullOverrideRule from './no-stylex-null-override.js';
// =============================================================================
// Rule: no-hardcoded-styles
@@ -218,6 +219,7 @@ const plugin = {
'boolean-prop-naming': booleanPropNamingRule,
'presentational-component': presentationalComponentRule,
'docblock-example-format': docblockExampleFormatRule,
+ 'no-stylex-null-override': noStylexNullOverrideRule,
},
configs: {},
};
@@ -232,6 +234,7 @@ plugin.configs.strict = {
'@xds/boolean-prop-naming': 'error',
'@xds/presentational-component': 'error',
'@xds/docblock-example-format': 'error',
+ '@xds/no-stylex-null-override': 'error',
},
};
@@ -245,6 +248,7 @@ plugin.configs.recommended = {
'@xds/boolean-prop-naming': 'warn',
'@xds/presentational-component': 'error',
'@xds/docblock-example-format': 'warn',
+ '@xds/no-stylex-null-override': 'warn',
},
};
diff --git a/internal/eslint-plugin-xds/no-stylex-null-override.js b/internal/eslint-plugin-xds/no-stylex-null-override.js
new file mode 100644
index 0000000000..4ad7f5600e
--- /dev/null
+++ b/internal/eslint-plugin-xds/no-stylex-null-override.js
@@ -0,0 +1,95 @@
+/**
+ * @file no-stylex-null-override.js
+ * @description Disallow null values as style overrides in stylex.create().
+ *
+ * Null values in StyleX style objects create a "remove this property" override
+ * that requires property-key deduplication at runtime (via styleq). This
+ * prevents the build from inlining style objects into pre-resolved class name
+ * strings — a ~39KB savings and elimination of the styleq runtime dependency.
+ *
+ * Pattern 1 (OK): { default: null, ':hover': value }
+ * This means "no default, only on hover." StyleX compiles away the null —
+ * no null appears in the output. This is fine.
+ *
+ * Pattern 2 (BAD): { default: null, ':hover': null }
+ * This means "remove both default and hover from a base style." The null
+ * persists in compiled output and blocks build optimizations.
+ *
+ * Pattern 3 (BAD): transform: { default: null, ':active': null }
+ * Same as Pattern 2 — use an explicit value like 'none' instead.
+ *
+ * Fix: Replace null overrides with explicit values.
+ * transform: { default: null, ':active': null } → transform: 'none'
+ * backgroundImage: { default: null, ':hover': null } → backgroundImage: 'none'
+ */
+
+/**
+ * Check if we're inside a stylex.create() call
+ */
+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;
+}
+
+/**
+ * Check if an ObjectExpression has ALL non-$$css values as null.
+ * This is the "override/remove" pattern we want to flag.
+ * If at least one value is non-null, it's the harmless
+ * "default: null, ':hover': value" pattern.
+ */
+function isFullNullOverride(objectExpression) {
+ const properties = objectExpression.properties.filter(
+ p => p.type === 'Property' && p.key?.value !== '$$css'
+ );
+ return properties.length > 0 && properties.every(
+ p => p.value?.type === 'Literal' && p.value.value === null
+ );
+}
+
+const rule = {
+ meta: {
+ type: 'problem',
+ docs: {
+ description:
+ 'Disallow null values as style overrides in stylex.create() — use explicit values instead',
+ category: 'Best Practices',
+ recommended: true,
+ },
+ messages: {
+ noNullOverride:
+ 'Avoid null style overrides in stylex.create(). Use an explicit value like \'none\' instead. ' +
+ 'Null overrides prevent the build from inlining style objects into class name strings.',
+ },
+ schema: [],
+ },
+ create(context) {
+ return {
+ Property(node) {
+ if (!isInsideStylexCreate(node)) return;
+
+ // Only check: Object value where all entries are null
+ // e.g., backgroundImage: { default: null, ':hover': null }
+ // or transform: { default: null, ':active': null }
+ if (
+ node.value?.type === 'ObjectExpression' &&
+ isFullNullOverride(node.value)
+ ) {
+ context.report({ node, messageId: 'noNullOverride' });
+ }
+ },
+ };
+ },
+};
+
+export default rule;
diff --git a/internal/eslint-plugin-xds/no-stylex-null-override.test.mjs b/internal/eslint-plugin-xds/no-stylex-null-override.test.mjs
new file mode 100644
index 0000000000..52b09d3668
--- /dev/null
+++ b/internal/eslint-plugin-xds/no-stylex-null-override.test.mjs
@@ -0,0 +1,84 @@
+/**
+ * @file no-stylex-null-override.test.mjs
+ */
+
+import {RuleTester} from 'eslint';
+import rule from './no-stylex-null-override.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ ecmaVersion: 2022,
+ sourceType: 'module',
+ },
+});
+
+ruleTester.run('no-stylex-null-override', rule, {
+ valid: [
+ // Pattern 1: default: null with non-null pseudo is OK
+ {
+ code: `
+ import * as stylex from '@stylexjs/stylex';
+ const styles = stylex.create({
+ base: {
+ backgroundImage: {
+ default: null,
+ ':hover': 'linear-gradient(...)',
+ },
+ },
+ });
+ `,
+ },
+ // Normal styles without null
+ {
+ code: `
+ import * as stylex from '@stylexjs/stylex';
+ const styles = stylex.create({
+ base: {
+ transform: 'none',
+ backgroundColor: 'transparent',
+ },
+ });
+ `,
+ },
+ // Null outside stylex.create is OK
+ {
+ code: `
+ const obj = { value: null };
+ `,
+ },
+ ],
+ invalid: [
+ // Pattern 2: Full null override (default + pseudo both null)
+ {
+ code: `
+ import * as stylex from '@stylexjs/stylex';
+ const styles = stylex.create({
+ disabled: {
+ transform: {
+ default: null,
+ ':active': null,
+ },
+ },
+ });
+ `,
+ errors: [{ messageId: 'noNullOverride' }],
+ },
+ // Direct null at property level
+ {
+ code: `
+ import * as stylex from '@stylexjs/stylex';
+ const styles = stylex.create({
+ disabled: {
+ backgroundImage: {
+ default: null,
+ ':hover': null,
+ },
+ },
+ });
+ `,
+ errors: [{ messageId: 'noNullOverride' }],
+ },
+ ],
+});
+
+console.log('All tests passed!');
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index 4a4722ca63..1e1340bf56 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -68,8 +68,8 @@ const styles = stylex.create({
cursor: 'not-allowed',
opacity: 0.5,
transform: {
- default: null,
- ':active': null,
+ default: 'none',
+ ':active': 'none',
},
},
iconOnly: {
diff --git a/packages/core/src/Calendar/styles.ts b/packages/core/src/Calendar/styles.ts
index 364f41feb7..9a8b34f25f 100644
--- a/packages/core/src/Calendar/styles.ts
+++ b/packages/core/src/Calendar/styles.ts
@@ -281,8 +281,10 @@ export const dayCellTheme = stylex.create({
dayDisabled: {
opacity: 0.3,
backgroundImage: {
- default: null,
- ':hover': null,
+ default: 'none',
+ ':hover': {
+ '@media (hover: hover)': 'none',
+ },
},
},
});