@estiva-app/ui 0.28.0 → 0.30.0

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

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../src/registry/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAEvD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,aAAa,CAAA;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;;OAKG;IACH,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAoDD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAS,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,EAAE,CAEnH;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAS,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,EAAE,CAmEzH;AAED,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAGhF;AAUD,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgD1G"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../src/registry/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAEvD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,aAAa,CAAA;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;;OAKG;IACH,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAoDD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAS,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,EAAE,CAEnH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAS,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,EAAE,CAuEzH;AAED,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAGhF;AAUD,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgD1G"}

package/dist/registry/index.js

@@ -10,7 +10,7 @@ import {
   hasSeenIn,
   linkProblems,
   pageProblem
-} from "./chunk-6OH3TWGF.js";
+} from "./chunk-KMZIMB3G.js";
 import {
   buildAppRegistry
 } from "./chunk-XCBN2EKW.js";

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.28.0",
+  "version": "0.30.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.28.0",
+    "packageVersion": "0.30.0",
     "exports": 87,
     "typeExports": 96,
     "files": null

package/skill/estiva-ui.md

@@ -0,0 +1,128 @@
+# 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 its reason on the line above it. For the gate:
+   `// @estiva-escape: <reason>`, never `eslint-disable`. For the token lint:
+   `// eslint-disable-next-line <rule> -- @estiva-escape: <reason>`.
+
+## 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: a gate escape never inside `eslint-disable`, a token-lint
+    one inside `eslint-disable-next-line <rule> --`.
+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/ScrollArea.mdx

@@ -33,14 +33,18 @@ the content is moving; nothing moves when it appears.
 ```tsx
 import { ScrollArea } from '@estiva-app/ui'
 
-<ScrollArea className="h-[240px]" viewportClassName="p-2">
+<ScrollArea className="h-[240px]" contentClassName="flex flex-col p-2">
   {rows}
 </ScrollArea>
 ```
 
-- `className` sizes and places the region; `viewportClassName` styles the
-  scrolling box inside it — padding, gap, the layout of the content.
-- The region needs a height (or a `max-h-*`) to have anything to scroll.
+- Three boxes, and each class prop lands on one. `className` is the
+  region: its size and placement. `viewportClassName` is the box that
+  scrolls: a `max-h-*` cap goes there and nowhere else. `contentClassName`
+  is the box the children sit in: the padding, the gap, `flex flex-col`.
+- The region needs a height to have anything to scroll. A cap on the region
+  lets the viewport grow to its content and nothing scrolls; cap the
+  viewport instead: `viewportClassName="max-h-[240px]"`.
 - **`viewportRef` and `onScroll` hand back the box that scrolls**, for a
   region that reads or drives its own scrolling: a conversation that arrives
   at its newest message, keeps its place when older ones load above it, and

package/src/ScrollArea.stories.tsx

@@ -18,7 +18,7 @@ const rows = Array.from({ length: 40 }, (_, i) => `Row ${i + 1}`)
 export const Default: Story = {
   render: () => (
     <div className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
-    <ScrollArea className="h-full" viewportClassName="p-2">
+    <ScrollArea className="h-full" contentClassName="p-2">
       <ul className="flex flex-col gap-px">
         {rows.map((row) => (
           <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
@@ -55,7 +55,7 @@ export const StickyHeadings: Story = {
 export const Fits: Story = {
   render: () => (
     <div className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
-    <ScrollArea className="h-full" viewportClassName="p-2">
+    <ScrollArea className="h-full" contentClassName="p-2">
       <ul className="flex flex-col gap-px">
         {rows.slice(0, 4).map((row) => (
           <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
@@ -72,7 +72,7 @@ export const Fits: Story = {
 export const Horizontal: Story = {
   render: () => (
     <div className="w-[280px] rounded-lg border border-border-default bg-bg-surface">
-    <ScrollArea orientation="horizontal" viewportClassName="p-2">
+    <ScrollArea orientation="horizontal" contentClassName="p-2">
       <div className="flex w-max gap-2">
         {rows.slice(0, 12).map((row) => (
           <div key={row} className="w-[120px] shrink-0 rounded-md bg-bg-inset px-2 py-1.5 text-body-2 text-text-primary">
@@ -89,7 +89,7 @@ export const Horizontal: Story = {
 export const Both: Story = {
   render: () => (
     <div className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
-    <ScrollArea orientation="both" className="h-full" viewportClassName="p-2">
+    <ScrollArea orientation="both" className="h-full" contentClassName="p-2">
       <div className="flex w-max flex-col gap-px">
         {rows.map((row) => (
           <div key={row} className="w-[480px] rounded-md px-2 py-1.5 text-body-2 text-text-primary">
@@ -106,7 +106,7 @@ export const Both: Story = {
 export const SidewaysInsideAPage: Story = {
   render: () => (
     <div className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface">
-    <ScrollArea className="h-full" viewportClassName="p-2">
+    <ScrollArea className="h-full" contentClassName="p-2">
       <div className="flex flex-col gap-px">
         {rows.slice(0, 3).map((row) => (
           <p key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
@@ -114,7 +114,7 @@ export const SidewaysInsideAPage: Story = {
           </p>
         ))}
         <div className="my-1 rounded-md border border-border-default">
-        <ScrollArea orientation="horizontal" viewportClassName="p-2">
+        <ScrollArea orientation="horizontal" contentClassName="p-2">
           <div className="flex w-max gap-2">
             {rows.slice(0, 12).map((row) => (
               <div key={row} className="w-[120px] shrink-0 rounded-md bg-bg-inset px-2 py-1.5 text-body-2 text-text-primary">

package/src/cn.ts

@@ -1,4 +1,5 @@
 import { clsx, type ClassValue } from 'clsx'
+// eslint-disable-next-line no-restricted-imports -- @estiva-escape: cn() is the one place tailwind-merge is taught the type ramp
 import { extendTailwindMerge } from 'tailwind-merge'
 
 /**

package/src/gates/app-checks.ts

@@ -199,11 +199,24 @@ 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')) },
     ]),
+    // What loads into every Claude session (UIG-21): CLAUDE.md is an index, the
+    // rest loads where it applies, and a rule a check can hold is a check.
     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:')) },
+      { what: 'CLAUDE.md with its imports is under 200 lines, and every rule file is scoped', run: () => h.instructions(200) },
+      { what: "CI's job gate runs the token lint", run: () => {
+        const tokens = h.ciJob('gate', 'lint:tokens')
+        return tokens.result === 'pass' ? tokens : h.ciJob('gate', 'lint')
+      } },
+      { what: "a plain tailwind-merge is an error naming the package's cn()", run: tokenProbe("import { twMerge } from 'tailwind-merge'\nexport const merged = twMerge('p-2', 'p-3')\n", 'error', 'cn()', 'src/lib/__gates_probe__.ts') },
     ]),
     ticket('UIG-22', [
       { what: 'a hand-made header row is an error naming the header part', run: all(h, headers.map((name) => probe(component(`<section className="flex flex-col"><div className="flex items-center px-3 py-2"><span>${name === 'SectionHeader' ? 'Issues' : 'Folders'}</span></div><div /></section>`), 'error', name)), 'a hand-made header row is an error naming the header part') },

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,13 @@ 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')
+    // What loads into every session starts small and imports nothing (UIG-21).
+    expect(files['CLAUDE.md'].replace(/\n$/, '').split('\n').length).toBeLessThan(200)
+    expect(files['CLAUDE.md']).not.toMatch(/^@\S/m)
   })
 
   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
@@ -292,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/gates.test.ts

@@ -68,6 +68,15 @@ describe('tokenLint and tokenValues', () => {
     expect(messages.filter((m) => m.ruleId?.startsWith('token-'))).toEqual([expect.objectContaining({ ruleId: 'token-spacing/no-restricted-classes', severity: 1 })])
   })
 
+  it('refuse a plain tailwind-merge and name cn(), for an app and for the package (UIG-21)', async () => {
+    const code = "import { twMerge } from 'tailwind-merge'\nexport const merged = twMerge('p-2', 'p-3')\n"
+    const app = await lintWith([tokenLint(), tokenValues()], code, 'src/lib/probe.ts')
+    expect(app).toEqual([expect.objectContaining({ ruleId: 'no-restricted-imports', severity: 2, message: expect.stringContaining("package's cn()") })])
+    const pkg = await lintWith([tokenLint({ audience: 'package' })], code, 'src/probe.ts')
+    expect(pkg).toEqual([expect.objectContaining({ ruleId: 'no-restricted-imports', message: expect.stringContaining('src/cn.ts') })])
+    expect(await lintWith([tokenLint()], "import { cn } from '@estiva-app/ui'\nexport const merged = cn('p-2', 'p-3')\n", 'src/lib/probe.ts')).toEqual([])
+  })
+
   it('leave a test file to its test', async () => {
     const messages = await lintWith([tokenLint(), tokenValues()], component('<div style={{ color: "red" }}>x</div>'), 'src/Probe.test.tsx')
     expect(messages.filter((m) => m.severity === 2)).toEqual([])
@@ -178,6 +187,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 })
@@ -203,6 +237,18 @@ describe('gates:status', () => {
     expect(h.script('package.json', 'gates:status').result).toBe('pass')
   })
 
+  it('counts what loads into every session, imports included, and refuses a rule file with no paths (UIG-21)', () => {
+    const lines = (n: number) => Array.from({ length: n }, (_, i) => `line ${i}`).join('\n') + '\n'
+    const scoped = '---\npaths:\n  - "src/**"\n---\n\nA rule.\n'
+    const small = helpers(app('instructions-small', { 'CLAUDE.md': lines(40), '.claude/rules/ui.md': scoped }))
+    expect(small.instructions(200)).toMatchObject({ result: 'pass', detail: expect.stringContaining('40 lines') })
+    // 150 + 60 = 210: CLAUDE.md alone is under the limit, and its import takes it over.
+    const imported = helpers(app('instructions-import', { 'CLAUDE.md': `${lines(149)}@RULES.md\n`, 'RULES.md': lines(60) }))
+    expect(imported.instructions(200)).toMatchObject({ result: 'fail', detail: expect.stringContaining('210 lines') })
+    const unscoped = helpers(app('instructions-unscoped', { 'CLAUDE.md': lines(10), '.claude/rules/ui.md': scoped, '.claude/rules/all.md': 'Loads every time.\n' }))
+    expect(unscoped.instructions(200)).toMatchObject({ result: 'fail', detail: expect.stringContaining('.claude/rules/all.md') })
+  })
+
   it('prints a repo on its own: its own rows, then its parts', async () => {
     const dir = app('status-run', {
       'scripts/gates-checks.mjs': "export default (h) => ({ repo: 'probe', tickets: [\n  { ref: 'UIG-2', title: 'Rails', owner: false, checks: [{ what: 'wired', run: () => h.PASS('yes') }] },\n  { ref: 'UIG-9', title: 'Allow-list', owner: false, checks: [{ what: 'a look is refused', run: () => h.FAIL('no') }] },\n] })\n",

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/status.ts

@@ -75,6 +75,12 @@ export interface GateHelpers {
   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>
+  /**
+   * What loads into every Claude session stays small (UIG-21): `CLAUDE.md` and
+   * every file it imports with `@` come to fewer than `limit` lines, and each
+   * `.claude/rules` file has `paths:`, so it loads only where it applies.
+   */
+  instructions(limit?: number): CheckResult
 }
 
 export interface GateCheck {
@@ -193,6 +199,25 @@ export function helpers(ROOT: string): GateHelpers {
       }
     },
 
+    instructions(limit = 200) {
+      if (!exists('CLAUDE.md')) return FAIL('there is no CLAUDE.md')
+      // As `wc -l` counts them: a last line ending in a newline is not one more.
+      const lines = (rel: string) => read(rel).replace(/\r?\n$/, '').split(/\r?\n/).length
+      const imports = [...read('CLAUDE.md').matchAll(/^@(\S+)\s*$/gm)].map((m) => m[1])
+      const missing = imports.filter((rel) => !exists(rel))
+      if (missing.length) return FAIL(`CLAUDE.md imports ${missing.join(', ')}, which is not there`)
+      const total = imports.reduce((n, rel) => n + lines(rel), lines('CLAUDE.md'))
+      const what = imports.length ? `CLAUDE.md with ${imports.join(', ')}` : 'CLAUDE.md'
+      if (total >= limit) return FAIL(`${what}: ${total} lines load into every session; the limit is ${limit}`)
+      const rules = listFiles('.claude/rules', (n) => n.endsWith('.md'))
+      const unscoped = rules.filter((rel) => {
+        const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(read(rel))
+        return !front || !/^paths:/m.test(front[1])
+      })
+      if (unscoped.length) return FAIL(`${unscoped.join(', ')} has no paths:, so it loads into every session`)
+      return PASS(`${what}: ${total} lines in every session; ${rules.length ? `${rules.length} rule files, each loading only for its paths` : 'no rule files'}`)
+    },
+
     file(rel) {
       return exists(rel) ? PASS(`${rel} exists`) : FAIL(`${rel} does not exist`)
     },