@askewly/design 0.2.0 → 0.3.0

package/dist/index.js

@@ -169,15 +169,27 @@ program
         console.error(`--typography-threshold must be a positive integer (got "${options.typographyThreshold}")`);
         process.exit(2);
     }
-    const { files, violations } = verifyDir(target, options.ext.split(",").map((e) => e.trim()), { typographyThreshold });
+    const { files, violations, typographySkips } = verifyDir(target, options.ext.split(",").map((e) => e.trim()), { typographyThreshold });
+    // Exemptions are printed on every run, pass or fail. A file that opted out
+    // silently would read as a file that passed.
+    const printSkips = (write) => {
+        if (typographySkips.length === 0)
+            return;
+        write(`\n${typographySkips.length} file(s) exempt from the typography rule:`);
+        for (const skip of typographySkips) {
+            write(`  ${path.relative(target, skip.file)}:${skip.line} — ${skip.reason}`);
+        }
+    };
     if (violations.length === 0) {
         console.log(`verify PASS — ${files} file(s) scanned, no color literals and no file over ${typographyThreshold} type sizes`);
+        printSkips((line) => console.log(line));
         return;
     }
     console.error(`verify FAIL — ${violations.length} violation(s) in ${files} file(s):`);
     for (const violation of violations) {
         console.error(`  ${path.relative(target, violation.file)}:${violation.line} [${violation.rule}] ${violation.excerpt}`);
     }
+    printSkips((line) => console.error(line));
     console.error("\nFix: replace color literals with semantic token utilities (bg-primary, text-foreground, ...);");
     console.error("     collapse extra type sizes onto the token scale, or raise --typography-threshold.");
     process.exit(1);

package/dist/typography.js

@@ -61,6 +61,26 @@ function stripVariants(utility) {
     const parts = utility.split(":");
     return parts[parts.length - 1];
 }
+/**
+ * Named breakpoints plus the `min-*`/`max-*` families. Matching the families by
+ * shape rather than listing them keeps arbitrary variants (`max-[900px]`,
+ * `min-[40rem]`) in the same space as the named ones.
+ */
+const NAMED_BREAKPOINTS = new Set(["sm", "md", "lg", "xl", "2xl"]);
+function isBreakpointVariant(variant) {
+    if (NAMED_BREAKPOINTS.has(variant))
+        return true;
+    return /^(?:min|max)-/.test(variant);
+}
+/**
+ * The breakpoint a utility renders at, as a stable key. Non-breakpoint variants
+ * (`hover`, `dark`, `group-*`) do not create a bucket: they are states of the
+ * same screen, and their sizes are visible alongside the rest.
+ */
+function breakpointBucket(utility) {
+    const variants = utility.split(":").slice(0, -1).filter(isBreakpointVariant);
+    return [...new Set(variants)].sort().join("+");
+}
 function lengthToPx(raw) {
     const text = raw.trim();
     let match = /^(-?\d*\.?\d+)px$/.exec(text);
@@ -77,8 +97,10 @@ function lengthToPx(raw) {
         return Math.round((Number(match[1]) * 96) / 72);
     return null;
 }
-// `text-lg`, `md:text-lg`, `text-[13px]`, `md:text-[0.9rem]`
-const UTILITY_RULE = /(?:^|["'`\s{])((?:[a-z0-9-]+:)*text-(?:\[[^\]\s]+\]|[a-z0-9]+))(?=["'`\s}]|$)/g;
+// `text-lg`, `md:text-lg`, `text-[13px]`, `md:text-[0.9rem]`, `min-[900px]:text-lg`
+// The bracket in the variant half is load-bearing: without it an arbitrary
+// breakpoint made the whole utility invisible to the scan, not just its prefix.
+const UTILITY_RULE = /(?:^|["'`\s{])((?:[a-z0-9-]+(?:\[[^\]\s]+\])?:)*text-(?:\[[^\]\s]+\]|[a-z0-9]+))(?=["'`\s}]|$)/g;
 // `fontSize: "14px"` / `fontSize: '1rem'` / `font-size: 14px`
 const INLINE_RULE = /fontSize\s*:\s*["'`]([^"'`]+)["'`]/g;
 const CSS_RULE = /font-size\s*:\s*([^;}\n]+)/g;
@@ -89,58 +111,109 @@ const CSS_RULE = /font-size\s*:\s*([^;}\n]+)/g;
  */
 export function resolveTypographySteps(source, scale = typographyScale()) {
     const steps = new Set();
+    for (const sizes of resolveTypographyBuckets(source, scale).values()) {
+        for (const size of sizes)
+            steps.add(size);
+    }
+    return steps;
+}
+/** The base bucket: sizes that render with no breakpoint variant attached. */
+export const BASE_BUCKET = "";
+/**
+ * Same resolution as `resolveTypographySteps`, but keyed by the breakpoint the
+ * size renders at.
+ *
+ * Counting every size in one set punished the ordinary responsive pair:
+ * `text-5xl md:text-7xl` is one element at one size on any given screen, yet it
+ * read as two steps. Buckets are judged independently because only one
+ * breakpoint is live at a time.
+ *
+ * Known limit: inline styles and CSS declarations land in the base bucket even
+ * inside `@media` — attributing those needs block parsing, and the files that
+ * drove this change express sizes as utilities.
+ */
+export function resolveTypographyBuckets(source, scale = typographyScale()) {
+    const buckets = new Map();
+    const add = (bucket, px) => {
+        const existing = buckets.get(bucket);
+        if (existing)
+            existing.add(px);
+        else
+            buckets.set(bucket, new Set([px]));
+    };
     for (const match of source.matchAll(UTILITY_RULE)) {
+        const bucket = breakpointBucket(match[1]);
         const utility = stripVariants(match[1]);
         const suffix = utility.slice("text-".length);
         if (suffix.startsWith("[")) {
             const px = lengthToPx(suffix.slice(1, -1));
             if (px !== null)
-                steps.add(px);
+                add(bucket, px);
             continue;
         }
         // `text-center`, `text-primary` and friends share the prefix but are not
         // sizes — only names present in the scale count.
         if (suffix in scale)
-            steps.add(Math.round(scale[suffix]));
+            add(bucket, Math.round(scale[suffix]));
     }
     for (const match of source.matchAll(INLINE_RULE)) {
         const px = lengthToPx(match[1]);
         if (px !== null)
-            steps.add(px);
+            add(BASE_BUCKET, px);
     }
     for (const match of source.matchAll(CSS_RULE)) {
         const px = lengthToPx(match[1]);
         if (px !== null)
-            steps.add(px);
+            add(BASE_BUCKET, px);
     }
-    return steps;
+    return buckets;
 }
 /**
  * Default step limit.
  *
- * Kraft (당근) uses 4. We use 5 because our own token scale defines five sizes
- * (sm 14 / base 16 / lg 20 / xl 28 / 2xl 40) — at 4, a screen that uses the
- * design system's full scale and nothing else would be a violation. Borrowing
- * someone else's number without checking it against our tokens would have made
- * the rule contradict the system it is supposed to defend.
+ * Kraft (당근) uses 4. Borrowing that number unchecked would have made the rule
+ * contradict the system it defends, so DOG3 set it to 5 — the size of our token
+ * scale (sm 14 / base 16 / lg 20 / xl 28 / 2xl 40).
+ *
+ * M1 re-measured it against real screens and found 5 too tight, because the
+ * scale is not the whole story: pages draw headings (30/48/72) and micro labels
+ * (10/12) from outside it. Three ordinary screens — the colors page, get
+ * started, the recipe gallery — landed at 6-7 with textbook hierarchy (one
+ * micro label, two or three body sizes, two headings) and nothing to collapse.
+ *
+ * 7 passes those and still catches the real thing: the files that motivated
+ * this rule sit at 14-15 sizes, twice over the limit either way.
  */
-export const DEFAULT_TYPOGRAPHY_THRESHOLD = 5;
+export const DEFAULT_TYPOGRAPHY_THRESHOLD = 7;
 /**
- * Returns the violation for one file, or null when it stays within the limit.
- * The reported line is where the step that broke the limit first appears —
- * pointing at the first line of the file would say nothing about what to fix.
+ * Returns the violation for one file, or null when every breakpoint stays
+ * within the limit. The reported line is where the step that broke the limit
+ * first appears — pointing at the first line of the file would say nothing
+ * about what to fix.
+ *
+ * Buckets are judged separately, which under-counts on purpose: at `md` the
+ * screen also shows whatever base sizes `md` did not override, and a text
+ * scanner cannot tell which those are. The alternative — adding base into every
+ * breakpoint — reinstates the false positive this rule exists to avoid, so the
+ * rule stays quiet where it cannot be sure.
  */
 export function typographyViolation(source, threshold = DEFAULT_TYPOGRAPHY_THRESHOLD, scale = typographyScale()) {
-    const seen = new Set();
-    let breakingLine = null;
+    const seen = new Map();
+    let breaking = null;
     source.split("\n").forEach((text, index) => {
-        for (const step of resolveTypographySteps(text, scale)) {
-            seen.add(step);
-            if (breakingLine === null && seen.size > threshold)
-                breakingLine = index + 1;
+        for (const [bucket, sizes] of resolveTypographyBuckets(text, scale)) {
+            const known = seen.get(bucket) ?? new Set();
+            seen.set(bucket, known);
+            for (const step of sizes) {
+                known.add(step);
+                if (breaking === null && known.size > threshold)
+                    breaking = { line: index + 1, bucket };
+            }
         }
     });
-    if (breakingLine === null)
+    if (breaking === null)
         return null;
-    return { line: breakingLine, steps: [...seen].sort((a, b) => a - b), threshold };
+    const { line, bucket } = breaking;
+    const steps = [...(seen.get(bucket) ?? new Set())].sort((a, b) => a - b);
+    return { line, steps, threshold, bucket };
 }

package/dist/verify.js

@@ -1,6 +1,16 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { DEFAULT_TYPOGRAPHY_THRESHOLD, typographyViolation } from "./typography.js";
+/**
+ * File-level opt-out for the typography rule. Some files are not one screen —
+ * a gallery holding a dozen demos, a miniature mockup drawn at fractional
+ * sizes — and for those the count answers a question nobody asked.
+ *
+ * The reason is mandatory: an exemption nobody had to justify is how a gate
+ * stops being a gate. Files claiming the marker are also reported by name, so
+ * the exemptions stay countable instead of disappearing into a PASS.
+ */
+const TYPOGRAPHY_MARKER = /askewly-typography-ok(?::([^\n]*))?/;
 const DEFAULT_EXTENSIONS = ["tsx", "ts", "jsx", "js", "css", "html"];
 const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git", ".next"]);
 // Generated token files legitimately contain raw color values.
@@ -131,6 +141,7 @@ export function verifyDir(dir, extensions = DEFAULT_EXTENSIONS, options = {}) {
     const threshold = options.typographyThreshold ?? DEFAULT_TYPOGRAPHY_THRESHOLD;
     const files = collectFiles(dir, extensions);
     const violations = [];
+    const typographySkips = [];
     for (const file of files) {
         const source = readFileSync(file, "utf8");
         const masked = maskIgnoredRegions(source, path.extname(file).slice(1));
@@ -145,18 +156,37 @@ export function verifyDir(dir, extensions = DEFAULT_EXTENSIONS, options = {}) {
                 violations.push({ file, line: index + 1, rule: name, excerpt: original[index].trim().slice(0, 120) });
             }
         });
+        // The marker is read from the original source: it lives in a comment, and
+        // the masked copy has blanked those out.
+        const markerLine = original.findIndex((text) => TYPOGRAPHY_MARKER.test(text));
+        if (markerLine !== -1) {
+            const reason = (TYPOGRAPHY_MARKER.exec(original[markerLine])?.[1] ?? "").trim();
+            if (reason.length === 0) {
+                violations.push({
+                    file,
+                    line: markerLine + 1,
+                    rule: "typography-marker-no-reason",
+                    excerpt: "askewly-typography-ok needs a reason: askewly-typography-ok: <why this file is not one screen>",
+                });
+            }
+            else {
+                typographySkips.push({ file, line: markerLine + 1, reason });
+            }
+            continue;
+        }
         // Typography counts per file, not per line: the question is how many sizes
         // one screen uses. Comments and SVG are masked out here too — a size
         // mentioned in a comment is not rendered.
         const typography = typographyViolation(masked, threshold);
         if (typography) {
+            const where = typography.bucket === "" ? "" : ` at ${typography.bucket}`;
             violations.push({
                 file,
                 line: typography.line,
                 rule: "typography-scale-exceeded",
-                excerpt: `font-size steps: ${typography.steps.join(", ")} (${typography.steps.length} > limit ${typography.threshold})`,
+                excerpt: `font-size steps${where}: ${typography.steps.join(", ")} (${typography.steps.length} > limit ${typography.threshold})`,
             });
         }
     }
-    return { files: files.length, violations };
+    return { files: files.length, violations, typographySkips };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askewly/design",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Query, inject, and verify the Askewly Design system (tokens, UI vocabulary, recipes) from your terminal or coding agent.",
   "license": "MIT",
   "homepage": "https://ui.askewly.com",