@askewly/design 0.1.0 → 0.2.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,26 @@ 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 } = verifyDir(target, options.ext.split(",").map((e) => e.trim()), { typographyThreshold });
     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`);
         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, ...).");
+    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,146 @@
+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];
+}
+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]`
+const UTILITY_RULE = /(?:^|["'`\s{])((?:[a-z0-9-]+:)*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 match of source.matchAll(UTILITY_RULE)) {
+        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);
+            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]));
+    }
+    for (const match of source.matchAll(INLINE_RULE)) {
+        const px = lengthToPx(match[1]);
+        if (px !== null)
+            steps.add(px);
+    }
+    for (const match of source.matchAll(CSS_RULE)) {
+        const px = lengthToPx(match[1]);
+        if (px !== null)
+            steps.add(px);
+    }
+    return steps;
+}
+/**
+ * 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.
+ */
+export const DEFAULT_TYPOGRAPHY_THRESHOLD = 5;
+/**
+ * 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.
+ */
+export function typographyViolation(source, threshold = DEFAULT_TYPOGRAPHY_THRESHOLD, scale = typographyScale()) {
+    const seen = new Set();
+    let breakingLine = 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;
+        }
+    });
+    if (breakingLine === null)
+        return null;
+    return { line: breakingLine, steps: [...seen].sort((a, b) => a - b), threshold };
+}

package/dist/verify.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
+import { DEFAULT_TYPOGRAPHY_THRESHOLD, typographyViolation } from "./typography.js";
 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 +127,14 @@ 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 = [];
     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 +145,18 @@ export function verifyDir(dir, extensions = DEFAULT_EXTENSIONS) {
                 violations.push({ file, line: index + 1, rule: name, excerpt: original[index].trim().slice(0, 120) });
             }
         });
+        // 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) {
+            violations.push({
+                file,
+                line: typography.line,
+                rule: "typography-scale-exceeded",
+                excerpt: `font-size steps: ${typography.steps.join(", ")} (${typography.steps.length} > limit ${typography.threshold})`,
+            });
+        }
     }
     return { files: files.length, violations };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askewly/design",
-  "version": "0.1.0",
+  "version": "0.2.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",