@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/writing.md

@@ -0,0 +1,152 @@
+# Writing interface copy
+
+Kerf UI follows Apple's capitalization conventions for interface text.
+Apple's _Writing_ guidance asks for one style per UI element type, applied
+consistently, and its element guidance assigns those styles. This page is the
+package default, so every Kerf application, demo, and recipe uses the same
+rule. An application may replace it only through a written, product-wide
+style. It should never vary from one screen to the next.
+
+## Capitalization
+
+**Names are title style. Descriptions are sentence style.** Text that names a
+command, control, view, or field uses title style ("Save Draft", "Workspace
+Settings", "Release Date"). Text that describes, explains, reports, or asks
+uses sentence style ("Changes sync when you reconnect").
+
+| Element                                                                                             | Style                        | Examples                                               |
+| --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------ |
+| Buttons, split-button and toolbar actions, link-style commands                                      | Title                        | Save Draft, Add to Favorites, Don’t Save, Log In       |
+| Menu items, menu group headings, popup-menu triggers                                                | Title                        | Copy Reference, Sort By, Recently Updated, New Folder… |
+| Segmented-control segments, `Select` and pop-up choices, tabs                                       | Title                        | List View, Last 30 Days, In Review                     |
+| Page, view, pane, dialog, and toolbar titles (`ToolbarText` titles), back labels                    | Title                        | Workspace Settings, Back to Inbox                      |
+| Group and list headers (`ListHeader`), table column headings                                        | Title                        | Saved Projects, Needs Attention, Last Modified         |
+| Catalog example and stack labels (`CatalogExample`, `CatalogExampleStack`)                          | Title                        | Heading Identity Stays Whole, Icon Trigger in a Group  |
+| Content item titles: the name an item or card shows                                                 | Title                        | Build Output, Work Area, Unsaved Changes               |
+| Field labels (`FieldLabel`, a field's `label`)                                                      | Title                        | Project Name, Release Date                             |
+| Region and landmark names (accessible names of panes, toolbars, groups, lists, tab bars)            | Title                        | Ticket Workbench, View Actions, Open Documents         |
+| Accessible names of icon-only controls                                                              | Title                        | More Actions, Clear Search                             |
+| `EmptyState`, `StateBanner`, alert, and notification titles that are fragments                      | Title, no ending punctuation | No Release Tasks, Migration Needs Review               |
+| The same titles written as complete sentences                                                       | Sentence, with punctuation   | Release tasks could not be refreshed.                  |
+| Checkbox, switch, and radio option text                                                             | Sentence                     | Show hidden files, Notify me about replies             |
+| Body copy, `description`, `detail`, hints, empty-state and banner detail, dialog and alert messages | Sentence, with punctuation   | Changes sync when you reconnect.                       |
+| Tooltips and help text                                                                              | Sentence                     | Copy the link to this ticket                           |
+| Placeholders                                                                                        | Sentence                     | Search tickets                                         |
+| Status lines, counts, and timestamps (`ToolbarText` status, `Badge`, `CornerStatus`)                | Sentence                     | Saved just now, 3 of 12 updated                        |
+| Progress labels (`LoadingSpinner` and `Skeleton` `label`): the operation under way                  | Sentence, trailing ellipsis  | Loading preview…, Refreshing release tasks…            |
+
+A name that a component composes into a longer label is a name too, so pass
+it in title style. A panel toolbar's `toggle: { action, name }` labels the
+toggle group with `name` and completes "Show …" / "Hide …" with it:
+`name: "Navigator"` gives "Show Navigator". Kerf UI never recapitalizes it.
+
+Data is never recapitalized. Names that a person or a system supplies keep
+their own spelling: file names, ticket titles, user names, and tags. So do
+code identifiers shown as text, such as a prop value a specimen is labeled
+with (`danger`, `transparent`). A content
+item that shows such data (a ticket subject, a message) keeps it as written;
+only a title the interface itself names is title style. `ContentItem`'s own
+`title` prop is a native tooltip, so it is sentence style. Keep a content
+item's `ariaLabel` equal to its visible title.
+
+### Title-style rules
+
+From the [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web)
+(_capitalization_):
+
+- **Capitalize** the first and last word, whatever their part of speech.
+- **Capitalize** nouns, pronouns, verbs, adjectives, and adverbs, however
+  short: It, This, Your, Is, Are, Be.
+- **Capitalize** subordinating conjunctions such as If, and prepositions of
+  five letters or more: About, Between, Through.
+- **Capitalize** a preposition of any length that belongs to a phrasal verb
+  or acts as another part of speech: Start Up the Computer, Turn On, Log In to
+  the Server.
+- **Capitalize** the second word of a hyphenated compound: High-Level Events,
+  Pop-Up Menu. Built-in and Plug-in are the exceptions.
+- **Keep lowercase**:
+  - articles (a, an, the), unless one is the first word or follows a colon;
+  - coordinating conjunctions (and, but, or, nor, for, yet, so);
+  - _to_ in an infinitive (How to Start Your Computer);
+  - _as_ (Export a Document as a PDF);
+  - prepositions of four letters or fewer (at, by, for, from, in, into, of,
+    off, on, onto, out, over, to, up, with).
+- **Keep the brand's own spelling** for words that always start lowercase,
+  such as iPad, iOS, and macOS.
+
+### Sentence-style rules
+
+Capitalize the first word and proper nouns or adjectives only. End a complete
+sentence with punctuation. Leave a fragment without ending punctuation.
+Tooltips may omit the final period.
+
+### Related conventions
+
+- An ellipsis (…) ends a command or menu item that needs more input before it
+  acts: New Ticket…, Save As…. The dialog it opens repeats the command as its
+  title, without the ellipsis.
+- Label an action with its result. Prefer a verb: Publish Update, not OK.
+- Keep a control's accessible name equal to its visible label, or starting
+  with it.
+
+## Diagnostics
+
+`kerf-ui-doctor` reports `KUI-D040` (warning) when a string or template
+literal passed to a known title-style prop leaves a word lowercase that title
+style capitalizes. In a template literal it judges only the static words:
+`` `Edit ${name} shortcut` `` should be `` `Edit ${name} Shortcut` ``, and the
+interpolated value keeps its own spelling. The covered props are:
+
+- `ToolbarText` `text` when the text is a title: it has `headingLevel`, a
+  large size, or sits in a toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` `label`;
+- `CatalogExample` and `CatalogExampleStack` `label`;
+- `EmptyState` and `StateBanner` `title`;
+- `PopupMenu` `text` and item and heading labels, including submenus;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }`;
+- region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
+  `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
+  `FloatingToolbar`, and `ResizableRegion`, the `ariaLabel` of `SunkenPanel`
+  and `List`, a `Pane`'s `contentLabel`, the panel, toolbar, and pane labels
+  inside `Workbench`, `CollapsiblePanel`, and `NavStack` configuration, and
+  the `aria-label` of a landmark element (`section`, `nav`, `aside`, `main`,
+  `header`, `footer`, `form`, `search`) or landmark role;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`;
+- the accessible names of icon-only controls: `IconButton` and
+  `IconToggleButton` `label`, `PopupMenu` `label`, `SplitButton`
+  `optionsLabel`, `TokenSearchField` `clearLabel`, and the `aria-label` of a
+  `button` or `wa-button` whose only content is an icon.
+
+The check never judges sentence-style surfaces (including `wa-checkbox`,
+`wa-switch`, and `wa-radio` option text and the `LoadingSpinner` and
+`Skeleton` status labels), interpolated or other dynamic values, or text
+ending with `.`, `!`, or `?`. It skips a word joined to an interpolation, tokens containing digits, code, or paths, and
+lowercase-led brands such as iOS. It does not report capitalized short words,
+because Apple capitalizes a phrasal verb's particle. Suppress `KUI-D040` for a
+lowercase brand or product name. See [the doctor](./ui-doctor.md).
+
+## Sources
+
+- Apple Human Interface Guidelines,
+  [Writing](https://developer.apple.com/design/human-interface-guidelines/writing):
+  choose a capitalization style for each element type and use it consistently.
+- [Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
+  and [The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar):
+  menu items and multi-word menu titles use title-style capitalization.
+- [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+  and [Notifications](https://developer.apple.com/design/human-interface-guidelines/notifications):
+  a fragment title uses title style. A complete-sentence title and the
+  message use sentence style with punctuation.
+- [Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help):
+  tooltips use sentence case.
+- The archived OS X Human Interface Guidelines, _Use the Right Capitalization
+  Style in Labels and Text_. Title style covers menu titles and items, push
+  buttons, toolbar item labels, and labels that are not sentences, such as
+  group box and list headings. Sentence style covers checkbox and radio option
+  text and dialog messages.
+- [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web),
+  _capitalization_: the title-style word rules above.

package/doctor/cli.mjs

@@ -54,6 +54,7 @@ Options:
   --browser <list>       Comma-separated chromium,firefox,webkit
   --eslint <preset>      recommended-ui or strict-ui
   --format <format>      text or json (default: text)
+  --fail-on <severity>   error, review, or warning (default: error)
   --output <path>        Also write the merged report
   --no-cache             Disable the content-addressed cache
 
@@ -68,6 +69,7 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
   const browserList = take('--browser');
   const eslintConfig = take('--eslint') ?? 'recommended-ui';
   const format = take('--format') ?? 'text';
+  const failOn = take('--fail-on');
   const output = take('--output');
   const full = args.includes('--full');
   const changed = args.includes('--changed');
@@ -80,6 +82,8 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
     throw new Error('--full and --changed are mutually exclusive.');
   if (!['text', 'json'].includes(format))
     throw new Error('--format must be text or json.');
+  if (failOn && !['error', 'review', 'warning'].includes(failOn))
+    throw new Error('--fail-on must be error, review, or warning.');
   if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
     throw new Error('--eslint must be recommended-ui or strict-ui.');
   const abort = new globalThis.AbortController();
@@ -95,6 +99,7 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
     cache: !noCache,
     signal: abort.signal,
     eslintConfig,
+    failOn,
     browser: url
       ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
       : undefined,

package/doctor/component-style-checks.mjs

@@ -0,0 +1,457 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
+
+import postcss from 'postcss';
+import ts from 'typescript';
+
+import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
+import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
+
+const scriptExtensions = new Set(['.tsx', '.jsx']);
+const kebab = (name) =>
+  name
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+const componentName = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+const classNames = (value) =>
+  [...value.matchAll(/(?:^|\s)([a-z][a-z0-9_-]*)(?=\s|$)/g)].map(
+    (match) => match[1],
+  );
+const block = (name) => name.split(/__|--/)[0];
+const unknown = '\u0000';
+
+function combinations(left, right) {
+  if (left.length * right.length > 32) return [unknown];
+  return left.flatMap((a) => right.map((b) => a + b));
+}
+
+function staticPatterns(node, bindings = new Map(), seen = new Set()) {
+  if (!node) return [unknown];
+  if (ts.isIdentifier(node) && bindings.has(node.text) && !seen.has(node.text))
+    return staticPatterns(
+      bindings.get(node.text),
+      bindings,
+      new Set([...seen, node.text]),
+    );
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'join'
+  ) {
+    const target = node.expression.expression;
+    const array = ts.isIdentifier(target) ? bindings.get(target.text) : target;
+    if (array && ts.isArrayLiteralExpression(array)) {
+      const separator =
+        node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+          ? node.arguments[0].text
+          : ',';
+      let patterns = [''];
+      for (const [index, element] of array.elements.entries())
+        patterns = combinations(
+          patterns,
+          staticPatterns(element, bindings, seen).map(
+            (part) => `${index ? separator : ''}${part}`,
+          ),
+        );
+      return patterns;
+    }
+  }
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return staticPatterns(node.expression, bindings, seen);
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    return [node.text];
+  if (ts.isConditionalExpression(node))
+    return [
+      ...new Set([
+        ...staticPatterns(node.whenTrue, bindings, seen),
+        ...staticPatterns(node.whenFalse, bindings, seen),
+      ]),
+    ];
+  if (ts.isTemplateExpression(node)) {
+    let patterns = [node.head.text];
+    for (const span of node.templateSpans)
+      patterns = combinations(
+        combinations(patterns, staticPatterns(span.expression, bindings, seen)),
+        [span.literal.text],
+      );
+    return patterns;
+  }
+  if (
+    ts.isBinaryExpression(node) &&
+    node.operatorToken.kind === ts.SyntaxKind.PlusToken
+  )
+    return combinations(
+      staticPatterns(node.left, bindings, seen),
+      staticPatterns(node.right, bindings, seen),
+    );
+  return [unknown];
+}
+
+function guaranteedClasses(node, bindings) {
+  if (!node) return new Set();
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return guaranteedClasses(node.expression, bindings);
+  const patterns = staticPatterns(node, bindings);
+  const classes = new Set(classNames(patterns[0]));
+  for (const pattern of patterns.slice(1)) {
+    const other = new Set(classNames(pattern));
+    for (const name of classes) if (!other.has(name)) classes.delete(name);
+  }
+  return classes;
+}
+
+function returnedIntrinsic(node) {
+  while (node && ts.isParenthesizedExpression(node)) node = node.expression;
+  if (node && ts.isConditionalExpression(node))
+    return (
+      returnedIntrinsic(node.whenTrue) && returnedIntrinsic(node.whenFalse)
+    );
+  const tag =
+    node && ts.isJsxElement(node)
+      ? node.openingElement.tagName
+      : node && ts.isJsxSelfClosingElement(node)
+        ? node.tagName
+        : undefined;
+  return Boolean(tag && ts.isIdentifier(tag) && /^[a-z]/.test(tag.text));
+}
+
+function belongsToComponentReturn(node, owner) {
+  let scope = node.parent;
+  while (scope && !ts.isFunctionLike(scope)) scope = scope.parent;
+  if (!scope) return false;
+  if (ts.isFunctionDeclaration(scope)) return scope.name?.text === owner;
+  return (
+    ts.isArrowFunction(scope) &&
+    ts.isVariableDeclaration(scope.parent) &&
+    ts.isIdentifier(scope.parent.name) &&
+    scope.parent.name.text === owner
+  );
+}
+
+async function catalogAliases(workspaceRoot, packageRoot) {
+  const aliases = new Map();
+  const profile = await loadApplicationUiProfile({
+    workspaceRoot,
+    startDirectory: packageRoot,
+    knownRules: [],
+    packageProfile: resolve(
+      import.meta.dirname,
+      '../ai/application-ui-profile.defaults.json',
+    ),
+  });
+  for (const catalog of profile.profile?.catalogs ?? []) {
+    const owner = profile.provenance?.[`$catalogs.${catalog.package}`];
+    if (!owner || !catalog.selection?.path) continue;
+    try {
+      const selection = JSON.parse(
+        await readFile(resolve(dirname(owner), catalog.selection.path), 'utf8'),
+      );
+      const composition = catalog.composition?.path
+        ? JSON.parse(
+            await readFile(
+              resolve(dirname(owner), catalog.composition.path),
+              'utf8',
+            ),
+          )
+        : { entries: [] };
+      const composed = new Map(
+        (composition.entries ?? []).map((entry) => [entry.key, entry]),
+      );
+      for (const entry of selection.entries ?? []) {
+        if (!entry.source || !entry.name) continue;
+        const source = resolve(dirname(owner), entry.source);
+        const relativeSource = relative(packageRoot, source);
+        if (relativeSource === '..' || relativeSource.startsWith('../'))
+          continue;
+        const detail = composed.get(
+          `${selection.package ?? catalog.package}:${entry.id}`,
+        );
+        const classes = [
+          detail?.boundaries?.rootClass,
+          ...(detail?.boundaries?.publicClasses ?? []),
+          ...(entry.publicClasses ?? []),
+        ].filter(Boolean);
+        const styleSources = [
+          ...(detail?.styleSources ?? []),
+          ...(entry.styleSources ?? []),
+        ].map((style) => resolve(dirname(owner), style));
+        aliases.set(`${source}:${entry.name}`, {
+          classes: new Set(classes),
+          styles: new Set(styleSources),
+        });
+      }
+    } catch {
+      // The catalog stage reports invalid or missing artifacts.
+    }
+  }
+  return aliases;
+}
+
+function componentFacts(file, source) {
+  const syntax = file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
+  const ast = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    syntax,
+  );
+  const components = new Map();
+  const visit = (node, owner) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    else if (
+      owner &&
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer
+    )
+      components.get(owner)?.bindings.set(node.name.text, node.initializer);
+    if (
+      owner &&
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node))
+    ) {
+      if (ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
+        for (const attribute of node.attributes.properties) {
+          if (
+            !ts.isJsxAttribute(attribute) ||
+            !['class', 'className'].includes(attribute.name.text)
+          )
+            continue;
+          const value = attribute.initializer;
+          const classes =
+            value && ts.isStringLiteral(value)
+              ? classNames(value.text)
+              : value && ts.isJsxExpression(value)
+                ? guaranteedClasses(
+                    value.expression,
+                    components.get(owner)?.bindings,
+                  )
+                : [];
+          if (
+            value &&
+            ts.isJsxExpression(value) &&
+            staticPatterns(
+              value.expression,
+              components.get(owner)?.bindings,
+            ).every((pattern) => pattern === unknown)
+          )
+            components.get(owner).uncertain = true;
+          for (const name of classes) components.get(owner)?.add(name);
+        }
+      }
+    }
+    if (
+      owner &&
+      ts.isReturnStatement(node) &&
+      belongsToComponentReturn(node, owner) &&
+      returnedIntrinsic(node.expression)
+    )
+      components.get(owner).intrinsic = true;
+    if (
+      owner &&
+      ts.isArrowFunction(node) &&
+      ts.isVariableDeclaration(node.parent) &&
+      ts.isIdentifier(node.parent.name) &&
+      node.parent.name.text === owner &&
+      returnedIntrinsic(node.body)
+    )
+      components.get(owner).intrinsic = true;
+    ts.forEachChild(node, (child) => visit(child, owner));
+  };
+  const declarations = (node) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
+    ts.forEachChild(node, declarations);
+  };
+  declarations(ast);
+  visit(ast);
+  return components;
+}
+
+function diagnostic(id, file, line, message, action) {
+  return {
+    id,
+    severity: 'error',
+    stage: 'analyzer',
+    message,
+    location: { file, line, column: 1 },
+    action,
+    documentation: '@kerfjs/ui/docs/ui-doctor.md#component-style-naming',
+    meaning: {
+      'KUI-D030': 'Component root class does not match its name',
+      'KUI-D031': 'Component stylesheet does not match its name',
+      'KUI-D032': 'Stylesheet selects another component class',
+    }[id],
+  };
+}
+
+export async function checkComponentStyles(
+  packageRoot,
+  inputs,
+  ownershipGroups = [],
+  selectedPaths,
+  workspaceRoot = packageRoot,
+) {
+  const aliases = await catalogAliases(workspaceRoot, packageRoot);
+  const scripts = new Map();
+  const styles = new Map();
+  const importedBy = new Map();
+  for (const file of inputs) {
+    if (isUiTraversalExcluded(packageRoot, file)) continue;
+    const extension = extname(file);
+    if (scriptExtensions.has(extension)) {
+      const source = await readFile(file, 'utf8');
+      scripts.set(file, componentFacts(file, source));
+      for (const match of source.matchAll(
+        /\bimport\s*(?:['"]|[^;]*?\bfrom\s*['"])(\.[^'"]+\.css)['"]/g,
+      )) {
+        const style = resolve(dirname(file), match[1]);
+        const importers = importedBy.get(style) ?? [];
+        importers.push(file);
+        importedBy.set(style, importers);
+      }
+    } else if (extension === '.css')
+      styles.set(file, await readFile(file, 'utf8'));
+  }
+  const owners = new Map();
+  for (const [file, components] of scripts)
+    for (const [name, classes] of components)
+      if (classes.has(kebab(name)))
+        owners.set(kebab(name), { file, name, classes });
+  const diagnostics = [];
+  for (const [file, source] of styles) {
+    if (
+      ownershipGroups.some((group) =>
+        group.styleSources?.some(
+          (style) => resolve(packageRoot, style) === file,
+        ),
+      )
+    )
+      continue;
+    const stem = basename(file, '.css');
+    const pair =
+      [...scriptExtensions]
+        .map((extension) => resolve(dirname(file), `${stem}${extension}`))
+        .find((candidate) => scripts.has(candidate)) ??
+      (importedBy.get(file)?.length === 1
+        ? importedBy.get(file)[0]
+        : undefined);
+    if (!pair) continue;
+    const path = relative(packageRoot, file).replaceAll('\\', '/');
+    if (
+      selectedPaths?.length &&
+      !selectedPaths.includes(path) &&
+      !selectedPaths.includes(relative(packageRoot, pair).replaceAll('\\', '/'))
+    )
+      continue;
+    const components = scripts.get(pair);
+    const matching =
+      [...components].find(([name]) => kebab(name) === stem) ??
+      [...components].find(([name]) =>
+        aliases.get(`${pair}:${name}`)?.styles.has(file),
+      );
+    if (!matching) {
+      const names = [...components.keys()];
+      if (names.length === 1)
+        diagnostics.push(
+          diagnostic(
+            'KUI-D031',
+            path,
+            1,
+            `${basename(file)} is paired with ${basename(pair)}, but its component ${names[0]} calls for ${kebab(names[0])}.css.`,
+            `Rename the stylesheet and its import to ${kebab(names[0])}.css, or rename the component and source pair.`,
+          ),
+        );
+      continue;
+    }
+    const [name, renderedClasses] = matching;
+    const declaredClasses =
+      aliases.get(`${pair}:${name}`)?.classes ?? new Set();
+    if (
+      renderedClasses.intrinsic &&
+      !renderedClasses.uncertain &&
+      !renderedClasses.has(stem) &&
+      ![...declaredClasses].some((className) => renderedClasses.has(className))
+    )
+      diagnostics.push(
+        diagnostic(
+          'KUI-D030',
+          relative(packageRoot, pair).replaceAll('\\', '/'),
+          1,
+          `${name} must render its own .${stem} root class.`,
+          `Add class="${stem}" to an element rendered by ${name}, then select that class in ${basename(file)}.`,
+        ),
+      );
+    let sheet;
+    try {
+      sheet = postcss.parse(source, { from: file });
+    } catch {
+      continue;
+    }
+    sheet.walkRules((rule) => {
+      if (
+        rule.parent?.type === 'atrule' &&
+        /keyframes$/i.test(rule.parent.name)
+      )
+        return;
+      const selected = [
+        ...new Set(
+          [...rule.selector.matchAll(/\.([a-z][a-z0-9_-]*)/gi)].map(
+            (match) => match[1],
+          ),
+        ),
+      ];
+      for (const className of selected) {
+        const foreign = owners.get(block(className));
+        if (!foreign || foreign.name === name || foreign.file === pair)
+          continue;
+        diagnostics.push(
+          diagnostic(
+            'KUI-D032',
+            path,
+            rule.source?.start?.line ?? 1,
+            `${basename(file)} selects .${className}, which belongs to ${foreign.name} in ${relative(packageRoot, foreign.file).replaceAll('\\', '/')}.`,
+            `Move this rule to ${kebab(foreign.name)}.css or configure ${foreign.name} through its public API.`,
+          ),
+        );
+      }
+    });
+  }
+  return diagnostics;
+}

package/doctor/config.schema.json

@@ -9,6 +9,31 @@
     "schemaVersion": { "const": 1 },
     "mode": { "enum": ["full", "changed"] },
     "package": { "type": "string", "minLength": 1 },
+    "ownership": { "enum": ["package", "component"] },
+    "ownershipContext": { "enum": ["subject", "any", "any-package"] },
+    "implicitComponentOwnership": { "type": "boolean" },
+    "ownershipGroups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["styleSources", "sources"],
+        "properties": {
+          "styleSources": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/path" }
+          },
+          "sources": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/path" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "stages": {
       "type": "object",
       "properties": {
@@ -37,6 +62,7 @@
       "additionalProperties": false
     },
     "cache": { "type": "boolean" },
+    "failOn": { "enum": ["error", "review", "warning"] },
     "suppressions": {
       "type": "array",
       "items": {