@bastani/atomic 0.9.5-alpha.7 → 0.9.5-alpha.9

package/dist/builtin/workflows/skills/impeccable/reference/ios.md

@@ -0,0 +1,45 @@
+# iOS platform
+
+For native iOS / iPadOS apps: SwiftUI, UIKit, React Native, Expo, Flutter shipping to Apple hardware.
+
+On native, register narrows. HIG conformance governs structure, navigation, and interaction whatever the register; brand expresses through the expressive layer the platform provides (tint, type, motion, content). Calm, Duolingo, and Spotify carry strong identity entirely inside HIG conventions.
+
+## The iOS slop test
+
+Would a fluent iPhone user trust this app, or pause at off-spec controls? The tell is "ported from a website": reinvented navigation bars, custom back gestures, web-shaped buttons, hover-dependent affordances. Default to the platform's components; depart only for a reason the user would thank you for.
+
+## Layout & structure
+
+- **Safe area.** Lay out inside the safe-area insets. No controls under the notch, Dynamic Island, home indicator, or rounded corners.
+- **System navigation.** Tab bar for 2–5 top-level sections (sections, never actions), navigation stack for hierarchy, sheet for self-contained tasks. No custom global nav, no mixed metaphors.
+- **Edge-swipe back stays alive.** The left-edge back gesture is muscle memory; never disable or overlay it.
+- **Large titles** on top-level screens, collapsing to inline on scroll. Deep detail screens stay inline.
+
+## Touch targets
+
+- **44×44 pt minimum** for every tappable control, with breathing room between adjacent targets.
+
+## Typography
+
+- **Dynamic Type.** Use the system text styles (Large Title through Caption) so text follows the user's reading size. No hard-coded point sizes.
+- **San Francisco carries the UI.** Body, labels, and controls stay on SF Pro / SF Compact; a brand face may appear in display moments.
+- **11 pt floor**; Body is 17 pt.
+
+## Color & materials
+
+- **Semantic system colors** (label, secondaryLabel, systemBackground, separator, tint). They adapt to Dark Mode and increased contrast automatically; raw hex breaks there.
+- **Dark Mode is a first-class appearance.** Design and test both.
+- **One tint color** drives interactive elements; decoration is not its job.
+- **System materials** for blur and translucency behind bars and sheets; no hand-rolled glassmorphism.
+
+## Components & controls
+
+- **Platform controls.** Switch, segmented control, stepper, system pickers, action sheets, alerts, context menus, swipe actions. Reinventing these for flavor is the most common native slop.
+- **SF Symbols** for iconography: baseline-aligned, Dynamic Type-aware, weight and scale variants. Don't mix in a web icon set.
+- **Deliberate modality.** Sheet for a focused dismissible sub-task, full-screen cover for immersion. Clear Cancel/Done; honor swipe-to-dismiss unless data loss requires a guard.
+- **Grouped/inset lists** for settings-shaped content; no bespoke card stacks.
+
+## Motion
+
+- **System transitions.** Push slides, sheets rise, dismiss reverses the entrance. Custom transitions that fight the navigation model disorient.
+- **Honor Reduce Motion.** Crossfade instead of parallax and large slides.

package/dist/builtin/workflows/skills/impeccable/reference/layout.md

@@ -8,11 +8,33 @@ Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-b
 
 Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
 
+Native (`ios` / `android` / `adaptive`): structure follows the Layout section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): platform navigation, insets, and touch targets, never the CSS tooling below.
+
+---
+
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the layout assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, documented spacing scale when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (layout assessment)**: give it the full [Assess Current Layout](#assess-current-layout) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to layout:
+
+```bash
+node .agents/skills/impeccable/scripts/detect.mjs --json --scope layout [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The detector abstains on arbitrary Tailwind spacing (`gap-[13px]`, `p-[7px]`) and ad-hoc `z-index` stacks, so when the project documents a spacing scale, also grep `gap-\[`, `p[trblxy]?-\[`, `m[trblxy]?-\[`, `z-\[` and judge those hits against it. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a monotone grid with uniform spacing passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
 ---
 
 ## Assess Current Layout
 
-Analyze what's weak about the current spatial design:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak about the current spatial design:
 
 1. **Spacing**:
    - Is spacing consistent or arbitrary? (Random padding/margin values)
@@ -138,6 +160,8 @@ Create a systematic plan:
 - **Consistency**: Is the spacing system applied uniformly?
 - **Responsiveness**: Does the layout adapt gracefully across screen sizes?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the rhythm and hierarchy land, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params

package/dist/builtin/workflows/skills/impeccable/reference/typeset.md

@@ -10,9 +10,29 @@ Product: system fonts and familiar sans stacks are legitimate here. One well-tun
 
 ---
 
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the typography assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, **DESIGN.md** content when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (typography assessment)**: give it the full [Assess Current Typography](#assess-current-typography) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to type:
+
+```bash
+node .agents/skills/impeccable/scripts/detect.mjs --json --scope type [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The scan checks literal font sizes against the **DESIGN.md** ramp but abstains on `em`, `%`, `clamp()`, and line-heights, so also grep `font-size\s*:`, `fontSize`, `text-\[`, `leading-\[` and judge those hits against the spec. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a generic font stack at a flat scale passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
+---
+
 ## Assess Current Typography
 
-Analyze what's weak or generic about the current type:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak or generic about the current type:
 
 1. **Font choices**:
    - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
@@ -109,6 +129,8 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the type carries the hierarchy on its own, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params

package/dist/builtin/workflows/skills/impeccable/scripts/context-signals.mjs

@@ -21,7 +21,7 @@ import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { loadContext, extractRegister } from './context.mjs';
+import { loadContext, extractRegister, extractPlatform } from './context.mjs';
 import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 /** Is there code here at all, or just context files / an empty repo? */
@@ -197,6 +197,7 @@ export async function gatherSignals(cwd = process.cwd()) {
       designPath: ctx.designPath,
       hasCode: hasCode(cwd),
       register: extractRegister(ctx.product),
+      platform: extractPlatform(ctx.product),
     },
     critique: { latest: latestCritique(cwd) },
     git,

package/dist/builtin/workflows/skills/impeccable/scripts/context.mjs

@@ -1,8 +1,10 @@
 /**
  * Context loader: prints PRODUCT.md (and DESIGN.md if present) as one
- * markdown block on stdout, or exits with empty stdout when no PRODUCT.md
- * is found anywhere. The skill keys off "empty stdout" to branch into the
- * init flow.
+ * markdown block on stdout, or prints a `NO_PRODUCT_MD:` message when no
+ * PRODUCT.md is found anywhere. The skill keys off that message to branch:
+ * from-scratch build commands (init / teach / craft / shape) and clear
+ * build/shape intent divert into the init flow, while scoped commands proceed
+ * using the existing code as context.
  *
  * Path resolution (first match wins):
  *   1. Active project root, if PRODUCT.md or DESIGN.md is there
@@ -692,27 +694,63 @@ function escapeRegExp(value) {
 }
 
 /**
- * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
- * for a `## Register` section and reading the first non-empty line that
- * follows it. Returns null when the file is legacy / register-less.
+ * Read the first non-empty line under a bare `## <heading>` section of
+ * PRODUCT.md (e.g. `## Register`, `## Platform`). Returns null when the
+ * section is absent. The heading match is exact (`\s*$`) so near-miss
+ * headings like `## Register guidelines` don't shadow the real field.
  */
-export function extractRegister(product) {
+export function extractSectionValue(product, heading) {
   if (!product) return null;
+  const headingRe = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'i');
   const lines = product.split('\n');
   for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Register\b/i.test(lines[i].trim())) {
+    if (headingRe.test(lines[i].trim())) {
       for (let j = i + 1; j < lines.length; j++) {
         const next = lines[j].trim();
-        if (!next) continue;
-        const word = next.toLowerCase();
-        if (word === 'brand' || word === 'product') return word;
-        return null;
+        // A new heading before any value means the section is empty.
+        if (/^#{1,6}\s/.test(next)) return null;
+        if (next) return next;
       }
     }
   }
   return null;
 }
 
+/**
+ * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
+ * for a `## Register` section and reading the first non-empty line that
+ * follows it. Returns null when the file is legacy / register-less.
+ */
+export function extractRegister(product) {
+  const word = (extractSectionValue(product, 'Register') || '').toLowerCase();
+  return word === 'brand' || word === 'product' ? word : null;
+}
+
+/**
+ * Pull the platform (`web`, `ios`, `android`, or `adaptive`) out of PRODUCT.md
+ * by looking for a `## Platform` section and reading the first non-empty line
+ * that follows it. `adaptive` is for cross-platform apps (Flutter, React
+ * Native) that ship both iOS and Android from one codebase; a line that names
+ * both targets (e.g. `ios, android`) is also read as `adaptive`. Returns null
+ * when the file is legacy / platform-less, which the skill treats as `web`
+ * (the default the general rules already assume).
+ */
+export function extractPlatform(product) {
+  const value = (extractSectionValue(product, 'Platform') || '').toLowerCase();
+  if (!value) return null;
+  if (value === 'web' || value === 'ios' || value === 'android' || value === 'adaptive') return value;
+  // A short list naming both native targets (`ios, android`, `ios and
+  // android`) = adaptive. Only list separators and the two platform words may
+  // appear; anything else (prose, negations) is unrecognized and falls
+  // through to the CLI's WARNING path.
+  const tokens = value.split(/[\s,+&/]+/).filter(t => t && t !== 'and');
+  if (tokens.length >= 2 && tokens.every(t => t === 'ios' || t === 'android')
+    && tokens.includes('ios') && tokens.includes('android')) {
+    return 'adaptive';
+  }
+  return null;
+}
+
 /**
  * Read the installed skill's own version from the sibling SKILL.md frontmatter
  * (this file lives at `<skill>/scripts/context.mjs`). Returns null when the
@@ -860,8 +898,11 @@ async function cli() {
     // — cheap models miss the empty case more often than the explicit one.
     const parts = [
       'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
-      'Stop the current task, load reference/init.md, and follow its ' +
-      'instructions to write PRODUCT.md before resuming.',
+      'Follow SKILL.md Setup step 1: for `init`, `teach`, `craft`, `shape`, ' +
+      'or wording that clearly maps to a from-scratch build/shape flow, load ' +
+      'reference/init.md and write PRODUCT.md first; for any other (scoped) ' +
+      'command against existing code, proceed using the code as context and ' +
+      'offer `/impeccable init` as a suggestion (do not block).',
     ];
     parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
@@ -884,6 +925,26 @@ async function cli() {
     ? `NEXT STEP: This project's register is \`${register}\`. You MUST now read \`reference/${register}.md\` before producing any design output.`
     : `NEXT STEP: You MUST now read the matching register reference (\`reference/brand.md\` or \`reference/product.md\`) before producing any design output. Pick based on PRODUCT.md above.`;
   parts.push(next);
+  const platform = extractPlatform(ctx.product);
+  const nativeRefs =
+    platform === 'adaptive' ? ['ios', 'android'] : platform === 'ios' || platform === 'android' ? [platform] : [];
+  if (nativeRefs.length) {
+    const refList = nativeRefs.map(p => `\`reference/${p}.md\``).join(' and ');
+    const label = platform === 'adaptive' ? '`adaptive` (both iOS and Android)' : `\`${platform}\``;
+    parts.push(
+      `NEXT STEP: This project targets ${label}. Also read ${refList} for native conventions, in addition to the register reference.`,
+    );
+  } else if (!platform) {
+    // A `## Platform` section that names something we don't recognize (a
+    // toolchain like `flutter`, a typo) would otherwise silently fall back to
+    // web — the wrong default exactly when the user tried to say "native".
+    const rawPlatform = extractSectionValue(ctx.product, 'Platform');
+    if (rawPlatform) {
+      parts.push(
+        `WARNING: PRODUCT.md's \`## Platform\` value \`${rawPlatform}\` is not recognized; treating the project as \`web\`. Valid values are \`web\`, \`ios\`, \`android\`, or \`adaptive\` (cross-platform, ships both). If this project is native, fix the field (name the design language the app renders, not the toolchain) and surface it to the user.`,
+      );
+    }
+  }
   if (updateDirective) parts.push(updateDirective);
   process.stdout.write(parts.join('\n\n---\n\n') + '\n');
 }

package/dist/builtin/workflows/skills/impeccable/scripts/detector/browser/injected/index.mjs

@@ -1276,7 +1276,7 @@ if (IS_BROWSER) {
 
   function browserPrimaryFont(stack) {
     if (!stack || /var\(/i.test(stack)) return '';
-    return String(stack)
+    return String(stack || '')
       .split(',')
       .map(normalizeBrowserFontName)
       .find(font => font && !GENERIC_FONTS.has(font)) || '';

package/dist/builtin/workflows/skills/impeccable/scripts/detector/cli/main.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { loadDesignSystemForCwd } from '../design-system.mjs';
+import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
 import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
 import { detectHtml } from '../engines/static-html/detect-html.mjs';
 import { detectText } from '../engines/regex/detect-text.mjs';
@@ -93,6 +94,8 @@ Options:
   --quiet             In text mode, only print the final findings count
   --gpt               Also report GPT-specific provider tells (off by default)
   --gemini            Also report Gemini-specific provider tells (off by default)
+  --scope <name>      Only report rules in the given design domain
+                      (type, layout). Comma-separated.
   --no-config         Do not apply project config, detector ignores, inline
                       ignore comments, or DESIGN.md
   --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
@@ -151,6 +154,33 @@ async function detectCli() {
   const providers = [];
   if (args.includes('--gpt')) providers.push('gpt');
   if (args.includes('--gemini')) providers.push('gemini');
+  const scopes = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
+    const inline = args[i].startsWith('--scope=');
+    const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
+    const parsed = (value && !value.startsWith('--'))
+      ? value.split(',').map(s => s.trim()).filter(Boolean)
+      : [];
+    // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
+    // fail loudly so a mistyped pre-scan never runs the wrong rule set.
+    if (parsed.length === 0) {
+      process.stderr.write(
+        `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+      );
+      process.exit(1);
+    }
+    scopes.push(...parsed);
+    args.splice(i, inline ? 1 : 2);
+    i -= 1;
+  }
+  const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
+  if (unknownScopes.length > 0) {
+    process.stderr.write(
+      `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+    );
+    process.exit(1);
+  }
   const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
   const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
   // Inline `impeccable-disable*` waivers are part of the scanned file, so they
@@ -276,6 +306,7 @@ async function detectCli() {
   }
 
   allFindings = filterDetectionFindings(allFindings, detectionConfig);
+  allFindings = filterByScopes(allFindings, scopes);
 
   if (allFindings.length > 0) {
     if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');

package/dist/builtin/workflows/skills/impeccable/scripts/detector/design-system.mjs

@@ -9,6 +9,8 @@ const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
 const FALLBACK_DIRS = ['.agents/context', 'docs'];
 const COLOR_CHANNEL_TOLERANCE = 6;
 const RADIUS_TOLERANCE_PX = 0.5;
+const FONT_SIZE_TOLERANCE_PX = 0.5;
+const FONT_SIZE_LITERAL_RE = /^-?[\d.]+(?:px|rem)$/;
 
 const CSS_COLOR_RE = /#[0-9a-f]{3,8}\b|rgba?\([^)]+\)|oklch\([^)]+\)|hsla?\([^)]+\)/gi;
 const FONT_DECL_RE = /font-family\s*:\s*([^;}\n]+)/gi;
@@ -16,6 +18,9 @@ const FONT_JS_RE = /fontFamily\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
 const GOOGLE_FONT_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
 const BORDER_RADIUS_RE = /border-radius\s*:\s*([^;}\n]+)/gi;
 const BORDER_RADIUS_JS_RE = /borderRadius\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
+const FONT_SIZE_DECL_RE = /font-size\s*:\s*([^;}\n]+)/gi;
+const FONT_SIZE_JS_RE = /fontSize\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
+const TAILWIND_FONT_SIZE_RE = /\btext-\[(-?[\d.]+(?:px|rem))\]/g;
 const STATIC_DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
 
 function firstExisting(dir, names) {
@@ -283,6 +288,18 @@ function addTypographyFonts(out, typography) {
   }
 }
 
+function addTypographySizes(out, typography) {
+  if (!typography || typeof typography !== 'object') return;
+  for (const role of Object.values(typography)) {
+    if (!role || typeof role !== 'object') continue;
+    const raw = String(role.fontSize ?? '').trim().toLowerCase();
+    if (!FONT_SIZE_LITERAL_RE.test(raw)) continue;
+    const px = resolveLengthPx(raw, 16);
+    if (px == null || !Number.isFinite(px) || px <= 0) continue;
+    out.allowedFontSizes.push({ value: raw, px });
+  }
+}
+
 function addRoundedScale(out, rounded) {
   if (!rounded || typeof rounded !== 'object') return;
   for (const [rawName, value] of Object.entries(rounded)) {
@@ -340,10 +357,12 @@ function normalizeDesignSystem(input = {}) {
     allowedFonts: new Set(),
     allowedColorKeys: new Map(),
     allowedRadii: [],
+    allowedFontSizes: [],
     hasPillRadius: false,
   };
 
   addTypographyFonts(out, frontmatter.typography);
+  addTypographySizes(out, frontmatter.typography);
   addColorObject(out, frontmatter.colors);
   addSidecarColors(out, sidecar);
   addRoundedScale(out, frontmatter.rounded);
@@ -352,6 +371,7 @@ function normalizeDesignSystem(input = {}) {
   out.hasFonts = out.allowedFonts.size > 0;
   out.hasColors = out.allowedColorKeys.size > 0;
   out.hasRadii = out.allowedRadii.length > 0;
+  out.hasFontSizes = out.allowedFontSizes.length > 0;
   return out;
 }
 
@@ -418,6 +438,17 @@ function isAllowedRadiusRaw(raw, designSystem) {
   return designSystem.allowedRadii.some(entry => Math.abs(entry.px - px) <= RADIUS_TOLERANCE_PX);
 }
 
+function isAllowedFontSizeRaw(raw, designSystem) {
+  if (!designSystem?.hasFontSizes) return true;
+  const text = String(raw || '').trim().toLowerCase().replace(/\s*!important\s*$/, '');
+  if (!FONT_SIZE_LITERAL_RE.test(text)) return true;
+  const px = resolveLengthPx(text, 16);
+  if (px == null || !Number.isFinite(px) || px <= 0) return true;
+  return designSystem.allowedFontSizes.some(
+    entry => Math.abs(entry.px - px) <= FONT_SIZE_TOLERANCE_PX,
+  );
+}
+
 function lineLooksCommented(line) {
   const trimmed = String(line || '').trim();
   return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('<!--');
@@ -509,6 +540,18 @@ function checkRadiusValue(value, filePath, line, designSystem, context) {
   return findings;
 }
 
+function checkFontSizeValue(value, filePath, line, designSystem, context) {
+  const token = String(value || '').trim();
+  if (isAllowedFontSizeRaw(token, designSystem)) return [];
+  return [makeDesignFinding(
+    'design-system-font-size',
+    filePath,
+    `${context}: ${token} is off the DESIGN.md type ramp`,
+    line,
+    { ignoreValue: token },
+  )];
+}
+
 function checkSourceDesignSystem(content, filePath, options = {}) {
   const designSystem = options.designSystem;
   if (!designSystem?.present) return [];
@@ -567,6 +610,18 @@ function checkSourceDesignSystem(content, filePath, options = {}) {
         findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'borderRadius'));
       }
     }
+
+    if (designSystem.hasFontSizes) {
+      for (const match of line.matchAll(FONT_SIZE_DECL_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'font-size'));
+      }
+      for (const match of line.matchAll(FONT_SIZE_JS_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'fontSize'));
+      }
+      for (const match of line.matchAll(TAILWIND_FONT_SIZE_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'text-[…] class'));
+      }
+    }
   }
 
   return dedupeDesignFindings(findings);
@@ -581,6 +636,8 @@ function sampleText(el) {
   return text ? ` "${text.slice(0, 40)}"` : '';
 }
 
+// Font-size design-system checks are source-scan-only (see checkSourceDesignSystem).
+// Computed font-size cascades and clamp() ramps resolve to off-ramp px in the browser.
 function collectStaticDesignSystemFindings(document, window, filePath, designSystem) {
   if (!designSystem?.present) return [];
   const findings = [];
@@ -698,6 +755,12 @@ function canonicalDesignFindingKey(item) {
     const label = String(value || '').trim().toLowerCase();
     return label ? `${item.antipattern}:radius:${label}` : null;
   }
+  if (item.antipattern === 'design-system-font-size') {
+    const px = resolveLengthPx(String(value || '').trim(), 16);
+    if (px != null && Number.isFinite(px)) return `${item.antipattern}:font-size:${Math.round(px * 100) / 100}`;
+    const label = String(value || '').trim().toLowerCase();
+    return label ? `${item.antipattern}:font-size:${label}` : null;
+  }
   return null;
 }
 
@@ -744,6 +807,7 @@ export {
   isAllowedFont,
   isAllowedColorRaw,
   isAllowedRadiusRaw,
+  isAllowedFontSizeRaw,
   checkSourceDesignSystem,
   collectStaticDesignSystemFindings,
   mergeDesignSystemFindings,