@starci/eslint-grammar-core 0.0.0-stage → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.13.0 - 2026-10-27
+
+- Changed: `@starci/eslint-canon-fe` is a peer dependency (9.2.0), installed by the app beside this package, instead of a nested dependency.
+- Changed: the package lives in github.com/starci183/starci-harness under `packages/` and publishes from there; its bundled `runtime/` is committed source, edited in place (no generator, no `prepack`/`pretest` hook).
+- Changed: owner ruling: there are exactly two Grammar families, `core` and `offset-pop`. This package is renamed from
+  `@starci/eslint-grammar-starci` to `@starci/eslint-grammar-core`, and its factory from `starciGrammarConfig` to
+  `coreGrammarConfig`, which loads for `sides.fe.grammar: core`.
+- Removed: the ids `starci` and `starci-core` are not families and have no alias; an app that names them is refused.
+  Migrate: `sides.fe.grammar: core`, depend on `@starci/eslint-grammar-core`, call `coreGrammarConfig`.
+
+## 0.12.14 - 2026-10-27
+
+- Changed: versioned together with Grammar 0.12.14; bundled canon pins moved.
+
+## 0.12.13 - 2026-10-26
+
+- Changed: versioned together with Grammar 0.12.13 (control height 40, shared scroll carets).
+
+## 0.12.12 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.12 (the family equality spec); the bundled canon pins and runtime copies follow the final package versions. No rule changes.
+
+## 0.12.11 - 2026-10-26
+
+- Changed: versioned with the other lint families; depends on the exact front-end canon 9.1.7; the alpha.31.1 round folded into alpha.31; the bundled canon pins and runtime copies follow the final package versions. No rule changes.
+
+## 0.12.10 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.10; depends on the exact canon-fe 9.1.6; the bundled canon pins follow the new package pins. No rule changes.
+
+## 0.12.9 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.9; depends on the exact canon-fe 9.1.5; the bundled canon pins follow the new package pins. No rule changes.
+
+## 0.12.8 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.8; depends on the exact canon-fe 9.1.4; the bundled canon pins follow the new package pins. No rule changes.
+
+## 0.12.7 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.7; depends on the exact canon-fe 9.1.3; the bundled canon pins follow the new package pins. No rule changes.
+
+## 0.12.6 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.6; depends on @starci/eslint-canon-fe 9.1.2; the bundled runtime copies follow the new sources. No rule changes.
+
+## 0.12.5 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.5; depends on @starci/eslint-canon-fe 9.1.1; the bundled canon pins follow the new package pins. No rule changes.
+
+## 0.12.4 - 2026-10-26
+
+- Changed: versioned with Grammar 0.12.4; no rule changes beyond the version pin.
+
+## 0.12.3 - 2026-10-26
+
+- Added: the StarCi Grammar lint package, released with Grammar 0.12.3. Concrete family laws move from the universal FE canon with their rule IDs and behavioral specs, including the Grammar 0.12.3 lane's `no-icon-size-class` and `destructive-menu-entry-needs-danger-tone` in their latest form. The R318 surface composition rules stay in the universal canon.
+- Added: the `starciGrammarConfig` flat-config factory, complete error-level recommendations, ownership citations and a generated runtime closure.
+- Shared: generic lint readers are imported from `@starci/eslint-canon-fe` 9.0.0.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @starci/eslint-grammar-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Concrete StarCi Grammar component, prop, variant and token contracts belong here under
+[FE-RULE-OWNERSHIP](../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).
+The package version follows `@starci/grammar`; universal FE laws remain in `@starci/eslint-canon-fe`.
+
+```js
+import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+import { coreGrammarConfig } from "@starci/eslint-grammar-core"
+
+const hfs = loadHfs(import.meta.url)
+export default [...starciFeConfig({ hfs }), ...coreGrammarConfig({ hfs })]
+```
+
+Every rule uses the `starci-grammar` namespace and runs at error. The factory checks the selected
+Grammar and covers the same source files as the universal factory. Shared AST, type, slot and
+binding readers are imported from the universal package's explicit infrastructure exports.
+Family helpers and the generated runtime closure belong to this package.
+
+The rule IDs remain stable when their namespace moves. Laws cover the fixed app shell and navbar,
+Grammar-owned structural elements, glyphs and icon sizes, destructive menu entries, status inks,
+heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
+its behavioral knowledge source and the governing ownership test. The R318 surface composition
+rules (nested control variants, panel-list alignment, layout-only CSS) stay in the universal canon.
+
+## Migrating from @starci/eslint-canon-fe 8.x
+
+The pinned canon-fe release moved twenty rules here. Their IDs, finding codes and error severity are unchanged;
+only the namespace changes from `starci-fe/` to `starci-grammar/`: `app-shell-frame`,
+`no-shell-bottom-tabs`, `navbar-control-size`, `navbar-cluster`, `no-navbar-create`,
+`no-raw-structural-element`, `no-heading-tag-outside-heading-component`,
+`status-text-uses-soft-foreground`, `vendor-primitive-has-named-owner`,
+`no-vendor-icon-outside-icon-leaf`, `heroicons-is-the-glyph-vendor`, `no-off-scale-glyph-size`,
+`no-icon-size-class`, `destructive-menu-entry-needs-danger-tone`,
+`no-decorative-icon-in-metric-cell`, `no-inline-svg-outside-brand-mark-leaf`, `no-fractional-step`,
+`no-hand-rolled-heading`, `no-unresolved-token-class` and `slot-status-through-slotview`.
+
+1. Set `sides.fe.grammar` to `core` in `hfs.json`; no family is inferred.
+2. Install this package at its canon-pins version beside `@starci/eslint-canon-fe` 9 in the app
+   root `devDependencies`. `starci app check` refuses canon-fe 9 without it
+   (`FE_STACK_FAMILY_LINT_MISSING`), so the rules cannot be lost silently.
+3. Compose the universal factory first and this one second, with the same HFS view (the block
+   above). `starci app sync` renders that managed `fe/eslint.config.mjs`.
+4. Rename references to the moved rules from `starci-fe/` to `starci-grammar/`.
+
+Consuming apps migrate in their own release.
+
+Offset Pop inherits the Common component contract through `@starci/eslint-grammar-offset-pop`.
+Its own adapter selects that family and reuses these implementations.
+
+Regression checks live in this ESLint package. The Grammar and consuming app front ends carry no specs.

package/app-shell.mjs

@@ -0,0 +1,208 @@
+import { defineFamilyRules } from "./lib/rule-contract.mjs"
+/** FE-APP-SHELL-1..5: static app-frame and visible navbar composition from the UI canon. */
+import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs"
+import { grammarName, isBarControl, propOf, resolveLocal, semanticText, textProp } from "./lib/app-shell.mjs"
+import { appBarOpenings, isAppBar, isAppShell, isNavigationDrawer, ownsAppFrame } from "./lib/app-shell-scope.mjs"
+import { visitVisible } from "./lib/app-shell-visible.mjs"
+import { clusterAlternatives } from "./lib/app-shell-cluster.mjs"
+import { isCreateAction, menuHasCreate } from "./lib/app-shell-create.mjs"
+import { provesImportedBar, provesNavigationOpener } from "./lib/app-shell-owner.mjs"
+import { variableOf } from "@starci/eslint-canon-fe/lib/bindings.mjs"
+import { walk } from "@starci/eslint-canon-fe/lib/ast.mjs"
+
+const CANON = "knowledge/ui/composition/app-shell.yaml"
+const BOTTOM_TABS = /^(?:BottomNav|BottomNavigation|BottomTabBar|MobileBottomNav|MobileTabBar)$/
+const EXPECTED_CLUSTER = ["language:IconButton", "theme:Switch", "notifications:IconButton", "account:AvatarButton"]
+
+const meta = (code, description, messages) => ({
+  type: "problem",
+  docs: { description: `${code}: ${description}`, url: CANON },
+  schema: [],
+  messages,
+})
+
+/** Whether a slot is present; unknown spreads do not prove either presence or absence. */
+const slotPresence = (context, opening, name) => {
+  const prop = propOf(context, opening, name)
+  if (!prop.known) return null
+  const value = resolveLocal(context, prop.value)
+  if (value === null || value.type === "Literal" && (value.value == null || value.value === false)) return false
+  return !(value.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length)
+}
+
+/** Resolve constants and require every possible conditional value to prove the slot contract. */
+const everyValue = (context, expression, proves, seen = new Set()) => {
+  const node = resolveLocal(context, expression)
+  if (!node || seen.has(node)) return false
+  if (node.type !== "ConditionalExpression") return proves(node)
+  const visited = new Set(seen).add(node)
+  return [node.consequent, node.alternate].every((branch) => everyValue(context, branch, proves, visited))
+}
+
+const hasMobileNavigation = (context, opening) => {
+  const drawerProp = propOf(context, opening, "navigationDrawer")
+  const drawer = drawerProp.known && everyValue(context, drawerProp.value, (value) => value.type === "ObjectExpression")
+  const opener = drawer || provesNavigationOpener(context, propOf(context, opening, "compactHeader").value)
+  const visibility = propOf(context, opening, "navigationVisibility")
+  const defaultsWide = opener && visibility.known && slotPresence(context, opening, "navigationVisibility") === false
+  if (!defaultsWide && (!visibility.known || !everyValue(context, visibility.value, (value) => value.type === "Literal" && value.value === "wide"))) return false
+  return opener
+}
+
+/** App-owned tab names count only in a frame owner or a shell's rendered slots. */
+const visibleFromShell = (context, target) => {
+  let visible = false
+  walk(context.sourceCode, context.sourceCode.ast, (node) => {
+    if (node.type !== "JSXOpeningElement" || !isAppShell(context, node)) return
+    const inspect = (opening) => { if (opening === target) visible = true }
+    for (const slot of ["header", "compactHeader", "navigation", "primary", "floatingLayer", "compactNavigation"]) visitVisible(context, propOf(context, node, slot).value, inspect)
+    for (const child of node.parent.children) visitVisible(context, child, inspect)
+  })
+  return visible
+}
+
+/** The app frame is the fixed-viewport Grammar shell; hand-written frame landmarks are rejected. */
+export const appShellFrame = {
+  meta: meta("FE_APP_SHELL_FRAME", "FE-APP-SHELL-1 uses WorkspaceShell viewport=fixed.", {
+    frame: "FE_APP_SHELL_FRAME: compose the app frame with WorkspaceShell viewport=\"fixed\"; navigation must resolve to navigationVisibility=\"wide\" and have navigationDrawer or a compactHeader with a left Drawer containing Sidebar presentation=\"drawer\". Grammar owns its header, navigation and independent scroll regions.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const shell = isAppShell(context, node)
+      const wrongViewport = shell && textProp(context, node, "viewport") !== "fixed"
+      const missingVisibility = shell && slotPresence(context, node, "navigation") !== false && !hasMobileNavigation(context, node)
+      const handFrame = ownsAppFrame(context, node) && (node.name.type === "JSXIdentifier" && ["header", "nav", "main"].includes(node.name.name) || isAppBar(context, node) && !appBarOpenings(context).has(node))
+      if (wrongViewport || missingVisibility || handFrame) {
+        context.report({ node, messageId: "frame" })
+      }
+    } }
+  },
+}
+
+/** Bottom navigation is not an alternative compact app-shell frame. */
+export const noShellBottomTabs = {
+  meta: meta("FE_APP_SHELL_BOTTOM_TABS", "FE-APP-SHELL-4 keeps mobile navigation in the sidebar drawer.", {
+    bottom: "FE_APP_SHELL_BOTTOM_TABS: the app shell uses a mobile subnav opener and Sidebar drawer. Remove bottom tab navigation and WorkspaceShell compactNavigation.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const name = grammarName(context, node)
+      const appTab = name === null && node.name.type === "JSXIdentifier" && BOTTOM_TABS.test(node.name.name) && (ownsAppFrame(context, node) || visibleFromShell(context, node))
+      const compact = name === "WorkspaceShell" && propOf(context, node, "compactNavigation")
+      const value = compact && resolveLocal(context, compact.value)
+      const absent = value?.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length
+      if (BOTTOM_TABS.test(name ?? "") || appTab || compact && !absent && (!compact.known || compact.value !== null || compact.present)) context.report({ node, messageId: "bottom" })
+    } }
+  },
+}
+
+const visitBar = (context, node, visit) => {
+  const name = grammarName(context, node)
+  if (name === "WorkspaceShell" && isAppShell(context, node)) {
+    for (const slot of ["header", "compactHeader"]) visitVisible(context, propOf(context, node, slot).value, visit)
+  } else if (isAppBar(context, node)) {
+    visitVisible(context, node.parent, visit)
+  } else if (isNavigationDrawer(context, node)) {
+    visitVisible(context, propOf(context, node, "trigger").value, visit)
+  }
+}
+
+const delegatesImportedBar = (context, expression) => {
+  let imported = false
+  let controls = false
+  let unknown = false
+  visitVisible(context, expression, (opening, name) => {
+    if (isBarControl(context, opening, name)) controls = true
+    if (name !== null) return
+    const proof = provesImportedBar(context, opening)
+    if (proof === true) imported = true
+    if (proof === false) unknown = true
+  })
+  return imported && !controls && !unknown
+}
+
+/** Every visible control in a navbar band uses the shared control size. */
+export const navbarControlSize = {
+  meta: meta("FE_NAVBAR_CONTROL_SIZE", "FE-APP-SHELL-2 requires size=control on bar controls.", {
+    control: "FE_NAVBAR_CONTROL_SIZE: {{name}} in the navbar band needs size=\"control\" so every bar control shares Grammar's control height.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const reported = new Set()
+    return { JSXOpeningElement(node) {
+      visitBar(context, node, (control, name) => {
+        if (!isBarControl(context, control, name) || textProp(context, control, "size") === "control" || reported.has(control)) return
+        reported.add(control)
+        context.report({ node: control, messageId: "control", data: { name } })
+      })
+    } }
+  },
+}
+
+/** The right cluster is checked at the bar's actions composition, in visual source order. */
+export const navbarCluster = {
+  meta: meta("FE_NAVBAR_CLUSTER", "FE-APP-SHELL-3 fixes navbar action kinds and order.", {
+    cluster: "FE_NAVBAR_CLUSTER: navbar actions must be a tertiary Language IconButton in DropdownMenu, theme Switch, notification IconButton in Popover, account AvatarButton in DropdownMenu, in that order. Mobile retains notifications then account and moves language/theme into the drawer.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const name = grammarName(context, node)
+      if (!isAppShell(context, node) && !isAppBar(context, node)) return
+      const shellHeader = name === "WorkspaceShell"
+      const actions = propOf(context, node, shellHeader ? "header" : "actions")
+      const { alternatives, ownsBar } = clusterAlternatives(context, actions.value, shellHeader)
+      if (ownsBar) return
+      if (shellHeader && delegatesImportedBar(context, actions.value)) return
+      const desktop = EXPECTED_CLUSTER.join("|")
+      const mobile = EXPECTED_CLUSTER.slice(2).join("|")
+      const sequences = alternatives.map((sequence) => sequence.join("|"))
+      if (!sequences.includes(desktop) || sequences.some((sequence) => sequence !== desktop && sequence !== mobile)) context.report({ node, messageId: "cluster" })
+    } }
+  },
+}
+
+/** Creation belongs to its page, never to the global app bar. */
+export const noNavbarCreate = {
+  meta: meta("FE_NAVBAR_CREATE", "FE-APP-SHELL-5 keeps create actions on pages.", {
+    create: "FE_NAVBAR_CREATE: move this create action from the navbar to its page.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const reported = new Set()
+    const report = (node) => {
+      if (reported.has(node)) return
+      reported.add(node)
+      context.report({ node, messageId: "create" })
+    }
+    const inspect = (control, name) => {
+      if (name === "DropdownMenu" || name === "Popover") {
+        if (["entries", "items", "sections"].some((slot) => menuHasCreate(context, propOf(context, control, slot).value))) report(control)
+        visitVisible(context, propOf(context, control, "content").value, inspect)
+        for (const child of control.parent.children) visitVisible(context, child, inspect)
+      }
+      if (!isBarControl(context, control, name) || reported.has(control)) return
+      const text = `${semanticText(context, control)} ${control.parent.children.map((child) => context.sourceCode.getText(child)).join(" ")}`
+      if (isCreateAction(text)) report(control)
+    }
+    return { JSXOpeningElement(node) {
+      visitBar(context, node, inspect)
+    } }
+  },
+}
+
+/** Every app-shell enforcer is gathered into the ordinary FE lint and gate path. */
+export const rules = {
+  "app-shell-frame": appShellFrame,
+  "no-shell-bottom-tabs": noShellBottomTabs,
+  "navbar-control-size": navbarControlSize,
+  "navbar-cluster": navbarCluster,
+  "no-navbar-create": noNavbarCreate,
+}
+
+defineFamilyRules(rules, "knowledge/ui/composition/app-shell.yaml")
+
+/** Every rule is mandatory. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/docs/app-shell.md

@@ -0,0 +1,52 @@
+# App shell
+
+Owner: contexts/ui/composition.md
+
+The application composes `WorkspaceShell viewport="fixed"`. The `app-shell-frame` rule identifies
+workspace chrome from a fixed shell, sidebar/navigation slot, workspace identity, HFS layout owner,
+or a shell owner combining a bar and sidebar. It rejects hand-written app-frame landmarks and
+workspace shells without the fixed viewport. Generic flow-based site chrome stays in its own scope.
+`no-shell-bottom-tabs` rejects bottom navigation components and the shell's `compactNavigation` slot.
+
+The `navbar-cluster` rule reads the visible `TopBar` or `NavigationFeatureNav` actions in source order:
+tertiary Language `IconButton` triggering `DropdownMenu`, theme `Switch`, notification `IconButton`
+triggering `Popover`, account `AvatarButton` triggering `DropdownMenu`. It follows
+local JSX constants and components, constant object members, imported Grammar aliases, and namespace imports. Translated
+labels may be dynamic; icon sources identify language and notifications. Menu contents and popover
+content belong to their overlays and are outside the bar's control sequence. Conditional render
+branches are checked separately. Grammar `TopBar` and `NavigationFeatureNav` compositions are app
+bars by default. A proven `WorkspaceShell viewport="flow"` with no workspace/sidebar evidence owns
+generic site chrome. A shell hosting an imported navbar delegates only after its owned public
+export and rendered Base chain prove a `TopBar` or `NavigationFeatureNav` in every alternative.
+Workspace exports resolve back to source. Raw or unknown imported headers are red; the actual
+bar's own actions are checked where composed. Each lint source snapshot has fresh dependency proofs.
+
+`navbar-control-size` requires `size="control"` on each bar control. Unknown trailing prop spreads
+cannot prove a size; put the explicit size after a spread. A left `Drawer` containing
+`Sidebar presentation="drawer"` also identifies a mobile bar opener when composed in a separate
+client owner. Its trigger is checked; drawer bodies and footers retain their normal field sizes.
+`no-navbar-create` places creation on its
+own page and rejects create controls in the navbar and its attached menus or popovers. Static
+evidence includes literal labels, translated keys with create semantics, and conventional create
+handlers. Runtime-generated labels and arbitrary handler behavior need semantic review; the rule
+does not execute application code.
+
+| Rule | Invalid composition | Valid composition |
+| --- | --- | --- |
+| `app-shell-frame` | An app `Shell` returns a hand-written `<header>` and `<nav>`. | `WorkspaceShell viewport="fixed"` owns the app frame. |
+| `no-shell-bottom-tabs` | The shell supplies `compactNavigation={<BottomNav />}`. | The shell supplies `navigationDrawer` with a drawer `Sidebar`. |
+| `navbar-control-size` | A navbar `IconButton` uses `size="md"`. | The same control uses `size="control"`. |
+| `navbar-cluster` | Account precedes notifications, or a language trigger uses a regular `Button`. | Language menu, theme switch, notification popover, account menu use their stated Grammar trigger kinds in that order. |
+| `no-navbar-create` | A navbar button or attached menu item creates a record. | The page owns its create action. |
+
+```tsx
+// Invalid: the navbar action creates a page record and has a different height.
+<TopBar actions={<Button onPress={on.create}>Create</Button>} />
+
+// Valid: a page action belongs to page content.
+<SurfaceCard><Button onPress={on.create}>Create</Button></SurfaceCard>
+```
+
+All five rules are errors in the gathered FE canon and run through the ordinary application gate.
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/docs/grammar-boundary.md

@@ -0,0 +1,37 @@
+# Grammar boundary
+
+Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element).
+
+Page structure and text are composed from `@starci/grammar` (or the repository's `<family>-ui` package), not drawn as raw HTML.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline.
+
+## `starci-grammar/no-raw-structural-element`
+
+Page structure and text are grammar components, not raw `div`-family HTML; only `fe.package.ui` renderers draw raw tags.
+
+Applies to app source that composes the grammar (slots `fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and to every workspace package except the `<family>-ui` package (`fe.package.ui`), whose components are the renderers. Spec files render raw HTML as a harness and are not judged; a file no slot owns is not judged.
+
+The refused tags are exactly those `@starci/grammar` has a component for (the twin test reads the package source): `h1-h6` (`Heading`), `p` and `span` (`Text`), `hr` (`Divider`), `label` (`Label`), `form` (`Form`), `fieldset` (`Fieldset`), `dl` `dt` `dd` (`DescriptionList`), `table` `thead` `tbody` `tr` `td` `th` (`DataTable`), `ul` `ol` `li` (`List` and `ListItem` for a plain semantic list, `SurfaceListCard`, `StaticStateRow`), `header` (`SectionHeader`, `TopBar`), `footer` (`Footer`), `nav` (`NavLandmark` for a named row of links, `Subnav`, `Breadcrumbs`, `NavigationFeatureNav`), `section` (`Region` for a named non-card region, `SurfaceCard`), `main` (`WorkspaceShell`), `figure` and `figcaption` (`MediaFrame`). `div`, `br`, `aside` and `article` are not refused: the grammar has no component for them.
+
+Native `<time>` remains available for an absolute timestamp. Live relative time and countdown labels use `RelativeTime` (the universal canon's `starci-fe/no-app-relative-clock`).
+
+**Invalid** (`src/features/pages/home/component.tsx`)
+
+```ts
+export const Home = () => <section><p>{t("intro")}</p></section>
+```
+
+**Valid** (`src/features/pages/home/component.tsx`)
+
+```ts
+export const Home = () => <SurfaceCard><Text>{t("intro")}</Text></SurfaceCard>
+```
+
+**Finding code:** `FE_NATIVE_FORM_CONTROL`
+
+**Why:** Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not written as raw HTML.
+
+**Fix:** Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if the grammar lacks one, add it to the grammar or the ui package instead of drawing it in place.
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/docs/status-colors.md

@@ -0,0 +1,34 @@
+# Status colours: text and icons take the soft pair
+
+Law module: `status-colors.mjs`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
+
+A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.mjs`, which is generated from the grammar with the stylelint vocabulary.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline.
+
+## `starci-grammar/status-text-uses-soft-foreground`
+
+No class that paints text, an icon or a text decoration with a solid status tone: `text-<tone>`, `fill-<tone>`, `stroke-<tone>`, `decoration-<tone>` (with any variant, opacity or `!`), read from `className`/`class`, from `cn()`/`clsx()` arguments, conditionals, arrays, constants and `classes` entries.
+
+**Invalid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="text-success" />
+<svg className={cn("size-4", ok && "fill-danger")} />
+```
+
+**Valid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="bg-success-soft text-success-soft-foreground" />
+<button className="bg-success text-success-foreground" />
+<div className="border-danger ring-2 ring-warning" />
+```
+
+**Finding code:** `FE_STYLE_TOKEN_ONLY`
+
+**Why:** `<file>` colours text or an icon with a solid status tone (`<what>`, for example `text-success`). A solid tone is a background colour; used as a text colour it reads below 4.5:1 on the page background.
+
+**Fix:** Change to the soft pair: `text-<tone>-soft-foreground` (with `bg-<tone>-soft` if it sits on a light background); solid tones are used only with `bg-<tone>` and `text-<tone>-foreground`.
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/drawing.mjs

@@ -0,0 +1,60 @@
+/** StarCi per-slot status composition, governed by FE-RULE-OWNERSHIP. */
+import { pureHalf } from "@starci/eslint-canon-fe/lib/drawing-scope.mjs"
+import { defineFamilyRules } from "./lib/rule-contract.mjs"
+
+// -- DRAWING-4 ----------------------------------------------------------------------------------
+
+/** Flags that are a slot's data status. */
+const STATUS_FLAG = /^(?:isLoading|isError|isForbidden|isPending|isValidating|isEmpty)$/
+
+/** The name a test expression reads, if it is a status flag. */
+const statusFlagOf = (node) => {
+  if (!node) return null
+  if (node.type === "UnaryExpression") return statusFlagOf(node.argument)
+  if (node.type === "ChainExpression") return statusFlagOf(node.expression)
+  if (node.type === "Identifier" && STATUS_FLAG.test(node.name)) return node.name
+  if (node.type === "MemberExpression" && node.property?.type === "Identifier" && STATUS_FLAG.test(node.property.name)) {
+    return node.property.name
+  }
+  if (node.type === "LogicalExpression" || node.type === "BinaryExpression") return statusFlagOf(node.left) ?? statusFlagOf(node.right)
+  return null
+}
+
+/** A block's pure half never branches on a data status itself. */
+export const slotStatusThroughSlotView = {
+  meta: {
+    type: "problem",
+    docs: { description: "A block's pure half renders data status through `SlotView`, never its own branch." },
+    schema: [],
+    messages: {
+      branch:
+        "This branches on `{{flag}}` by hand. Every slot renders its status through `SlotView`, the one recipe: a second branch drifts from it and becomes one more variant somebody draws.",
+    },
+  },
+  create(context) {
+    if (pureHalf(context) !== "blocks") return {}
+    const check = (node, test) => {
+      const flag = statusFlagOf(test)
+      if (flag) context.report({ node, messageId: "branch", data: { flag } })
+    }
+    return {
+      ConditionalExpression(node) {
+        check(node, node.test)
+      },
+      IfStatement(node) {
+        check(node, node.test)
+      },
+      LogicalExpression(node) {
+        if (node.operator === "&&" && node.parent?.type === "JSXExpressionContainer") check(node, node.left)
+      },
+    }
+  },
+}
+
+/** The family status recipe retains its published rule ID. */
+export const rules = { "slot-status-through-slotview": slotStatusThroughSlotView }
+
+defineFamilyRules(rules, "knowledge/grammars/core/playbook.yaml#state-recipes")
+
+/** Every family composition rule is mandatory. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))

package/grammar-boundary.mjs

@@ -0,0 +1,94 @@
+import { defineFamilyRules } from "./lib/rule-contract.mjs"
+/**
+ * The boundary between product code and `@starci/grammar`.
+ *
+ * Grammar is a business-neutral HeroUI-backed component package. Product code composes its components with ordinary React
+ * children and typed props. A page's structure and text are made of those components, not of raw HTML: a raw `<section>`, `<p>`
+ * or `<ul>` carries no density, no focus or landmark contract and no dark value from the design system, and the class names
+ * written by hand to compensate are where a second visual language starts.
+ *
+ * Which tags are refused is decided by the package: a tag is in the list only when `@starci/grammar` exports a component that
+ * renders it (`GRAMMAR_OWNERS` below, each entry verified against the package source by the twin test). A tag the grammar has no
+ * component for (`div`, `br`, `aside`, `article`) is not refused: there is nothing to compose instead, and refusing it would
+ * demand a workaround. When the grammar gains a component for one, the tag joins the list.
+ *
+ * WHERE IT APPLIES. App source that composes the grammar (slots `fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and any
+ * workspace package except the `<family>-ui` package (`fe.package.ui`), whose components are the renderers and are the one place
+ * a raw tag belongs. Spec files render raw HTML as a harness and are not judged. A file no slot owns is not judged either: the
+ * rule refuses to guess a scope.
+ */
+
+import { hfsOf } from "@starci/eslint-canon-fe/lib/hfs.mjs"
+
+/**
+ * The intrinsic elements of page structure and text, each with the grammar components that render it.
+ * Read against packages/grammar/src (`export const <Component>`); `grammar-boundary.spec.mjs` fails when one is not exported.
+ */
+export const GRAMMAR_OWNERS = Object.freeze({
+  h1: "Heading", h2: "Heading", h3: "Heading", h4: "Heading", h5: "Heading", h6: "Heading",
+  p: "Text", span: "Text",
+  hr: "Divider",
+  label: "Label",
+  form: "Form",
+  fieldset: "Fieldset",
+  dl: "DescriptionList", dt: "DescriptionList", dd: "DescriptionList",
+  table: "DataTable", thead: "DataTable", tbody: "DataTable", tr: "DataTable", td: "DataTable", th: "DataTable",
+  ul: "List, SurfaceListCard or StaticStateRow", ol: "List, SurfaceListCard or StaticStateRow", li: "ListItem, SurfaceListCard or StaticStateRow",
+  header: "SectionHeader or TopBar",
+  footer: "Footer",
+  nav: "NavLandmark, Subnav, Breadcrumbs or NavigationFeatureNav",
+  section: "Region or SurfaceCard",
+  main: "WorkspaceShell",
+  figure: "MediaFrame", figcaption: "MediaFrame",
+})
+
+/** The slots of app source that compose the grammar: features, components, routes and hooks. */
+const APP_SLOTS = new Set(["fe.feature", "fe.components", "fe.route", "fe.hooks"])
+
+/** The slot of the package whose leaves ARE the renderers: the only place raw structural tags belong. */
+const RENDERER_SLOT = "fe.package.ui"
+
+/**
+ * True for a file that composes the grammar: app source (`fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and any
+ * workspace package but the `<family>-ui` package, whose components are the renderers.
+ */
+const composesGrammar = (context, file) => {
+  const hfs = hfsOf(context)
+  const slot = hfs.slotOf(file)
+  if (slot === null || slot === RENDERER_SLOT) return false
+  return APP_SLOTS.has(slot) || hfs.tierOf(file) === "package"
+}
+
+/** No raw structural or text element in app source or in a package that composes the grammar. */
+export const noRawStructuralElement = {
+  meta: {
+    type: "problem",
+    docs: { description: "Page structure and text are grammar components, not raw `div`-family HTML; only `fe.package.ui` renderers draw raw tags." },
+    schema: [],
+    messages: {
+      raw:
+        "A raw `<{{tag}}>`. Page structure and text are composed from the grammar (`@starci/grammar`, or the repository's `<family>-ui` package): use {{owner}}. A raw tag brings none of the design system's density, landmark and state contract, and the class names written to make up for it start a second visual language. If the grammar cannot express this structure, add the component to the grammar or the ui package rather than drawing it here.",
+    },
+  },
+  create(context) {
+    const file = context.filename || context.getFilename()
+    if (!composesGrammar(context, file)) return {}
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier") return
+        const owner = Object.hasOwn(GRAMMAR_OWNERS, node.name.name) ? GRAMMAR_OWNERS[node.name.name] : null
+        if (owner !== null) context.report({ node, messageId: "raw", data: { tag: node.name.name, owner: `\`${owner}\`` } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-raw-structural-element": noRawStructuralElement,
+}
+
+defineFamilyRules(rules, "knowledge/patterns/fe/ui.yaml#FE-UI")
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]))