@weft-js/cli 0.1.0 → 0.1.2

package/src/design-checks/native-controls.mjs

@@ -0,0 +1,48 @@
+import { NATIVE, NATIVE_TYPES, addImport } from './rules.mjs'
+
+export function checkNativeControls({ el, f, report, localComponents }) {
+  const typed = (el.name === 'input' || el.name === 'Input') && NATIVE_TYPES[el.attr('type')?.value]
+  if (typed && !el.attr('hidden') && !el.attr('data-part'))
+    report(
+      'D005',
+      el.start,
+      el.tagEnd,
+      `\`type="${el.attr('type').value}"\` is painted by the browser: <${typed}> is warp's.`,
+    )
+  if (/^[a-z]/.test(el.name) && el.name !== 'iframe' && el.attr('title'))
+    report(
+      'D005',
+      el.start,
+      el.tagEnd,
+      'A `title` tooltip: the browser paints it, late, and never on touch or keyboard. Use <Tooltip>, or `aria-label` for a name.',
+    )
+  if (NATIVE[el.name] && !localComponents.has(NATIVE[el.name])) {
+    const swap =
+      el.name === 'button' &&
+      !el.attr('class') &&
+      !el.attr('className') &&
+      !el.attr('style') &&
+      f.text.slice(el.start, el.end).includes('</button')
+    report(
+      'D005',
+      el.start,
+      el.tagEnd,
+      `Native <${el.name}> in a warp app: <${NATIVE[el.name]}> brings the focus ring, the sweep, the tones and the touch target.`,
+      swap
+        ? {
+            description: 'Use <Button>',
+            safe: false,
+            edits: [
+              { start: el.start + 1, end: el.tagEnd, text: 'Button' },
+              {
+                start: f.text.lastIndexOf('</', el.end - 1) + 2,
+                end: el.end - 1,
+                text: 'Button',
+              },
+              ...addImport(f.text, ['Button']),
+            ].sort((a, b) => b.start - a.start),
+          }
+        : undefined,
+    )
+  }
+}

package/src/design-checks/outline.mjs

@@ -0,0 +1,39 @@
+import { scanParent } from './rules.mjs'
+
+export function checkOutline({ el, warpName, headings, solids, scan }) {
+  // -- outline --
+  const h = /^h([1-6])$/.exec(el.name)
+  const level = h
+    ? Number(h[1])
+    : el.name === 'Heading' && warpName('Heading')
+      ? Number(el.attr('level')?.value ?? /^\d$/.exec(el.attr('level')?.expr ?? '')?.[0] ?? 2)
+      : 0
+  if (level) headings.push({ level, el })
+
+  // -- one primary action per region --
+  if (
+    el.name === 'Button' &&
+    warpName('Button') &&
+    (!el.attr('emphasis') || el.attr('emphasis')?.value === 'solid') &&
+    !el.attr('tone')
+  ) {
+    const region =
+      el.ancestors.findLast((a) =>
+        [
+          'Card',
+          'Modal',
+          'Drawer',
+          'Popover',
+          'section',
+          'form',
+          'header',
+          'footer',
+          'main',
+          'aside',
+          'Alert',
+        ].includes(a),
+      ) ?? ''
+    const key = `${region}:${el.ancestors.length}:${scanParent(el, scan.elements)?.start ?? 0}`
+    solids.set(key, [...(solids.get(key) ?? []), el])
+  }
+}

package/src/design-checks/reporter.mjs

@@ -0,0 +1,37 @@
+import { diagnostic, positions } from '../diag.mjs'
+import { allowed } from './rules.mjs'
+
+export function makeReporter(out) {
+  const reporter = (file) => {
+    const pos = positions(file.text)
+    const allow = allowed(file.text)
+    const make = (severity) => (code, start, end, why, fix) => {
+      if (allow.has(`${code}:${pos.lineCol(start)[0]}`)) return
+      const edits =
+        fix &&
+        (
+          fix.edits ?? [{ start: fix.at?.[0] ?? start, end: fix.at?.[1] ?? end, text: fix.text }]
+        ).map((e) => ({
+          file: file.rel,
+          span: pos.span(e.start, e.end),
+          offset: [e.start, e.end],
+          text: e.text,
+        }))
+      out.push(
+        diagnostic({
+          code,
+          severity,
+          file: file.rel,
+          span: pos.span(start, end),
+          offset: [start, end],
+          why,
+          fix: fix && { description: fix.description, safe: fix.safe, edits },
+        }),
+      )
+    }
+    const report = make()
+    report.warning = make('warning')
+    return report
+  }
+  return reporter
+}

package/src/design-checks/rules.mjs

@@ -0,0 +1,274 @@
+import { WARP, HEADING_ROLE } from './values.mjs'
+
+export const NATIVE = { button: 'Button', select: 'Select', textarea: 'Textarea' }
+// the input types a browser paints, and the warp control for each; `Input` passes `type` through, so it counts too
+export const NATIVE_TYPES = {
+  date: 'DateField',
+  'datetime-local': 'DateTimeField',
+  time: 'TimeField',
+  month: 'MonthPicker',
+  week: 'DateField',
+  number: 'NumberField',
+  range: 'Slider',
+  color: 'ColorField',
+  checkbox: 'Checkbox',
+  radio: 'Radio',
+  file: 'a dropzone',
+}
+export const INTERACTIVE = new Set([
+  'a',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'summary',
+  'Button',
+  'Toggle',
+  'Input',
+  'Search',
+  'Textarea',
+  'Select',
+  'Checkbox',
+  'Switch',
+  'Chip',
+  'Link',
+])
+export const STATIC = new Set([
+  'div',
+  'span',
+  'p',
+  'li',
+  'section',
+  'article',
+  'td',
+  'tr',
+  'img',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'ul',
+  'label',
+])
+
+const NAMED = ['aria-label', 'aria-labelledby', 'title']
+/** Elements whose implicit role (generic, paragraph, emphasis…) may not be named, and the explicit roles that can't be either. */
+export const GENERIC = new Set([
+  'div',
+  'span',
+  'p',
+  'b',
+  'i',
+  'em',
+  'strong',
+  'small',
+  'code',
+  's',
+  'u',
+  'sub',
+  'sup',
+  'mark',
+  'del',
+  'ins',
+  'kbd',
+  'samp',
+  'var',
+])
+export const UNNAMED = new Set([
+  'generic',
+  'presentation',
+  'none',
+  'paragraph',
+  'caption',
+  'code',
+  'deletion',
+  'emphasis',
+  'insertion',
+  'strong',
+  'subscript',
+  'superscript',
+  'mark',
+  'time',
+])
+export const named = (el) =>
+  NAMED.some((n) => el.attr(n)) || el.attrs.some((a) => a.kind === 'spread')
+/** Children with something a screen reader can read: text, an expression, a component, an image with alt. */
+export const hasName = (children) => {
+  if (/<img\b[^>]*\balt=(["'])[^"']+\1/.test(children)) return true
+  const stripped = children
+    .replace(/<svg[\s\S]*?<\/svg>/g, '')
+    .replace(/<(Icon|[A-Z]\w*Icon)\b[^>]*\/>/g, '')
+    .replace(/<[^>]*aria-hidden[^>]*>[\s\S]*?<\/[^>]+>/g, '')
+  return /[^\s<>{}]/.test(stripped.replace(/<\/?[a-z][^>]*>/g, ''))
+}
+
+/** Parse `#rgb`, `#rrggbb`, `rgb(r, g, b)`, `white` and `black`, or null. */
+export function literalColor(v) {
+  const s = v.trim().toLowerCase()
+  if (s === 'white') return [255, 255, 255]
+  if (s === 'black') return [0, 0, 0]
+  const h = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(s)?.[1]
+  if (h)
+    return (h.length === 3 ? Array.from(h, (c) => c + c) : h.match(/../g)).map((x) =>
+      parseInt(x, 16),
+    )
+  const m = /^rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*\)$/.exec(s)
+  return m ? m.slice(1).map(Number) : null
+}
+const lum = (c) => {
+  const [r, g, b] = c.map((x) => {
+    const s = x / 255
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+export const ratio = (a, b) => {
+  const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}
+
+/** Lines an allow comment covers: `// weft-allow D001: reason` (or `{/* … *\/}`) on the line above or at the line's end. */
+export function allowed(text) {
+  const out = new Map()
+  text.split('\n').forEach((line, i) => {
+    const m = /weft-allow\s+((?:D\d{3}[\s,]*)+):\s*\S/.exec(line)
+    if (!m) return
+    for (const code of m[1].match(/D\d{3}/g))
+      for (const n of [i + 1, i + 2]) out.set(`${code}:${n}`, true)
+  })
+  return out
+}
+
+/** The edit that imports `names` from warp: into the file's existing import, or a new first line. */
+export function addImport(text, names) {
+  const m = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${WARP}['"]`).exec(text)
+  if (!m) return [{ start: 0, end: 0, text: `import { ${names.join(', ')} } from '${WARP}'\n` }]
+  const have = m[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  const missing = names.filter((n) => !have.includes(n))
+  if (!missing.length) return []
+  const at = m.index + m[0].indexOf(m[1]) + m[1].trimEnd().length
+  return [{ start: at, end: at, text: `, ${missing.join(', ')}` }]
+}
+
+/** Does the app have warp's tokens? */
+/** Where a host keeps response headers, outside the source. */
+export const HOST_HEADERS = ['public/_headers', '_headers', 'netlify.toml', 'vercel.json']
+const CSP_DIRECTIVE = /\b((?:default|style|script)-src(?:-attr|-elem)?)\b([^;\n"`]*)/gi
+
+/** Every source list a file gives each directive, wherever in it the policy is written. */
+export function cspDirectives(text) {
+  const out = new Map()
+  for (const m of text.matchAll(CSP_DIRECTIVE)) {
+    const name = m[1].toLowerCase()
+    out.set(name, [...(out.get(name) ?? []), m[2]])
+  }
+  return out
+}
+
+/** The first directive named governs, as in a browser's fallback; a nonce or a hash beside `unsafe-inline` cancels it. */
+export function inlineAllowed(policy, ...names) {
+  const lists = policy.get(names.find((n) => policy.has(n)))
+  return !lists || lists.every((l) => /'unsafe-inline'/i.test(l) && !/'(?:nonce|sha\d+)-/i.test(l))
+}
+
+/** Can any script of the page's own run? The client entry can switch on what an inline script was refused. */
+export function scriptsRun(policy) {
+  const lists = policy.get(
+    ['script-src-elem', 'script-src', 'default-src'].find((n) => policy.has(n)),
+  )
+  // Past `strict-dynamic` a browser ignores hosts, 'self' and 'unsafe-inline', and weft's scripts carry no nonce.
+  return (
+    !lists ||
+    lists.every(
+      (l) =>
+        !/'strict-dynamic'/i.test(l) &&
+        (/'self'/i.test(l) ||
+          l.replace(/'[^']*'/g, '').trim() !== '' ||
+          (/'unsafe-inline'/i.test(l) && !/'(?:nonce|sha\d+)-/i.test(l))),
+    )
+  )
+}
+
+/** What one heading renders at: `{ level, role, set }`, or null when a `level` or `role` expression hides it. `role` is null for a bare `<hN>`. */
+export function headingSite(el, bare) {
+  if (bare) return { level: Number(el.name[1]), role: null }
+  const lv = el.attr('level')
+  const level = !lv ? 2 : Number(lv.value ?? /^\d$/.exec(lv.expr ?? '')?.[0])
+  if (!HEADING_ROLE[level]) return null
+  const attr = el.attr('role')
+  if (attr && attr.kind !== 'string') return null
+  return { level, role: attr?.value ?? HEADING_ROLE[level], set: attr }
+}
+
+/** D006: the roles one level renders at across the app. The most used `Heading` role wins, then the level's default; every other site is fixed to it. */
+export function roleDrift(level, sites) {
+  const counts = new Map()
+  for (const s of sites) if (s.role) counts.set(s.role, (counts.get(s.role) ?? 0) + 1)
+  if (!counts.size || new Set(sites.map((s) => s.role)).size < 2) return
+  const fallback = HEADING_ROLE[level]
+  const top = Math.max(...counts.values())
+  const role = counts.get(fallback) === top ? fallback : [...counts].find(([, n]) => n === top)[0]
+  const prop = role === fallback ? '' : ` role="${role}"`
+  const all = [...counts.keys()].join(', ')
+  for (const { el, text, report, role: has, set } of sites) {
+    if (has === role) continue
+    if (has === null) {
+      const swap =
+        !el.attr('class') &&
+        !el.attr('className') &&
+        !el.attr('style') &&
+        text.slice(el.start, el.end).includes(`</${el.name}`)
+      report(
+        'D006',
+        el.start,
+        el.tagEnd,
+        `A bare <h${level}> beside <Heading level={${level}}>: this one renders at the browser's size, the rest at \`${role}\`.`,
+        swap
+          ? {
+              description: `Use <Heading level={${level}}>`,
+              safe: false,
+              edits: [
+                { start: el.start + 1, end: el.tagEnd, text: `Heading level={${level}}${prop}` },
+                { start: text.lastIndexOf('</', el.end - 1) + 2, end: el.end - 1, text: 'Heading' },
+                ...addImport(text, ['Heading']),
+              ].sort((a, b) => b.start - a.start),
+            }
+          : undefined,
+      )
+      continue
+    }
+    const fix = set
+      ? {
+          description:
+            role === fallback ? `Drop \`role\`: h${level} is \`${role}\`` : `Use role="${role}"`,
+          safe: false,
+          edits: [
+            role === fallback
+              ? { start: text.slice(0, set.start).trimEnd().length, end: set.end, text: '' }
+              : { start: set.valueStart, end: set.valueEnd, text: `"${role}"` },
+          ],
+        }
+      : { description: `Use role="${role}"`, safe: false, text: prop, at: [el.tagEnd, el.tagEnd] }
+    report(
+      'D006',
+      el.start,
+      el.tagEnd,
+      `h${level} renders at two roles in this app (${all}): a level is one size everywhere. This one is \`${has}\`, the rest \`${role}\`. \`// weft-allow D006: <reason>\` keeps a real exception.`,
+      fix,
+    )
+  }
+}
+
+/** The nearest element that contains `el`. */
+export function scanParent(el, elements) {
+  let best
+  for (const e of elements)
+    if (e !== el && e.start <= el.start && e.end >= el.end && (!best || e.start >= best.start))
+      best = e
+  return best
+}

package/src/design-checks/values.mjs

@@ -0,0 +1,262 @@
+/** warp's spacing scale at the default density, px → token (warp.css). */
+const SPACE = new Map([
+  [2, 'hair'],
+  [4, 'tight'],
+  [8, 'related'],
+  [16, 'group'],
+])
+const SPACE_NAMES = 'hair tight related group section page'.split(' ')
+/** warp's radii at the quiet stop, where a raw radius is most likely to have been copied from. */
+const RADIUS = new Map([
+  [4, 'mark'],
+  [8, 'control'],
+  [12, 'surface'],
+])
+export const WARP = '@weft-js/warp'
+/** The role each heading level takes by default: the same table as warp's `Heading` (packages/warp/src/Type.tsx). */
+export const HEADING_ROLE = {
+  1: 'title',
+  2: 'heading',
+  3: 'heading',
+  4: 'label',
+  5: 'label',
+  6: 'label',
+}
+
+const COLOR_EXPECTED =
+  'var(--warp-color-text), -text-subtle, -surface, -surface-raised, -accent-solid, -border, or a `tone` on the component'
+const COLOR =
+  /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(|(?<![-\w])(?:white|black|red|green|blue|gray|grey|orange|yellow|purple|pink|indigo|teal)(?![-\w])/i
+const COLOR_PROPS =
+  /^(color|background|background-color|border-color|border(-(top|right|bottom|left|block|inline)(-(start|end))?)?|outline-color|fill|stroke|box-shadow|caret-color|accent-color)$/
+const SPACE_PROPS =
+  /^(gap|row-gap|column-gap|padding|margin)(-(top|right|bottom|left|block|inline)(-(start|end))?)?$/
+const TYPE_PROPS = /^(font-size|font-weight|line-height|letter-spacing)$/
+/** Sizes that scale with the text, the container or the viewport: nothing on a fixed scale is what they mean. */
+const FLUID =
+  /\b(?:clamp|calc|min|max)\(|\d(?:em|ex|lh|rlh|ch|cap|ic|vw|vh|vi|vb|vmin|vmax|[dsl]v[wh]|cq[iwhb]|cqmin|cqmax)\b|%/
+
+const kebab = (s) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+
+/** `16px 8px` → the same with tokens, or null if any part isn't exactly on the scale. */
+function scaled(value) {
+  const parts = value.trim().split(/\s+/)
+  const out = parts.map((p) => {
+    if (p === '0' || p === '0px' || p === 'auto') return p
+    const m = /^(\d+(?:\.\d+)?)(px|rem)?$/.exec(p)
+    if (!m) return null
+    const px = m[2] === 'rem' ? Number(m[1]) * 16 : Number(m[1])
+    return SPACE.has(px) ? `var(--warp-space-${SPACE.get(px)})` : null
+  })
+  return out.every(Boolean) ? out.join(' ') : null
+}
+
+/** Declarations in a `style` attribute: `{ prop, value, numeric, start, end }` with offsets into the file. */
+export function styleDecls(attr) {
+  if (attr.kind === 'string') {
+    const at = attr.valueStart + 1
+    return [...attr.value.matchAll(/([\w-]+)\s*:\s*([^;]+)/g)].map((m) => {
+      const start = at + m.index + m[0].indexOf(m[2], m[1].length + 1)
+      return {
+        prop: m[1].toLowerCase(),
+        value: m[2].trim(),
+        start,
+        end: start + m[2].trimEnd().length,
+      }
+    })
+  }
+  const out = []
+  for (const m of (attr.expr ?? '').matchAll(
+    /([\w$]+|['"][\w-]+['"])\s*:\s*(?:(['"`])([^'"`$]*)\2|(\d+(?:\.\d+)?)(?=\s*[,}\s]))/g,
+  )) {
+    const value = m[3] ?? m[4]
+    const inner = m[0].lastIndexOf(value)
+    const start = attr.valueStart + m.index + inner - (m[3] !== undefined ? 1 : 0)
+    out.push({
+      prop: kebab(m[1].replace(/['"]/g, '')),
+      value,
+      numeric: m[3] === undefined,
+      start,
+      end: start + value.length + (m[3] !== undefined ? 2 : 0),
+      quote: m[2],
+    })
+  }
+  return out
+}
+
+/** The D-code for one raw declaration, or null. `report` takes (code, start, end, why, fix). */
+export function declaration({ prop, value, numeric, start, end, quote }, report) {
+  const css = (numeric && SPACE_PROPS.test(prop) ? `${value}px` : value).replace(
+    /\s*!important\s*$/i,
+    '',
+  )
+  if (/var\(|^(inherit|initial|unset|transparent|currentcolor|none)$/i.test(css.trim())) return
+  if (COLOR_PROPS.test(prop) && COLOR.test(css.replace(/url\([^)]*\)/gi, '')))
+    return report(
+      'D001',
+      start,
+      end,
+      `Raw colour \`${prop}: ${css}\`: it won't follow the theme, the dials or dark mode. Use ${COLOR_EXPECTED}, or promote it to a token in \`warp({ tokens })\`.`,
+    )
+  if (SPACE_PROPS.test(prop)) {
+    if (/^(0(px)?|auto)$/.test(css.trim()) || FLUID.test(css)) return
+    const token = scaled(css)
+    const text = token && (quote ? `${quote}${token}${quote}` : numeric ? `'${token}'` : token)
+    return report(
+      'D002',
+      start,
+      end,
+      `\`${prop}: ${css}\` is ${token ? 'a scale step written by hand' : 'off the spacing scale'}: gaps are relationships (${SPACE_NAMES.join(', ')}).`,
+      token ? { description: `Use ${token}`, safe: true, text } : undefined,
+    )
+  }
+  if (TYPE_PROPS.test(prop))
+    return report(
+      'D003',
+      start,
+      end,
+      `Raw \`${prop}: ${css}\`: type comes from roles, not sizes. Use \`<Heading role>\` or \`<Text role>\` (display title heading body label caption eyebrow code).`,
+    )
+  if (prop === 'border-radius') {
+    if (/^(0(px)?|\d+%)$/.test(css.trim())) return
+    const m = /^(\d+)(?:px)?$/.exec(css.trim())
+    const name = m && RADIUS.get(Number(m[1]))
+    const text = name && `var(--warp-radius-${name})`
+    return report(
+      'D003',
+      start,
+      end,
+      `Raw \`border-radius: ${css}\`: radii come from the expression dial (mark, control, surface, round).`,
+      name
+        ? {
+            description: `Use ${text}`,
+            safe: true,
+            text: quote ? `${quote}${text}${quote}` : numeric ? `'${text}'` : text,
+          }
+        : undefined,
+    )
+  }
+  if (prop === 'box-shadow' && !/^none$/i.test(css.trim()))
+    return report(
+      'D003',
+      start,
+      end,
+      'A raw shadow: elevation comes from `--warp-elevation-0…3`, which follow the dials and the theme.',
+    )
+}
+
+// -- Tailwind classes, for an app that has warp's tokens too --
+
+const TW_SPACE = new Map([
+  ['0.5', 'hair'],
+  ['1', 'tight'],
+  ['2', 'related'],
+  ['4', 'group'],
+])
+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_PX = 4
+
+/** D001–D003 for one class; returns `[code, why, replacement?]` or null. */
+export function utility(cls) {
+  const bare = cls
+    .slice(cls.lastIndexOf(':') + 1)
+    .replace(/^-/, '')
+    .replace(/!$/, '')
+  const variant = cls.slice(0, cls.length - cls.slice(cls.lastIndexOf(':') + 1).length)
+  const space =
+    /^(p|px|py|pt|pr|pb|pl|ps|pe|m|mx|my|mt|mr|mb|ml|ms|me|gap|gap-x|gap-y|space-x|space-y)-(.+)$/.exec(
+      bare,
+    )
+  if (space) {
+    const [, util, v] = space
+    if (['auto', 'px', '0'].includes(v) || SPACE_NAMES.includes(v)) return null
+    const arb = /^\[(.+)\]$/.exec(v)?.[1]
+    const px = arb
+      ? (/^(\d+(?:\.\d+)?)(px|rem)$/.exec(arb) ?? [])[1] * (arb.endsWith('rem') ? 16 : 1)
+      : Number(v) * TW_PX
+    const name = arb ? SPACE.get(px) : TW_SPACE.get(v)
+    if (arb || !Number.isNaN(Number(v)))
+      return [
+        'D002',
+        `\`${cls}\` is ${name ? 'a scale step under another name' : 'off the spacing scale'}.`,
+        name && `${variant}${util}-${name}`,
+      ]
+    return null
+  }
+  if (
+    new RegExp(
+      `^(bg|text|border|ring|fill|stroke|from|to|via|divide|outline|decoration|accent|caret|shadow)-(${TW_PALETTE})-\\d{2,3}(/\\d+)?$`,
+    ).test(bare) ||
+    /^(bg|text|border|ring|fill|stroke)-(white|black)$/.test(bare)
+  )
+    return [
+      'D001',
+      `\`${cls}\` is a raw palette colour: it won't follow the theme or the dials. Use \`bg-surface\`, \`text-text\`, \`text-text-subtle\`, \`bg-accent\`, \`border-border\`.`,
+    ]
+  if (/^(bg|text|border|ring|fill|stroke|from|to|via|outline)-\[(#|rgb|hsl|oklch)/.test(bare))
+    return ['D001', `\`${cls}\` is a raw colour: it won't follow the theme or the dials.`]
+  const radius = /^rounded(-[a-z]+)?-\[(\d+)px\]$/.exec(bare)
+  if (radius)
+    return [
+      'D003',
+      `\`${cls}\` is a raw radius.`,
+      RADIUS.has(Number(radius[2])) && !radius[1]
+        ? `${variant}rounded-${RADIUS.get(Number(radius[2]))}`
+        : undefined,
+    ]
+  if (
+    /^(text|leading|tracking|font|shadow)-\[/.test(bare) ||
+    /^(text-(xs|sm|base|lg|[2-9]?xl)|font-(thin|light|normal|medium|semibold|bold|extrabold|black))$/.test(
+      bare,
+    )
+  )
+    return [
+      'D003',
+      `\`${cls}\`: type and elevation come from roles, not sizes. Use \`<Heading role>\` or \`<Text role>\`.`,
+    ]
+  return null
+}
+
+/** `<div class="flex flex-col gap-4">` and `style={{ display: 'flex', … }}`: the primitive it spells out, or null. */
+export function layoutOf(el) {
+  const cls = el.attr('class') ?? el.attr('className')
+  if (cls?.kind === 'string') {
+    const c = cls.value.split(/\s+/).filter(Boolean)
+    if (!c.includes('flex') && !c.includes('grid')) return null
+    const dir = c.includes('flex-col') ? 'Stack' : c.includes('flex') ? 'Row' : null
+    if (!dir) return null
+    const gap = c.find((x) => x.startsWith('gap-'))?.slice(4)
+    const name = SPACE_NAMES.includes(gap) ? gap : TW_SPACE.get(gap)
+    return {
+      primitive: dir,
+      gap: name,
+      attr: cls,
+      exact:
+        c.every(
+          (x) => ['flex', 'flex-col', 'flex-row', 'flex-wrap'].includes(x) || x.startsWith('gap-'),
+        ) &&
+        (!gap || !!name),
+    }
+  }
+  const style = el.attr('style')
+  if (!style) return null
+  const decls = styleDecls(style)
+  if (!decls.some((d) => d.prop === 'display' && d.value === 'flex')) return null
+  const dir = decls.find((d) => d.prop === 'flex-direction')?.value
+  const gap = decls.find((d) => d.prop === 'gap')
+  const px = gap && Number(gap.value.replace('px', ''))
+  const name = gap && SPACE.get(px)
+  const only = decls.every((d) => ['display', 'flex-direction', 'gap'].includes(d.prop))
+  return {
+    primitive: dir === 'column' ? 'Stack' : 'Row',
+    gap: name,
+    attr: style,
+    exact:
+      only &&
+      (!gap || !!name) &&
+      style.kind === 'expr' &&
+      !/\.\.\./.test(style.expr) &&
+      (dir === 'column' || dir === undefined ? true : dir === 'row'),
+  }
+}