@hanzo/design 0.4.4 → 0.4.6

package/docs/integrate.md

@@ -22,7 +22,7 @@ every token below is a live CSS custom property.
 ```css
 .panel{
   background: var(--surface-card);
-  border: 1px solid var(--border-card);
+  border: 1px solid var(--border);
   border-radius: var(--radius-lg);
   padding: var(--space-6);
   color: var(--text-secondary);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "packageManager": "pnpm@11.17.0",
   "description": "Hanzo Design System \u2014 monochrome, dark-default tokens + components + brand assets, the single source of truth for every Hanzo surface. CSS + typed programmatic tokens.",
   "license": "BSD-3-Clause",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "test": "node scripts/check-tokens.mjs && node scripts/lint.mjs components guidelines",
+    "test": "node scripts/check-tokens.mjs && node scripts/lint.mjs .",
     "build": "pnpm gen && pnpm test && tsc -p tsconfig.json",
     "prepublishOnly": "pnpm build",
     "lint": "node scripts/lint.mjs"

package/scripts/check-tokens.mjs

@@ -59,6 +59,47 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : pass(`all ${urls.length} asset url()s resolve from the package root`)
 }
 
+// ── 1a. the bundles must PARSE ───────────────────────────────────────────
+// 0.4.2 and 0.4.3 shipped a stray `*/` in styles.css AND tailwind.css: an
+// edit added prose to the end of a comment that was already closed, so a
+// paragraph of English sat in the stylesheet as raw CSS, terminated by a
+// second `*/`. Browsers recover from that — they skip to the next thing that
+// looks like a rule and carry on — so the whole kit rendered correctly in
+// Chromium at three widths in both themes, and every screenshot looked right.
+// PostCSS does not recover. It throws, which means those two versions could
+// not be built against by any Vite/Next/Tailwind consumer at all.
+//
+// The lesson is specific: RENDERING IS NOT PARSING. A visual check cannot see
+// this class of defect, because the browser's error recovery is what hides it.
+// So it is checked structurally, here, on the artifacts a consumer receives.
+//
+// Done by hand rather than with postcss because the defect is lexical and the
+// scan is fifteen lines — CSS comments do not nest, so one left-to-right pass
+// that skips comment bodies finds every stray terminator and every unclosed
+// opener. A parser dependency would be a heavier answer to a smaller question.
+{
+  for (const f of ['styles.css', 'tailwind.css']) {
+    const s = read(join(root, f))
+    let i = 0, opened = 0, strays = [], unterminated = null
+    while (i < s.length - 1) {
+      if (s[i] === '/' && s[i + 1] === '*') {
+        opened++
+        const j = s.indexOf('*/', i + 2)
+        if (j < 0) { unterminated = s.slice(0, i).split('\n').length; break }
+        i = j + 2
+        continue
+      }
+      if (s[i] === '*' && s[i + 1] === '/') { strays.push(s.slice(0, i).split('\n').length); i += 2; continue }
+      i++
+    }
+    const braces = [...s].reduce((n, c) => n + (c === '{') - (c === '}'), 0)
+    if (unterminated !== null) fail(`${f}: unterminated /* at line ${unterminated}`)
+    else if (strays.length) fail(`${f}: stray */ outside any comment at line ${strays.join(', ')} — a consumer's PostCSS build throws here`)
+    else if (braces !== 0) fail(`${f}: ${Math.abs(braces)} unbalanced ${braces > 0 ? '{' : '}'}`)
+    else pass(`${f} is lexically sound — ${opened} comments closed, braces balanced`)
+  }
+}
+
 // ── 1b. the Tailwind bridge is complete and self-contained ───────────────
 // An app should write ONE import and get working utilities. Each thing checked
 // here failed silently in production before it was checked: a missing slot

package/scripts/lint.mjs

@@ -26,7 +26,15 @@ const TOKENS = new Set()
 }
 
 // ── what we read ─────────────────────────────────────────────────────────
-const EXT = new Set(['.css', '.scss', '.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte', '.html'])
+const EXT = new Set(['.css', '.scss', '.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte', '.html', '.md'])
+// Markdown is PROSE, and prose legitimately says `var(--x)` while explaining
+// what a var is. Only its FENCED CSS BLOCKS are code, and only rule 1 runs on
+// them. That is not a technicality — `docs/integrate.md` shipped the
+// copy-paste snippet every new consumer starts from, and its `.panel` rule
+// drew `1px solid var(--border-card)`, a token nothing declares. Anyone who
+// followed the integration guide got a white hairline on black, from the
+// document whose job is to prevent exactly that.
+const FENCED_CSS = /```(?:css|scss)\n([\s\S]*?)```/g
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', 'vendor', '__pycache__'])
 // Third-party marks keep their own hex by design (DESIGN.md §2.4); so do the
 // token files themselves, which are where raw values are SUPPOSED to live, and
@@ -41,7 +49,13 @@ const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', '
 // An undefined custom property makes the declaration invalid, `border-color`
 // falls back to `currentColor`, and the specimen cards for this system's own
 // border scale had been painting near-white hairlines on black.
-const EXEMPT = /(^|\/)(tokens|assets|logos|providers|ui_kits|guidelines)(\/|$)|\.card\.html$/
+// The three GENERATED artifacts are on the list for the same reason `tokens/`
+// is: each one is that directory, emitted. `src/tokens.gen.ts` carries every
+// authored literal into TypeScript; `styles.css` and `tailwind.css` are the
+// flattened bundles. Flagging any of them for raw colour is flagging them for
+// working. They are still checked by rule 1 and by check-tokens.mjs, which is
+// what actually governs them.
+const EXEMPT = /(^|\/)(tokens|assets|logos|providers|ui_kits|guidelines)(\/|$)|\.card\.html$|(^|\/)(tokens\.gen\.ts|styles\.css|tailwind\.css)$/
 
 const walk = (p, out = []) => {
   const st = statSync(p)
@@ -95,6 +109,15 @@ function lintUnresolved(rel, src) {
 function lintFile(abs, root) {
   const rel = relative(root, abs).split(sep).join('/')
   const raw = readFileSync(abs, 'utf8')
+  if (extname(rel) === '.md') {
+    // Line numbers stay true: replace everything outside a css fence with
+    // blanks rather than extracting the fences, so a reported line is the line.
+    let masked = raw.replace(/[^\n]/g, ' ')
+    for (const m of raw.matchAll(FENCED_CSS))
+      masked = masked.slice(0, m.index) + m[0] + masked.slice(m.index + m[0].length)
+    lintUnresolved(rel, strip(masked))
+    return
+  }
   const src = strip(raw)
   lintUnresolved(rel, src)
   if (EXEMPT.test('/' + rel)) return