@estiva-app/ui 0.27.0 → 0.29.0

package/dist/registry/siblings.d.ts

@@ -0,0 +1,21 @@
+export declare const PACKAGE_NAME = "@estiva-app/ui";
+export interface Sibling {
+    /** What its entries are called: its top folder's name. */
+    name: string;
+    /** The folder the catalogue is built from. */
+    folder: string;
+    /** Its `package.json` name, which says two checkouts are one app. */
+    packageName: string;
+}
+/** The name of the app in `folder`, or null when the folder is not one. */
+export declare function appName(folder: string): string | null;
+/**
+ * The folder that holds the repositories: the parent of the repository `from`
+ * is in, or `from` itself when it is in none (a folder that only holds them).
+ */
+export declare function workspaceOf(from: string): string;
+/** Every app in `workspace`, one per package name, except those named in `skip`. */
+export declare function findSiblings(workspace: string, { skip }?: {
+    skip?: string[];
+}): Sibling[];
+//# sourceMappingURL=siblings.d.ts.map

package/dist/registry/siblings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siblings.d.ts","sourceRoot":"","sources":["../../src/registry/siblings.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,YAAY,mBAAmB,CAAA;AAE5C,MAAM,WAAW,OAAO;IACtB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAA;CACpB;AAYD,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAUD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,IAAS,EAAE,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAAG,OAAO,EAAE,CAsBlG"}

package/dist/registry/skill.d.ts

@@ -0,0 +1,20 @@
+export declare const SKILL_NAME = "estiva-ui";
+/** When Claude opens the skill by itself. Kept under Claude Code's 1,536 characters. */
+export declare const SKILL_DESCRIPTION: string;
+/** The search, allowed without a prompt in the folder's committed `.claude/settings.json`. */
+export declare const SEARCH_RULES: string[];
+/** The skill's text, inside a package folder. */
+export declare const skillTextPath: (packageRoot: string) => string;
+/** Where a folder keeps its loader. */
+export declare const loaderPath: (folder: string) => string;
+/** Where a folder keeps the settings that allow the search. */
+export declare const settingsPath: (folder: string) => string;
+/** The loader for `folder`, reading the text from `packageRoot`, from where a session in `folder` starts. */
+export declare function loaderText(folder: string, packageRoot: string): string;
+/** `folder`'s settings with the search allowed, everything else as it was; null when they cannot be read. */
+export declare function settingsWithSearch(folder: string): string | null;
+/** The repository `from` is in: the nearest folder with `.git`, or `from` when there is none. */
+export declare function repositoryOf(from: string): string;
+/** What is wrong with `folder`'s loader, or null when it is what `loaderText` writes. */
+export declare function loaderProblem(folder: string, packageRoot: string): string | null;
+//# sourceMappingURL=skill.d.ts.map

package/dist/registry/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/registry/skill.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,UAAU,cAAc,CAAA;AAErC,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,QAKwB,CAAA;AAEtD,8FAA8F;AAC9F,eAAO,MAAM,YAAY,UAAiJ,CAAA;AAE1K,iDAAiD;AACjD,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,WAAmD,CAAA;AAEpG,uCAAuC;AACvC,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,WAA8D,CAAA;AAEvG,+DAA+D;AAC/D,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,WAA6C,CAAA;AAExF,6GAA6G;AAC7G,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAatE;AAcD,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQhE;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,7 @@
     "src",
     "stories",
     "registry.json",
+    "skill",
     "tailwind-preset.js",
     "tokens.css",
     "base.css",
@@ -65,8 +66,9 @@
     "registry": "node dist/registry/cli.js build",
     "preregistry:check": "node build.mjs",
     "registry:check": "node dist/registry/cli.js check",
+    "skill:check": "vitest run --project unit src/registry/skill.test.ts",
     "preui:find": "node build.mjs",
-    "ui:find": "node dist/registry/cli.js find --also peek=../peek --also ship=../ship/web",
+    "ui:find": "node dist/registry/cli.js find",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/registry.json

@@ -4,7 +4,7 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.27.0",
+    "packageVersion": "0.29.0",
     "exports": 87,
     "typeExports": 96,
     "files": null

package/skill/estiva-ui.md

@@ -0,0 +1,126 @@
+# Search before you build
+
+Every screen here is built from parts: the package `@estiva-app/ui`, and each
+app's own. Every reusable part has a Storybook page that says when to use it
+and when not to. Most of what gets asked for already exists somewhere.
+
+## When this applies
+
+- Building or changing a screen, panel, list, row, header, dialog or menu.
+- Adding a component, or a new file that draws one.
+- Changing how something looks: its size, spacing, colour or type.
+
+## Steps, in order
+
+1. **Search before creating anything.** Run
+   `npm run ui:find <what it does, in plain words>` in the repository you are
+   in. Do it yourself; never ask the person to. With nothing else typed it
+   searches the package and every app beside it, and prints a Storybook link
+   for each match. Show the person what it found, with the links.
+   - From a folder that holds several repositories, run it inside any one of
+     them (`npm --prefix <repo> run ui:find <words>`): each searches them all.
+   - Search again in other words before deciding nothing fits: "list column",
+     then "scrolling list"; "panel header", then "title row".
+2. **If something fits, read its page before using it:** the link, or the
+   `.mdx` beside its file. Read its opening line, **When** and **When not**.
+   *When not* names the part to use instead.
+3. **If nothing fits, say so and ask.** Do not invent a component. Do not copy
+   one from another app either: say which app has it, and ask whether it
+   should move into the package.
+4. **Never hand-roll what the package owns.** Its parts own their behaviour:
+   keys, focus, floating, closing, scrolling, truncation. The editor gate
+   refuses a raw element, a rebuilt behaviour or a restyled part, and its error
+   names the part to use.
+5. **An exception** carries `// @estiva-escape: <reason>` on the line above
+   it. Never `eslint-disable`.
+
+## Gotchas
+
+The mistakes made here more than once, from the record (UIG-20 counted 542
+recorded defects; these 24 cover the 111 that are screen work). Each says what
+to do instead. Apps differ in frame and theme: never carry one app's layout,
+sizes or colours into another; take them from tokens.
+
+**Layout**
+
+1. **A header row drawn by hand** at the top of a column → `ContainerHeader`.
+   Its actions are `IconButton`s with tooltips. A whole list column is
+   `ListColumn`, which draws the bar; a field that adds to the list goes in its
+   `above`.
+2. **A list with no scroll container**, cut off at the fold (no lint sees a box
+   that was never built) → a list column is `ListColumn`, which scrolls its
+   rows; anything else that grows goes in a `ScrollArea`. Check with more rows
+   than fit.
+3. **`EmptyState` at the wrong level** → `scope="page"` only when the whole
+   page is empty, `scope="section"` for one part of it, placed inside the box
+   its rows live in. Never wrap it in a box of your own that places it.
+4. **`EditableText` rendering too large**: it has no size of its own and takes
+   the size around it → put the text size on your own element around it. The
+   same holds for `Person`, `Link`, `Card` and `SectionLabel`.
+5. **Flex rows that move things**: loose children of an `items-start` row float
+   at different heights; a scrolling flex column squashes rows → group them in
+   one `items-center` row; give your own rows in a scrolling column `shrink-0`.
+6. **A group heading drawn by hand** (a row holding a `SectionLabel`) →
+   `SectionHeader` (`hover="none"` when nothing acts on it); a group that folds
+   is `CollapsibleSection`.
+7. **A line drawn by hand** (`border-t`, `<hr>`, a gap) → `Divider`; between a
+   menu's groups, `MenuSeparator`, which brings its own room.
+
+**Parts and props**
+
+8. **The browser's tooltip** (`title=`), or an icon button with none →
+   `WithTooltip` (`inline` inside text) or `IconButton`'s `tooltip`.
+9. **A row of icon buttons laid out by hand** → `Toolbar` with `ToolbarButton`
+   and `ToolbarLink` (they throw outside one). A row inside a `Popover` is a
+   `Toolbar` with `surface={false}`.
+10. **Fields sent by a hand-written Enter handler**, with no form → `Form`,
+    which owns the keys, `busy` and focus. Clear a field's `error` when it
+    changes, or the form will not send.
+11. **A link to an in-app page as a bare `href`**: every click reloads the app
+    → go through the app's router, as `NavItem` does.
+12. **Wrong loading and failure states**: an `EmptyState` while data is still
+    coming, a hand-made pulsing box → a skeleton shaped like what is coming
+    (`SkeletonList`, `SkeletonRow`, `SkeletonBar`). Say a failure in
+    words, never as "empty" and never in red; a failure toast or banner has
+    the `error` tone.
+13. **A floating panel mounted only while open** (`{open && <Popover…>}`), or
+    capped with a class → keep it mounted and drive `open`; cap a long list with
+    `Popover`'s `maxHeight`; never open a panel around an empty list.
+14. **Deleting a part without checking what else it carried** → read everything
+    the container holds first, and remove its imports, escapes and stories with it.
+
+**Stories and usage pages**
+
+15. **A story that shows one branch**: something drawn behind `{prop && …}` that
+    no story passes, or data with no fixture → a story for every branch; one
+    fixture holding what the backend really sends. `estiva-ui check` refuses
+    the first.
+16. **A screen with no story** is where mistakes hide: every gate was green on
+    a page with eight → look at the running screen, or give it a story with
+    more rows than fit, an empty state and a loading state.
+17. **A story under a new heading, or named after its file** → use a heading
+    the Storybook already has, name the entry after its part, give each meta its
+    `component` (or the part's page a **Seen in** line).
+18. **`{…}` in a usage page's prose** (MDX reads it as code and the page will
+    not compile), or a description over two lines → backticks around braces; a
+    part's description is one line.
+
+**Working in these repositories**
+
+19. **An escape with a false reason** ("no part does this" has been wrong
+    twice) → search for the thing first. Write the escape on the line above
+    the statement, never inside `eslint-disable`.
+20. **Classes the lint cannot see**: in a const not named `…_CLASSES` or
+    `…Styles`, or in an array that is `.join()`ed → keep classes in
+    `className` or `cn()`, or in a map with one of those names.
+21. **The editor gate and this skill need a session started at the repository's
+    top folder.** Started elsewhere, run the repository's `lint:rules` yourself
+    before committing.
+22. **`npm install` on Windows prunes Linux-only entries from the lockfile**, and
+    CI dies at `npm ci` → never commit a lockfile Windows rewrote; restore it and
+    bump only the package's own entry. Stop every dev server before `npm ci`.
+23. **Storybook shows old code after a package bump** → delete
+    `node_modules/.cache/storybook` and restart.
+24. **A local checkout lags `origin/main`, and a conflicting PR shows no CI** →
+    `git fetch` and read `origin/main`; when checks are missing, look for a
+    conflict first.

package/src/gates/app-checks.ts

@@ -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) =>
@@ -196,8 +199,14 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { 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') },
     ]),
+    // The Claude skill (UIG-20): its text is the installed package's, read in by a
+    // loader `estiva-ui skill` writes; the app commits the loader and the settings.
     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')) },
+      { what: "the skill's loader reads the installed package's text", run: () => h.contains('.claude/skills/estiva-ui/SKILL.md', `!\`cat "\${CLAUDE_PROJECT_DIR}/${at('node_modules/@estiva-app/ui/skill/estiva-ui.md')}"\``, 'the loader reads the package’s skill') },
+      { what: 'the search runs without a prompt', run: () => h.contains('.claude/settings.json', 'Bash(npm run ui:find *)', '.claude/settings.json allows npm run ui:find') },
+      { what: 'ui:find searches every app beside this one: it names none', run: () => h.lacks(at('package.json'), /"ui:find":[^\n]*--also/, 'ui:find names no neighbour, so it finds them all') },
+      ...(WEB ? [{ what: 'ui:find runs from the top folder too', run: () => h.contains('package.json', /"ui:find":/, 'the top folder has ui:find') }] : []),
+      { what: "CI's job gate refuses a loader that differs", run: () => (h.exists(at('node_modules/@estiva-app/ui/dist/registry/cli.js')) && /claude skill:/.test(h.read(at('node_modules/@estiva-app/ui/dist/registry/cli.js'))) ? h.ciJob('gate', 'registry:check') : h.FAIL('the installed package does not check the loader: take a version that does')) },
     ]),
     ticket('UIG-21', [
       { what: 'path-scoped instructions exist', run: () => (h.listFiles('.claude/rules', (n) => n.endsWith('.md')).some((f) => /^paths:/m.test(h.read(f))) ? h.PASS('.claude/rules has paths: instructions') : h.FAIL('no .claude/rules file with paths:')) },
@@ -248,5 +257,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.test.ts

@@ -30,7 +30,7 @@ describe('create-estiva-app', () => {
   it('makes the frame, the checks and the gates, each as a file that imports the package', () => {
     expect(Object.keys(files).sort()).toEqual(
       [
-        '.claude/settings.json', '.env.example', '.gates-count.json', '.github/workflows/deploy.yml', '.gitignore', '.storybook/main.ts', '.storybook/preview.tsx',
+        '.claude/settings.json', '.claude/skills/estiva-ui/SKILL.md', '.env.example', '.gates-count.json', '.github/workflows/deploy.yml', '.gitignore', '.storybook/main.ts', '.storybook/preview.tsx',
         'CLAUDE.md', 'README.md', 'docs/GATES-DEBT.md', 'eslint.config.js', 'eslint.gates.config.js', 'eslint.tokens.config.js', 'index.html', 'package.json',
         'postcss.config.js', 'scripts/gates-checks.mjs', 'src/App.test.tsx', 'src/App.tsx', 'src/auth/AuthShell.tsx', 'src/auth/boot.ts', 'src/auth/estivaId.ts',
         'src/config.ts', 'src/index.css', 'src/main.tsx', 'src/pages/HomePage.stories.tsx', 'src/pages/HomePage.tsx',
@@ -41,6 +41,10 @@ describe('create-estiva-app', () => {
     expect(files['eslint.gates.config.js']).toContain("from '@estiva-app/ui/gates'")
     expect(files['scripts/gates-checks.mjs']).toContain("appChecks(h, { page: 'src/pages/HomePage.tsx' })")
     expect(JSON.parse(files['.claude/settings.json']).hooks.PreToolUse[0].hooks[0].command).toBe('node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook')
+    // The skill loads from the package's one copy: the app holds its trigger and the line that reads it (UIG-20).
+    expect(JSON.parse(files['.claude/settings.json']).permissions.allow).toContain('Bash(npm run ui:find *)')
+    expect(files['.claude/skills/estiva-ui/SKILL.md']).toContain('!`cat "${CLAUDE_PROJECT_DIR}/node_modules/@estiva-app/ui/skill/estiva-ui.md"`')
+    expect(files['.claude/skills/estiva-ui/SKILL.md']).not.toContain('## Steps')
   })
 
   it('uses the sidebar frame and one theme, set on <html>', () => {

package/src/gates/create-app.ts

@@ -35,6 +35,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { APP_RULE_IDS } from '../eslint/index'
+import { loaderText, SEARCH_RULES } from '../registry/skill'
 
 interface PackageJson {
   version: string
@@ -264,18 +265,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 +280,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.
@@ -296,8 +293,12 @@ export default gateConfig({ quiet: { 'react-hooks': reactHooks } })
       hooks: {
         PreToolUse: [{ matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook' }] }],
       },
+      permissions: { allow: SEARCH_RULES },
     }),
 
+    // The Claude skill (UIG-20): its trigger, and a line reading the installed package's text in.
+    '.claude/skills/estiva-ui/SKILL.md': loaderText(resolve('/app'), resolve('/app/node_modules/@estiva-app/ui')),
+
     'scripts/gates-checks.mjs': `import { appChecks } from '@estiva-app/ui/gates'
 
 /**

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', () => {
@@ -144,6 +178,31 @@ describe('runHook', () => {
     }
   })
 
+  it('stops a new part once with what already exists, then lets it through (UIG-20)', async () => {
+    const seen = mkdtempSync(join(scratch, 'seen-'))
+    const input = { ...write('src/PanelHeader.tsx', 'export function PanelHeader() {\n  return <div>x</div>\n}\n'), session_id: 'one' }
+    const first = await runHook({ root: dir, input, seen })
+    expect(first.code).toBe(2)
+    expect(first.message).toContain('src/PanelHeader.tsx was not written yet: it adds a new part, PanelHeader.')
+    expect(first.message).toContain('What already exists for "panel header"')
+    expect(first.message).toContain('ContainerHeader')
+    expect((await runHook({ root: dir, input, seen })).code).toBe(0)
+    // Another session is asked again.
+    expect((await runHook({ root: dir, input: { ...input, session_id: 'two' }, seen })).code).toBe(2)
+    // The search reads every app beside this checkout: seconds on a machine that holds them all.
+  }, 60_000)
+
+  it('does not stop a file already there, a story, or a file that draws nothing', async () => {
+    const seen = mkdtempSync(join(scratch, 'seen-'))
+    for (const input of [
+      write('src/Page.tsx', 'export function Page() {\n  return <div>y</div>\n}\n'),
+      write('src/Panel.stories.tsx', 'export const Default = () => <div>x</div>\n'),
+      write('src/format.tsx', 'export function formatDate(date: Date) {\n  return date.toISOString()\n}\n'),
+    ]) {
+      expect((await runHook({ root: dir, input, seen })).code).toBe(0)
+    }
+  })
+
   it('finds the app in a folder of its own, as Ship keeps it in web/', async () => {
     const top = join(scratch, 'top')
     mkdirSync(top, { recursive: true })

package/src/gates/hook.ts

@@ -22,13 +22,24 @@
  * `replace_all` for Edit. An Edit carries no whole file, so the edit is applied
  * to the file on disk here. Anything it cannot read passes, and the tool itself
  * reports its own failure.
+ *
+ * **Search first** (UIG-20). A Write that would create a new file drawing a new
+ * part, and that the gate lets through, is stopped once: the hook runs
+ * `estiva-ui find` on the part's name and hands the matches back, so a session
+ * sees what already exists before it adds another. The same file written again
+ * in the same session goes through. The skill asks for the search; this makes
+ * sure it happened. A search that cannot run stops nothing.
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { tmpdir } from 'node:os'
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { ESLint as ESLintClass } from 'eslint'
 import { countGates } from '../eslint/index'
+import { repositoryOf } from '../registry/skill'
 
 export interface HookOptions {
   /** The repository's top folder. Defaults to `$CLAUDE_PROJECT_DIR`, then the tool call's `cwd`. */
@@ -39,6 +50,8 @@ export interface HookOptions {
   audience?: 'app' | 'package'
   /** The hook's input, when not read from stdin (tests). */
   input?: unknown
+  /** Where a session's searches are remembered. Defaults to a folder in the system's temp. */
+  seen?: string
 }
 
 export interface HookResult {
@@ -50,13 +63,14 @@ export interface HookResult {
 
 interface ToolCall {
   tool_name?: string
+  session_id?: string
   cwd?: string
   tool_input?: { file_path?: unknown; content?: unknown; old_string?: unknown; new_string?: unknown; replace_all?: unknown }
 }
 
 const PASS: HookResult = { code: 0, message: '' }
 
-export async function runHook({ root, app = '.', audience = 'app', input }: HookOptions = {}): Promise<HookResult> {
+export async function runHook({ root, app = '.', audience = 'app', input, seen }: HookOptions = {}): Promise<HookResult> {
   let call: ToolCall
   try {
     call = (input ?? JSON.parse(readFileSync(0, 'utf8'))) as ToolCall
@@ -86,7 +100,7 @@ export async function runHook({ root, app = '.', audience = 'app', input }: Hook
   // the typecheck's to judge; the gate looks again at the edit that completes it.
   const errors = results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId))
   const { disabled } = countGates(results)
-  if (errors.length === 0 && disabled.length === 0) return PASS
+  if (errors.length === 0 && disabled.length === 0) return searchFirst(call, file, text, appDir, top, seen) ?? PASS
 
   const shown = (p: string) => relative(top, p).split(sep).join('/')
   const lines = [`${shown(file)} was not written: the UI Guardrails refuse it (${shown(config)}).`]
@@ -96,6 +110,56 @@ export async function runHook({ root, app = '.', audience = 'app', input }: Hook
   return { code: 2, message: `${lines.join('\n')}\n` }
 }
 
+/** The part a Write would add in a new file, or null: a capitalised export, in a file that draws. */
+export function newPart(tool: string | undefined, file: string, text: string): string | null {
+  if (tool !== 'Write' || existsSync(file) || !file.endsWith('.tsx') || /\.stories\.tsx$/.test(file)) return null
+  if (!/<\/[A-Za-z]|\/>/.test(text)) return null
+  const named = /export\s+(?:default\s+)?(?:async\s+)?(?:function|const|class)\s+([A-Z][A-Za-z0-9]*)/.exec(text)?.[1]
+  if (named) return named
+  return /export\s+default\s+function\s*\(/.test(text) ? basename(file, '.tsx') : null
+}
+
+/** `PanelHeader` → `panel header`: the words the search is asked. */
+export const wordsOf = (name: string) => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z])([A-Z][a-z])/g, '$1 $2').toLowerCase()
+
+/** The catalogue command: beside this file once built, or the built one from source (tests). */
+function findCommand(): string | null {
+  for (const at of ['../registry/cli.js', '../../dist/registry/cli.js']) {
+    const path = fileURLToPath(new URL(at, import.meta.url))
+    if (existsSync(path)) return path
+  }
+  return null
+}
+
+/** Stop a new part's first Write with what already exists; null lets it through. */
+function searchFirst(call: ToolCall, file: string, text: string, appDir: string, top: string, seen?: string): HookResult | null {
+  const part = newPart(call.tool_name, file, text)
+  const command = findCommand()
+  if (!part || !command) return null
+  const folder = seen ?? join(tmpdir(), 'estiva-ui-search-first')
+  const mark = join(folder, createHash('sha1').update(`${call.session_id ?? ''}\n${resolve(file)}`).digest('hex'))
+  if (existsSync(mark)) return null
+  const words = wordsOf(part)
+  const repo = basename(repositoryOf(appDir))
+  const run = spawnSync(process.execPath, [command, 'find', ...words.split(' '), '--root', appDir, '--repo', repo, '--limit', '5'], { encoding: 'utf8', timeout: 60_000 })
+  if (run.status !== 0 || !run.stdout.trim()) return null
+  try {
+    mkdirSync(folder, { recursive: true })
+    writeFileSync(mark, '')
+  } catch {
+    return null
+  }
+  const shown = relative(top, file).split(sep).join('/')
+  return {
+    code: 2,
+    message:
+      `${shown} was not written yet: it adds a new part, ${part}. Search before building (UIG-20). What already exists for "${words}":\n\n` +
+      `${run.stdout.trim()}\n\n` +
+      `If one of these does the job, use it, and read its page first. If the words were wrong, run \`npm run ui:find <other words>\`. ` +
+      `If nothing fits, tell the person, then write the file again: it goes through.\n`,
+  }
+}
+
 /** The file as it will be after this tool call, or null when that cannot be known. */
 function proposed(tool: string | undefined, args: NonNullable<ToolCall['tool_input']>, file: string): string | null {
   if (tool === 'Write') return typeof args.content === 'string' ? args.content : null

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'