@estiva-app/ui 0.33.0 → 0.34.0

package/src/Tooltip.stories.tsx

@@ -3,6 +3,7 @@ import { IconArchive, IconPin, IconTrash } from '@tabler/icons-react'
 import { Button } from './Button'
 import { IconButton } from './IconButton'
 import { Tooltip, WithTooltip } from './Tooltip'
+import { Card } from './Card'
 
 const meta = {
   title: 'Primitives/Tooltip',
@@ -99,7 +100,7 @@ export const OnADisabledControl: Story = {
 export const InAToolbar: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex items-center gap-1 rounded-lg border border-border-default bg-bg-elevated p-1">
+    <Card fill="elevated" className="flex items-center gap-1 p-1">
       <IconButton aria-label="Pin" tooltip="Pin">
         <IconPin size={16} stroke={1.5} />
       </IconButton>
@@ -109,6 +110,6 @@ export const InAToolbar: Story = {
       <IconButton aria-label="Delete" tooltip="Delete" tooltipShortcut="Del">
         <IconTrash size={16} stroke={1.5} />
       </IconButton>
-    </div>
+    </Card>
   ),
 }

package/src/Tooltip.tsx

@@ -2,6 +2,7 @@ import type { ComponentPropsWithRef, ReactElement, ReactNode } from 'react'
 import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip'
 import { cn } from './cn'
 import { Kbd } from './Kbd'
+import { FLOATING_SURFACE_CLASSES } from './looks'
 
 /**
  * Peek's Tooltip and WithTooltip (2026-08-28) — the same 30px elevated pill,
@@ -72,7 +73,7 @@ export interface TooltipProps extends Omit<ComponentPropsWithRef<'div'>, 'childr
  */
 export function Tooltip({ label, shortcut, className, ...props }: TooltipProps) {
   return (
-    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg min-h-[30px] max-w-80 flex items-center justify-center gap-1.5 px-2 py-1 shadow-lg', className)} {...props}>
+    <div role="tooltip" className={cn(FLOATING_SURFACE_CLASSES, 'min-h-[30px] max-w-80 flex items-center justify-center gap-1.5 px-2 py-1', className)} {...props}>
       <span className="min-w-0 text-caption text-text-primary break-words">{label}</span>
       {shortcut && <Kbd>{shortcut}</Kbd>}
     </div>

package/src/eslint/index.test.ts

@@ -40,6 +40,7 @@ describe('the plugin object', () => {
       'no-handmade-header',
       'no-handmade-empty-state',
       'no-native-title',
+      'no-copied-look',
       'raw-element-outside-a-wrapper',
       'no-hand-rolled-behaviour',
       'component-has-a-page',
@@ -57,11 +58,12 @@ describe('the plugin object', () => {
    * change it deliberately, here.
    */
   it('gives an app only the app rules, as errors, under estiva/', () => {
-    for (const config of [estiva.configs.recommended, estiva.configs.strict]) {
-      expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
-      expect(config.rules).toEqual({ 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error', 'estiva/no-restyled-part': 'error', 'estiva/no-handmade-header': 'error', 'estiva/no-handmade-empty-state': 'error', 'estiva/no-native-title': 'error' })
-    }
-    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'])
+    const blocking = { 'estiva/no-raw-element': 'error', 'estiva/no-rebuilt-behaviour': 'error', 'estiva/no-restyled-part': 'error', 'estiva/no-handmade-header': 'error', 'estiva/no-handmade-empty-state': 'error', 'estiva/no-native-title': 'error' }
+    for (const config of [estiva.configs.recommended, estiva.configs.strict]) expect(config.plugins?.[PLUGIN_KEY]).toBe(estiva)
+    // The copied look warns in recommended (Katerina, 13 September), and strict makes it an error.
+    expect(estiva.configs.recommended.rules).toEqual({ ...blocking, 'estiva/no-copied-look': 'warn' })
+    expect(estiva.configs.strict.rules).toEqual({ ...blocking, 'estiva/no-copied-look': 'error' })
+    expect(APP_RULE_IDS).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title', 'estiva/no-copied-look'])
   })
 
   /**
@@ -82,9 +84,10 @@ describe('the plugin object', () => {
       'estiva/no-handmade-header': 'error',
       'estiva/no-handmade-empty-state': 'error',
       'estiva/no-native-title': 'error',
+      'estiva/no-copied-look': 'warn',
     })
     expect(PACKAGE_RULE_IDS).toEqual(Object.keys(estiva.configs.package.rules ?? {}))
-    for (const id of PACKAGE_RULE_IDS.filter((id) => !['estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'].includes(id))) {
+    for (const id of PACKAGE_RULE_IDS.filter((id) => !['estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title', 'estiva/no-copied-look'].includes(id))) {
       expect(estiva.configs.recommended.rules?.[id]).toBeUndefined()
       expect(estiva.configs.strict.rules?.[id]).toBeUndefined()
     }
@@ -151,8 +154,8 @@ describe('countGates', () => {
   it('counts an error, and an escape only when the lint reports escapes', async () => {
     const code = component('    <div>\n      <button>x</button>\n      {/* @estiva-escape: a preview drawn from its own palette */}\n      <button>y</button>\n    </div>')
     const none = { errors: 0, warnings: 0, escapes: 0 }
-    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none })
-    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none })
+    expect(countGates(await lint(code)).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 0 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })
+    expect(countGates(await lint(code, [countMode])).rules).toEqual({ 'estiva/no-raw-element': { errors: 1, warnings: 0, escapes: 1 }, 'estiva/no-rebuilt-behaviour': none, 'estiva/no-restyled-part': none, 'estiva/no-handmade-header': none, 'estiva/no-handmade-empty-state': none, 'estiva/no-native-title': none, 'estiva/no-copied-look': none })
   })
 
   it('lists a report an eslint-disable silenced, and counts it as neither an error nor an escape', async () => {
@@ -176,6 +179,7 @@ describe('countGates', () => {
         'estiva/no-handmade-header': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-handmade-empty-state': { errors: 0, warnings: 0, escapes: 0 },
         'estiva/no-native-title': { errors: 0, warnings: 0, escapes: 0 },
+        'estiva/no-copied-look': { errors: 0, warnings: 0, escapes: 0 },
       },
       disabled: [],
     })

package/src/eslint/index.ts

@@ -22,6 +22,7 @@ import { componentHasAPage, componentHasAStory } from './has-a-page-and-a-story'
 import { noHandRolledBehaviour } from './no-hand-rolled-behaviour'
 import { noHandmadeEmptyState } from './no-handmade-empty-state'
 import { noHandmadeHeader } from './no-handmade-header'
+import { noCopiedLook } from './no-copied-look'
 import { noNativeTitle } from './no-native-title'
 import { noRawElement } from './no-raw-element'
 import { noRebuiltBehaviour } from './no-rebuilt-behaviour'
@@ -32,6 +33,7 @@ export { ESCAPE_MARKER, MIN_REASON, SETTINGS_KEY, isEscaped, type EstivaSettings
 export { OWNED_BEHAVIOURS, type OwnedBehaviour } from './no-rebuilt-behaviour'
 export { PART_LOOK_PROPS, PLACEMENT } from './no-restyled-part'
 export { PARTS_WITH_A_TITLE } from './no-native-title'
+export { MIN_COVER, MIN_SHARED } from './looks-of'
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
@@ -51,6 +53,7 @@ const appRules = {
   'no-handmade-header': noHandmadeHeader,
   'no-handmade-empty-state': noHandmadeEmptyState,
   'no-native-title': noNativeTitle,
+  'no-copied-look': noCopiedLook,
 }
 
 /**
@@ -65,9 +68,10 @@ const appRules = {
  * app's version, UIG-7), and an app has no `.mdx` pages at all. `index.test.ts` holds the
  * apps' list to exactly the app rules.
  *
- * Four rules are in both sets: `no-restyled-part` (UIG-9), and the
+ * Five rules are in both sets: `no-restyled-part` (UIG-9), and the
  * fingerprints `no-handmade-header` (UIG-22), `no-handmade-empty-state`
- * (UIG-23) and `no-native-title` (UIG-24). The package restyles none of its own parts either (Katerina, 17
+ * (UIG-23), `no-native-title` (UIG-24) and `no-copied-look` (UIG-25, a
+ * warning). The package restyles none of its own parts either (Katerina, 17
  * September), and "my review isn't enough" (23 September).
  */
 const packageRules = {
@@ -79,6 +83,7 @@ const packageRules = {
   'no-handmade-header': noHandmadeHeader,
   'no-handmade-empty-state': noHandmadeEmptyState,
   'no-native-title': noNativeTitle,
+  'no-copied-look': noCopiedLook,
 }
 
 const rules = { ...appRules, ...packageRules }
@@ -97,8 +102,8 @@ export const PACKAGE_RULE_IDS = Object.keys(packageRules).map((name) => `${PLUGI
 /**
  * `recommended` switches every **app** rule on at the level it was ruled at: an
  * error blocks, a warning is reported and never blocks. `strict` makes every app
- * rule an error. With every app rule an error, the two are the same today; they part
- * when the first warning-level rule arrives (UIG-25).
+ * rule an error. They part at the first warning-level rule, `no-copied-look`
+ * (UIG-25): `recommended` warns on it, `strict` blocks on it.
  *
  * `package` is the inward set (UIG-5), which only this package runs.
  */
@@ -112,6 +117,8 @@ plugin.configs.recommended = {
     [`${PLUGIN_KEY}/no-handmade-header`]: 'error',
     [`${PLUGIN_KEY}/no-handmade-empty-state`]: 'error',
     [`${PLUGIN_KEY}/no-native-title`]: 'error',
+    // A warning, never an error (Katerina, 13 September): likeness is a judgement.
+    [`${PLUGIN_KEY}/no-copied-look`]: 'warn',
   },
 }
 plugin.configs.strict = {
@@ -122,7 +129,8 @@ plugin.configs.strict = {
 plugin.configs.package = {
   name: '@estiva-app/ui/package',
   plugins: { [PLUGIN_KEY]: plugin },
-  rules: Object.fromEntries(PACKAGE_RULE_IDS.map((id) => [id, 'error'])),
+  // Every inward rule blocks, but the copied look, which warns here too (UIG-25).
+  rules: Object.fromEntries(PACKAGE_RULE_IDS.map((id) => [id, id === `${PLUGIN_KEY}/no-copied-look` ? 'warn' : 'error'])),
 }
 
 export default plugin

package/src/eslint/looks-of.ts

@@ -0,0 +1,302 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve as resolvePath } from 'node:path'
+import ts from 'typescript'
+
+/**
+ * What a component looks like, read from its source: every class list it
+ * writes (UIG-25). Shared by the catalogue, which records each part's looks in
+ * `registry.json`, and by `estiva/no-copied-look`, which compares a class list
+ * typed by hand against them — so the two always mean the same thing by "look".
+ *
+ * A class list is read wherever it is written: a `className` (or any
+ * `…ClassName`), through `cn()`/`clsx()`, a ternary, a `&&`, a template, a
+ * `const` in the file, or a class map indexed by a key; and every string that
+ * is a class list on its own. A constant imported from another file is not
+ * followed: a look written once and imported is not a copy.
+ *
+ * Only the **look words** count — colour, text, border, corner, shadow.
+ * Placement (where it sits, how much room it takes) is everyone's and says
+ * nothing about which part a list is copied from.
+ */
+
+/** Where a thing sits and how much room it takes: never part of a look (the same list as `no-restyled-part`'s PLACEMENT). */
+const PLACEMENT = [
+  /^m[xytrblse]?-/,
+  /^p[xytrblse]?-/,
+  /^(?:w|h|size|min-w|min-h|max-w|max-h)-/,
+  /^(?:hidden|block|inline|inline-block|inline-flex|inline-grid|flex|grid|contents|flow-root)$/,
+  /^(?:grow|shrink)$|^(?:flex|basis|grow|shrink|order|gap|gap-x|gap-y|space-x|space-y|col|row|grid-cols|grid-rows|grid-flow|auto-cols|auto-rows)-/,
+  /^(?:self|justify|justify-items|justify-self|items|place-content|place-items|place-self)-|^content-(?!\[)/,
+  /^(?:static|relative|absolute|fixed|sticky)$|^(?:inset|inset-x|inset-y|top|right|bottom|left|start|end|z)-/,
+  /^(?:group|peer)(?:\/[\w-]+)?$/,
+]
+const bare = (token: string) => token.replace(/^(?:[^:\s[\]]+:)+/, '')
+export const isPlacementWord = (token: string) => PLACEMENT.some((pattern) => pattern.test(bare(token)))
+
+/** A word that could be a Tailwind class: lower case, dashes, variants, arbitrary values. */
+const CLASSY = /^!?(?:[a-z0-9-]+:|\[[^\]\s]+\]:)*-?[a-z@][a-z0-9-]*(?:-\[[^\]\s]+\]|\/[\w.[\]-]+|-[\w.]+)*$|^\[[^\]\s]+\]$/
+const words = (text: string) => text.split(/\s+/).filter(Boolean)
+const CLASS_FUNCTIONS = new Set(['cn', 'clsx', 'cx', 'twMerge', 'classNames'])
+const CLASS_PROP = /^(?:className|[a-z][A-Za-z]*ClassName)$/
+
+/** A string is a class list on its own when every word could be a class, and two at least have a dash or a variant. */
+function isClassList(text: string): boolean {
+  const list = words(text)
+  return list.length >= 3 && list.every((w) => CLASSY.test(w)) && list.filter((w) => /[-:[]/.test(w)).length >= 2
+}
+
+export interface ClassUnit {
+  /** Every class of the list, placement included, as written. */
+  tokens: string[]
+  /** Its look words only. */
+  look: string[]
+  /** Offsets in the file, for a report. */
+  start: number
+  end: number
+  /** A `className` (resolved through the file), or a string that is a class list on its own. */
+  via: 'attribute' | 'literal'
+  /** Where an escape for it is read: the element a `className` is on, or the string itself. */
+  anchor: number
+  /** The value of an exported `…_CLASSES` constant: a shared look, where it is written once. */
+  shared: boolean
+}
+
+const CAP = 24
+
+/**
+ * Every class list a file writes. `follow` resolves a name the file imports,
+ * for a part's own look: what it draws includes a look it takes from a shared
+ * file. A list being checked is never followed — using a shared look is not
+ * copying it.
+ */
+export function classUnits(source: ts.SourceFile, follow?: (name: string) => ts.Expression | undefined): ClassUnit[] {
+  const consts = new Map<string, ts.Expression>()
+  const collect = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isVariableDeclarationList(node.parent) && node.parent.flags & ts.NodeFlags.Const) {
+      consts.set(node.name.text, node.initializer)
+    }
+    ts.forEachChild(node, collect)
+  }
+  collect(source)
+
+  const product = (lists: string[][][]): string[][] => {
+    let out: string[][] = [[]]
+    for (const alternatives of lists) {
+      const next: string[][] = []
+      for (const a of out) for (const b of alternatives) if (next.length < CAP) next.push([...a, ...b])
+      out = next
+    }
+    return out
+  }
+  const resolve = (node: ts.Node | undefined, depth = 0): string[][] => {
+    if (!node || depth > 8) return [[]]
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return [words(node.text)]
+    if (ts.isTemplateExpression(node)) return product([[words(node.head.text)], ...node.templateSpans.flatMap((span) => [resolve(span.expression, depth + 1), [words(span.literal.text)]])])
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)) return resolve(node.expression, depth + 1)
+    if (ts.isJsxExpression(node)) return resolve(node.expression, depth + 1)
+    if (ts.isCallExpression(node)) return ts.isIdentifier(node.expression) && CLASS_FUNCTIONS.has(node.expression.text) ? product(node.arguments.map((a) => resolve(a, depth + 1))) : [[]]
+    if (ts.isConditionalExpression(node)) return [...resolve(node.whenTrue, depth + 1), ...resolve(node.whenFalse, depth + 1)].slice(0, CAP)
+    if (ts.isBinaryExpression(node)) {
+      // Off first: a look is the part at rest, with each option taken one at a time, never all at once.
+      if (node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) return [[], ...resolve(node.right, depth + 1)]
+      if (node.operatorToken.kind === ts.SyntaxKind.BarBarToken || node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) return [...resolve(node.left, depth + 1), ...resolve(node.right, depth + 1)].slice(0, CAP)
+      return [[]]
+    }
+    if (ts.isArrayLiteralExpression(node)) return product(node.elements.map((e) => resolve(e, depth + 1)))
+    if (ts.isObjectLiteralExpression(node)) return [[], node.properties.flatMap((p) => (p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) ? words(p.name.text) : []))]
+    if (ts.isIdentifier(node)) {
+      const init = consts.get(node.text) ?? follow?.(node.text)
+      return init ? resolve(init, depth + 1) : [[]]
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      let target: ts.Expression | undefined = node.expression
+      if (ts.isIdentifier(target)) target = consts.get(target.text) ?? follow?.(target.text)
+      while (target && (ts.isAsExpression(target) || ts.isSatisfiesExpression(target) || ts.isParenthesizedExpression(target))) target = target.expression
+      if (!target || !ts.isObjectLiteralExpression(target)) return [[]]
+      const key = ts.isPropertyAccessExpression(node) ? node.name.text : ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : null
+      return target.properties
+        .filter((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && (key === null || (!!p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === key)))
+        .flatMap((p) => resolve(p.initializer, depth + 1))
+        .slice(0, CAP)
+    }
+    return [[]]
+  }
+
+  const units: ClassUnit[] = []
+  const seen = new Set<string>()
+  const sharedAt = (node: ts.Node) => {
+    for (let at: ts.Node | undefined = node; at; at = at.parent) {
+      if (ts.isVariableDeclaration(at)) return ts.isIdentifier(at.name) && /_CLASSES$/.test(at.name.text) && !!at.parent?.parent && ts.isVariableStatement(at.parent.parent) && !!at.parent.parent.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    }
+    return false
+  }
+  // A string's escape is read above the line it starts: the widest thing that starts on that line.
+  const lineStart = (node: ts.Node) => {
+    const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line
+    let at = node
+    while (at.parent && !ts.isSourceFile(at.parent) && source.getLineAndCharacterOfPosition(at.parent.getStart(source)).line === line) at = at.parent
+    return at.getStart(source)
+  }
+  const add = (tokens: string[], node: ts.Node, via: ClassUnit['via'], anchor = via === 'literal' ? lineStart(node) : node.getStart(source)) => {
+    const list = [...new Set(tokens.filter((t) => CLASSY.test(t)))]
+    const look = list.filter((t) => !isPlacementWord(t))
+    if (look.length === 0) return
+    const key = `${via}:${node.getStart(source)}:${[...list].sort().join(' ')}`
+    if (seen.has(key)) return
+    seen.add(key)
+    units.push({ tokens: list, look, start: node.getStart(source), end: node.getEnd(), via, anchor, shared: via === 'literal' && sharedAt(node) })
+  }
+  const visit = (node: ts.Node) => {
+    if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && CLASS_PROP.test(node.name.text) && node.initializer) {
+      // An escape goes on the line above the element, as it does for every rule of the plugin.
+      const element = node.parent.parent
+      for (const alternative of resolve(node.initializer)) add(alternative, node, 'attribute', element.getStart(source))
+    }
+    if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && isClassList(node.text)) add(words(node.text), node, 'literal')
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return units
+}
+
+/** The function components a file declares, by name, with where each one's body is. */
+export function componentsOf(source: ts.SourceFile): Map<string, { start: number; end: number }> {
+  const found = new Map<string, { start: number; end: number }>()
+  const fn = (node: ts.Expression | undefined): ts.Node | undefined => {
+    let current = node
+    while (current && ts.isCallExpression(current) && current.arguments.length) current = current.arguments[0]
+    return current && (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) ? current : undefined
+  }
+  for (const statement of source.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name && /^[A-Z]/.test(statement.name.text)) found.set(statement.name.text, { start: statement.getStart(source), end: statement.getEnd() })
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        const body = fn(declaration.initializer)
+        if (ts.isIdentifier(declaration.name) && /^[A-Z]/.test(declaration.name.text) && body) found.set(declaration.name.text, { start: body.getStart(source), end: body.getEnd() })
+      }
+    }
+  }
+  return found
+}
+
+/** A look is worth comparing when it has this many look words at least: fewer is a text style, not a part. */
+export const MIN_LOOK_WORDS = 4
+
+/**
+ * Each named component's looks: its class lists' look words, one space-joined
+ * string per list, those with `MIN_LOOK_WORDS` or more. A list written outside
+ * every component of the file (a top-level constant, a class map) belongs to
+ * every component in it.
+ */
+export function looksOf(source: ts.SourceFile, names?: Iterable<string>): Map<string, string[]> {
+  const components = componentsOf(source)
+  const units = classUnits(source, importedConstants(source)).filter((u) => u.look.length >= MIN_LOOK_WORDS)
+  const inside = (u: ClassUnit, r: { start: number; end: number }) => u.start >= r.start && u.start < r.end
+  const out = new Map<string, string[]>()
+  for (const name of names ?? components.keys()) {
+    const range = components.get(name)
+    const mine = units.filter((u) => (range ? inside(u, range) : false) || ![...components.values()].some((r) => inside(u, r)))
+    out.set(name, [...new Set(mine.map((u) => u.look.join(' ')))])
+  }
+  return out
+}
+
+/** Read and parse a file for looks. */
+export function parseForLooks(fileName: string, text: string): ts.SourceFile {
+  return ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, fileName.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+}
+
+/** How much of a look a class list must share to be a copy of it (UIG-25, Katerina 24 September). */
+export const MIN_SHARED = 4
+export const MIN_COVER = 0.8
+
+/** The look words a list shares with a look, when it is a copy of it; otherwise null. */
+export function copies(list: string[], look: string[]): string[] | null {
+  const mine = new Set(list)
+  const shared = look.filter((word) => mine.has(word))
+  if (shared.length < MIN_SHARED) return null
+  return shared.length / Math.min(list.length, look.length) >= MIN_COVER ? shared : null
+}
+
+/** The file a relative or `@/` import names, from the file that imports it. */
+function importTarget(fromFile: string, specifier: string): string | null {
+  let base: string
+  if (specifier.startsWith('.')) base = resolvePath(dirname(fromFile), specifier)
+  else if (specifier.startsWith('@/')) {
+    let dir = dirname(resolvePath(fromFile))
+    while (!existsSync(join(dir, 'package.json')) && dirname(dir) !== dir) dir = dirname(dir)
+    base = join(dir, 'src', specifier.slice(2))
+  } else return null
+  for (const candidate of [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')]) if (existsSync(candidate)) return candidate
+  return null
+}
+
+const constantsCache = new Map<string, Map<string, ts.Expression>>()
+/** A file's top-level `const`s, by name. */
+function constantsOf(file: string): Map<string, ts.Expression> {
+  const cached = constantsCache.get(file)
+  if (cached) return cached
+  const found = new Map<string, ts.Expression>()
+  const source = parseForLooks(file, readFileSync(file, 'utf8'))
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const d of statement.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer) found.set(d.name.text, d.initializer)
+  }
+  constantsCache.set(file, found)
+  return found
+}
+
+/** A resolver for the class constants a file imports from its own repo: `FIELD_BOX_CLASSES` from `./looks`. */
+export function importedConstants(source: ts.SourceFile): (name: string) => ts.Expression | undefined {
+  const imported = new Map<string, { file: string; name: string }>()
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+    const bindings = statement.importClause?.namedBindings
+    if (!bindings || !ts.isNamedImports(bindings)) continue
+    const target = importTarget(source.fileName, statement.moduleSpecifier.text)
+    if (!target) continue
+    for (const element of bindings.elements) {
+      const local = element.name.text
+      if (/_CLASSES$/.test(element.propertyName?.text ?? local)) imported.set(local, { file: target, name: element.propertyName?.text ?? local })
+    }
+  }
+  return (name) => {
+    const from = imported.get(name)
+    if (!from) return undefined
+    try {
+      return constantsOf(from.file).get(from.name)
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/**
+ * The shared looks a file declares: each exported `…_CLASSES` constant, a string
+ * or a map of strings, by name (`FIELD_SIZE_CLASSES.small`). A hand-typed copy of
+ * one is told to use it.
+ */
+export function sharedLooksOf(source: ts.SourceFile): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const lookWords = (text: string) => words(text).filter((w) => CLASSY.test(w) && !isPlacementWord(w))
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue
+    for (const d of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(d.name) || !/_CLASSES$/.test(d.name.text) || !d.initializer) continue
+      let init: ts.Expression = d.initializer
+      while (ts.isAsExpression(init) || ts.isSatisfiesExpression(init) || ts.isParenthesizedExpression(init)) init = init.expression
+      if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+        const look = lookWords(init.text)
+        if (look.length >= MIN_LOOK_WORDS) out.set(d.name.text, [look.join(' ')])
+      } else if (ts.isObjectLiteralExpression(init)) {
+        for (const p of init.properties) {
+          if (!ts.isPropertyAssignment(p) || !p.name || !(ts.isIdentifier(p.name) || ts.isStringLiteral(p.name))) continue
+          if (!(ts.isStringLiteral(p.initializer) || ts.isNoSubstitutionTemplateLiteral(p.initializer))) continue
+          const look = lookWords(p.initializer.text)
+          if (look.length >= MIN_LOOK_WORDS) out.set(`${d.name.text}.${p.name.text}`, [look.join(' ')])
+        }
+      }
+    }
+  }
+  return out
+}

package/src/eslint/no-copied-look.test.ts

@@ -0,0 +1,155 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { ESLint, RuleTester } from 'eslint'
+import { parser } from 'typescript-eslint'
+import { describe, expect, it } from 'vitest'
+import { copies, looksOf, parseForLooks } from './looks-of'
+import { noCopiedLook } from './no-copied-look'
+import estiva from './index'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it.only
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } },
+  linterOptions: { reportUnusedDisableDirectives: 'off' },
+})
+
+/**
+ * Two small repos on disk: an app, with the package's catalogue installed beside
+ * it (`node_modules/@estiva-app/ui/registry.json`, its `looks`), and a copy of
+ * the package's own layout. The looks are the ones the parts have today.
+ */
+const root = mkdtempSync(join(tmpdir(), 'no-copied-look-'))
+const write = (path: string, text: string) => {
+  mkdirSync(dirname(join(root, path)), { recursive: true })
+  writeFileSync(join(root, path), text)
+}
+const SECTION_LABEL = 'text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary'
+const registry = (entries: { name: string; sourceFile: string; looks: string[] }[]) => JSON.stringify({ schemaVersion: 2, entries })
+write('app/package.json', '{ "name": "app" }')
+write(
+  'app/node_modules/@estiva-app/ui/registry.json',
+  registry([
+    { name: 'SectionLabel', sourceFile: 'src/SectionLabel.tsx', looks: [SECTION_LABEL] },
+    { name: 'Card', sourceFile: 'src/Card.tsx', looks: ['rounded-lg border bg-bg-surface border-border-default'] },
+    { name: 'Avatar', sourceFile: 'src/Avatar.tsx', looks: ['rounded-full bg-bg-inset text-text-secondary font-medium'] },
+  ]),
+)
+// The app's own reusable part, and its wrapper of the package's Avatar.
+write('app/src/components/ui/MetaText.tsx', "export function MetaText({ children }: { children: string }) {\n  return <span className=\"text-caption text-text-muted whitespace-nowrap signal:font-mono signal:text-small signal:tracking-wide signal:tabular-nums\">{children}</span>\n}\n")
+write('app/src/components/ui/Avatar.tsx', "import { Avatar as UiAvatar } from '@estiva-app/ui'\nexport function Avatar(props: { name: string }) {\n  return <UiAvatar {...props} />\n}\n")
+write('pkg/package.json', '{ "name": "@estiva-app/ui" }')
+write('pkg/src/TextInput.tsx', "export function TextInput() {\n  return <input className=\"bg-bg-inset border border-border-default hover:border-border-strong focus:border-border-focus rounded-lg px-3 py-2 text-input-value text-text-primary\" />\n}\n")
+write('app/src/components/ui/looks.ts', "export const WRITING_BOX_CLASSES = 'relative bg-bg-inset border border-border-default rounded-lg p-3 signal:focus-within:border-border-focus signal:focus-within:shadow-focus-ring'\n")
+write('pkg/src/looks.ts', "export const FIELD_BOX_CLASSES = 'bg-bg-inset border border-border-default hover:border-border-strong focus:border-border-focus rounded-lg'\n")
+
+const app = join(root, 'app/src/components/Probe.tsx')
+const appWrapper = join(root, 'app/src/components/ui/Avatar.tsx')
+const pkg = join(root, 'pkg/src/Textarea.tsx')
+const probe = (jsx: string) => `export function Probe() {\n  return (\n    ${jsx}\n  )\n}\n`
+
+tester.run('no-copied-look', noCopiedLook, {
+  valid: [
+    { name: 'placement only: where it sits is everyone’s', filename: app, code: probe('<div className="flex items-center gap-2 px-3 py-2 min-w-0 shrink-0" />') },
+    { name: 'three look words: a text style, not a part', filename: app, code: probe('<span className="text-caption text-text-muted truncate">x</span>') },
+    { name: 'the part used, not copied', filename: app, code: `import { SectionLabel } from '@estiva-app/ui'\n${probe('<SectionLabel tone="secondary">Files</SectionLabel>')}` },
+    {
+      name: 'a wrapper of the package’s part, named like it (Peek’s Avatar): its own look is the part’s, never a copy',
+      filename: appWrapper,
+      code: "import { Avatar as UiAvatar } from '@estiva-app/ui'\nexport function Avatar() {\n  return <span className=\"rounded-full bg-bg-inset text-text-secondary font-medium\"><UiAvatar /></span>\n}\n",
+    },
+    { name: 'a look written once in the package and imported is not a copy', filename: pkg, code: `import { FIELD_BOX_CLASSES } from './looks'\n${probe('<textarea className={FIELD_BOX_CLASSES} />')}` },
+    {
+      name: 'an escape with its reason',
+      filename: app,
+      code: probe(`<>\n      {/* @estiva-escape: recorded in GATES.md, a label strip Katerina left as it is */}\n      <span className="${SECTION_LABEL}">x</span>\n    </>`),
+    },
+  ],
+  invalid: [
+    {
+      name: 'the package’s SectionLabel, typed again in an app (the ticket’s ForeignObjectWidget case, in today’s words)',
+      filename: app,
+      code: probe(`<span className="min-w-0 ${SECTION_LABEL}">Assignee</span>`),
+      errors: [{ messageId: 'usePart' }],
+    },
+    {
+      name: 'the same look, the words in another order and one class more',
+      filename: app,
+      code: probe('<span className="text-text-secondary signal:tracking-widest signal:uppercase text-h5 signal:text-small signal:font-mono leading-3 shrink-0">x</span>'),
+      errors: [{ messageId: 'usePart' }],
+    },
+    {
+      name: 'a card’s frame in a const, used through cn(): reported once, at the const',
+      filename: app,
+      code: `import { cn } from '@/lib/utils'\nconst FRAME = 'rounded-lg border border-border-default bg-bg-surface'\n${probe('<div className={cn(FRAME, "p-3")} />')}`,
+      errors: [{ messageId: 'usePart', line: 2 }],
+    },
+    {
+      name: 'the app’s own part, typed again: covered because it is exported from src, with no list kept',
+      filename: app,
+      code: probe('<span className="text-caption text-text-muted whitespace-nowrap shrink-0 signal:font-mono signal:text-small signal:tracking-wide signal:tabular-nums">9:14</span>'),
+      errors: [{ messageId: 'usePart' }],
+    },
+    {
+      name: 'the package copying itself: Textarea typing TextInput’s field (the ticket’s TextInput ≈ Textarea)',
+      filename: pkg,
+      code: probe('<textarea className="bg-bg-inset border border-border-default hover:border-border-strong focus:border-border-focus rounded-lg px-3 py-2 text-input-value text-text-primary" />'),
+      errors: [{ messageId: 'shareIt' }],
+    },
+    {
+      name: 'a shared look typed again in the package: told to use it',
+      filename: pkg,
+      code: probe('<div className="bg-bg-inset border border-border-default hover:border-border-strong focus:border-border-focus rounded-lg" />'),
+      errors: [{ messageId: 'useShared' }],
+    },
+    {
+      name: 'an app’s own shared look typed again: told to use it (Peek’s writing box)',
+      filename: app,
+      code: probe('<div className="relative bg-bg-inset border border-border-default rounded-lg p-3 signal:focus-within:border-border-focus signal:focus-within:shadow-focus-ring" />'),
+      errors: [{ messageId: 'useShared' }],
+    },
+  ],
+})
+
+describe('looks', () => {
+  it('reads a part at rest with one option at a time, never every option at once', () => {
+    const source = parseForLooks('Card.tsx', "const FILL = { surface: 'bg-bg-surface border-border-default', inset: 'bg-bg-inset border-border-subtle' }\nexport function Card({ fill, selected }: { fill: 'surface' | 'inset'; selected: boolean }) {\n  return <div className={cn('rounded-lg border', FILL[fill], selected && 'bg-bg-selected border-accent-primary')} />\n}\n")
+    const looks = looksOf(source, ['Card']).get('Card') ?? []
+    expect(looks).toContain('rounded-lg border bg-bg-surface border-border-default')
+    expect(looks).toContain('rounded-lg border bg-bg-inset border-border-subtle')
+    expect(looks.some((l) => l.includes('bg-bg-surface') && l.includes('bg-bg-inset'))).toBe(false)
+  })
+
+  it('states its line: four look words, covering 80% of the shorter list', () => {
+    expect(copies(['a-1', 'b-1', 'c-1', 'd-1'], ['a-1', 'b-1', 'c-1', 'd-1', 'e-1'])).toHaveLength(4)
+    expect(copies(['a-1', 'b-1', 'c-1'], ['a-1', 'b-1', 'c-1'])).toBeNull()
+    expect(copies(['a-1', 'b-1', 'c-1', 'd-1', 'x-1', 'y-1'], ['a-1', 'b-1', 'c-1', 'd-1', 'e-1', 'f-1'])).toBeNull()
+  })
+})
+
+describe('a new part is covered the day it is added', () => {
+  it('reads the installed catalogue, so a part the package adds is compared without touching the rule', async () => {
+    const lint = async () => {
+      const eslint = new ESLint({
+        cwd: join(root, 'app'),
+        overrideConfigFile: true,
+        overrideConfig: [{ files: ['**/*.tsx'], languageOptions: { parser, parserOptions: { ecmaFeatures: { jsx: true } } }, ...estiva.configs.recommended }],
+      })
+      const [result] = await eslint.lintText(probe('<div className="rounded-full bg-accent-wash text-accent-primary font-semibold ring-1 ring-accent-outline">3</div>'), { filePath: app })
+      return result.messages.filter((m) => m.ruleId === 'estiva/no-copied-look')
+    }
+    expect(await lint()).toHaveLength(0)
+    write(
+      'app/node_modules/@estiva-app/ui/registry.json',
+      registry([{ name: 'CountBadge', sourceFile: 'src/CountBadge.tsx', looks: ['rounded-full bg-accent-wash text-accent-primary font-semibold ring-1 ring-accent-outline'] }]),
+    )
+    const found = await lint()
+    expect(found).toHaveLength(1)
+    // A warning, never an error (Katerina, 13 September).
+    expect(found[0].severity).toBe(1)
+    expect(found[0].message).toContain('CountBadge')
+  })
+})