@askewly/design 0.1.0 → 0.3.0

package/dist/index.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
 import { addRecipe, initProject, InjectError } from "./inject.js";
+import { DEFAULT_TYPOGRAPHY_THRESHOLD } from "./typography.js";
 import { verifyDir } from "./verify.js";
 import { loadRecipes, loadTerms, loadTokens, loadTokensCss, searchTerms, tokensForTier, } from "./load.js";
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -159,19 +160,38 @@ program
     .command("verify")
     .argument("[dir]", "directory to scan", ".")
     .option("--ext <list>", "comma-separated extensions to scan", "tsx,ts,jsx,js,css,html")
-    .description("scan for color values that bypass the token system (hex literals, raw rgb/hsl/oklch)")
+    .option("--typography-threshold <n>", "max distinct font sizes per file", String(DEFAULT_TYPOGRAPHY_THRESHOLD))
+    .description("scan for color values that bypass the token system and screens with too many type sizes")
     .action((dir, options) => {
     const target = path.resolve(dir);
-    const { files, violations } = verifyDir(target, options.ext.split(",").map((e) => e.trim()));
+    const typographyThreshold = Number(options.typographyThreshold);
+    if (!Number.isInteger(typographyThreshold) || typographyThreshold < 1) {
+        console.error(`--typography-threshold must be a positive integer (got "${options.typographyThreshold}")`);
+        process.exit(2);
+    }
+    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 (tokens.css/askewly.css and build dirs are excluded)`);
+        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}`);
     }
-    console.error("\nFix: replace literals with semantic token utilities (bg-primary, text-foreground, border-border, ...).");
+    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);
 });
 const recipes = program.command("recipes").description("component recipes (agent-ready implementation contracts)");

package/dist/typography.js

@@ -0,0 +1,219 @@
+import { loadTokens } from "./load.js";
+/**
+ * Counts how many distinct type sizes one file uses.
+ *
+ * The hard part is not counting — it is deciding what counts as one "step".
+ * A file can express font size four ways (named Tailwind utility, arbitrary
+ * value, inline style, CSS declaration) and they must land in the same space
+ * to be comparable. So every expression is resolved to an integer px value and
+ * the distinct set is what we report.
+ */
+const REM_PX = 16;
+/**
+ * Tailwind v4 defaults for names our token scale does not define. Our SSOT owns
+ * sm/base/lg/xl/2xl; everything else is Tailwind's, so it is looked up here
+ * rather than invented. Values in rem, converted at REM_PX.
+ */
+const TAILWIND_DEFAULTS_REM = {
+    xs: 0.75,
+    sm: 0.875,
+    base: 1,
+    lg: 1.125,
+    xl: 1.25,
+    "2xl": 1.5,
+    "3xl": 1.875,
+    "4xl": 2.25,
+    "5xl": 3,
+    "6xl": 3.75,
+    "7xl": 4.5,
+    "8xl": 6,
+    "9xl": 8,
+};
+/** Reads our own scale from the token SSOT. Never hardcode these — they move. */
+function scaleFromTokens() {
+    const tokens = loadTokens();
+    const scale = tokens.typography?.scale ?? {};
+    const out = {};
+    for (const [name, node] of Object.entries(scale)) {
+        const value = node?.$value?.value;
+        const unit = node?.$value?.unit;
+        if (typeof value !== "number")
+            continue;
+        out[name] = unit === "rem" ? value * REM_PX : value;
+    }
+    return out;
+}
+/**
+ * Our scale wins over Tailwind's defaults for the names it defines — that is
+ * the whole point of having a token SSOT. Names it does not define fall back.
+ */
+export function typographyScale() {
+    return { ...tailwindDefaultsPx(), ...scaleFromTokens() };
+}
+function tailwindDefaultsPx() {
+    const out = {};
+    for (const [name, rem] of Object.entries(TAILWIND_DEFAULTS_REM))
+        out[name] = Math.round(rem * REM_PX);
+    return out;
+}
+/** `md:text-lg`, `hover:text-xl`, `dark:md:text-sm` → `text-lg` etc. */
+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);
+    if (match)
+        return Math.round(Number(match[1]));
+    match = /^(-?\d*\.?\d+)rem$/.exec(text);
+    if (match)
+        return Math.round(Number(match[1]) * REM_PX);
+    match = /^(-?\d*\.?\d+)em$/.exec(text);
+    if (match)
+        return Math.round(Number(match[1]) * REM_PX);
+    match = /^(-?\d*\.?\d+)pt$/.exec(text);
+    if (match)
+        return Math.round((Number(match[1]) * 96) / 72);
+    return null;
+}
+// `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;
+/**
+ * Resolves every font-size expression in one file to px and returns the
+ * distinct set. Responsive/state prefixes are stripped: only one breakpoint
+ * renders at a time, so `md:text-lg` is not a step of its own.
+ */
+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)
+                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)
+            add(bucket, Math.round(scale[suffix]));
+    }
+    for (const match of source.matchAll(INLINE_RULE)) {
+        const px = lengthToPx(match[1]);
+        if (px !== null)
+            add(BASE_BUCKET, px);
+    }
+    for (const match of source.matchAll(CSS_RULE)) {
+        const px = lengthToPx(match[1]);
+        if (px !== null)
+            add(BASE_BUCKET, px);
+    }
+    return buckets;
+}
+/**
+ * Default step limit.
+ *
+ * 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 = 7;
+/**
+ * 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 Map();
+    let breaking = null;
+    source.split("\n").forEach((text, index) => {
+        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 (breaking === null)
+        return null;
+    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,5 +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.
@@ -126,12 +137,15 @@ function collectFiles(dir, extensions) {
  * hex literals and raw color functions. Token indirection means UI code
  * should only reference semantic utilities (bg-primary, text-foreground, ...).
  */
-export function verifyDir(dir, extensions = DEFAULT_EXTENSIONS) {
+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 scanned = maskIgnoredRegions(source, path.extname(file).slice(1)).split("\n");
+        const masked = maskIgnoredRegions(source, path.extname(file).slice(1));
+        const scanned = masked.split("\n");
         const original = source.split("\n");
         scanned.forEach((text, index) => {
             for (const { name, pattern } of RULES) {
@@ -142,6 +156,37 @@ export function verifyDir(dir, extensions = DEFAULT_EXTENSIONS) {
                 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${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.1.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",