@estiva-app/ui 0.26.0 → 0.28.0

package/src/MenuItem.stories.tsx

@@ -1,135 +1,151 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconCopy, IconPin, IconTrash } from '@tabler/icons-react'
-import { Avatar } from './Avatar'
-import { useRef, useState } from 'react'
-import { Button } from './Button'
-import { Divider } from './Divider'
-import { EnterHint, Menu, MenuItem, MenuPanel, MenuSub } from './Menu'
-
-/**
- * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
- * with an optional `description` line · one thing at the right edge —
- * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
- * chevron. Stories sit on a `MenuPanel` — the menu's surface, drawn without
- * its behaviour — so the row is seen where it lives. A live menu portals and
- * places itself, so it cannot stand in the page (Katerina, D25); **Menu →
- * FromATrigger** is where the keyboard and the placement are.
- */
-const meta = {
-  title: 'Overlays/MenuItem',
-  component: MenuItem,
-  decorators: [
-    (Story) => (
-      <div className="flex min-h-[120px] w-full items-center justify-center">
-        <MenuPanel className="w-72">
-          <Story />
-        </MenuPanel>
-      </div>
-    ),
-  ],
-  args: { label: 'Rename', onClick: () => {} },
-  argTypes: {
-    onClick: { control: false },
-    leading: { control: false },
-    trailing: { control: false },
-  },
-} satisfies Meta<typeof MenuItem>
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-export const Default: Story = {}
-
-export const WithAnIcon: Story = {
-  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
-}
-
-export const WithAShortcut: Story = {
-  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
-}
-
-/** The row opens another menu. */
-export const Submenu: Story = {
-  args: { label: 'Move to…', submenu: true },
-}
-
-/**
- * The submenu, working. The story above draws the row at rest — the chevron is
- * the whole affordance — but a row that opens another menu can only be tried
- * inside a real one, so here is one.
- *
- * Hover **Move to…**, or arrow onto it and press →. The panel opens beside the
- * row, flips to the other side at a screen edge, and stays open while you
- * cross the diagonal into it.
- *
- * From the keyboard: → opens it and leaves the highlight on the row, ↓ steps
- * into it, and ← closes it and puts the highlight back on the row. Measured in
- * that order — → then ← alone does nothing, because focus has not entered yet.
- */
-export const SubmenuLive: Story = {
-  parameters: { controls: { disable: true } },
-  decorators: [(Story) => <Story />],
-  render: () => (
-    <div className="flex min-h-[220px] w-full items-start justify-center pt-4">
-      <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
-        <MenuItem label="Rename" onClick={() => {}} />
-        <MenuSub label="Move to…">
-          <MenuItem label="Item one" onClick={() => {}} />
-          <MenuItem label="Item two" onClick={() => {}} />
-          <MenuItem label="Item three" onClick={() => {}} />
-        </MenuSub>
-        <Divider className="my-1" />
-        <MenuItem label="Delete" destructive onClick={() => {}} />
-      </Menu>
-    </div>
-  ),
-}
-
-/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
-export const APerson: Story = {
-  args: {
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    trailing: <EnterHint />,
-  },
-}
-
-/** The submenu's chosen value. */
-export const Selected: Story = {
-  args: { label: 'Item one', selected: true },
-}
-
-export const Destructive: Story = {
-  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
-}
-
-/** Every shape on one canvas. */
-export const AllVariants: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <>
-      <MenuItem label="Bare" onClick={() => {}} />
-      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
-      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
-      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
-      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
-      <MenuItem label="The chosen value" selected onClick={() => {}} />
-      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
-      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
-    </>
-  ),
-}
-
-/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
-export const Tall: Story = {
-  args: {
-    size: 'tall',
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    selected: true,
-    trailing: <EnterHint />,
-  },
-}
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconCopy, IconHash, IconPin, IconTrash } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { useRef, useState } from 'react'
+import { Button } from './Button'
+import { Divider } from './Divider'
+import { EnterHint, Menu, MenuItem, MenuPanel, MenuSub } from './Menu'
+
+/**
+ * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
+ * with an optional `description` line · one thing at the right edge —
+ * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
+ * chevron. Stories sit on a `MenuPanel` — the menu's surface, drawn without
+ * its behaviour — so the row is seen where it lives. A live menu portals and
+ * places itself, so it cannot stand in the page (Katerina, D25); **Menu →
+ * FromATrigger** is where the keyboard and the placement are.
+ */
+const meta = {
+  title: 'Overlays/MenuItem',
+  component: MenuItem,
+  decorators: [
+    (Story) => (
+      <div className="flex min-h-[120px] w-full items-center justify-center">
+        <MenuPanel className="w-72">
+          <Story />
+        </MenuPanel>
+      </div>
+    ),
+  ],
+  args: { label: 'Rename', onClick: () => {} },
+  argTypes: {
+    onClick: { control: false },
+    leading: { control: false },
+    trailing: { control: false },
+  },
+} satisfies Meta<typeof MenuItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const WithAnIcon: Story = {
+  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
+}
+
+export const WithAShortcut: Story = {
+  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
+}
+
+/** The row opens another menu. */
+export const Submenu: Story = {
+  args: { label: 'Move to…', submenu: true },
+}
+
+/**
+ * The submenu, working. The story above draws the row at rest — the chevron is
+ * the whole affordance — but a row that opens another menu can only be tried
+ * inside a real one, so here is one.
+ *
+ * Hover **Move to…**, or arrow onto it and press →. The panel opens beside the
+ * row, flips to the other side at a screen edge, and stays open while you
+ * cross the diagonal into it.
+ *
+ * From the keyboard: → opens it and leaves the highlight on the row, ↓ steps
+ * into it, and ← closes it and puts the highlight back on the row. Measured in
+ * that order — → then ← alone does nothing, because focus has not entered yet.
+ */
+export const SubmenuLive: Story = {
+  parameters: { controls: { disable: true } },
+  decorators: [(Story) => <Story />],
+  render: () => (
+    <div className="flex min-h-[220px] w-full items-start justify-center pt-4">
+      <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
+        <MenuItem label="Rename" onClick={() => {}} />
+        <MenuSub label="Move to…">
+          <MenuItem label="Item one" onClick={() => {}} />
+          <MenuItem label="Item two" onClick={() => {}} />
+          <MenuItem label="Item three" onClick={() => {}} />
+        </MenuSub>
+        <Divider className="my-1" />
+        <MenuItem label="Delete" destructive onClick={() => {}} />
+      </Menu>
+    </div>
+  ),
+}
+
+/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
+export const APerson: Story = {
+  args: {
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    trailing: <EnterHint />,
+  },
+}
+
+/** The submenu's chosen value. */
+export const Selected: Story = {
+  args: { label: 'Item one', selected: true },
+}
+
+export const Destructive: Story = {
+  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
+}
+
+/** Every shape on one canvas. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <MenuItem label="Bare" onClick={() => {}} />
+      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
+      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
+      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
+      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
+      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
+      <MenuItem label="The chosen value" selected onClick={() => {}} />
+      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
+    </>
+  ),
+}
+
+/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
+export const Tall: Story = {
+  args: {
+    size: 'tall',
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    selected: true,
+    // `hint`, not `trailing`: shown only while the row is highlighted, on the fill's own timing.
+    hint: <EnterHint />,
+  },
+}
+
+/** A topic in the picker: `EnterHint`'s `target` says what Enter gives you, after the key. Hover another row and back to see the hint follow the highlight. */
+export const ATopic: Story = {
+  args: {
+    size: 'tall',
+    label: 'design',
+    description: '12 members',
+    leading: <IconHash size={16} stroke={1.5} className="text-text-secondary" />,
+    selected: true,
+    hint: <EnterHint target="#design" />,
+  },
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the
+  // target is muted text, 3.05:1 on a highlighted row in signal (AA 4.5:1).
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+}

package/src/Person.stories.tsx

@@ -13,6 +13,13 @@ type Story = StoryObj<typeof meta>
 
 export const Named: Story = {}
 
+/** With their picture — here an inline SVG, as Avatar's own story uses, so the story needs nothing from anywhere. */
+export const WithPicture: Story = {
+  args: {
+    picture: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="%2346c08a"/><circle cx="5" cy="4" r="2" fill="%23fff"/></svg>',
+  },
+}
+
 /** Nobody has published a name: the silhouette and the em dash, muted — the same mark a property with no value uses. */
 export const Unnamed: Story = {
   args: { name: undefined },

package/src/PersonTrigger.stories.tsx

@@ -14,6 +14,13 @@ type Story = StoryObj<typeof meta>
 /** The row shape — face · name · chevron on a 32px button, Ship's top bar. */
 export const Row: Story = {}
 
+/** The row with the person's picture — an inline SVG, as Avatar's own story uses. */
+export const RowWithPicture: Story = {
+  args: {
+    picture: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="%2346c08a"/><circle cx="5" cy="4" r="2" fill="%23fff"/></svg>',
+  },
+}
+
 /** While what it opens is open, the row holds its hover fill. */
 export const RowOpen: Story = {
   args: { open: true },

package/src/SectionHeader.stories.tsx

@@ -17,6 +17,11 @@ type Story = StoryObj<typeof meta>
 
 export const Plain: Story = {}
 
+/** `chevron`: the header of a section that folds. The title becomes the toggle, and the chevron turns with it. CollapsibleSection draws this for you. */
+export const Folding: Story = {
+  args: { chevron: true, isExpanded: true, onToggle: () => {} },
+}
+
 /** Actions beside the title, in the order given — revealed on hover or focus. */
 export const WithActions: Story = {
   args: {

package/src/gates/app-checks.ts

@@ -45,7 +45,7 @@ export const APP_TICKET_TITLES: Record<string, string> = {
   'UIG-9': 'Lint rule — the className allow-list',
   'UIG-10': 'create-app — a command that makes a new Estiva app that runs',
   'UIG-13': "The registry widens to Peek's 115 and Ship's 74, with classification",
-  'UIG-19': 'Lock the contract in CI, and make the three Storybooks one search',
+  'UIG-19': 'Lock the contract in CI',
   'UIG-20': 'The Claude skill, reading the registry',
   'UIG-21': 'CLAUDE.md becomes an index, not a lecture',
   'UIG-22': 'Fingerprint — a hand-made header row',
@@ -56,6 +56,7 @@ export const APP_TICKET_TITLES: Record<string, string> = {
   'UIG-28': 'Close the two holes in the token contract — arbitrary values, and inline style',
   'UIG-30': 'RichText — one component that draws a message\'s text, for both apps',
   'UIG-32': 'Peek and Ship take their gate pieces from the package',
+  'UIG-37': 'The gates refuse a TypeScript eslint-disable comment — know the rule names, rules off',
 }
 
 /** Run several checks as one: the first that does not pass is the answer. */
@@ -81,6 +82,8 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
   const installed = at('node_modules/@estiva-app/ui/dist/index.d.ts')
   const realPage = (): Promise<CheckResult> => h.lint({ ...(cwd ? { cwd } : {}), config: GATES, file: page, code: h.read(at(page)), expect: 'none' })
   const button = component('<button type="button">x</button>')
+  /** A line TypeScript's own lint writes; ESLint refuses it where TypeScript's plugin is unknown (UIG-37). */
+  const typescriptDirective = '// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const probe: any = 1\n'
   const ticket = (ref: string, checks: GateCheck[], owner = false): GateTicket => ({ ref, title: APP_TICKET_TITLES[ref], owner, checks })
 
   const tokenProbe = (code: string, expect: 'error' | 'warning' | 'none', mentions?: string, file = PROBE) =>
@@ -190,7 +193,11 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'every part is described and sorted, and every file is accounted for', run: () => h.catalogue(at('.')) },
     ]),
     ticket('UIG-19', [
-      { what: 'the usage-page contract runs in CI', run: () => h.ci(/[\w:-]*contract[\w:-]*/) },
+      // The contract runs inside `estiva-ui check`, which the gate job already runs
+      // (UIG-13), so an app changes no script: it takes the package that has it.
+      { what: 'the installed package checks the usage-page contract and the story links', run: () => h.contains(at('node_modules/@estiva-app/ui/dist/registry/cli.js'), 'the usage-page contract', "the installed estiva-ui check runs the contract") },
+      { what: "CI's job gate runs it", run: () => h.ciJob('gate', 'registry:check') },
+      { what: 'the app keeps no copy of it in its own gates-checks.mjs', run: () => h.exists(at('scripts/gates-checks.mjs')) ? h.lacks(at('scripts/gates-checks.mjs'), '"When not"', 'the app checks no page sections itself') : h.PASS('the app has no gates-checks.mjs') },
     ]),
     ticket('UIG-20', [
       { what: 'a committed skill runs ui:find', run: () => (h.listFiles('.claude/skills', (n) => n === 'SKILL.md').some((f) => h.read(f).includes('ui:find')) ? h.PASS('a skill runs ui:find') : h.FAIL('no skill in .claude/skills runs ui:find')) },
@@ -244,5 +251,15 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
         () => (h.exists('scripts/gates-status.mjs') ? h.FAIL('scripts/gates-status.mjs is a copy of the status engine: run estiva-gates status instead') : h.PASS('no copy of the status engine')),
       ], 'the gate config, the hook and gates:status are the package\'s; no copy of the engine') },
     ]),
+    ticket('UIG-37', [
+      { what: 'a TypeScript eslint-disable comment breaks neither the gate nor the token lint', run: all(h, [
+        probe(typescriptDirective, 'none'),
+        tokenProbe(typescriptDirective, 'none'),
+      ], `${[GATES, ...tokenConfigs].join(', ')}: a TypeScript directive is no error`) },
+      { what: 'a token lint on its own is the package\'s tokenConfig, not built by hand', run: () =>
+        (h.exists(at('eslint.tokens.config.js'))
+          ? h.contains(at('eslint.tokens.config.js'), /\btokenConfig\(/, 'eslint.tokens.config.js runs tokenConfig from @estiva-app/ui/gates')
+          : h.PASS('no token lint on its own')) },
+    ]),
   ]
 }

package/src/gates/create-app.ts

@@ -264,18 +264,13 @@ export default defineConfig([
   gateLint(),
 ])
 `,
-    'eslint.tokens.config.js': `import { TOKEN_LINT_IGNORES, tokenLint, tokenValues } from '@estiva-app/ui/gates'
+    'eslint.tokens.config.js': `import { tokenConfig } from '@estiva-app/ui/gates'
 import reactHooks from 'eslint-plugin-react-hooks'
-import { defineConfig, globalIgnores } from 'eslint/config'
 
-// The token contract on its own (\`npm run lint:tokens\`). React's hooks plugin is
-// registered with its rules off, so its directives in the source do not break it.
-export default defineConfig([
-  globalIgnores(TOKEN_LINT_IGNORES),
-  { plugins: { 'react-hooks': reactHooks }, linterOptions: { reportUnusedDisableDirectives: 'off' } },
-  tokenLint(),
-  tokenValues(),
-])
+// The token contract on its own (\`npm run lint:tokens\`), the package's piece.
+// React's hooks plugin is named so its directives do not break it; TypeScript's
+// the package names itself.
+export default tokenConfig({ quiet: { 'react-hooks': reactHooks } })
 `,
     'eslint.gates.config.js': `import { gateConfig } from '@estiva-app/ui/gates'
 import reactHooks from 'eslint-plugin-react-hooks'
@@ -284,7 +279,8 @@ import reactHooks from 'eslint-plugin-react-hooks'
  * The UI Guardrails' rules on their own — \`npm run lint:rules\`, CI's job \`gate\`
  * (GitHub requires it on main: never rename it), and what the editor hook in
  * \`.claude/settings.json\` lints a proposed write with. The package's gate,
- * imported. React's hooks plugin is named so its directives do not break it.
+ * imported. React's hooks plugin is named so its directives do not break it;
+ * TypeScript's the package names itself.
  *
  * A place that keeps something the gate refuses says why, on the line above:
  * \`// @estiva-escape: <reason>\`. Never \`eslint-disable\`: the count refuses it.

package/src/gates/gate-config.ts

@@ -20,7 +20,7 @@ import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { parser as typescriptParser } from 'typescript-eslint'
 import estiva from '../eslint/index'
-import { TOKEN_LINT_IGNORES } from './token-lint'
+import { KNOWN_PLUGINS, TOKEN_LINT_IGNORES } from './token-lint'
 
 export interface GateConfigOptions {
   /** `app` (the default) runs `configs.recommended`; `package` runs this package's inward set. */
@@ -29,7 +29,7 @@ export interface GateConfigOptions {
    * Plugins whose `eslint-disable` directives appear in the source, registered
    * here with every rule off. ESLint refuses a directive for a rule it does not
    * know, so without them the gate would fail on another lint's comments.
-   * The token lint's names are registered already.
+   * The token lint's names and TypeScript's are registered already (UIG-37).
    */
   quiet?: Record<string, ESLint.Plugin>
   /** Folders the gate never reads, beside build output. */
@@ -63,6 +63,7 @@ export function gateConfig({ audience = 'app', quiet = {}, ignores = [] }: GateC
     { ignores: [...TOKEN_LINT_IGNORES, ...ignores] },
     {
       plugins: {
+        ...KNOWN_PLUGINS,
         ...quiet,
         'better-tailwindcss': betterTailwindcss,
         'token-values': betterTailwindcss,

package/src/gates/gates.test.ts

@@ -7,7 +7,7 @@ import { writeGateCount } from './count'
 import { gateConfig, gateLint } from './gate-config'
 import { runHook } from './hook'
 import { helpers, runStatus } from './status'
-import { tokenLint, tokenValues } from './token-lint'
+import { tokenConfig, tokenLint, tokenValues } from './token-lint'
 
 /**
  * The gate pieces, as an app and this package use them (UIG-10, docs/GATES.md
@@ -44,6 +44,8 @@ async function lintWith(config: Linter.Config[], code: string, filePath: string)
 }
 
 const component = (body: string) => `export function Probe() {\n  return ${body}\n}\n`
+/** A line TypeScript's own lint writes: Peek PR #324 failed the token lint on it (UIG-37). */
+const typescriptDirective = '// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const probe: any = 1\n'
 
 describe('tokenLint and tokenValues', () => {
   it('refuse a hand-written text size and name the token, in the words for an app', async () => {
@@ -98,6 +100,38 @@ describe('gateConfig', () => {
     const directive = `// eslint-disable-next-line house/some-rule\n${component('<div>x</div>')}`
     expect(await lintWith(gateConfig({ quiet: { house: quiet } }), directive, 'src/Probe.tsx')).toEqual([])
   })
+
+  it("knows TypeScript's rule names, so a TypeScript directive does not break the gate (UIG-37)", async () => {
+    expect(await lintWith(gateConfig(), typescriptDirective, 'src/lib/probe.ts')).toEqual([])
+    // An app that names the plugin itself, from its own copy, still loads: its copy wins.
+    const own = { rules: { 'no-explicit-any': { create: () => ({}) } } }
+    expect(await lintWith(gateConfig({ quiet: { '@typescript-eslint': own } }), typescriptDirective, 'src/lib/probe.ts')).toEqual([])
+  })
+})
+
+describe('tokenConfig', () => {
+  it('runs the token contract on its own: the same messages as the two pieces, for an app and for the package', async () => {
+    const code = component('<div className="bg-gray-100 rounded-[3px]">x</div>')
+    const app = await lintWith(tokenConfig(), code, 'src/Probe.tsx')
+    expect(app.length).toBeGreaterThan(0)
+    expect(app).toEqual(await lintWith([tokenLint(), tokenValues()], code, 'src/Probe.tsx'))
+    const pkg = await lintWith(tokenConfig({ audience: 'package' }), code, 'src/Probe.tsx')
+    expect(pkg).toEqual(await lintWith([tokenLint({ audience: 'package' }), tokenValues({ audience: 'package' })], code, 'src/Probe.tsx'))
+  })
+
+  it("knows TypeScript's rule names and the quiet plugins, so their directives do not break it (UIG-37)", async () => {
+    expect(await lintWith(tokenConfig(), typescriptDirective, 'src/lib/probe.ts')).toEqual([])
+    const quiet = { rules: { 'some-rule': { create: () => ({}) } } }
+    const directive = `// eslint-disable-next-line house/some-rule\n${component('<div>x</div>')}`
+    expect(await lintWith(tokenConfig({ quiet: { house: quiet } }), directive, 'src/Probe.tsx')).toEqual([])
+  })
+
+  it('never reads build output, nor a folder the app names', async () => {
+    const hand = component('<div className="text-[14px]">x</div>')
+    const ignored = (messages: Linter.LintMessage[]) => messages.every((m) => !m.ruleId)
+    expect(ignored(await lintWith(tokenConfig(), hand, 'dist/Probe.tsx'))).toBe(true)
+    expect(ignored(await lintWith(tokenConfig({ ignores: ['demo'] }), hand, 'demo/Probe.tsx'))).toBe(true)
+  })
 })
 
 describe('writeGateCount', () => {

package/src/gates/index.ts

@@ -8,6 +8,7 @@
  * here, and an app imports them:
  *
  * - `tokenLint`, `tokenValues` — the token contract's lint settings (UIG-28).
+ * - `tokenConfig` — the token lint on its own, as `lint:tokens` runs it (UIG-37).
  * - `gateLint`, `gateConfig` — where the rules apply, and the gate that runs them alone.
  * - `writeGateCount` — `.gates-count.json` (seam S3).
  * - `runHook` — the editor gate a `PreToolUse` hook runs.
@@ -21,7 +22,7 @@
  * Built by build.mjs into `dist/gates/`, for Node. Nothing here reaches the
  * components' browser bundle.
  */
-export { TOKEN_LINT_IGNORES, tokenLint, tokenValues, type TokenAudience, type TokenLintOptions } from './token-lint'
+export { TOKEN_LINT_IGNORES, tokenConfig, tokenLint, tokenValues, type TokenAudience, type TokenConfigOptions, type TokenLintOptions } from './token-lint'
 export { gateConfig, gateLint, type GateConfigOptions } from './gate-config'
 export { writeGateCount, type CountOptions, type CountResult } from './count'
 export { runHook, type HookOptions, type HookResult } from './hook'

package/src/gates/status.ts

@@ -73,6 +73,8 @@ export interface GateHelpers {
   share(files: string[], test: (file: string) => boolean, label: string): CheckResult
   /** Build the catalogue of the app in `appDir` (UIG-13): passes when every part is described and sorted. */
   catalogue(appDir: string): Promise<CheckResult>
+  /** Every reusable part keeps the usage-page contract (UIG-19): the package's one copy of it. */
+  contract(appDir: string): Promise<CheckResult>
 }
 
 export interface GateCheck {
@@ -178,6 +180,19 @@ export function helpers(ROOT: string): GateHelpers {
       }
     },
 
+    async contract(appDir) {
+      try {
+        const { buildAppRegistry, contractProblems, CONTRACT_KINDS } = await import('../registry/index')
+        const registry = buildAppRegistry({ root: abs(appDir) })
+        const problems = contractProblems(registry, abs(appDir))
+        const owed = registry.entries.filter((entry) => (CONTRACT_KINDS as readonly string[]).includes(entry.app?.class ?? '')).length
+        if (problems.length) return FAIL(`${problems.length} of ${owed}; the first: ${problems[0]}`)
+        return PASS(`all ${owed} reusable parts keep the usage-page contract and are drawn somewhere`)
+      } catch (error) {
+        return FAIL(String(error instanceof Error ? error.message : error).split('\n')[0])
+      }
+    },
+
     file(rel) {
       return exists(rel) ? PASS(`${rel} exists`) : FAIL(`${rel} does not exist`)
     },

package/src/gates/token-lint.ts

@@ -16,6 +16,9 @@
  *   inline style that sets a colour (errors); heights, spacing and border
  *   widths written by hand (warnings, never blocking).
  *
+ * And `tokenConfig`, the two on their own as an app's `lint:tokens` runs them
+ * (UIG-37), with TypeScript's rule names known so its directives pass.
+ *
  * The patterns are the same for everyone. Only the words differ: an app is told
  * to use "the package", the package is told to add the token to `tokens.css`.
  * Measured on 17 September: the UIG-28 block was byte for byte the same in Peek
@@ -32,10 +35,10 @@
  */
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
-import type { Linter } from 'eslint'
+import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults'
-import { parser as typescriptParser } from 'typescript-eslint'
+import { parser as typescriptParser, plugin as typescriptPlugin } from 'typescript-eslint'
 
 /** Who reads the messages. */
 export type TokenAudience = 'app' | 'package'
@@ -47,9 +50,30 @@ export interface TokenLintOptions {
   audience?: TokenAudience
 }
 
+export interface TokenConfigOptions extends TokenLintOptions {
+  /**
+   * Plugins whose `eslint-disable` directives appear in the source, registered
+   * with every rule off. ESLint refuses a directive for a rule it does not
+   * know. TypeScript's are registered already.
+   */
+  quiet?: Record<string, ESLint.Plugin>
+  /** Folders the token lint never reads, beside build output. */
+  ignores?: string[]
+}
+
 /** What the token lint never reads: build output. */
 export const TOKEN_LINT_IGNORES = ['dist/', 'storybook-static/', 'node_modules/']
 
+/**
+ * Plugins a check that runs on its own registers, every rule off, so the
+ * directives another lint writes do not fail it (UIG-37). TypeScript's lint is
+ * in every app and writes `eslint-disable-next-line @typescript-eslint/...`;
+ * Peek PR #324 failed the token lint on one. Only the checks that run alone
+ * take this — a full lint that loads TypeScript's rules from its own copy would
+ * refuse a second plugin under the same name.
+ */
+export const KNOWN_PLUGINS: Record<string, ESLint.Plugin> = { '@typescript-eslint': typescriptPlugin as ESLint.Plugin }
+
 const CLASS_MAP_SELECTOR = {
   kind: 'variable',
   name: '^(?:[A-Z][A-Z0-9_]*_(?:STYLES|CLASSES)|[a-z][a-zA-Z0-9]*(?:Styles|Classes))$',
@@ -229,3 +253,24 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
     },
   }
 }
+
+/**
+ * The token lint on its own — an app's `eslint.tokens.config.js`, `npm run
+ * lint:tokens`, the CI step. It fails on the token contract and on nothing
+ * else, so a backlog in the full lint never blocks it. Peek built this file by
+ * hand until UIG-37.
+ */
+export function tokenConfig({ quiet = {}, ignores = [], ...options }: TokenConfigOptions = {}): Linter.Config[] {
+  return [
+    { ignores: [...TOKEN_LINT_IGNORES, ...ignores] },
+    {
+      plugins: { ...KNOWN_PLUGINS, ...quiet },
+      // Every other lint's directives are unused here, because their rules are
+      // off here. Reporting them would be this config complaining about the
+      // others' business.
+      linterOptions: { reportUnusedDisableDirectives: 'off' },
+    },
+    tokenLint(options),
+    tokenValues({ audience: options.audience }),
+  ]
+}