@teamblind-chorus/ui 1.0.0

package/eslint/README.md

@@ -0,0 +1,79 @@
+# `@teamblind-chorus/ui/eslint` — Chorus lint preset
+
+The **deterministic backstop for "Chorus First."** LOVABLE.md and the other agent
+guides are prose — they can be skipped, truncated past the paste cap, or diluted
+as a chat grows, after which the model drifts back to its shadcn/Tailwind prior.
+This preset runs in the **consumer project's own toolchain**, so it flags
+design-system violations regardless of whether the agent read or remembered the
+guide. An AI builder's lint-error fix loop reads these errors and self-corrects.
+
+## What it catches
+
+| Rule | Severity | Catches | "Chorus First" failure it guards |
+| :--- | :--- | :--- | :--- |
+| `chorus/no-raw-hex` | error | `'#1A1A1A'`, `#fff` in any string (style, className, props) | ignoring color tokens |
+| `chorus/no-tailwind-color` | error | `bg-white`, `text-black`, `border-gray-200`, `hover:bg-blue-500` in `className` | ignoring color tokens |
+| `chorus/no-raw-cta` | error | raw `<button>`; `<a>` used as an action (`onClick` / no `href`) | escaping to non-Chorus |
+| `chorus/no-offscale-space` | warn | `fontSize: 13`, `gap: 6`, `padding: '10px 12px'`, `borderRadius: 6` in inline `style` | ignoring spacing/typo/radius tokens |
+| `no-restricted-imports` (built-in) | error | `@/components/ui/*` (shadcn), `@/components/chorus/*` (legacy mirror) | escaping to non-Chorus |
+
+Rules report only on **statically-known** values — runtime-computed expressions
+(`var(...)`, `calc(...)`, identifiers, conditionals) are left alone, so false
+positives stay near zero.
+
+## Setup
+
+Requires ESLint 9 (flat config).
+
+```bash
+npm install -D eslint
+```
+
+### JavaScript / JSX projects (turnkey)
+
+```js
+// eslint.config.js
+import chorus from "@teamblind-chorus/ui/eslint";
+
+export default [
+  ...chorus,
+];
+```
+
+### TypeScript / TSX projects
+
+The preset is parser-agnostic — layer its rules onto your TypeScript parser so
+they also run on `.ts` / `.tsx`:
+
+```js
+// eslint.config.js
+import tseslint from "typescript-eslint";
+import { plugin as chorus, recommendedRules, restrictedImports } from "@teamblind-chorus/ui/eslint";
+
+export default [
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.{ts,tsx}"],
+    plugins: { chorus },
+    rules: {
+      ...recommendedRules,
+      "no-restricted-imports": restrictedImports,
+    },
+  },
+];
+```
+
+## Escape hatch
+
+These are hard rules, not preferences — a hit means regenerate, not suppress.
+For the rare legitimate exception (a real external `<a href>`, an intentional
+non-token literal authorized in `DESIGN.md § Adapting Chorus`), disable on the
+single line and say why:
+
+```jsx
+{/* eslint-disable-next-line chorus/no-offscale-space -- intrinsic slot geometry per DESIGN.md */}
+<div style={{ width: 48 }} />
+```
+
+If a value has no token and isn't an authorized exception, that's a **Chorus
+gap** to report — not a license to disable the rule.

package/eslint/index.js

@@ -0,0 +1,78 @@
+// Chorus ESLint preset — the deterministic backstop for "Chorus First".
+//
+// Prose guardrails in LOVABLE.md can be skipped, truncated, or diluted as a
+// session grows; this preset runs in the consumer project's own toolchain, so
+// it catches design-system violations whether or not the agent read (or
+// remembered) the guide. An AI builder's lint-error fix loop sees these errors
+// and self-corrects.
+//
+// Flat config (ESLint 9+). Two ways to consume:
+//
+//   // eslint.config.js — JavaScript / JSX projects (turnkey)
+//   import chorus from "@teamblind-chorus/ui/eslint";
+//   export default [ ...chorus ];
+//
+//   // eslint.config.js — TypeScript / TSX projects (layer onto your TS parser)
+//   import tseslint from "typescript-eslint";
+//   import { plugin as chorus, recommendedRules } from "@teamblind-chorus/ui/eslint";
+//   export default [
+//     ...tseslint.configs.recommended,
+//     { files: ["**/*.{ts,tsx}"], plugins: { chorus }, rules: recommendedRules },
+//   ];
+
+import { rules } from "./rules.js";
+
+export const plugin = {
+  meta: { name: "@teamblind-chorus/ui/eslint", version: "0.1.0" },
+  rules,
+};
+
+// The Chorus rules. Color/import/CTA/link violations are hard errors (they
+// produce visibly off-brand or broken UI); off-scale spacing and full-bleed
+// wrapping are warnings — real, but the lowest-severity drift and the highest
+// false-positive risk (spatial heuristics over statically-known padding).
+export const recommendedRules = {
+  "chorus/no-raw-hex": "error",
+  "chorus/no-tailwind-color": "error",
+  "chorus/no-raw-cta": "error",
+  "chorus/no-offscale-space": "warn",
+  "chorus/no-fullbleed-wrapper": "warn",
+  "chorus/no-redundant-link": "error",
+  "chorus/no-reinvented-family": "warn",
+};
+
+// Escaping to shadcn / the removed legacy mirror is caught by a built-in rule —
+// no custom AST needed.
+export const restrictedImports = [
+  "error",
+  {
+    patterns: [
+      {
+        group: ["@/components/ui", "@/components/ui/*"],
+        message: "shadcn UI is forbidden under Chorus First — import the equivalent from @teamblind-chorus/ui.",
+      },
+      {
+        group: ["@/components/chorus", "@/components/chorus/*"],
+        message: "The legacy Chorus mirror was removed — import from the @teamblind-chorus/ui package.",
+      },
+    ],
+  },
+];
+
+const recommended = {
+  name: "chorus/recommended",
+  files: ["**/*.{js,jsx,mjs,cjs}"],
+  languageOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+  plugins: { chorus: plugin },
+  rules: {
+    ...recommendedRules,
+    "no-restricted-imports": restrictedImports,
+  },
+};
+
+// Default export: a flat-config array. Spread it into eslint.config.js.
+export default [recommended];

package/eslint/rules.js

@@ -0,0 +1,472 @@
+// Custom ESLint rules that enforce Chorus design-system invariants in CONSUMER
+// code (the app a Lovable/AI agent generates against @teamblind-chorus/ui). These are
+// the deterministic backstop for the four "Chorus First" failure modes that
+// prose guardrails in LOVABLE.md cannot guarantee:
+//
+//   1. escaping to non-Chorus       → no-shadcn-import (built-in), no-raw-cta
+//   2. ignoring tokens (color)      → no-raw-hex, no-tailwind-color
+//   3. ignoring tokens (spacing/typo) → no-offscale-space
+//
+// Plain ESM, no build step. AST-based (ESTree + JSX) so they work under espree
+// (.js/.jsx) and typescript-eslint (.ts/.tsx) alike — any parser that emits the
+// standard JSX nodes. Rules report only on statically-known violations to keep
+// false positives near zero; runtime-computed values are left alone.
+
+const HEX_COLOR = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/;
+
+// Tailwind color utilities: <prefix>-<palette>-<shade> | <prefix>-{white,black,…}
+// Matches `bg-white`, `text-black`, `border-gray-200`, and state/responsive
+// variants like `hover:bg-blue-500`, `dark:text-white/80`.
+const TW_PALETTE =
+  'slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose';
+const TW_PREFIX =
+  'bg|text|border|ring|ring-offset|from|via|to|fill|stroke|divide|outline|decoration|caret|accent|placeholder|shadow';
+const TW_COLOR = new RegExp(
+  `(?:^|[\\s:])(?:${TW_PREFIX})-(?:(?:${TW_PALETTE})-\\d{2,3}|white|black|transparent|current|inherit)(?:\\/\\d{1,3})?\\b`,
+);
+
+// Style props where every value must resolve to a token (var/calc) or a
+// structural keyword. A raw number or px/rem string here is off-scale drift.
+const TOKEN_ONLY_PROPS = new Set([
+  'gap', 'rowGap', 'columnGap',
+  'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+  'paddingInline', 'paddingBlock', 'paddingInlineStart', 'paddingInlineEnd',
+  'margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft',
+  'marginInline', 'marginBlock',
+  'fontSize', 'lineHeight', 'letterSpacing', 'fontWeight',
+  'borderRadius', 'borderWidth',
+]);
+
+const STRUCTURAL_VALUE = /^(0|auto|100%|inherit|initial|unset|none|normal)$/;
+
+function stringIsTokenLike(raw) {
+  const s = String(raw).trim();
+  if (STRUCTURAL_VALUE.test(s)) return true;
+  if (s.includes('var(') || s.includes('calc(') || s.includes('clamp(')) return true;
+  if (/^-?\d+(\.\d+)?%$/.test(s)) return true; // bare percentage
+  return false;
+}
+
+// Collect every statically-known string from a JSX attribute value:
+// plain string literals, the static quasis of template literals, and string
+// arguments to helpers like clsx()/cn()/classNames(). Dynamic parts are skipped.
+function collectStaticStrings(node, out) {
+  if (!node) return;
+  switch (node.type) {
+    case 'Literal':
+      if (typeof node.value === 'string') out.push(node.value);
+      break;
+    case 'TemplateLiteral':
+      for (const q of node.quasis) out.push(q.value.cooked ?? q.value.raw);
+      for (const ex of node.expressions) collectStaticStrings(ex, out);
+      break;
+    case 'JSXExpressionContainer':
+      collectStaticStrings(node.expression, out);
+      break;
+    case 'CallExpression':
+      for (const arg of node.arguments) collectStaticStrings(arg, out);
+      break;
+    case 'ArrayExpression':
+      for (const el of node.elements) collectStaticStrings(el, out);
+      break;
+    case 'ObjectExpression':
+      // clsx({ 'bg-white': cond }) — keys carry the class names
+      for (const prop of node.properties) {
+        if (prop.type === 'Property' && !prop.computed) {
+          if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') out.push(prop.key.value);
+          else if (prop.key.type === 'Identifier') out.push(prop.key.name);
+        }
+      }
+      break;
+    case 'ConditionalExpression':
+      collectStaticStrings(node.consequent, out);
+      collectStaticStrings(node.alternate, out);
+      break;
+    case 'LogicalExpression':
+      collectStaticStrings(node.left, out);
+      collectStaticStrings(node.right, out);
+      break;
+    default:
+      break;
+  }
+}
+
+function jsxAttrName(attr) {
+  return attr && attr.type === 'JSXAttribute' && attr.name && attr.name.type === 'JSXIdentifier'
+    ? attr.name.name
+    : null;
+}
+
+// Chorus families that own their page-rail inline padding internally
+// (layoutInset="full-bleed"). Wrapping one in a padded element, passing it
+// inline padding, or making the whole card a navigation link all re-pay the
+// page gutter and misalign the component with sibling rails (NavigationBar /
+// TabBar / section headings). Mirrors the runtime useFullBleedGuard.
+const FULL_BLEED = new Set([
+  'Feed', 'FeedGroup', 'FeedAd', 'Section', 'Carousel', 'PostCarousel', 'ProfileCarousel',
+  'NavigationBar', 'TabBar', 'BottomNav', 'Tabs', 'List', 'NavList',
+  'DirectoryList', 'SuggestionList', 'AvatarRail', 'ProfileHeader', 'SubHeader',
+]);
+
+// Generic HTML containers that, when padded around a full-bleed child, cause
+// the double-pay. Chorus full-bleed hosts (the Uppercase names above) are the
+// documented embedded-composition parents and are intentionally NOT flagged.
+const HTML_CONTAINERS = new Set([
+  'div', 'section', 'main', 'article', 'span', 'header', 'footer', 'aside', 'nav', 'form', 'ul', 'ol', 'li',
+]);
+
+// Inline-axis padding only — padding-block / py-* do not touch the page rail.
+const INLINE_PAD_STYLE = new Set([
+  'padding', 'paddingInline', 'paddingLeft', 'paddingRight', 'paddingInlineStart', 'paddingInlineEnd',
+]);
+const INLINE_MARGIN_STYLE = new Set([
+  'margin', 'marginInline', 'marginLeft', 'marginRight', 'marginInlineStart', 'marginInlineEnd',
+]);
+// px-* / pl-* / pr-* / ps-* / pe-* / p-* (inline or shorthand), non-zero value.
+const TW_INLINE_PAD = /(?:^|\s)p(?:x|l|r|s|e)?-(?!0(?:\s|$|\/))/;
+
+function getOpeningName(opening) {
+  return opening && opening.name && opening.name.type === 'JSXIdentifier' ? opening.name.name : null;
+}
+
+function getStyleObject(opening) {
+  for (const attr of opening.attributes) {
+    if (jsxAttrName(attr) === 'style') {
+      const v = attr.value;
+      if (v && v.type === 'JSXExpressionContainer' && v.expression.type === 'ObjectExpression') {
+        return v.expression;
+      }
+    }
+  }
+  return null;
+}
+
+function getClassNameStrings(opening) {
+  const out = [];
+  for (const attr of opening.attributes) {
+    const n = jsxAttrName(attr);
+    if (n === 'className' || n === 'class') collectStaticStrings(attr.value, out);
+  }
+  return out;
+}
+
+// A style prop in `nameSet` is "set" unless it's an explicit zero / none.
+function objHasNonzeroProp(obj, nameSet) {
+  for (const prop of obj.properties) {
+    if (prop.type !== 'Property' || prop.computed) continue;
+    const key = prop.key.type === 'Identifier' ? prop.key.name
+      : prop.key.type === 'Literal' ? String(prop.key.value) : null;
+    if (!key || !nameSet.has(key)) continue;
+    const v = prop.value;
+    if (v.type === 'Literal' && (v.value === 0 || v.value === '0' || v.value === 'none')) continue;
+    return true;
+  }
+  return false;
+}
+
+// The negative-margin opt-out idiom that legitimately negates a bounded
+// surface's padding (marginInline: calc(-1 * ...) / a leading '-').
+function styleHasNegativeInlineMargin(obj) {
+  if (!obj) return false;
+  for (const prop of obj.properties) {
+    if (prop.type !== 'Property' || prop.computed) continue;
+    const key = prop.key.type === 'Identifier' ? prop.key.name
+      : prop.key.type === 'Literal' ? String(prop.key.value) : null;
+    if (!key || !INLINE_MARGIN_STYLE.has(key)) continue;
+    const raw = prop.value.type === 'Literal' ? String(prop.value.value)
+      : prop.value.type === 'TemplateLiteral'
+        ? prop.value.quasis.map((q) => q.value.cooked ?? q.value.raw).join('')
+        : '';
+    if (raw.includes('-') || raw.includes('calc(')) return true;
+  }
+  return false;
+}
+
+// Reinvented-family heuristics. An identity header / author row / entity row
+// hand-built from primitives matches a family's anatomy and should BE the
+// family (ProfileHeader / Metadata / List entry).
+const HEADING_TAGS = new Set(['h1', 'h2', 'h3']);
+const PLAIN_BLOCK_TAGS = new Set(['div', 'section', 'header', 'article', 'a', 'li']);
+const IDENTITY_LEADING = new Set(['Thumbnail', 'Avatar']);
+const META_SEPARATORS = new Set(['·', '•', '・', '∙']);
+
+// Does `node`'s JSX subtree contain an element whose tag is in `names`?
+function subtreeHasComponent(node, names) {
+  for (const c of node.children ?? []) {
+    if (c.type === 'JSXElement') {
+      if (names.has(getOpeningName(c.openingElement))) return true;
+      if (subtreeHasComponent(c, names)) return true;
+    } else if (c.type === 'JSXFragment') {
+      if (subtreeHasComponent(c, names)) return true;
+    }
+  }
+  return false;
+}
+
+export const rules = {
+  // ───────────────────────────────────────────────────────────────────────
+  'no-raw-hex': {
+    meta: {
+      type: 'problem',
+      docs: { description: 'Disallow raw hex colors; every color must resolve to a Chorus token (var(--sys-*) / var(--ref-*)).' },
+      schema: [],
+      messages: {
+        rawHex: 'Raw hex color "{{ hex }}" — use a Chorus token: var(--sys-color-*) (or var(--ref-*) if no semantic alias). See LOVABLE.md § Token strictness.',
+      },
+    },
+    create(context) {
+      function check(node, str) {
+        const m = HEX_COLOR.exec(str);
+        if (m) context.report({ node, messageId: 'rawHex', data: { hex: m[0] } });
+      }
+      return {
+        Literal(node) {
+          if (typeof node.value === 'string') check(node, node.value);
+        },
+        TemplateElement(node) {
+          check(node, node.value.cooked ?? node.value.raw ?? '');
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-tailwind-color': {
+    meta: {
+      type: 'problem',
+      docs: { description: 'Disallow Tailwind color utilities in className; color comes from Chorus tokens via styles.css, not utility classes.' },
+      schema: [],
+      messages: {
+        twColor: 'Tailwind color utility "{{ cls }}" — Chorus color comes from tokens, not utilities. Drop it; surfaces/text inherit from @teamblind-chorus/tokens. See anti-patterns.md.',
+      },
+    },
+    create(context) {
+      return {
+        JSXAttribute(node) {
+          const name = jsxAttrName(node);
+          if (name !== 'className' && name !== 'class') return;
+          const strings = [];
+          collectStaticStrings(node.value, strings);
+          for (const s of strings) {
+            const m = TW_COLOR.exec(s);
+            if (m) {
+              context.report({ node, messageId: 'twColor', data: { cls: m[0].trim() } });
+              break;
+            }
+          }
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-raw-cta': {
+    meta: {
+      type: 'problem',
+      docs: { description: 'Disallow raw <button>, and <a> used as an action; commits go through the @teamblind-chorus/ui Button family.' },
+      schema: [],
+      messages: {
+        rawButton: 'Raw <button> — use <Button> from @teamblind-chorus/ui (variant standard/text/icon/fab). See compose.md § CTAs.',
+        anchorAsButton: '<a> used as an action (onClick / no href) — use <Button variant="text" appearance="accent"> from @teamblind-chorus/ui.',
+      },
+    },
+    create(context) {
+      return {
+        JSXOpeningElement(node) {
+          if (node.name.type !== 'JSXIdentifier') return;
+          const tag = node.name.name;
+          if (tag === 'button') {
+            context.report({ node, messageId: 'rawButton' });
+            return;
+          }
+          if (tag === 'a') {
+            let hasOnClick = false;
+            let hasHref = false;
+            for (const attr of node.attributes) {
+              const n = jsxAttrName(attr);
+              if (n === 'onClick') hasOnClick = true;
+              if (n === 'href') hasHref = true;
+            }
+            // Flag only anchors behaving like buttons; leave real navigation links.
+            if (hasOnClick || !hasHref) context.report({ node, messageId: 'anchorAsButton' });
+          }
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-offscale-space': {
+    meta: {
+      type: 'suggestion',
+      docs: { description: 'Disallow off-scale numeric/px spacing, typography, and radius in inline style; values must resolve to sys.layout.* / sys.radius.* / sys.typo.* tokens.' },
+      schema: [],
+      messages: {
+        offScale: 'Off-scale "{{ prop }}: {{ value }}" — resolve to a Chorus token (e.g. var(--sys-layout-*), var(--sys-radius-*)). For typography use className="sys-typo-<role>-<rung>". See compose.md § raw → token map.',
+      },
+    },
+    create(context) {
+      function checkObject(obj) {
+        for (const prop of obj.properties) {
+          if (prop.type !== 'Property' || prop.computed) continue;
+          const key = prop.key.type === 'Identifier' ? prop.key.name
+            : prop.key.type === 'Literal' ? String(prop.key.value) : null;
+          if (!key || !TOKEN_ONLY_PROPS.has(key)) continue;
+          const v = prop.value;
+          if (v.type === 'Literal') {
+            if (typeof v.value === 'number' && v.value !== 0) {
+              context.report({ node: v, messageId: 'offScale', data: { prop: key, value: String(v.value) } });
+            } else if (typeof v.value === 'string' && !stringIsTokenLike(v.value)) {
+              context.report({ node: v, messageId: 'offScale', data: { prop: key, value: v.value } });
+            }
+          } else if (v.type === 'TemplateLiteral') {
+            const raw = v.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+            if (!stringIsTokenLike(raw)) {
+              context.report({ node: v, messageId: 'offScale', data: { prop: key, value: raw || '…' } });
+            }
+          }
+        }
+      }
+      return {
+        JSXAttribute(node) {
+          if (jsxAttrName(node) !== 'style') return;
+          const val = node.value;
+          if (val && val.type === 'JSXExpressionContainer' && val.expression.type === 'ObjectExpression') {
+            checkObject(val.expression);
+          }
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-fullbleed-wrapper': {
+    meta: {
+      type: 'suggestion',
+      docs: { description: 'Disallow wrapping a full-bleed Chorus component in a padded element, or passing it inline padding; the page rail is paid once and a full-bleed child reaches the container edges.' },
+      schema: [],
+      messages: {
+        directPadding: '<{{ name }}> is full-bleed and owns its page-rail padding internally — drop the inline padding (paddingInline / padding / px-* / pl-* / pr-*) on it. A full-bleed child reaches its container edges; the gutter is paid once at the shell. See LOVABLE.md §★ Layout-Type & Padding Contract.',
+        wrappedInPadding: '<{{ name }}> (full-bleed) wrapped in a padded <{{ wrapper }}> — the page rail is double-paid, so section headings, list-row leading content, and feed author blocks land at different rails. Remove the wrapper\'s inline padding (the shell pays the gutter once), or — inside a bounded surface — apply the negative-margin opt-out on <{{ name }}>. See anti-patterns.md § Rail self-diagnostic.',
+      },
+    },
+    create(context) {
+      return {
+        JSXElement(node) {
+          const opening = node.openingElement;
+          const name = getOpeningName(opening);
+          if (!name || !FULL_BLEED.has(name)) return;
+
+          // (a) inline padding on the full-bleed component itself.
+          const ownStyle = getStyleObject(opening);
+          const ownClasses = getClassNameStrings(opening);
+          if ((ownStyle && objHasNonzeroProp(ownStyle, INLINE_PAD_STYLE)) ||
+              ownClasses.some((s) => TW_INLINE_PAD.test(s))) {
+            context.report({ node: opening, messageId: 'directPadding', data: { name } });
+            return;
+          }
+
+          // (b) wrapped in a padded plain HTML container (gutter double-paid),
+          // unless this instance opts out with a negative inline margin.
+          const parent = node.parent;
+          if (parent && parent.type === 'JSXElement') {
+            const pName = getOpeningName(parent.openingElement);
+            if (pName && HTML_CONTAINERS.has(pName)) {
+              const pStyle = getStyleObject(parent.openingElement);
+              const pClasses = getClassNameStrings(parent.openingElement);
+              const padded = (pStyle && objHasNonzeroProp(pStyle, INLINE_PAD_STYLE)) ||
+                pClasses.some((s) => TW_INLINE_PAD.test(s));
+              if (padded && !styleHasNegativeInlineMargin(ownStyle)) {
+                context.report({ node: opening, messageId: 'wrappedInPadding', data: { name, wrapper: pName } });
+              }
+            }
+          }
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-redundant-link': {
+    meta: {
+      type: 'problem',
+      docs: { description: 'Disallow wrapping a full-bleed Chorus component in a navigation <Link>/<a>; pass the component\'s own onClick instead — an outer link re-pays the page rail as a gutter and nests the card\'s own anchors.' },
+      schema: [],
+      messages: {
+        redundantLink: '<{{ name }}> wrapped in <{{ tag }}> for navigation — pass <{{ name }}>\'s own onClick (e.g. router.push) instead. An outer link re-pays the page rail as a gutter (misaligning it with NavigationBar / TabBar) and nests the card\'s own anchors (channel link / citation / mention), which breaks DOM parsing. See feed/post.spec.json § forbidden.',
+      },
+    },
+    create(context) {
+      return {
+        JSXElement(node) {
+          const opening = node.openingElement;
+          const tag = getOpeningName(opening);
+          if (tag !== 'Link' && tag !== 'a') return;
+          // Only real navigation links: <Link>, or <a href>. A bare <a onClick>
+          // is already covered by no-raw-cta.
+          if (tag === 'a' && !opening.attributes.some((at) => jsxAttrName(at) === 'href')) return;
+
+          for (const child of node.children) {
+            if (child.type !== 'JSXElement') continue;
+            const cName = getOpeningName(child.openingElement);
+            if (cName && FULL_BLEED.has(cName)) {
+              context.report({ node: opening, messageId: 'redundantLink', data: { name: cName, tag } });
+              break;
+            }
+          }
+        },
+      };
+    },
+  },
+
+  // ───────────────────────────────────────────────────────────────────────
+  'no-reinvented-family': {
+    meta: {
+      type: 'suggestion',
+      docs: { description: 'Flag identity headers / meta rows hand-assembled from primitives (Thumbnail + heading, or a manual middot separator) — use the ProfileHeader / Metadata / List families instead of reinventing them.' },
+      schema: [],
+      messages: {
+        reinventedIdentity: 'Identity block hand-assembled from primitives (Thumbnail/Avatar + heading) — use a Chorus family: <ProfileHeader> for a profile/channel header, <Metadata> for a card-head author row, or <List variant="entry"> for an entity row. Resolve the exact usage in usage.json; never reinvent a family from token primitives. See anti-patterns.md §18.',
+        manualMetaSeparator: 'Hand-rolled "{{ sep }}" separator between meta spans — the <Metadata> family owns this row (name · subhandle · timestamp, middot-separated). Use <Metadata> instead of assembling it from spans. See anti-patterns.md §18.',
+      },
+    },
+    create(context) {
+      return {
+        JSXElement(node) {
+          const tag = getOpeningName(node.openingElement);
+          if (!tag || !HEADING_TAGS.has(tag)) return;
+          // Walk up a few levels: if a nearby plain container also holds a
+          // Thumbnail/Avatar, this is a reinvented identity block. Stop at any
+          // Chorus (Uppercase) ancestor — a heading legitimately inside a
+          // family is not a reinvention.
+          let cur = node.parent;
+          for (let hops = 0; cur && hops < 4; hops += 1) {
+            if (cur.type === 'JSXElement') {
+              const pName = getOpeningName(cur.openingElement);
+              if (pName && /^[A-Z]/.test(pName)) return;
+              if (pName && PLAIN_BLOCK_TAGS.has(pName) && subtreeHasComponent(cur, IDENTITY_LEADING)) {
+                context.report({ node, messageId: 'reinventedIdentity' });
+                return;
+              }
+            }
+            cur = cur.parent;
+          }
+        },
+        JSXText(node) {
+          const t = (node.value ?? '').trim();
+          if (!META_SEPARATORS.has(t)) return;
+          const parent = node.parent;
+          if (!parent || !parent.children) return;
+          // Only a separator *between* sibling elements, not middot inside a
+          // single text run (e.g. "공개 · 팔로우" stays one JSXText, untrimmed-equal).
+          const elementSiblings = parent.children.filter((c) => c.type === 'JSXElement').length;
+          if (elementSiblings >= 2) {
+            context.report({ node, messageId: 'manualMetaSeparator', data: { sep: t } });
+          }
+        },
+      };
+    },
+  },
+};
+
+export default rules;