stablekit.ts 0.2.0

package/README.md

@@ -0,0 +1,207 @@
+# StableKit
+
+React components that make layout shift structurally impossible.
+
+## The Problem
+
+React couples two things that should be independent: **what a component looks like** (paint) and **how much space it takes up** (geometry). When state changes, both change at once, and the browser reflows the page.
+
+```tsx
+// When isLoading flips, the spinner is destroyed and replaced by a table.
+// The browser reflows the entire page.
+{isLoading ? <Spinner /> : <DataTable rows={rows} />}
+```
+
+Every ternary, every conditional render, every `{data && <Component />}` is a geometry mutation disguised as a paint change. This is not a bug — it's the default rendering model.
+
+## The Fix
+
+One rule:
+
+> **A container's dimensions must be a function of its maximum possible future state, not its current instantaneous state.**
+
+Geometry is pre-allocated before data arrives, before the user clicks, before the state changes. Paint changes freely. Geometry never moves.
+
+```tsx
+// One tree describes both loading and loaded states.
+// The geometry is identical in both. Only the paint changes.
+<LoadingBoundary loading={isLoading} exitDuration={150}>
+  <MediaSkeleton aspectRatio={1} className="w-16 rounded-full">
+    <img src={user.avatar} alt={user.name} />
+  </MediaSkeleton>
+  <StableText as="h2" className="text-xl font-bold">{user.name}</StableText>
+  <StableText as="p" className="text-sm text-muted">{user.email}</StableText>
+</LoadingBoundary>
+```
+
+## Install
+
+```bash
+npm install stablekit
+```
+
+## Three Kinds of Stability
+
+### Temporal Pre-allocation
+
+If a component depends on async data, its bounding box is declared synchronously before the data arrives. `MediaSkeleton` forces an `aspectRatio`. `CollectionSkeleton` forces a `stubCount`. `StableText` reserves space at the exact line-height of the text it will display.
+
+### Spatial Pre-allocation
+
+If a UI region has multiple states, all states render simultaneously in a CSS grid overlap. The container sizes to the largest. `LayoutMap` renders a dictionary of views, toggles visibility with `[inert]` + `data-state`, and never changes dimensions. `StateSwap` does the same for boolean content inside buttons and labels.
+
+```tsx
+<LayoutMap value={activeTab} map={{
+  profile: <Profile />,
+  invoices: <Invoices />,
+  settings: <Settings />,
+}} />
+
+<button onClick={toggle}>
+  <StateSwap state={expanded} true="Close" false="View Details" />
+</button>
+```
+
+### Monotonic Geometry
+
+Once a container expands, it cannot shrink unless explicitly reset. `SizeRatchet` tracks the maximum size ever observed and applies `min-width`/`min-height` that only grows. `resetKey` resets the floor when the context changes.
+
+## Components
+
+| Component | What it does |
+|---|---|
+| `LoadingBoundary` | Loading orchestrator — composes shimmer + ratchet + exit transition |
+| `StableText` | Typography + skeleton in one tag |
+| `MediaSkeleton` | Aspect-ratio placeholder that constrains its child |
+| `CollectionSkeleton` | Loading-aware list with forced stub count |
+| `LayoutMap` | Type-safe dictionary of views with stable dimensions |
+| `LayoutGroup` + `LayoutView` | Multi-state spatial container (use LayoutMap when possible) |
+| `StateSwap` | Boolean content swap — both options rendered, zero shift |
+| `StableCounter` | Numeric/text width pre-allocation via ghost reserve |
+| `StableField` | Form error height pre-allocation via ghost reserve |
+| `SizeRatchet` | Container that never shrinks (ResizeObserver ratchet) |
+| `FadeTransition` | Enter/exit animation wrapper, geometry untouched |
+| `createPrimitive` | Factory for UI primitives with architectural enforcement |
+
+## Keeping Visual Decisions in CSS
+
+There's a problem adjacent to layout stability: **visual decisions leaking into JavaScript.**
+
+A component's appearance can change for two reasons. **Identity** — a brand button is always indigo because that's the brand. **Data** — a badge is green when active and red when churned. Identity is fixed and belongs in a className. Data-dependent appearance changes at runtime based on values the component receives.
+
+When a component picks its own visuals based on data — `className={status === "paid" ? "text-green-500" : "text-red-500"}` — the visual decision lives in JavaScript. Changing a color means editing a `.tsx` file. A designer can't update the palette without a developer. A developer can't refactor the component without understanding the color system.
+
+The fix is a hard boundary: **components declare what state they're in, and CSS decides what that looks like.** A `<Badge>` says `data-variant="active"`. CSS says `.sk-badge[data-variant="active"] { color: green }`. The component never knows its own color, font weight, border, opacity, or any other visual property that depends on data. It only knows its state.
+
+### `createPrimitive`
+
+`createPrimitive` makes this boundary automatic. It builds UI primitives where `className` and `style` are blocked at the type level, and variant props are mapped to `data-*` attributes:
+
+```tsx
+import { createPrimitive } from "stablekit";
+
+const Badge = createPrimitive("span", "sk-badge", {
+  variant: ["active", "trial", "churned"],
+});
+```
+
+Consumers get type-checked variants and a locked-down surface:
+
+```tsx
+<Badge variant="active">Paid</Badge>         // renders data-variant="active"
+<Badge variant="bogus">Paid</Badge>          // TypeScript error
+<Badge className="text-red-500">Paid</Badge> // TypeScript error
+```
+
+CSS owns the visuals:
+
+```css
+.sk-badge[data-variant="active"] { color: var(--color-success); }
+.sk-badge[data-variant="trial"]  { color: var(--color-warning); }
+```
+
+Changing a color means editing CSS. Never a component file.
+
+### Architecture Linters
+
+StableKit ships two linter factories that enforce the Structure → Presentation boundary on both sides:
+
+**ESLint** (`stablekit/eslint`) — catches visual decisions leaking into JS:
+
+```js
+// eslint.config.js
+import { createArchitectureLint } from "stablekit/eslint";
+
+export default [
+  createArchitectureLint({
+    stateTokens: ["success", "warning", "destructive"],
+    variantProps: ["variant", "intent"],
+  }),
+];
+```
+
+`stateTokens` declares your project's functional color vocabulary — the token names that represent data-dependent state. The linter flags `bg-success`, `text-warning`, etc. in className strings (these should use `data-*` attributes and CSS).
+
+`variantProps` declares the prop names from your `createPrimitive` calls. The linter flags ternaries on these props — `intent={x ? "primary" : "outline"}` is a visual decision in JS. If a variant changes based on data, the component should use a data-attribute and CSS should handle the visual difference.
+
+It also catches universally: bare hex color literals (`"#f0c040"`), color functions (`rgba()`, `hsl()`, `oklch()`), color properties in style props (`style={{ color: x }}`), className ternaries (`className={x ? "a" : "b"}`), and conditional style ternaries.
+
+**Stylelint** (`stablekit/stylelint`) — catches CSS targeting child elements by tag name:
+
+```js
+// stylelint.config.js
+import { createStyleLint } from "stablekit/stylelint";
+
+export default createStyleLint({
+  functionalTokens: ["--color-status-", "--color-danger"],
+});
+```
+
+This bans element selectors like `& svg { color: green }` — set color on the container and let `currentColor` inherit. Bans `!important`. And with `functionalTokens`, bans functional color tokens inside `@utility` blocks — `@utility text-status-success { color: var(--color-status-active) }` is an error because it launders a functional color into a reusable className, crossing back from Presentation into Structure.
+
+## How It Works
+
+**Spatial stability** uses CSS grid overlap (`grid-area: 1/1`). All views render in the DOM simultaneously. The container auto-sizes to the largest child. Inactive views are hidden with `[inert]` + `data-state="inactive"` (CSS-driven opacity/visibility). Consumers can add CSS transitions to `.sk-layout-view[data-state]` for custom animations.
+
+**Loading skeletons** use `1lh` CSS units to match line-height exactly. Shimmer width comes from inert ghost content — the skeleton is exactly as wide as the text it replaces.
+
+**`MediaSkeleton`** constrains its child via `cloneElement` inline styles (`position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover`). No CSS `!important`.
+
+**`SizeRatchet`** uses a one-way ResizeObserver. It tracks the maximum border-box size ever observed and applies `min-width`/`min-height` that only grows.
+
+## CSS Custom Properties
+
+```css
+--sk-shimmer-color: #e5e7eb;
+--sk-shimmer-highlight: #f3f4f6;
+--sk-shimmer-radius: 0.125rem;
+--sk-shimmer-duration: 1.5s;
+--sk-skeleton-gap: 0.75rem;
+--sk-skeleton-bone-gap: 0.125rem;
+--sk-skeleton-bone-padding: 0.375rem 0.5rem;
+--sk-fade-duration: 200ms;
+--sk-fade-offset-y: -12px;
+--sk-fade-offset-scale: 0.98;
+--sk-loading-exit-duration: 150ms;
+--sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);
+--sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+--sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);
+```
+
+## Style Injection
+
+Styles are auto-injected via a `<style data-stablekit>` tag on first import. To opt out (e.g. if you import `stablekit/styles.css` manually):
+
+```html
+<meta name="stablekit-disable-injection" />
+```
+
+For CSP nonce support:
+
+```html
+<meta name="stablekit-nonce" content="your-nonce-here" />
+```
+
+## License
+
+MIT

package/dist/eslint.cjs

@@ -0,0 +1,157 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/eslint.ts
+var eslint_exports = {};
+__export(eslint_exports, {
+  createArchitectureLint: () => createArchitectureLint
+});
+module.exports = __toCommonJS(eslint_exports);
+function createArchitectureLint(options) {
+  const {
+    stateTokens,
+    variantProps = [],
+    banColorUtilities = true,
+    files = ["src/components/**/*.{tsx,jsx}"]
+  } = options;
+  const tokenPattern = stateTokens.join("|");
+  const twColors = "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone|white|black";
+  const twPrefixes = "text|bg|border|ring|shadow|outline|accent|fill|stroke|from|to|via|divide|decoration";
+  return {
+    files,
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        // --- 1. Hardcoded design tokens (universal) ---
+        {
+          selector: "Literal[value=/text-\\[\\d+/]",
+          message: "Hardcoded font size. Define a named token in @theme."
+        },
+        {
+          selector: "Literal[value=/\\[.*(?:#[0-9a-fA-F]|rgba?).*\\]/]",
+          message: "Hardcoded color value. Define a CSS custom property."
+        },
+        {
+          selector: "JSXAttribute[name.name='style'] Property > Literal[value=/(?:#[0-9a-fA-F]{3,8}|rgba?\\()/]",
+          message: "Hardcoded color value in style object. Define a CSS custom property."
+        },
+        {
+          selector: "Literal[value=/^#[0-9a-fA-F]{3}([0-9a-fA-F]([0-9a-fA-F]{2}([0-9a-fA-F]{2})?)?)?$/]",
+          message: "Hardcoded hex color. Define a CSS custom property."
+        },
+        {
+          selector: "Literal[value=/(?:^|[^a-zA-Z])(?:rgba?|hsla?|oklch|lab|lch)\\(/]",
+          message: "Hardcoded color function. Define a CSS custom property."
+        },
+        // --- 1b. Color properties in style props ---
+        {
+          selector: "JSXAttribute[name.name='style'] Property[key.name=/^(color|backgroundColor|background|borderColor|outlineColor|fill|stroke|accentColor|caretColor)$/]",
+          message: "Visual color property in style prop. Use a data-attribute and CSS selector."
+        },
+        // --- 1c. Visual state properties in style props ---
+        {
+          selector: "JSXAttribute[name.name='style'] Property[key.name=/^(opacity|visibility|transition|pointerEvents)$/]",
+          message: "Visual state property in style prop. Use a data-attribute and CSS selector."
+        },
+        // --- 1d. Hardcoded magic numbers ---
+        {
+          selector: "Literal[value=/z-\\[\\d/]",
+          message: "Hardcoded z-index. Define a named z-index token in @theme."
+        },
+        {
+          selector: "Literal[value=/-m\\w?-\\[|m\\w?-\\[-/]",
+          message: "Negative margin with magic number. This usually fights the layout \u2014 fix the spacing structure instead."
+        },
+        {
+          selector: "Literal[value=/(?:min-|max-)?(?:w|h)-\\[\\d+px\\]/]",
+          message: "Hardcoded pixel dimension. Define a named size token in @theme or use a relative unit."
+        },
+        {
+          selector: "Literal[value=/\\w-\\[(?!calc).*?\\d+(?![\\d%]|[dsl]?v[hw]|fr)/]",
+          message: "Hardcoded magic number in arbitrary value. Define a named token in @theme or use a standard utility."
+        },
+        // --- 2. Data-dependent visual decisions (project-specific) ---
+        ...tokenPattern ? [
+          {
+            selector: `Literal[value=/\\b(bg|text|border)-(${tokenPattern})/]`,
+            message: "Data-dependent visual property. Use a data-attribute and CSS selector."
+          }
+        ] : [],
+        {
+          selector: "JSXAttribute[name.name='style'] ConditionalExpression",
+          message: "Conditional style object. Use a data-state attribute and CSS selector."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] ConditionalExpression",
+          message: "Conditional className. Use a data-attribute and CSS selector instead of switching classes with a ternary."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] LogicalExpression[operator='&&']",
+          message: "Conditional className. Use a data-attribute and CSS selector instead of conditionally applying classes."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] ObjectExpression",
+          message: "Conditional className via object syntax. Use a data-attribute and CSS selector instead of cx/cn({ class: condition })."
+        },
+        // --- 2c. !important in className ---
+        {
+          selector: "JSXAttribute[name.name='className'] Literal[value=/(?:^|\\s)![a-z]/]",
+          message: "Tailwind !important modifier in className. !important breaks the cascade \u2014 use specificity or data-attributes."
+        },
+        // --- 2d. Tailwind color utilities in className ---
+        ...banColorUtilities ? [
+          {
+            selector: `Literal[value=/(?:^|\\s)(?:${twPrefixes})-(?:${twColors})(?:-\\d+)?(?:\\/\\d+)?(?:\\s|$)/]`,
+            message: "Tailwind color utility in className. Colors belong in CSS \u2014 use a CSS class with a custom property or data-attribute selector."
+          }
+        ] : [],
+        // --- 3. Ternaries on variant props (from createPrimitive) ---
+        ...variantProps.map((prop) => ({
+          selector: `JSXAttribute[name.name='${prop}'] ConditionalExpression`,
+          message: `Data-dependent ${prop}. Use a data-attribute and CSS selector instead of switching ${prop} with a ternary.`
+        })),
+        // --- 4. Geometric instability (conditional content) ---
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
+          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <LayoutMap> for keyed views, or <LoadingBoundary> for async states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
+          message: "Conditional mount in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT use the hidden attribute \u2014 it renders children unconditionally and will crash on null data. For state-driven mounts, use <FadeTransition> for enter/exit, <StableField> for form errors, or <LayoutGroup> for pre-rendered views."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='||']",
+          message: "Fallback content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='??']",
+          message: "Nullish fallback in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
+          message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
+        }
+      ]
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createArchitectureLint
+});

package/dist/eslint.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Architecture Linter Factory
+ *
+ * Creates an ESLint flat config that enforces the Structure → Presentation
+ * boundary. Rules organized by category:
+ *
+ * 1. Hardcoded visual values — bare hex colors (#f0c040), color functions
+ *    (rgba, hsl, oklch), font sizes in Tailwind arbitrary values,
+ *    color properties in style props, visual state properties (opacity,
+ *    visibility, transition, pointerEvents) in style props.
+ *
+ * 1d. Hardcoded magic numbers — arbitrary z-index (z-[999]), negative
+ *     margins with arbitrary values (m-[-4px]), and arbitrary pixel
+ *     dimensions (w-[347px], h-[200px]).
+ *
+ * 2. Data-dependent visual decisions — state color tokens in className,
+ *    conditional style ternaries, className ternaries, className logical
+ *    AND, cx/cn object syntax, and !important in className.
+ *
+ * 3. Ternaries on variant props — if a variant prop created by
+ *    createPrimitive has a ternary, the visual decision is in JS.
+ *
+ * 4. Geometric instability — conditional content in JSX children that
+ *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
+ *    and interpolated template literals. Each message guides toward
+ *    extracting the expression to a variable (for data transforms) or
+ *    using a StableKit component (for state-driven swaps). Always on.
+ */
+interface ArchitectureLintOptions {
+    /** State token names that should never appear in JS as Tailwind classes.
+     *  e.g. ["success", "warning", "destructive", "canceled"] */
+    stateTokens: string[];
+    /** Variant prop names from createPrimitive that should never have ternaries.
+     *  e.g. ["intent", "variant"] — bans intent={x ? "a" : "b"} */
+    variantProps?: string[];
+    /** Ban all Tailwind color palette utilities in className.
+     *  Catches bg-red-500, text-green-600, border-cyan-400, etc.
+     *  Colors must live in CSS — not in component classNames.
+     *  @default true */
+    banColorUtilities?: boolean;
+    /** Glob patterns for files to lint.
+     *  @default ["src/components/**\/*.{tsx,jsx}"] */
+    files?: string[];
+}
+declare function createArchitectureLint(options: ArchitectureLintOptions): {
+    files: string[];
+    rules: {
+        "no-restricted-syntax": (string | {
+            selector: string;
+            message: string;
+        })[];
+    };
+};
+
+export { type ArchitectureLintOptions, createArchitectureLint };

package/dist/eslint.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Architecture Linter Factory
+ *
+ * Creates an ESLint flat config that enforces the Structure → Presentation
+ * boundary. Rules organized by category:
+ *
+ * 1. Hardcoded visual values — bare hex colors (#f0c040), color functions
+ *    (rgba, hsl, oklch), font sizes in Tailwind arbitrary values,
+ *    color properties in style props, visual state properties (opacity,
+ *    visibility, transition, pointerEvents) in style props.
+ *
+ * 1d. Hardcoded magic numbers — arbitrary z-index (z-[999]), negative
+ *     margins with arbitrary values (m-[-4px]), and arbitrary pixel
+ *     dimensions (w-[347px], h-[200px]).
+ *
+ * 2. Data-dependent visual decisions — state color tokens in className,
+ *    conditional style ternaries, className ternaries, className logical
+ *    AND, cx/cn object syntax, and !important in className.
+ *
+ * 3. Ternaries on variant props — if a variant prop created by
+ *    createPrimitive has a ternary, the visual decision is in JS.
+ *
+ * 4. Geometric instability — conditional content in JSX children that
+ *    causes layout shift: ternary swaps, && mounts, || / ?? fallbacks,
+ *    and interpolated template literals. Each message guides toward
+ *    extracting the expression to a variable (for data transforms) or
+ *    using a StableKit component (for state-driven swaps). Always on.
+ */
+interface ArchitectureLintOptions {
+    /** State token names that should never appear in JS as Tailwind classes.
+     *  e.g. ["success", "warning", "destructive", "canceled"] */
+    stateTokens: string[];
+    /** Variant prop names from createPrimitive that should never have ternaries.
+     *  e.g. ["intent", "variant"] — bans intent={x ? "a" : "b"} */
+    variantProps?: string[];
+    /** Ban all Tailwind color palette utilities in className.
+     *  Catches bg-red-500, text-green-600, border-cyan-400, etc.
+     *  Colors must live in CSS — not in component classNames.
+     *  @default true */
+    banColorUtilities?: boolean;
+    /** Glob patterns for files to lint.
+     *  @default ["src/components/**\/*.{tsx,jsx}"] */
+    files?: string[];
+}
+declare function createArchitectureLint(options: ArchitectureLintOptions): {
+    files: string[];
+    rules: {
+        "no-restricted-syntax": (string | {
+            selector: string;
+            message: string;
+        })[];
+    };
+};
+
+export { type ArchitectureLintOptions, createArchitectureLint };

package/dist/eslint.js

@@ -0,0 +1,132 @@
+// src/eslint.ts
+function createArchitectureLint(options) {
+  const {
+    stateTokens,
+    variantProps = [],
+    banColorUtilities = true,
+    files = ["src/components/**/*.{tsx,jsx}"]
+  } = options;
+  const tokenPattern = stateTokens.join("|");
+  const twColors = "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone|white|black";
+  const twPrefixes = "text|bg|border|ring|shadow|outline|accent|fill|stroke|from|to|via|divide|decoration";
+  return {
+    files,
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        // --- 1. Hardcoded design tokens (universal) ---
+        {
+          selector: "Literal[value=/text-\\[\\d+/]",
+          message: "Hardcoded font size. Define a named token in @theme."
+        },
+        {
+          selector: "Literal[value=/\\[.*(?:#[0-9a-fA-F]|rgba?).*\\]/]",
+          message: "Hardcoded color value. Define a CSS custom property."
+        },
+        {
+          selector: "JSXAttribute[name.name='style'] Property > Literal[value=/(?:#[0-9a-fA-F]{3,8}|rgba?\\()/]",
+          message: "Hardcoded color value in style object. Define a CSS custom property."
+        },
+        {
+          selector: "Literal[value=/^#[0-9a-fA-F]{3}([0-9a-fA-F]([0-9a-fA-F]{2}([0-9a-fA-F]{2})?)?)?$/]",
+          message: "Hardcoded hex color. Define a CSS custom property."
+        },
+        {
+          selector: "Literal[value=/(?:^|[^a-zA-Z])(?:rgba?|hsla?|oklch|lab|lch)\\(/]",
+          message: "Hardcoded color function. Define a CSS custom property."
+        },
+        // --- 1b. Color properties in style props ---
+        {
+          selector: "JSXAttribute[name.name='style'] Property[key.name=/^(color|backgroundColor|background|borderColor|outlineColor|fill|stroke|accentColor|caretColor)$/]",
+          message: "Visual color property in style prop. Use a data-attribute and CSS selector."
+        },
+        // --- 1c. Visual state properties in style props ---
+        {
+          selector: "JSXAttribute[name.name='style'] Property[key.name=/^(opacity|visibility|transition|pointerEvents)$/]",
+          message: "Visual state property in style prop. Use a data-attribute and CSS selector."
+        },
+        // --- 1d. Hardcoded magic numbers ---
+        {
+          selector: "Literal[value=/z-\\[\\d/]",
+          message: "Hardcoded z-index. Define a named z-index token in @theme."
+        },
+        {
+          selector: "Literal[value=/-m\\w?-\\[|m\\w?-\\[-/]",
+          message: "Negative margin with magic number. This usually fights the layout \u2014 fix the spacing structure instead."
+        },
+        {
+          selector: "Literal[value=/(?:min-|max-)?(?:w|h)-\\[\\d+px\\]/]",
+          message: "Hardcoded pixel dimension. Define a named size token in @theme or use a relative unit."
+        },
+        {
+          selector: "Literal[value=/\\w-\\[(?!calc).*?\\d+(?![\\d%]|[dsl]?v[hw]|fr)/]",
+          message: "Hardcoded magic number in arbitrary value. Define a named token in @theme or use a standard utility."
+        },
+        // --- 2. Data-dependent visual decisions (project-specific) ---
+        ...tokenPattern ? [
+          {
+            selector: `Literal[value=/\\b(bg|text|border)-(${tokenPattern})/]`,
+            message: "Data-dependent visual property. Use a data-attribute and CSS selector."
+          }
+        ] : [],
+        {
+          selector: "JSXAttribute[name.name='style'] ConditionalExpression",
+          message: "Conditional style object. Use a data-state attribute and CSS selector."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] ConditionalExpression",
+          message: "Conditional className. Use a data-attribute and CSS selector instead of switching classes with a ternary."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] LogicalExpression[operator='&&']",
+          message: "Conditional className. Use a data-attribute and CSS selector instead of conditionally applying classes."
+        },
+        {
+          selector: "JSXAttribute[name.name='className'] ObjectExpression",
+          message: "Conditional className via object syntax. Use a data-attribute and CSS selector instead of cx/cn({ class: condition })."
+        },
+        // --- 2c. !important in className ---
+        {
+          selector: "JSXAttribute[name.name='className'] Literal[value=/(?:^|\\s)![a-z]/]",
+          message: "Tailwind !important modifier in className. !important breaks the cascade \u2014 use specificity or data-attributes."
+        },
+        // --- 2d. Tailwind color utilities in className ---
+        ...banColorUtilities ? [
+          {
+            selector: `Literal[value=/(?:^|\\s)(?:${twPrefixes})-(?:${twColors})(?:-\\d+)?(?:\\/\\d+)?(?:\\s|$)/]`,
+            message: "Tailwind color utility in className. Colors belong in CSS \u2014 use a CSS class with a custom property or data-attribute selector."
+          }
+        ] : [],
+        // --- 3. Ternaries on variant props (from createPrimitive) ---
+        ...variantProps.map((prop) => ({
+          selector: `JSXAttribute[name.name='${prop}'] ConditionalExpression`,
+          message: `Data-dependent ${prop}. Use a data-attribute and CSS selector instead of switching ${prop} with a ternary.`
+        })),
+        // --- 4. Geometric instability (conditional content) ---
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
+          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <LayoutMap> for keyed views, or <LoadingBoundary> for async states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
+          message: "Conditional mount in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT use the hidden attribute \u2014 it renders children unconditionally and will crash on null data. For state-driven mounts, use <FadeTransition> for enter/exit, <StableField> for form errors, or <LayoutGroup> for pre-rendered views."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='||']",
+          message: "Fallback content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='??']",
+          message: "Nullish fallback in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+        },
+        {
+          selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
+          message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
+        }
+      ]
+    }
+  };
+}
+export {
+  createArchitectureLint
+};