@starci/eslint-canon-fe 9.7.0 → 9.8.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 9.8.0 - 2026-10-31
+
+- Added: `no-spacing-utility` (R350, `FE_SPACING_UTILITY`): no padding, margin, gap or space utility (variants and arbitrary values included) in an app class string; the message names the role prop to use. It ships in the closed counting cohort (`COUNTING` of `src/lib/config.ts`) at warn for this release.
+- Changed: `nested-control-variant` refuses the pill (`variant="secondary"`) on `Tabs` wherever it is set, and no longer refuses `variant="primary"` inside a surface: tabs are the underline bar everywhere.
+
 ## 9.7.0 - 2026-10-31
 
 - Added: R349 `no-hand-built-panes` (`FE_HAND_BUILT_PANES`, surface rules, slot-free): a multi-pane frame is a `PaneGrid`, so a vertical Grammar `Divider` used as a column seam (among the plain columns of a flex row, or anywhere inside a `SurfaceCard composition="joined"`) and a joined card that holds a flex row of two or more plain columns are refused.

package/README.md

@@ -38,7 +38,7 @@ configuration for source that has not adopted the product composition laws.
 
 The [surface composition law](docs/surface-rules.md) (R318) holds ANATOMY-2 and PADDING-0 for every
 family that publishes the shared HeroUI surface and field API: `nested-control-variant` refuses static
-variants on layer-aware fields and primary Tabs inside painted Grammar surfaces (`FE_NESTED_VARIANT`),
+variants on layer-aware fields and the pill (`variant="secondary"`) on Tabs, which are the underline bar (`FE_NESTED_VARIANT`),
 `no-app-surface-paint` keeps surface paint in Grammar (`FE_GRAMMAR_LAYOUT_ONLY`) and
 `no-list-panel-padding` refuses horizontal padding wrappers around Grammar lists and section captions
 within the nearest painted surface, a `Pane` or a `PaneSection` included (`FE_LIST_PANEL_PADDING`), and
@@ -46,6 +46,12 @@ within the nearest painted surface, a `Pane` or a `PaneSection` included (`FE_LI
 columns inside a joined card, where `PaneGrid` owns both (`FE_HAND_BUILT_PANES`). The R65 budget law's
 `no-app-relative-clock` leaves live relative time and countdowns to Grammar's shared clock.
 
+The spacing law (R350) leaves every distance to Grammar: `no-spacing-utility` refuses a padding, margin, gap
+or space utility (`p-*`, `px-*`, `m*-*`, `gap-*`, `space-*`, arbitrary values and variants included) in an app class
+string, where a role prop names the relation instead (`Stack`/`Cluster` `gap`, `Grid` `kind`, `PaneSection`, `Page`;
+`FE_SPACING_UTILITY`). It runs in the counting cohort (`COUNTING` of `src/lib/config.ts`): `starci app lint` reports
+and counts every finding at warn and fails on none, while `starci app codemod spacing-roles` migrates the app.
+
 The [button intent law](docs/button-intent.md) (CTA-6) requires every app Button and IconButton to
 declare intent and leave variants to Grammar. It contains destructive confirms in their same-file
 dialog, counts mutually exclusive render paths separately and reserves commit for the view's

package/dist/index.d.ts

@@ -37,9 +37,10 @@ export declare const rules: Record<string, Rule>;
  * The levels this canon asks for, as the plugin's own opinion.
  *
  * Every FE canon rule is an error. Existing debt is fixed before adoption; lowering architecture
- * to warn teaches every later author that the boundary is optional and is not a supported rollout.
+ * to warn teaches every later author that the boundary is optional and is not a supported rollout. The one
+ * exception is the closed counting cohort of lib/config.ts (`COUNTING`), an owner-ruled warn for one release.
  */
-export declare const recommended: Record<string, "error">;
+export declare const recommended: Record<string, "error" | "warn">;
 /** Flat-config options that make inline directives ineffective rather than merely forbidden. */
 export { linterOptions } from "./lib/config.js";
 export { loadHfs } from "./lib/hfs.js";

package/dist/index.js

@@ -45,7 +45,8 @@ import { recommended as translationRecommended, rules as translationRules } from
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.js";
 import { recommended as projectGraphRecommended, rules as projectGraphRules } from "./project-graph.js";
 import { recommended as sonarParityRecommended, rules as sonarParityRules } from "./sonar-parity.js";
-import { buildFeConfig, buildPlainSourceConfig } from "./lib/config.js";
+import { recommended as spacingRecommended, rules as spacingRules } from "./spacing.js";
+import { buildFeConfig, buildPlainSourceConfig, COUNTING } from "./lib/config.js";
 import { why } from "./lib/why.js";
 import { recommended as uiRulingsRecommended, rules as uiRulingsRules } from "./ui-rulings.js";
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
@@ -89,6 +90,7 @@ const CONTRIBUTIONS = [
     { law: "transport", rules: transportRules, recommended: transportRecommended },
     { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
     { law: "sonar-parity", rules: sonarParityRules, recommended: sonarParityRecommended },
+    { law: "spacing", rules: spacingRules, recommended: spacingRecommended },
 ];
 /** Every gathered law. */
 export const lawOwners = CONTRIBUTIONS.map((entry) => entry.law);
@@ -120,7 +122,8 @@ export const rules = Object.fromEntries(CONTRIBUTIONS.flatMap((entry) => Object.
  * The levels this canon asks for, as the plugin's own opinion.
  *
  * Every FE canon rule is an error. Existing debt is fixed before adoption; lowering architecture
- * to warn teaches every later author that the boundary is optional and is not a supported rollout.
+ * to warn teaches every later author that the boundary is optional and is not a supported rollout. The one
+ * exception is the closed counting cohort of lib/config.ts (`COUNTING`), an owner-ruled warn for one release.
  */
 export const recommended = Object.fromEntries(CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.recommended)));
 /** Flat-config options that make inline directives ineffective rather than merely forbidden. */
@@ -223,7 +226,7 @@ export const reactHooksRules = (reactHooks) => {
  */
 export const starciFeConfig = ({ hfs } = {}) => {
     const published = Object.keys(rules).map((name) => `starci-fe/${name}`);
-    const notRequested = published.filter((name) => recommended[name] !== "error");
+    const notRequested = published.filter((name) => recommended[name] !== (name in COUNTING ? "warn" : "error"));
     if (notRequested.length > 0) {
         throw new Error(`starciFeConfig: these published rules are not requested at error: ${notRequested.join(", ")}`);
     }

package/dist/lib/config.d.ts

@@ -27,6 +27,15 @@ export declare const IGNORED: readonly string[];
  * and the Sonar rules that need the checker: S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async` function that never awaits).
  */
 export declare const BORROWED: Readonly<Record<string, "error">>;
+/**
+ * The counting cohort: a rule the owner ruled to ship at `warn` for one release while a codemod moves apps onto the API
+ * it asks for, each with the HFS rule id it enforces. `starci app lint` reports and counts its findings and never fails
+ * on them; the next cohort moves the rule to error and deletes its entry. No other rule may be below error.
+ */
+export declare const COUNTING: Readonly<Record<string, {
+    readonly rule: string;
+    readonly ruling: string;
+}>>;
 /**
  * The flat config of one front-end repository.
  *

package/dist/lib/config.js

@@ -40,6 +40,14 @@ export const BORROWED = Object.freeze({
     "@typescript-eslint/require-await": "error",
 });
 const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting);
+/**
+ * The counting cohort: a rule the owner ruled to ship at `warn` for one release while a codemod moves apps onto the API
+ * it asks for, each with the HFS rule id it enforces. `starci app lint` reports and counts its findings and never fails
+ * on them; the next cohort moves the rule to error and deletes its entry. No other rule may be below error.
+ */
+export const COUNTING = Object.freeze({
+    "starci-fe/no-spacing-utility": { rule: "R350", ruling: "spacing-roles" },
+});
 /**
  * The flat config of one front-end repository.
  *
@@ -60,9 +68,9 @@ export const buildFeConfig = ({ hfs, plugin, source, reactHooks, tsPlugin, sonar
         throw new Error(`starciFeConfig lints the fe side of an app (its eslint.config.mjs lives in fe/); this view is ${hfs.side ? `the ${hfs.side} side` : "the app root"}`);
     if (Object.keys(source).length === 0)
         throw new Error("starciFeConfig received an empty source recommendation - a config with no rules is not adoption");
-    const weak = Object.entries(source).filter(([, setting]) => levelOf(setting) !== "error").map(([name]) => name);
+    const weak = Object.entries(source).filter(([name, setting]) => levelOf(setting) !== (name in COUNTING ? "warn" : "error")).map(([name]) => name);
     if (weak.length > 0)
-        throw new Error(`starciFeConfig refuses source rules not at error: ${weak.join(", ")}`);
+        throw new Error(`starciFeConfig refuses source rules not at error (or not at warn in the counting cohort): ${weak.join(", ")}`);
     const settings = { starci: { hfs } };
     return [
         { ignores: [...IGNORED] },

package/dist/lib/rule.d.ts

@@ -21,6 +21,8 @@ export type Comment = TSESTree.Comment;
 export type Rules = Readonly<Record<string, Rule<string, readonly unknown[]>>>;
 /** The level a law asks for each of its rules, by `starci-fe/<name>`. */
 export type Recommended = Readonly<Record<string, "error">>;
+/** The level of a rule in its counting cohort (lib/config.ts `COUNTING`): reported and counted, never failing. */
+export type CountingRecommended = Readonly<Record<string, "warn">>;
 /**
  * A rule with its message ids and options inferred from the literal: `defineRule({ meta: { messages: { a: "..." } }, ... })`
  * types `context.report({ messageId })` against `a`. It returns the object it is given.

package/dist/lib/why.d.ts

@@ -32,6 +32,11 @@ export declare const why: {
         en: string;
         fix: string;
     };
+    "no-spacing-utility": {
+        code: string;
+        en: string;
+        fix: string;
+    };
     "no-hand-built-panes": {
         code: string;
         en: string;

package/dist/lib/why.js

@@ -32,6 +32,11 @@ export const why = {
         en: "`<file>` insets a horizontal Grammar divider with wrapper padding.",
         fix: "Move horizontal padding to the sibling content bands so the divider reaches both surface edges.",
     },
+    "no-spacing-utility": {
+        code: "FE_SPACING_UTILITY",
+        en: "`<file>` writes a padding, margin, gap or space utility (`<what>`): a distance the Grammar owns.",
+        fix: "Name the relation instead: a Stack or Cluster gap role, a Grid kind, or the inset of the Grammar box that holds the content.",
+    },
     "no-hand-built-panes": {
         code: "FE_HAND_BUILT_PANES",
         en: "`<file>` draws a multi-pane frame by hand: a vertical Divider between columns of a flex row, or a flex row of columns inside a joined SurfaceCard.",

package/dist/spacing.d.ts

@@ -0,0 +1,18 @@
+import { type CountingRecommended } from "./lib/rule.js";
+/** The role a Tailwind gap step names, as the spacing-roles codemod maps it; a step with no role is a judgement. */
+export declare const GAP_STEP_ROLE: Readonly<Record<string, string>>;
+/** The utility a class names once its variants (`sm:`, `hover:`, `[&>*]:`) and importance (`!`) are dropped. */
+export declare const baseUtility: (cls: string) => string;
+/** Every spacing utility of a class string, in the order written. */
+export declare const spacingUtilities: (text: string) => string[];
+/** No padding, margin, gap or space utility in an app class string: the relation is named, the step is the Grammar's. */
+export declare const noSpacingUtility: import("./lib/rule.js").Rule<"utility", []>;
+/** The rules of the spacing law. */
+export declare const rules: {
+    "no-spacing-utility": import("./lib/rule.js").Rule<"utility", []>;
+};
+/**
+ * The rule runs in its counting cohort (lib/config.ts `COUNTING`): every finding is reported and counted by `starci app
+ * lint`, none fails the gate, while `starci app codemod spacing-roles` moves the app onto role props.
+ */
+export declare const recommended: CountingRecommended;

package/dist/spacing.js

@@ -0,0 +1,83 @@
+/**
+ * Spacing is the Grammar's (HFS R350): an app names the relation between the blocks it places through a role prop
+ * (`<Stack gap="section">`, `<Cluster gap="inline">`, `<Grid kind="cards">`, `PaneSection`, `Page`), and the Grammar
+ * resolves the role to its step. A padding, margin, gap or space utility in an app class string is a second owner of
+ * a distance the Grammar already owns.
+ */
+import { classTextVisitors } from "./lib/class-text.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
+import { defineRule } from "./lib/rule.js";
+/** The spacing utility families: padding, margin, gap and the space-between utilities, each side and axis. */
+const SPACING_UTILITY = /^-?(?:p|px|py|pt|pb|ps|pe|pl|pr|m|mx|my|mt|mb|ms|me|ml|mr|gap|gap-x|gap-y|space-x|space-y)-(.+)$/;
+/** The role a Tailwind gap step names, as the spacing-roles codemod maps it; a step with no role is a judgement. */
+export const GAP_STEP_ROLE = Object.freeze({
+    "0": "seam (a joined face or a divider)",
+    "0.5": "identity",
+    "1": "identity",
+    "1.5": "identity",
+    "2": "inline",
+    "2.5": "inline",
+    "3": "row",
+    "4": "section",
+    "5": "section",
+    "6": "region",
+    "8": "region",
+});
+/** The utility a class names once its variants (`sm:`, `hover:`, `[&>*]:`) and importance (`!`) are dropped. */
+export const baseUtility = (cls) => {
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < cls.length; index += 1) {
+        const char = cls[index];
+        if (char === "[" || char === "(")
+            depth += 1;
+        else if (char === "]" || char === ")")
+            depth -= 1;
+        else if (char === ":" && depth === 0)
+            start = index + 1;
+    }
+    return cls.slice(start).replace(/^!|!$/g, "");
+};
+/** Every spacing utility of a class string, in the order written. */
+export const spacingUtilities = (text) => text.split(/\s+/).filter((cls) => SPACING_UTILITY.test(baseUtility(cls)));
+/** What to write instead of one spacing utility. */
+const instead = (cls) => {
+    const base = baseUtility(cls);
+    const match = SPACING_UTILITY.exec(base);
+    const family = base.replace(/^-/, "").split("-")[0] ?? "";
+    if (family === "gap" || family === "space") {
+        const role = GAP_STEP_ROLE[match?.[1] ?? ""];
+        return role === undefined
+            ? "the role of the relation on a Stack, Cluster or Grid gap"
+            : `gap="${role}" on the Stack or Cluster that holds these siblings`;
+    }
+    if (family.startsWith("m"))
+        return "the parent's gap (a Stack or Cluster role); the Grammar alone places a margin";
+    return "the inset of the Grammar box that holds this content (SurfaceCard, PaneSection, Page, Dialog); a box of your own takes none";
+};
+/** No padding, margin, gap or space utility in an app class string: the relation is named, the step is the Grammar's. */
+export const noSpacingUtility = exemptFreestyle(defineRule({
+    meta: {
+        type: "suggestion",
+        docs: { description: "Spacing is the Grammar's: an app names the relation through a role prop, never a spacing utility." },
+        schema: [],
+        messages: {
+            utility: "`{{cls}}` writes a distance the Grammar owns. Use {{instead}} (R350 `FE_SPACING_UTILITY`).",
+        },
+    },
+    create(context) {
+        return classTextVisitors(context, (node, text) => {
+            if (!text)
+                return;
+            for (const cls of spacingUtilities(text))
+                context.report({ node, messageId: "utility", data: { cls, instead: instead(cls) } });
+        });
+    },
+}));
+/** The rules of the spacing law. */
+export const rules = { "no-spacing-utility": noSpacingUtility };
+/**
+ * The rule runs in its counting cohort (lib/config.ts `COUNTING`): every finding is reported and counted by `starci app
+ * lint`, none fails the gate, while `starci app codemod spacing-roles` moves the app onto role props.
+ */
+export const recommended = { "starci-fe/no-spacing-utility": "warn" };

package/dist/surface-rules.js

@@ -289,11 +289,11 @@ const inSectionCaption = (context, node) => {
 export const nestedControlVariant = defineRule({
     meta: {
         type: "problem",
-        docs: { description: "ANATOMY-2: Grammar context supplies field variants; nested Tabs cannot force primary." },
+        docs: { description: "ANATOMY-2: Grammar context supplies field variants; Tabs are the underline bar, never the pill." },
         schema: [],
         messages: {
             variant: "FE_NESTED_VARIANT: app fields cannot set a static variant. Omit variant so Grammar's surface context supplies the appropriate default.",
-            tabs: "FE_NESTED_VARIANT: Tabs inside a Grammar surface cannot force variant=\"primary\". Omit variant so Grammar supplies secondary.",
+            tabs: "FE_NESTED_VARIANT: Tabs are the underline bar, their labels text on the content edge; variant=\"secondary\" is the pill, a filter's shape. Omit variant, or filter a collection with a selectable TagGroup.",
         },
     },
     create(context) {
@@ -308,9 +308,9 @@ export const nestedControlVariant = defineRule({
                         context.report({ node: variant, messageId: "variant" });
                 }
                 else if (name[0] === "Tabs") {
-                    const primary = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "primary"));
-                    if (primary && [...surfaceAncestors(context, node.parent)].some((ancestor) => isSurface(context, ancestor, node)))
-                        context.report({ node: primary, messageId: "tabs" });
+                    const pill = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "secondary"));
+                    if (pill)
+                        context.report({ node: pill, messageId: "tabs" });
                 }
             },
         };

package/docs/surface-rules.md

@@ -4,7 +4,7 @@ Law module: `surface-rules.mjs`. HFS rule: R318. Canon: ANATOMY-2 and PADDING-0.
 
 ## `starci-fe/nested-control-variant`
 
-Finding code: `FE_NESTED_VARIANT`. Grammar context supplies field variants on the page background and inside painted surfaces. App code omits every static `variant` on layer-aware fields, including fields rendered by imported or helper components. Named import aliases, namespace imports, static constants and props spreads preserve Grammar ownership. Explicit primary `Tabs` inside a painted surface is also refused; its default follows the surface context.
+Finding code: `FE_NESTED_VARIANT`. Grammar context supplies field variants on the page background and inside painted surfaces. App code omits every static `variant` on layer-aware fields, including fields rendered by imported or helper components. Named import aliases, namespace imports, static constants and props spreads preserve Grammar ownership. `Tabs` are the underline bar everywhere, their labels text on the content edge, so the pill (`variant="secondary"`) is refused wherever it is set: a pill is a filter's shape, and a filter over a collection is a selectable `TagGroup`.
 
 Invalid:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.7.0",
+  "version": "9.8.0",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.0
+    version: 3.11.1
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.7.0
+    version: 9.8.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.17.0
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.3.0
+    version: 2.4.0
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.15.0
+    version: 4.16.0
     group: starci
     install: registry
     side: both