trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/glass/type/long-form-prose.md

@@ -0,0 +1,151 @@
+# Long-form prose
+
+How Glass sets the reading half: looser leading and spacing than anything else on the site, inside the *same* 640px measure, at the *same* two sizes. The blocks, their axes and the rules they keep are in `domains/type/prose-and-emphasis.md`; this file holds Glass's values and code.
+
+## The container sets the register
+
+```tsx
+<div className="text-[14px] leading-[1.75] text-gray-1000">
+```
+
+Prose body is 14/1.75: a UI paragraph's size, noticeably more open (1.75 vs 1.55).
+
+Why 1.75: a 576px text column at 14px holds roughly 85–95 characters a line, past comfortable, and long lines need more leading for the eye to find the next line's start. A shorter measure could pull it back toward 1.6.
+
+## The reading column is two sizes
+
+16 for headings, 14 for everything a reader reads. The blocks sharing 14px each own a different signal (domain law 4):
+
+| Block | Size | The signal |
+|---|---|---|
+| Lead | 14 | leading at 1.9, and 32px below |
+| Keyline | 14 | weight 500, and 36px of air on both sides |
+| Body | 14 | leading at 1.75 — the baseline the others are read against |
+| Pull quote | 14 | a 3px rounded bar and a 16px indent |
+| Note | 13 | a 1px rule, the faint tier, and a step down in size |
+
+## Keyline and note
+
+Both came from one diagnosis: a body of writing that was 114 paragraphs and almost nothing else. What each is for, and the build check that keeps them honest: `domains/type/prose-and-emphasis.md`, **Two block types worth having**.
+
+**`keyline`** — body size, weight 500, `my-9`.
+
+```tsx
+case "keyline":
+  return <p className="reveal my-9 text-[14px] font-medium leading-[1.6] text-gray-1000">…</p>;
+```
+
+**`note`** — 13px, faint tier, a 1px left rule and 16px of indent.
+
+```tsx
+case "note":
+  return <p className="reveal my-7 border-l border-gray-alpha-300 pl-4 text-[13px] leading-[1.6] text-faint">…</p>;
+```
+
+The note's rule is 1px and the quote's 3px, with the type inside four steps apart, so the two indented rules can't be mistaken for each other.
+
+## Block spacing
+
+| Block | Spacing | Note |
+|---|---|---|
+| Paragraph | `mb-6` (24px) | ~1.7× the type size. |
+| Lead | `mb-8` (32px) | More air below, to set the opening apart. |
+| Heading (h2) | `mt-10 mb-3` (40 / 12) | Asymmetric: a heading belongs to what follows it. |
+| Keyline | `my-9` (36px) | Symmetric — it belongs to neither neighbour, which is the point. |
+| Quote | `my-9` (36px) | More air than a paragraph, both sides. |
+| Note | `my-7` (28px) | Stepped in from the quote so the two read differently. |
+| Figure | `my-9` (36px) | |
+| List | `mb-6`, items `space-y-2` | Matches paragraph spacing so a list reads as one block. |
+
+The heading's 40 above and 12 below, ~3.3:1, is the domain's asymmetric heading space; the keyline is its symmetric exception.
+
+## Headings inside prose
+
+```tsx
+<h2 className="mt-10 mb-3 text-[16px] font-medium leading-[1.2] tracking-[-0.015em]">
+```
+
+16px against 14px body is one step; the weight (500), the tight leading (1.2) and the 40px above do the real work.
+
+It matches a page-level section heading and the detail page's own `<h1>`: three levels at one size, separated by position and spacing. Flatter than most article templates, and deliberate — the alternative was an in-body heading larger than the page title.
+
+## Quotes
+
+```tsx
+<blockquote className="my-9 flex gap-4">
+  <span aria-hidden className="w-[3px] shrink-0 rounded-full bg-gray-500" />
+  <div className="text-[14px] leading-[1.75] text-gray-1000">…</div>
+</blockquote>
+```
+
+The type matches the body around it, so the bar is the entire signal: the 2px `gray-alpha-300` border it replaced is domain law 4's example of auditing what's left after a signal goes. Why a flex child with no vertical margin: `domains/type/prose-and-emphasis.md`, **Quotes**.
+
+- **`bg-gray-500`, from the grey ramp, not the alpha ramp.** It's a decorative mark on an opaque surface — see the Glass colour guide (`glass/color/guide.md`) on why decorative marks stay on the solid ramp.
+
+Still absent: italic (globally disabled), quotation marks, background, colour step. Stepping the quote *down* to secondary, as earlier versions did, at body size just makes a de-emphasised paragraph.
+
+The citation goes quieter and explicitly kills the browser's italic (domain law 9):
+
+```tsx
+<cite className="mt-2 block text-[13px] not-italic text-quiet">— {cite}</cite>
+```
+
+## Figures
+
+```tsx
+<figure className="reveal my-9">
+  <div className="overflow-hidden rounded-[10px] bg-gray-100 ring-1 ring-gray-alpha-300">
+    <div style={{ aspectRatio: b.aspect ?? "16 / 9" }}>
+      <img src={b.src} alt={b.alt} loading="lazy" decoding="async" className="h-full w-full object-cover" />
+    </div>
+  </div>
+  <figcaption className="mt-2.5 text-[13px] leading-[1.55] text-faint">{caption}</figcaption>
+</figure>
+```
+
+The aspect ratio sits on a wrapper so the box is reserved before the image loads. `ring-1` rather than a border, so the outline stays out of the box model and the corner radius stays exact.
+
+**The caption is the point of the figure, not a label on it**: what the thing was for, and which constraint shaped it. It sits at the note/meta tier (13px, faint).
+
+## Lists
+
+```tsx
+<ul className="mb-6 list-disc space-y-2 pl-5 marker:text-gray-500">
+```
+
+The `marker:` variant puts the domain's quiet marker (`domains/type/prose-and-emphasis.md`, **Lists**) on `gray-500`; the same goes for `list-decimal`.
+
+## Hand-rolled bullets in UI context
+
+Outside prose, as in a role's responsibilities list, a custom marker gives finer control:
+
+```tsx
+<li className="flex gap-2.5 text-[14px] leading-[1.65]">
+  <span aria-hidden className="mt-[9px] h-[3px] w-[3px] shrink-0 rounded-full bg-gray-500" />
+  <span>{text}</span>
+</li>
+```
+
+A 3px dot at the quiet tier, offset `mt-[9px]` onto the first line's optical centre. The 9px is derived: 14px × 1.65 leading = 23.1px line box, centre at ~11.5px; minus half the 3px dot = 10px; minus a hair because a dot reads slightly low against lowercase x-height = 9px.
+
+`aria-hidden` matters — a decorative span inside a real `<li>` would otherwise be announced.
+
+## Emphasis in prose
+
+The mapping is §5 of `glass/type/guide.md`. **`<strong>` and the keyline are the same weight at the same size**, so a bolded clause can read as a keyline that failed to get its own line; keep it to a few words (domain law 9).
+
+## Reveal on scroll
+
+Every block carries `reveal`, so paragraphs fade up one by one as they enter the viewport instead of the article arriving as one slab. See the Glass motion guide (`glass/motion/guide.md`) for the implementation and its reduced-motion behaviour.
+
+## The dek
+
+```tsx
+<p className="mt-2 text-[14px] leading-[1.55] text-muted">{dek}</p>
+```
+
+Body size, muted, tighter leading. It was 17px, the ladder's one odd number, sitting between a 30px title and 16px prose; with both gone it separates on colour and leading alone: 1.55, against the body's 1.75 and the lead's 1.9. Dek and lead are the domain's tightest pairing; check them first.
+
+## Cover art and the measure
+
+The cover image stays in the text's 640px column, not bled full-width, so the page reads as one block from title to last paragraph and the image belongs to the article rather than bannering it. A `16 / 7` default aspect ratio is reserved before load so nothing shifts — in-body figures default to `16 / 9`, and both take an explicit ratio when the source has one.

package/plugins/keyline/skills/keyline/glass/type/scale.md

@@ -0,0 +1,69 @@
+# The scale, derived
+
+Why the ladder in `glass/type/guide.md` looks the way it does, and how to extend it without wrecking it. The case against modular scales, and the general method for adding and cutting roles, are in `domains/type/ladders.md`.
+
+## Role-first
+
+A modular scale gives too few sizes in the 11–16px band, where Glass needs 11, 12, 13, 14 and 16 — tooltip, tag, timestamp, nav row and paragraph are five jobs at five densities — and hands out 22, 27 and 34 above an 18px ceiling. Every size here exists because a specific piece of the interface needs it. Grouped by where they appear:
+
+**Content — one measure, top to bottom**
+- 18px index-page title, the largest role: `/writing`, `/work`, `/experience`, `/resume`, `/skills`, a skill's own page. It labels a collection, and it's the only place tracking goes to −0.02em.
+- 16px everything structural — a detail page's title, a section heading, a prose heading. Three roles, separated by leading (1.3 for a wrapping title, 1.2 for a heading) and position.
+- 14px everything read — body, lead, keyline, pull quote, dek, sub-headings. Six roles at one size, where the system does its real work; §1 of `glass/type/guide.md` tabulates how they stay apart.
+- 13.5px summary lines. The half-pixel is deliberate: a collapsed summary is read once, deciding whether to continue — a hair above the note tier, below the body it summarises. Use half-steps at most once.
+- 13px the apparatus — notes, captions, citations, facts, meta, back links.
+
+**Chrome — dense, scannable**
+- 12.5px code. Monospace runs wide, so it steps down to occupy the same measure as the prose around it — the one size that compensates for a *family* rather than a role.
+- 12px. Tags, prev/next labels, hover-card titles; small enough to read as annotation.
+- 11px. Tooltips and avatar initials. The floor for anything a user is expected to read.
+- 8.5px lettermarks, 7.5px card lettering. Below the floor on purpose — recognised rather than read, which is also why 7.5px is the one place a 600 weight is allowed.
+
+**What was deleted**
+
+An earlier ladder had 30, 19, 17 and 15. All four are gone, cut from the top down (domain law 1):
+
+| Size | Was | Why it went |
+|---|---|---|
+| 30 | Article title | Two templates opening two steps above every other page. Now 16. |
+| 19 | Prose heading, pull quote | Came down with the title — an in-body heading can't outrank the page's own. Now 16 and 14. |
+| 17 | Article dek | Existed only to sit between 30 and 16; with both gone, no gap to fill. Now 14, muted. |
+| 15 | `<body>` base | A default nothing used explicitly — a size waiting to be used by accident. |
+
+## Adding a role
+
+Ask the three questions in `domains/type/ladders.md`. Here the first — can an existing size take it with different leading or weight? — is the answer 80% of the time: 14px carries four roles this way.
+
+## The 1–2px step
+
+In the 11–16px band the steps are 1px, and that is enough (`domains/type/ladders.md`, **Small steps are not small**): a 13px meta line and a 14px paragraph are told apart mostly by faint against primary, and position. Above 16px there is one step, 18, where the ladder stops — the system's most consequential choice; §1 of `glass/type/guide.md` argues it.
+
+## Responsive behaviour
+
+**Nothing resizes.** The 30px article title used to drop to 26px below `sm`, because in a ~311px phone column it wrapped to three lines; at an 18px ceiling the rule went with the size. Why fixing the ladder beats tuning a breakpoint, and why sizes hold on a phone: `domains/type/ladders.md`, **Viewports**.
+
+## Fixed sizes, not `rem`, and why that's a choice
+
+The reference implementation uses `px` throughout (`text-[14px]`, not `text-sm` or `0.875rem`).
+
+The trade: `rem` respects a user's browser font-size setting and `px` doesn't, a real accessibility cost. But this hierarchy depends on precise 1px relationships in the 11–16 band, a root scaled to 20px turns them into 15px steps that break the ladder, and browser *zoom* — which everyone uses, and which scales `px` fine — already covers the need.
+
+If your audience skews toward users who set a root font size — documentation, government, healthcare — use `rem` and accept a looser ladder. Convert at a fixed 16px root: 18px → 1.125rem, 14px → 0.875rem, 13px → 0.8125rem. Never mix the two (the domain's unit dial).
+
+## Keeping every element on it
+
+Every type change ends in the sweep in `domains/type/type-audit.md`: every route, raw sizes moved onto role tokens, the same element checked across pages. Glass's role names, registered with `tailwind-merge` so `cn()` doesn't file `text-copy` as a colour and drop it:
+
+```ts
+import { extendTailwindMerge } from "tailwind-merge";
+
+export const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: ["page", "section", "copy", "summary", "dense", "code", "micro", "tip", "mark", "card"] }],
+    },
+  },
+});
+```
+
+Then check the *rendered* size of one element per role, not the source: the class can be written there and never reach the markup.

package/plugins/keyline/skills/keyline/glass/type/weight-and-tracking.md

@@ -0,0 +1,61 @@
+# Weight and tracking
+
+Glass's weights and tracking values, with the decisions behind them. Why two weights, why weight is a state signal and why tracking runs negative with size: domain laws 5 and 7 in `domains/type/guide.md`.
+
+## Weight
+
+### Two weights
+
+400 and 500: a 100-unit gap, the smallest step most families offer, and enough. Keep the gap at 100 and the axis stays free for active nav rows, sub-headings, emphasis and lettermarks.
+
+### Where each lands
+
+**400 — the default.**
+All body copy. All prose. Deks. Meta lines. Tags. Tooltips. Timestamps. Quiet nav rows. Pull quotes (already set apart by size, leading and a border; weight makes them strident).
+
+**500 — structure and state.**
+Headings h1–h4. `<strong>`. The active row in a table of contents. Names and wordmarks. Captions that label an image rather than describe it. Lettermarks. Company/role titles in a list, where the role is structural and the date supporting.
+
+### Quiet and lifted, by scenario
+
+The lists above are defaults; the choice is made per spot, by the rules in domain law 5. The same 13px line is 400 as a date under a title and 500 as the name heading a group, because the job changed, not the importance. With two weights, a step is the whole axis, so when a screen feels heavy the fix is moving lines back to 400, one context at a time; there's never a lighter scale to reach for.
+
+### When 300 is legitimate
+
+Rarely, and never for text read at length: at a very large display size (48px+), where 400 starts to look heavy, or a decorative numeral. If your interface tops out at 30px — most do — you don't need it. The reference implementation loaded 300 for a while and never used it; dropping it from the font request was a straight performance win.
+
+### Weight as an accessibility signal
+
+The active table-of-contents row takes the primary text colour *and* weight 500 (domain law 5):
+
+```tsx
+className={`… ${tone} ${state === "active" ? "font-medium" : ""}`}
+```
+
+Weight is cheaper here than a background pill, border or icon, each of which adds visual weight to a list meant to be quiet.
+
+## Tracking
+
+### The ladder
+
+| Size | Tracking | Reasoning |
+|---|---|---|
+| 7.5px | −0.01em | Card lettering, set solid. The exception below the floor — see the note. |
+| 8.5–11px | +0.02em | Tiny glyphs and near-caps need air or the counters close up. |
+| 12–14px | 0 | Default metrics are designed for this range. Leave them. |
+| 16px | −0.015em | Enough to look set; small enough to be invisible as a decision. |
+| 18px | −0.02em | A page title is a tighter, more deliberate object than a section heading two pixels below. |
+
+Only two rows are the negative-tracking-at-size rule, because the ladder tops out at 18px. An earlier table ran to 30px at −0.025em, with separate values for a 19px heading and a 19px quote; all three sizes left the ladder and took their tracking with them.
+
+The 7.5px row doesn't contradict the 8.5–11px one: that lettering is set solid at near-caps size on a card, so the tightening compensates for the *setting*, not the size. It's also the one place a 600 weight is allowed. Two exceptions in one place hint you're outside the text system — which you are, since nobody reads it.
+
+### The 8.5px lettermark
+
+```tsx
+<span className="… border border-gray-alpha-400 px-[3px] text-[8.5px] font-medium tracking-[0.02em] text-gray-800">
+  {letters}
+</span>
+```
+
+Not text but a mark: a two-or-three-letter stand-in for a logo, in the same 20px optical box as the real SVG logos beside it. It's below the readability floor on purpose — you recognise "TS" the way you recognise an icon (domain law 1). The `+0.02em` and the `px-[3px]` both keep the letters off the border box.

package/plugins/keyline/skills/keyline/scripts/check/css.mjs

@@ -0,0 +1,112 @@
+/**
+ * A forgiving CSS reader: enough structure for lint rules, no dependencies.
+ *
+ * It returns every declaration with its line, the selector it sits under and
+ * the at-rules around it, plus every at-rule prelude. It doesn't validate and
+ * it doesn't resolve var(); nested rules (SCSS, CSS nesting) keep their
+ * innermost selector. Comments are blanked rather than removed, so offsets and
+ * line numbers stay true to the source.
+ */
+
+/** Replace comments with spaces, keeping newlines, so positions survive. */
+export function blankComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "));
+}
+
+export function lineAt(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < text.length; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+}
+
+/** Lines start offsets, for fast offset → line lookups on big files. */
+export function lineIndex(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  return (offset) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+
+/**
+ * @param {string} source CSS text
+ * @param {number} baseLine line number of the first character (for <style> blocks)
+ */
+export function parseCss(source, baseLine = 1) {
+  const text = blankComments(source);
+  const at = lineIndex(text);
+  const decls = [];
+  const atRules = [];
+  const blocks = []; // { selector, atRules, decls }
+  const stack = []; // open blocks: { kind: 'rule'|'at', prelude, block }
+  let start = 0;
+  let quote = null;
+  let paren = 0;
+
+  const context = () => ({
+    selector: [...stack].reverse().find((s) => s.kind === "rule")?.prelude ?? "",
+    atRules: stack.filter((s) => s.kind === "at").map((s) => s.prelude),
+    block: stack.at(-1)?.block ?? null,
+  });
+
+  const pushDecl = (from, to) => {
+    const raw = text.slice(from, to);
+    const colon = raw.indexOf(":");
+    if (colon < 1) return;
+    const prop = raw.slice(0, colon).trim().toLowerCase();
+    if (!/^(--)?[a-z-]+$/.test(prop) && !/^--[\w-]+$/.test(prop)) return;
+    const value = raw.slice(colon + 1).trim();
+    const lead = from + raw.search(/\S/);
+    const ctx = context();
+    const d = { prop, value, line: at(lead) + baseLine - 1, offset: lead, selector: ctx.selector, atRules: ctx.atRules, block: ctx.block };
+    decls.push(d);
+    ctx.block?.decls.push(d);
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === "(") paren++;
+    else if (c === ")") paren = Math.max(0, paren - 1);
+    else if (paren > 0) continue;
+    else if (c === "{") {
+      const prelude = text.slice(start, i).trim().replace(/\s+/g, " ");
+      const kind = prelude.startsWith("@") ? "at" : "rule";
+      const lead = start + text.slice(start, i).search(/\S/);
+      const block = { selector: kind === "rule" ? prelude : context().selector, atRules: [...context().atRules, ...(kind === "at" ? [prelude] : [])], decls: [], line: at(Math.max(lead, 0)) + baseLine - 1 };
+      if (kind === "at") atRules.push({ prelude, line: block.line });
+      blocks.push(block);
+      stack.push({ kind, prelude, block });
+      start = i + 1;
+    } else if (c === ";") {
+      if (stack.length) pushDecl(start, i);
+      else {
+        const prelude = text.slice(start, i).trim();
+        if (prelude.startsWith("@")) atRules.push({ prelude, line: at(start + text.slice(start, i).search(/\S/)) + baseLine - 1 });
+      }
+      start = i + 1;
+    } else if (c === "}") {
+      if (stack.length) pushDecl(start, i);
+      stack.pop();
+      start = i + 1;
+    }
+  }
+  return { decls, atRules, blocks };
+}
+
+/** Parse a `style="..."` attribute's body. */
+export function parseInlineStyle(body, line) {
+  return parseCss(`x{${body}}`, line).decls.map((d) => ({ ...d, selector: "[style]", inline: true }));
+}

package/plugins/keyline/skills/keyline/scripts/check/design.mjs

@@ -0,0 +1,67 @@
+/**
+ * What the detector takes from DESIGN.md: the preset (which turns some rules on
+ * or off), the motion ladder and the z-index ladder. Everything else in the
+ * file is for the agent; the detector only needs what changes a verdict.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PRESETS = ["editorial", "product", "expressive", "glass"];
+
+function section(md, heading) {
+  const m = md.match(new RegExp(`^##\\s+${heading}\\b[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|(?![\\s\\S]))`, "mi"));
+  return m ? m[1] : "";
+}
+
+export function readDesign(root) {
+  const name = existsSync(root) ? readdirSync(root).find((f) => f.toLowerCase() === "design.md") : null;
+  if (!name) return { found: false, preset: null, durations: null, roles: new Map(), zLadder: null };
+  const md = readFileSync(join(root, name), "utf8");
+  const headingLine = (h) => {
+    const i = md.search(new RegExp(`^##\\s+${h}\\b`, "mi"));
+    return i < 0 ? 1 : md.slice(0, i).split("\n").length;
+  };
+
+  const profile = section(md, "Profile");
+  const presetRow = profile.split("\n").find((l) => /^\|\s*Preset\s*\|/i.test(l)) ?? "";
+  const preset = PRESETS.find((p) => new RegExp(`\`${p}\`|\\b${p}\\b`).test(presetRow.split("|").slice(2).join("|"))) ?? null;
+
+  // Durations: every ms / s value in the Motion section's table rows. Rows on a
+  // canonical duration.* role (before any "Named exemptions" line) are also kept by
+  // role, so the detector can check they grow with the size of the change.
+  const motion = section(md, "Motion");
+  const durations = new Set();
+  const roles = new Map();
+  let inExemptions = false;
+  for (const line of motion.split("\n")) {
+    if (!line.startsWith("|")) {
+      if (/exemption/i.test(line)) inExemptions = true;
+      continue;
+    }
+    for (const m of line.matchAll(/(?<![\w.])(\d+(?:\.\d+)?)(ms|s)\b/g)) {
+      const ms = m[2] === "s" ? Math.round(parseFloat(m[1]) * 1000) : Math.round(parseFloat(m[1]));
+      durations.add(ms);
+      const role = line.split("|")[1]?.match(/duration\.(\w+)/)?.[1];
+      if (!inExemptions && role && !roles.has(role)) roles.set(role, ms);
+    }
+  }
+
+  // z-index: rows whose role is z.*, or a project role whose name is a z utility
+  // or mentions one — their values are the ladder.
+  const layout = section(md, "Layout");
+  const zLadder = new Set();
+  for (const row of layout.split("\n").filter((l) => /^\|\s*`?z\./.test(l) || (l.startsWith("|") && /`-?z-\[?-?\d|`z\./.test(l)))) {
+    const cells = row.split("|").slice(1, -1).map((c) => c.trim());
+    for (const c of cells.slice(1)) for (const m of c.matchAll(/(?<![\w.#-])(-?\d+)(?![\w.%])/g)) zLadder.add(Number(m[1]));
+  }
+
+  return {
+    found: true,
+    file: name,
+    lines: { motion: headingLine("Motion"), layout: headingLine("Layout") },
+    preset,
+    durations: durations.size ? durations : null,
+    roles,
+    zLadder: zLadder.size ? zLadder : null,
+  };
+}

package/plugins/keyline/skills/keyline/scripts/check/files.mjs

@@ -0,0 +1,44 @@
+/**
+ * Which files the detector reads. The same skips as scan.mjs, so the two never
+ * disagree about what counts as the project's interface.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { extname, join, relative, sep } from "node:path";
+
+export const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".next", ".nuxt", ".output", ".svelte-kit", ".turbo",
+  ".vercel", ".cache", "dist", "build", "out", "coverage", "vendor",
+  "storybook-static", ".claude", ".agents", "public", "static",
+]);
+export const STYLE = new Set([".css", ".scss", ".sass", ".less", ".pcss"]);
+export const MARKUP = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".vue", ".svelte", ".astro", ".html", ".mdx"]);
+const SKIP_FILES = /\.(min|d|test|spec|stories|config)\.[a-z]+$|^(eslint|postcss|tailwind|next|vite|vitest|jest|playwright)\.config\./;
+
+/** Every style and markup file under `paths`, relative to `root`, minus ignores. */
+export function collect(root, paths, ignores) {
+  const out = [];
+  const ignored = (rel) => ignores.some((ig) => ig && (rel === ig || rel.startsWith(ig.endsWith("/") ? ig : ig + "/")));
+  const visit = (abs) => {
+    const rel = relative(root, abs).split(sep).join("/");
+    if (rel && ignored(rel)) return;
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      return;
+    }
+    if (st.isDirectory()) {
+      const name = abs.split(sep).pop();
+      if (rel && (SKIP_DIRS.has(name) || (name.startsWith(".") && name !== ".storybook"))) return;
+      for (const e of readdirSync(abs)) visit(join(abs, e));
+      return;
+    }
+    const ext = extname(abs);
+    if (!(STYLE.has(ext) || MARKUP.has(ext))) return;
+    if (SKIP_FILES.test(abs.split(sep).pop())) return;
+    if (st.size > 400_000) return; // generated bundles, not source
+    out.push({ abs, rel: rel || abs.split(sep).pop(), ext, kind: STYLE.has(ext) ? "style" : "markup" });
+  };
+  for (const p of paths) visit(p);
+  return out;
+}

package/plugins/keyline/skills/keyline/scripts/check/markup.mjs

@@ -0,0 +1,149 @@
+/**
+ * What the detector needs from markup and script files, found without a parser:
+ * class lists (attributes, class helpers, string constants), inline styles,
+ * <style> blocks, CSS-in-JS templates, and the text of buttons and links.
+ *
+ * Regexes rather than an AST so it reads any framework's files the same way
+ * and never fails on syntax it doesn't know. The cost is precision: a class
+ * built by concatenation is invisible, and a string that only looks like a
+ * class list can be read as one. Rules are written to tolerate both.
+ */
+import { blankComments, lineIndex, parseCss, parseInlineStyle } from "./css.mjs";
+
+const CLASS_ATTR = /\b(?:class|className|class:list)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*"([^"]*)"\s*\}|\{\s*'([^']*)'\s*\}|\{\s*`([^`]*)`\s*\})/g;
+const CLASS_CALL = /\b(?:cn|clsx|cx|classNames|classnames|twMerge|twJoin|cva|tv)\s*\(/g;
+const EXPR_STRING = /(?:[=:(,\[?]|\breturn|&&|\|\|)\s*(["'`])((?:(?!\1)[^\\\n]|\\.)*)\1/g;
+const CLASSY = /^[\w\s:\-\[\]\/.#%(),!&>*@=+'"~]*$/;
+const TAILWINDISH = /(?:^|\s)!?(?:[\w-]+:)*-?(?:p[xytrbl]?|m[xytrbl]?|text|bg|border|rounded|flex|grid|gap|w|h|min-w|min-h|max-w|max-h|font|leading|tracking|shadow|z|opacity|transition|duration|ease|animate|backdrop|ring|outline|uppercase|italic|hidden|block|inline|absolute|relative|fixed|sticky|top|left|right|bottom|inset|items|justify|self|space|overflow|cursor|select|pointer|translate|scale|rotate|blur|from|to|via|fill|stroke)(?:-[\w.\[\]#%/():,-]+)?(?=\s|$)/;
+
+/** Split a class token into its variants and its utility, respecting [arbitrary:values]. */
+export function splitClass(token) {
+  let t = token.replace(/^!/, "").replace(/!$/, "");
+  let depth = 0;
+  let cut = -1;
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === "[" || t[i] === "(") depth++;
+    else if (t[i] === "]" || t[i] === ")") depth--;
+    else if (t[i] === ":" && depth === 0) cut = i;
+  }
+  return { variants: cut < 0 ? [] : t.slice(0, cut).split(":"), base: cut < 0 ? t : t.slice(cut + 1), raw: token };
+}
+
+function balanced(text, open, openCh, closeCh) {
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c;
+    else if (c === openCh) depth++;
+    else if (c === closeCh && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Static parts of a template literal body; ${…} becomes spaces of equal length. */
+const staticParts = (s) => s.replace(/\$\{[^}]*\}/g, (m) => " ".repeat(m.length));
+
+export function readMarkup(source, ext) {
+  // Blank JS comments only in script-like files; in HTML `//` is just text.
+  const isHtmlLike = ext === ".html" || ext === ".vue" || ext === ".svelte" || ext === ".astro";
+  let text = blankComments(source);
+  if (!isHtmlLike) text = text.replace(/(^|[^:"'`\\])\/\/[^\n]*/g, (m, pre) => pre + " ".repeat(m.length - pre.length));
+  text = text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
+  const at = lineIndex(text);
+
+  const classLists = []; // { value, offset, line, tokens: [{...splitClass, line}] }
+  const seen = new Set();
+  const addList = (value, offset, origin) => {
+    if (seen.has(offset)) return;
+    seen.add(offset);
+    const tokens = [];
+    const re = /\S+/g;
+    let m;
+    while ((m = re.exec(value))) tokens.push({ ...splitClass(m[0]), line: at(offset + m.index) });
+    if (tokens.length) classLists.push({ value, offset, line: at(offset), tokens, origin, tag: origin === "attribute" ? tagAround(offset, value.length) : "" });
+  };
+
+  /** The opening tag a class attribute sits in, for rules that need its element or attributes. */
+  const tagAround = (offset, length) => {
+    let lt = offset;
+    while (lt > 0 && !(text[lt] === "<" && /[A-Za-z]/.test(text[lt + 1] ?? ""))) lt--;
+    const rest = text.slice(offset + length, offset + length + 600);
+    const gt = rest.search(/(?<![=-])>/);
+    return text.slice(lt, offset + length + (gt < 0 ? 0 : gt + 1));
+  };
+
+  for (const m of text.matchAll(CLASS_ATTR)) {
+    const idx = m.slice(1).findIndex((g) => g !== undefined);
+    const value = m[idx + 1];
+    const offset = m.index + m[0].indexOf(value, m[0].indexOf("="));
+    addList(idx === 4 ? staticParts(value) : value, offset, "attribute");
+  }
+  for (const m of text.matchAll(CLASS_CALL)) {
+    const open = m.index + m[0].length - 1;
+    const close = balanced(text, open, "(", ")");
+    if (close < 0) continue;
+    const args = text.slice(open + 1, close);
+    for (const s of args.matchAll(/(["'`])((?:(?!\1)[^\\]|\\.)*)\1/g)) {
+      addList(s[1] === "`" ? staticParts(s[2]) : s[2], open + 1 + s.index + 1, "helper");
+    }
+  }
+  if (!isHtmlLike || ext !== ".html") {
+    for (const m of text.matchAll(EXPR_STRING)) {
+      const value = m[2];
+      if (value.length < 3 || !CLASSY.test(value) || !TAILWINDISH.test(value)) continue;
+      if (/^[a-z]+(-[a-z]+)*$/.test(value) && !/\s/.test(value) && !/^(uppercase|italic|transition-all|h-screen|min-h-screen|outline-none)$/.test(value)) continue;
+      addList(m[1] === "`" ? staticParts(value) : value, m.index + m[0].lastIndexOf(m[1] + value) + 1, "string");
+    }
+  }
+
+  // Styles: <style> blocks, style="…" attributes, style={{…}} objects, CSS-in-JS templates.
+  const css = [];
+  for (const m of text.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
+    const body = source.slice(m.index + m[0].indexOf(">") + 1, m.index + m[0].lastIndexOf("</"));
+    css.push(parseCss(body, at(m.index + m[0].indexOf(">") + 1)));
+  }
+  const inline = [];
+  for (const m of text.matchAll(/\bstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    const body = m[1] ?? m[2];
+    if (body.includes(":")) inline.push(...parseInlineStyle(body, at(m.index)));
+  }
+  for (const m of text.matchAll(/\bstyle\s*=\s*\{\{/g)) {
+    const open = m.index + m[0].length - 1;
+    const close = balanced(text, open, "{", "}");
+    if (close < 0) continue;
+    const body = text.slice(open + 1, close);
+    for (const p of body.matchAll(/([A-Za-z]+)\s*:\s*("[^"]*"|'[^']*'|`[^`]*`|-?[\d.]+)/g)) {
+      const prop = p[1].replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+      const value = p[2].replace(/^["'`]|["'`]$/g, "");
+      inline.push({ prop, value, line: at(open + 1 + p.index), selector: "[style]", atRules: [], block: null, inline: true });
+    }
+  }
+  for (const m of text.matchAll(/\b(?:styled(?:\.\w+|\([^)]*\))|css|createGlobalStyle|keyframes|injectGlobal)\s*`([^`]*)`/g)) {
+    const bodyOffset = m.index + m[0].indexOf("`") + 1;
+    css.push(parseCss(`x{${staticParts(m[1])}}`, at(bodyOffset)));
+  }
+
+  // Visible text of buttons and links, for the copy rules.
+  const labels = [];
+  for (const m of text.matchAll(/<(button|Button|a|Link)\b[^>]*>\s*([^<>{}]+?)\s*<\/\1>/g)) {
+    labels.push({ element: m[1], text: m[2].replace(/\s+/g, " ").trim(), line: at(m.index + m[0].indexOf(m[2])) });
+  }
+
+  // Navigation blocks: how many links each writes out, and whether it groups them.
+  // Links rendered from an array (`items.map`) are invisible here, so the count is a floor.
+  const navs = [];
+  for (const m of text.matchAll(/<nav\b[^>]*>([\s\S]*?)<\/nav>/g)) {
+    const body = m[1];
+    const links = (body.match(/<(?:a|Link|NavLink)\b/g) ?? []).length;
+    const grouped = /<details\b|<h[2-6]\b|role\s*=\s*["']group|<section\b|<fieldset\b/.test(body) || (body.match(/<ul\b/g) ?? []).length > 1;
+    navs.push({ line: at(m.index), links, grouped });
+  }
+
+  return { text, classLists, css, inline, labels, navs };
+}