@estiva-app/ui 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "default": "./dist/eslint/index.js"
+    },
     "./tailwind-preset": "./tailwind-preset.js",
     "./tokens.css": "./tokens.css",
     "./package.json": "./package.json",

package/src/Avatar.tsx

@@ -118,7 +118,7 @@ export function Avatar({ src, name, alt = '', size = 36, label: spoken, classNam
           */
           className="w-full h-full flex items-center justify-center font-semibold leading-none"
           style={{
-            /* eslint-disable no-restricted-syntax -- the per-person palette (the note at
+            /* eslint-disable no-restricted-syntax -- @estiva-escape: the per-person palette (the note at
                the top): eight hues picked from the name, the one ink that reads on all
                of them, and a size that follows `size`. None of it can be a token. */
             // The one ink colour that reads on all eight hues, which are a

package/src/AvatarGroup.tsx

@@ -55,7 +55,7 @@ export function AvatarGroup({ members, size = 24 }: AvatarGroupProps) {
         <span
           key={i}
           className="relative flex rounded-sm"
-          /* eslint-disable-next-line no-restricted-syntax -- the ring's width is the `ring` prop, so it cannot be a class; its colour is the surface token */
+          /* eslint-disable-next-line no-restricted-syntax -- @estiva-escape: the ring's width is the `ring` prop, so it cannot be a class; its colour is the surface token */
           style={{ marginRight: -overlap, boxShadow: `0 0 0 ${ring}px var(--bg-surface)` }}
         >
           {/* Each face says whose it is: a stack stands on its own, with no

package/src/ChipInput.mdx

@@ -65,6 +65,15 @@ import { ChipInput } from '@estiva-app/ui'
 <ChipInput aria-labelledby="to-label" value={chosen} onChange={setChosen} options={directory} />
 ```
 
+- **`InputChip` on its own** names its ✕ `Remove <label>`. Where the ✕ does
+  something else, say what with `removeLabel` (a scope chip: "Leave Ship").
+- To cap a long label, give the chip a `max-w-*` and `truncate`: the label is
+  cut and the ✕ keeps its size. `truncate` is off unless asked, because
+  cutting clips a letter's soft edge by up to 4px at 1x even when the label
+  fits.
+
+<Canvas of={ChipInputStories.ALongLabelCut} />
+
 ## Keys
 
 | Input | What happens |

package/src/ChipInput.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { useState } from 'react'
+import { IconSquareRounded } from '@tabler/icons-react'
 import { Avatar } from './Avatar'
 import { ChipInput, InputChip, type ChipInputOption } from './ChipInput'
 
@@ -97,3 +98,20 @@ export const TheChipItself: Story = {
     </div>
   ),
 }
+
+/** A chip capped in width, its long label cut, and a ✕ named for what it does. */
+export const ALongLabelCut: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <InputChip
+        label="A label much longer than the chip may be"
+        leading={<IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />}
+        onRemove={() => {}}
+        removeLabel="Leave the label"
+        truncate
+        className="max-w-44"
+      />
+    </div>
+  ),
+}

package/src/ChipInput.test.tsx

@@ -215,4 +215,22 @@ describe('InputChip', () => {
     render(<InputChip label="Label" />)
     expect(screen.queryByRole('button')).toBeNull()
   })
+
+  it('names its ✕ with removeLabel when given', async () => {
+    const user = userEvent.setup()
+    const onRemove = vi.fn()
+    render(<InputChip label="Label" onRemove={onRemove} removeLabel="Leave Label" />)
+    await user.click(screen.getByRole('button', { name: 'Leave Label' }))
+    expect(onRemove).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('button', { name: 'Remove Label' })).toBeNull()
+  })
+
+  it('cuts its label only when asked, and then the ✕ never gives way', () => {
+    const { rerender } = render(<InputChip label="Label" onRemove={() => {}} />)
+    expect(screen.getByText('Label').className).not.toMatch(/\btruncate\b/)
+    expect(screen.getByRole('button').className).not.toMatch(/\bshrink-0\b/)
+    rerender(<InputChip label="Label" onRemove={() => {}} truncate className="max-w-[160px]" />)
+    expect(screen.getByText('Label').className).toMatch(/\bmin-w-0\b.*\btruncate\b/)
+    expect(screen.getByRole('button').className).toMatch(/\bshrink-0\b/)
+  })
 })

package/src/ChipInput.tsx

@@ -38,14 +38,27 @@ export interface InputChipProps {
   leading?: ReactNode
   /** Draws the ✕; absent, the chip is display-only. */
   onRemove?: () => void
+  /**
+   * The ✕'s name for a screen reader. `Remove <label>` when not given. A chip
+   * whose ✕ does something other than remove it names what it does — a
+   * launcher's scope chip leaves the scope ("Leave Ship").
+   */
+  removeLabel?: string
+  /**
+   * Cut a long label with an ellipsis once the chip is capped, by a
+   * `max-w-*` on `className`. Off unless asked: cutting clips up to 4px of a
+   * letter's soft edge at 1x even when the label fits (measured 2026-09-15),
+   * so a chip that is never capped keeps every pixel.
+   */
+  truncate?: boolean
   className?: string
 }
 
-export function InputChip({ label, leading, onRemove, className }: InputChipProps) {
+export function InputChip({ label, leading, onRemove, removeLabel, truncate, className }: InputChipProps) {
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>
       {leading && <span className="flex shrink-0 items-center">{leading}</span>}
-      <span className={CHIP_LABEL}>{label}</span>
+      <span className={cn(CHIP_LABEL, truncate && 'min-w-0 truncate')}>{label}</span>
       {/* Base UI's `Button`, as every button in the package is (D6). Base UI
           has no chip of its own — its only chips are `Combobox.Chip` and
           `ChipRemove`, which throw outside a combobox — so the ✕ is the one
@@ -57,8 +70,9 @@ export function InputChip({ label, leading, onRemove, className }: InputChipProp
             e.stopPropagation()
             onRemove()
           }}
-          className={CHIP_REMOVE}
-          aria-label={`Remove ${label}`}
+          // In a capped chip the label gives way, never the ✕.
+          className={cn(CHIP_REMOVE, truncate && 'shrink-0')}
+          aria-label={removeLabel ?? `Remove ${label}`}
         >
           <IconX size={10} stroke={1.5} />
         </BaseButton>

package/src/Select.test.tsx

@@ -32,6 +32,23 @@ function Controlled({ initial = 'todo', ...rest }: { initial?: string } & Partia
   return <Select value={value} onChange={setValue} options={STATUSES} ariaLabel="Status" {...rest} />
 }
 
+/**
+ * The open list, once it has focus.
+ *
+ * The list is findable as soon as it opens, but Base UI moves focus into it an
+ * animation frame later. A key pressed before that frame goes to the trigger:
+ * Tab then moves focus into the list instead of closing it, and an arrow or End
+ * is lost. A person presses keys at a list that has focus, so these tests wait
+ * for it. CI failed "Tab closes the list" this way on 15 September (PR #36);
+ * with every frame 100ms late the three tests that use this failed 3 runs of 3,
+ * focus measured still on the trigger when Tab was pressed.
+ */
+async function focusedList() {
+  const list = await screen.findByRole('listbox')
+  await waitFor(() => expect(list.contains(document.activeElement)).toBe(true))
+  return list
+}
+
 describe('Select', () => {
   it('is a button naming itself, showing the chosen label', () => {
     render(<Controlled initial="in_progress" />)
@@ -65,7 +82,7 @@ describe('Select', () => {
     const trigger = screen.getByRole('combobox', { name: 'Status' })
     trigger.focus()
     await user.keyboard('{ArrowDown}')
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     await user.keyboard('{ArrowDown}{Enter}')
     expect(onChange).toHaveBeenCalledWith('in_progress')
     expect(document.activeElement).toBe(trigger)
@@ -130,7 +147,7 @@ describe('Select', () => {
     render(<Controlled initial="in_progress" />)
     screen.getByRole('combobox', { name: 'Status' }).focus()
     await user.keyboard('{ArrowDown}')
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     const highlighted = () => screen.getAllByRole('option').find((o) => o.getAttribute('data-highlighted') !== null)?.textContent
     await user.keyboard('{End}')
     expect(highlighted()).toContain('Done')
@@ -142,7 +159,7 @@ describe('Select', () => {
     const user = userEvent.setup()
     render(<Controlled />)
     await user.click(screen.getByRole('combobox', { name: 'Status' }))
-    expect(await screen.findByRole('listbox')).toBeTruthy()
+    expect(await focusedList()).toBeTruthy()
     await user.tab()
     await waitFor(() => expect(screen.queryByRole('listbox')).toBeNull())
   })

package/src/eslint/escape.ts

@@ -0,0 +1,112 @@
+import type { AST, Rule } from 'eslint'
+
+/**
+ * The escape marker (UIG-3, seam S4 in docs/GATES.md §16): one written reason
+ * why one element stays as it is.
+ *
+ * A line comment directly above the element,
+ *
+ *     // @estiva-escape: <reason>
+ *
+ * or, where the element is a JSX child, the JSX comment on the line above,
+ *
+ *     {/* @estiva-escape: <reason> *\/}
+ *
+ * with at least ten characters of reason, spaces not counted.
+ *
+ * Not `eslint-disable`. A directive switches a rule off without saying it was
+ * meant, and the count of escapes (`.gates-count.json`) could not see it. A
+ * marker written inside a directive that switches one of these rules off is
+ * reported for that reason.
+ *
+ * The token lint's older notes (`eslint-disable-next-line <rule> -- @estiva-escape:
+ * <reason>`, Katerina's ruling A2 of 15 September) are not read here: they
+ * escape the token lint's rules, which are not this plugin's, and they stay as
+ * they are (Katerina, 15 September).
+ */
+export const ESCAPE_MARKER = '@estiva-escape'
+
+/** Characters of reason, spaces not counted. */
+export const MIN_REASON = 10
+
+/** The key under ESLint's `settings` this plugin reads. */
+export const SETTINGS_KEY = 'estiva'
+
+/**
+ * Every rule spreads these into its `meta.messages`, because `isEscaped`
+ * reports through the rule that called it.
+ */
+export const ESCAPE_MESSAGES = {
+  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}: <why this stays>\`. An escape with no reason hides nothing.`,
+  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}: <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escaped: 'Escaped: {{reason}}',
+} as const
+
+export interface EstivaSettings {
+  /**
+   * Report every sanctioned escape as a message with the id `escaped`, so a
+   * count can read them. Off in the lint anyone runs; on only in the count.
+   */
+  reportEscapes?: boolean
+}
+
+interface Located {
+  loc?: AST.SourceLocation | null
+  range?: [number, number]
+}
+
+const DIRECTIVE = /^\s*eslint-disable(?:-next-line|-line)?(?=\s|$)([^]*)$/
+
+/** The rules a directive names: what comes before its ` -- ` description. None means every rule. */
+function directiveRules(rest: string): string[] {
+  const dashes = rest.search(/(?:^|\s)--(?:\s|$)/)
+  return (dashes === -1 ? rest : rest.slice(0, dashes)).split(/[\s,]+/).filter(Boolean)
+}
+
+/** Only spaces and a JSX expression's closing brace between the marker and the element. */
+const BETWEEN = /^[\s}]*$/
+
+/**
+ * Whether the element at `node` carries a valid escape on the line above.
+ *
+ * Every rule of this plugin calls it before it reports. It reports, through
+ * that rule, a marker with too short a reason and a marker inside an
+ * eslint-disable directive for this rule; either way the element is not
+ * escaped, so the rule reports it too.
+ */
+export function isEscaped(context: Rule.RuleContext, node: Located): boolean {
+  const { sourceCode } = context
+  if (!node.loc || !node.range) return false
+  const line = node.loc.start.line
+  const nodeStart = node.range[0]
+
+  const comment = sourceCode
+    .getAllComments()
+    .find((c) => c.loc && c.range && c.loc.end.line === line - 1 && BETWEEN.test(sourceCode.text.slice(c.range[1], nodeStart)))
+  if (!comment?.loc) return false
+
+  const at = comment.value.indexOf(ESCAPE_MARKER)
+  if (at === -1) return false
+
+  const directive = DIRECTIVE.exec(comment.value)
+  if (directive) {
+    const rules = directiveRules(directive[1])
+    // A directive for other rules (the token lint's notes) is not an escape of this one.
+    if (rules.length > 0 && !rules.includes(context.id)) return false
+    context.report({ loc: comment.loc, messageId: 'escapeInDirective' })
+    return false
+  }
+
+  const reason = comment.value
+    .slice(at + ESCAPE_MARKER.length)
+    .replace(/^:/, '')
+    .trim()
+  if (reason.replace(/\s/g, '').length < MIN_REASON) {
+    context.report({ loc: comment.loc, messageId: 'escapeWithoutReason' })
+    return false
+  }
+
+  const settings = context.settings[SETTINGS_KEY] as EstivaSettings | undefined
+  if (settings?.reportEscapes) context.report({ loc: comment.loc, messageId: 'escaped', data: { reason } })
+  return true
+}

package/src/eslint/index.test.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs'
+import { ESLint, type Linter } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import estiva, { countGates, PLUGIN_KEY } from './index'
+
+/**
+ * The plugin as an app uses it: a flat config with `configs.recommended`,
+ * linting text the way Peek's editor hook does (`lintText`). The rule's own
+ * cases are in no-raw-button.test.ts.
+ */
+const tsx: Linter.Config = {
+  files: ['**/*.tsx'],
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+}
+
+async function lint(code: string, extra: Linter.Config[] = []) {
+  const eslint = new ESLint({
+    cwd: process.cwd(),
+    overrideConfigFile: true,
+    overrideConfig: [tsx, estiva.configs.recommended, ...extra],
+  })
+  return eslint.lintText(code, { filePath: 'src/Probe.tsx' })
+}
+
+const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
+const countMode: Linter.Config = { settings: { estiva: { reportEscapes: true } } }
+
+describe('the plugin object', () => {
+  it('names itself and carries the package version', () => {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+    expect(estiva.meta).toEqual({ name: '@estiva-app/ui/eslint', version: pkg.version })
+  })
+
+  it('has no-raw-button, and both configs switch it on as an error under estiva/', () => {
+    expect(Object.keys(estiva.rules)).toEqual(['no-raw-button'])
+    for (const config of [estiva.configs.recommended, estiva.configs.strict]) {
+      expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
+      expect(config.rules).toEqual({ 'estiva/no-raw-button': 'error' })
+    }
+  })
+})
+
+describe('an app lint with configs.recommended', () => {
+  it('reports a raw <button>, naming Button', async () => {
+    const [result] = await lint(component('    <button type="button">x</button>'))
+    expect(result.messages.map((m) => [m.ruleId, m.severity, m.message])).toEqual([
+      ['estiva/no-raw-button', 2, 'Use `Button` from @estiva-app/ui instead of a raw <button>.'],
+    ])
+  })
+
+  it('passes the same element under an escape', async () => {
+    const [result] = await lint(component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'))
+    expect(result.messages).toEqual([])
+  })
+})
+
+describe('countGates', () => {
+  it('counts an error, and an escape only when the lint reports escapes', async () => {
+    const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
+    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-button': { errors: 1, warnings: 0, escapes: 0 } })
+    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-button': { errors: 1, warnings: 0, escapes: 1 } })
+  })
+
+  it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
+    const results = await lint(component('    // eslint-disable-next-line estiva/no-raw-button\n    <button>x</button>'), [countMode])
+    const count = countGates(results)
+    expect(count.rules['estiva/no-raw-button']).toEqual({ errors: 0, warnings: 0, escapes: 0 })
+    expect(count.disabled).toEqual([{ filePath: results[0].filePath, line: 4, ruleId: 'estiva/no-raw-button' }])
+  })
+
+  it('counts a marker inside that directive as an error of the rule', async () => {
+    const results = await lint(component('    // eslint-disable-next-line estiva/no-raw-button -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'), [countMode])
+    const count = countGates(results)
+    expect(count.rules['estiva/no-raw-button']).toEqual({ errors: 1, warnings: 0, escapes: 0 })
+    expect(count.disabled).toHaveLength(1)
+  })
+
+  it('lists every rule of the plugin, even with nothing found', () => {
+    expect(countGates([])).toEqual({ rules: { 'estiva/no-raw-button': { errors: 0, warnings: 0, escapes: 0 } }, disabled: [] })
+  })
+})

package/src/eslint/index.ts

@@ -0,0 +1,100 @@
+/// <reference types="node" />
+/**
+ * `@estiva-app/ui/eslint` — the UI Guardrails' lint rules, as a plugin (UIG-3,
+ * seam S1 in docs/GATES.md §16).
+ *
+ * A plugin rather than config, so every app — Peek, Ship, Leaf — gets a new
+ * rule through an ordinary version bump, and an app's editor hook runs the
+ * very rule code its CI runs.
+ *
+ *     import estiva from '@estiva-app/ui/eslint'
+ *     export default [{ files: ['src/**\/*.tsx'], ...estiva.configs.recommended }]
+ *
+ * Register it under `estiva` (the configs do): the rule ids are
+ * `estiva/<rule>`, and `countGates` counts those ids.
+ *
+ * Built on its own by build.mjs, for Node, into `dist/eslint/`; nothing here
+ * reaches the components' browser bundle.
+ */
+import { createRequire } from 'node:module'
+import type { ESLint, Linter } from 'eslint'
+import { noRawButton } from './no-raw-button'
+
+export { ESCAPE_MARKER, MIN_REASON, SETTINGS_KEY, isEscaped, type EstivaSettings } from './escape'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+/** The name the configs register the plugin under, so every rule id is `estiva/<rule>`. */
+export const PLUGIN_KEY = 'estiva'
+
+const rules = {
+  'no-raw-button': noRawButton,
+}
+
+const plugin = {
+  meta: { name: '@estiva-app/ui/eslint', version },
+  rules,
+  configs: {} as { recommended: Linter.Config; strict: Linter.Config },
+} satisfies ESLint.Plugin
+
+const ruleIds = Object.keys(rules).map((name) => `${PLUGIN_KEY}/${name}`)
+
+/**
+ * `recommended` switches every rule on at the level it was ruled at: an error
+ * blocks, a warning is reported and never blocks. `strict` makes every rule an
+ * error. With one rule, an error, the two are the same today; they part when
+ * the first warning-level rule arrives (UIG-25).
+ */
+plugin.configs.recommended = {
+  name: '@estiva-app/ui/recommended',
+  plugins: { [PLUGIN_KEY]: plugin },
+  rules: { [`${PLUGIN_KEY}/no-raw-button`]: 'error' },
+}
+plugin.configs.strict = {
+  name: '@estiva-app/ui/strict',
+  plugins: { [PLUGIN_KEY]: plugin },
+  rules: Object.fromEntries(ruleIds.map((id) => [id, 'error'])),
+}
+
+export default plugin
+
+export interface GateRuleCount {
+  errors: number
+  warnings: number
+  escapes: number
+}
+
+export interface GateCount {
+  /** Per rule id, including rules with nothing to report. */
+  rules: Record<string, GateRuleCount>
+  /**
+   * Reports of these rules that an `eslint-disable` directive silenced. Not
+   * an escape: a gate fails on any of these (docs/GATES.md §16, S4).
+   */
+  disabled: { filePath: string; line: number; ruleId: string }[]
+}
+
+/**
+ * Count what a lint of these rules found, for `.gates-count.json` (seam S3).
+ *
+ * Run the lint with `settings: { estiva: { reportEscapes: true } }` for the
+ * escapes to be counted; without it they are silent and count 0. A marker
+ * with no reason, or inside a directive, counts as an error of its rule.
+ */
+export function countGates(results: ESLint.LintResult[]): GateCount {
+  const counts: Record<string, GateRuleCount> = Object.fromEntries(ruleIds.map((id) => [id, { errors: 0, warnings: 0, escapes: 0 }]))
+  const disabled: GateCount['disabled'] = []
+  for (const result of results) {
+    for (const message of result.messages) {
+      const count = message.ruleId ? counts[message.ruleId] : undefined
+      if (!count) continue
+      if (message.messageId === 'escaped') count.escapes += 1
+      else if (message.severity === 2) count.errors += 1
+      else count.warnings += 1
+    }
+    for (const message of result.suppressedMessages ?? []) {
+      if (message.ruleId && counts[message.ruleId]) disabled.push({ filePath: result.filePath, line: message.line, ruleId: message.ruleId })
+    }
+  }
+  return { rules: counts, disabled }
+}

package/src/eslint/no-raw-button.test.ts

@@ -0,0 +1,118 @@
+import { RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, it } from 'vitest'
+import { noRawButton } from './no-raw-button'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  // A directive for a rule these cases do not load is not what they test.
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
+
+tester.run('no-raw-button', noRawButton, {
+  valid: [
+    { name: "the package's Button", code: component('<Button>Save</Button>') },
+    { name: 'a member expression named button', code: component('<Foo.button>Save</Foo.button>') },
+    { name: 'a name that starts with button', code: component('<buttonish />') },
+    {
+      name: 'a line comment escape directly above',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button type="button">x</button>'),
+    },
+    {
+      name: 'a JSX comment escape on the line above a child',
+      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button type="button">x</button>\n    </div>'),
+    },
+    {
+      name: 'a JSX comment escape over several lines',
+      code: component('    <div>\n      {/*\n        @estiva-escape: a preview drawn from its own palette\n      */}\n      <button type="button">x</button>\n    </div>'),
+    },
+    {
+      name: 'an escape above an opening tag that spans lines',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button\n      type="button"\n      onClick={() => {}}\n    >\n      x\n    </button>'),
+    },
+    {
+      name: 'exactly ten characters of reason, spaces not counted',
+      code: component('    // @estiva-escape: ab cd ef gh ij\n    <button>x</button>'),
+    },
+  ],
+  invalid: [
+    { name: 'a raw button', code: component('    <button type="button">x</button>'), errors: [{ messageId: 'raw', line: 3 }] },
+    { name: 'a self-closing raw button', code: component('    <button />'), errors: [{ messageId: 'raw' }] },
+    {
+      name: 'an opening tag that spans lines (what grep misses)',
+      code: component('    <button\n      type="button"\n    >\n      x\n    </button>'),
+      errors: [{ messageId: 'raw', line: 3 }],
+    },
+    {
+      name: 'a raw button nested in other elements',
+      code: component('    <div>\n      <span>\n        <button>x</button>\n      </span>\n    </div>'),
+      errors: [{ messageId: 'raw', line: 5 }],
+    },
+    {
+      name: 'the message names the component',
+      code: component('    <button>x</button>'),
+      errors: [{ message: 'Use `Button` from @estiva-app/ui instead of a raw <button>.' }],
+    },
+    {
+      name: 'an escape with no reason is an error, and hides nothing',
+      code: component('    // @estiva-escape:\n    <button>x</button>'),
+      errors: [
+        { messageId: 'escapeWithoutReason', line: 3 },
+        { messageId: 'raw', line: 4 },
+      ],
+    },
+    {
+      name: 'nine characters of reason is too short',
+      code: component('    <div>\n      {/* @estiva-escape: ab cd ef gh i */}\n      <button>x</button>\n    </div>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
+    },
+    {
+      name: 'a marker with no colon and no reason',
+      code: component('    // @estiva-escape\n    <button>x</button>'),
+      errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'raw' }],
+    },
+    {
+      name: 'an escape two lines above does not reach the element',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 5 }],
+    },
+    {
+      name: 'an escape above a sibling does not reach the next element',
+      code: component('    <div>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <span />\n      <button>x</button>\n    </div>'),
+      errors: [{ messageId: 'raw', line: 6 }],
+    },
+    {
+      name: 'a free comment is not an escape',
+      code: component('    // a raw button, on purpose\n    <button>x</button>'),
+      errors: [{ messageId: 'raw' }],
+    },
+    {
+      name: 'a marker inside a directive that switches every rule off is refused',
+      code: component('    // eslint-disable-next-line -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      // The directive silences the element's own report; the refusal sits on the directive's line.
+      errors: [{ messageId: 'escapeInDirective', line: 3 }],
+    },
+    {
+      name: 'a marker inside a directive that names this rule is refused',
+      code: component('    // eslint-disable-next-line rule-to-test/no-raw-button -- @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      errors: [{ messageId: 'escapeInDirective', line: 3 }],
+    },
+    {
+      name: "the token lint's note for another rule is not an escape of this one",
+      code: component('    // eslint-disable-next-line no-console -- @estiva-escape: its hand-written type waits for that\n    <button>x</button>'),
+      errors: [{ messageId: 'raw', line: 4 }],
+    },
+    {
+      name: 'with reportEscapes on, a sanctioned escape is reported for the count',
+      code: component('    // @estiva-escape: a preview drawn from its own palette\n    <button>x</button>'),
+      settings: { estiva: { reportEscapes: true } },
+      errors: [{ messageId: 'escaped', data: { reason: 'a preview drawn from its own palette' }, line: 3 }],
+    },
+  ],
+})

package/src/eslint/no-raw-button.ts

@@ -0,0 +1,39 @@
+import type { Rule } from 'eslint'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+
+interface JSXOpeningElement {
+  name: { type: string; name?: string }
+  loc: NonNullable<Rule.Node['loc']>
+  range: [number, number]
+}
+
+/**
+ * A raw `<button>` in an app (UIG-3, the tracer). The package's `Button`,
+ * `IconButton`, `MenuItem` and chips are buttons already; an app that writes
+ * its own has a look and a behaviour nobody else keeps in step with.
+ *
+ * Only the JSX element named `button`. `<Button>`, `<Foo.button>` and
+ * `createElement('button')` are not this rule's business.
+ */
+export const noRawButton: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'A raw <button> where @estiva-app/ui has one' },
+    schema: [],
+    messages: {
+      raw: 'Use `Button` from @estiva-app/ui instead of a raw <button>.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    return {
+      // ESLint's types know ESTree's nodes, not JSX's; the parser hands this one over.
+      JSXOpeningElement(node: Rule.Node) {
+        const element = node as unknown as JSXOpeningElement
+        if (element.name.type !== 'JSXIdentifier' || element.name.name !== 'button') return
+        if (isEscaped(context, element)) return
+        context.report({ loc: element.loc, messageId: 'raw' })
+      },
+    }
+  },
+}

package/stories/TokensPage.tsx

@@ -172,7 +172,7 @@ function Users({ names }: { names: string[] }) {
 function SwatchBox({ token }: { token: Token }) {
   const v = `var(${token.cssVar})`
   const base = 'h-6 w-10 shrink-0 rounded-md'
-  /* eslint-disable no-restricted-syntax -- this page draws every token from its CSS
+  /* eslint-disable no-restricted-syntax -- @estiva-escape: this page draws every token from its CSS
      variable, so a swatch shows the value the theme holds, including a token no
      class spells yet. */
   switch (token.swatch) {