mlola-ui 1.1.25 → 1.1.26

package/README.md

@@ -44,9 +44,44 @@ Tailwind's preflight in either import order.
 | `add <items…> [--no-install]` | copy items and their dependencies into the project, and install the packages they import |
 | `list [--json]` | print every installable item |
 | `doctor` | report project and registry problems |
+| `check [path…] [--json] [--strict] [--all]` | check every file's markup and CSS against the contract, and count the colors and spacing typed by hand |
 | `login <token>` | save a Mlola Pro token (from /account) for this user |
 | `logout` | forget the saved token |
 
+## Checking a project
+
+`check` runs the same check as the MCP server's `check_markup` over every
+HTML, JSX, TSX, Vue, Svelte, Astro and CSS file in the project (or the paths
+you name), and reports each issue with its line and fix:
+
+```bash
+npx mlola-ui check            # the whole project
+npx mlola-ui check src --json # one folder, every issue as data
+```
+
+It ends with the drift: how many different colors and spacing values were
+typed by hand instead of read from the tokens, and which ones most. It works
+in any project, so it can measure one before it uses Mlola. In a Mlola
+project it leaves out what the CLI installed (`--all` takes the copied source
+in; the theme it builds, where the tokens are defined, is never checked); where
+Tailwind, UnoCSS or Windi is installed it leaves utility classes alone and
+counts only the values typed into them (`bg-[#fafafa]`, `p-[13px]`).
+
+It exits 1 when it finds an error (with `--strict`, a warning too), and on
+GitHub Actions each issue is also an annotation on the pull request:
+
+```yaml
+# .github/workflows/ui.yml
+name: UI
+on: pull_request
+jobs:
+  mlola:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx -y mlola-ui@latest check src
+```
+
 ## Coding agents
 
 `init` (or `agents`, in an existing project) tells the project's coding agents
@@ -63,7 +98,8 @@ that its UI is Mlola:
 this CLI, offline: `get_design_rules`, `search_components`, `get_component`,
 `get_tokens`, `check_markup` (invented classes, wrong `data-*` values, utility
 classes, and hand-written colors, spacing off the `--ml-space-*` scale or
-faded text in `style` attributes and `<style>` blocks), `add_components` and `init_project`. For Claude Code
+faded text in `style` attributes, `<style>` blocks and utility classes, each
+with its line), `add_components` and `init_project`. For Claude Code
 without init:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mlola-ui",
-  "version": "1.1.25",
+  "version": "1.1.26",
   "mcpName": "io.github.mlolahq/mlola-ui",
   "description": "Source-copy CLI that writes framework-free Mlola UI items into your project",
   "type": "module",

package/registry/catalog.json

@@ -815,7 +815,7 @@
       "name": "generative-ui",
       "type": "registry:ui",
       "title": "Generative UI",
-      "description": "Renders a JSON interface a model streams — metrics, charts, tables, alerts, buttons — from the library's own components as it arrives",
+      "description": "Renders a JSON interface a model streams (metrics, charts, tables, alerts, buttons) from the library's own components as it arrives",
       "category": "ai-agents",
       "tags": [
         "generative ui",

package/registry/index.json

@@ -2,7 +2,7 @@
   "$schema": "./schema/registry-index.schema.json",
   "schemaVersion": 2,
   "name": "mlola-ui",
-  "version": "1.1.25",
+  "version": "1.1.26",
   "homepage": "https://ui.mlola.com",
   "themeContract": {
     "attribute": "data-theme",
@@ -177,8 +177,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -239,7 +239,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -401,7 +401,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -493,7 +493,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -546,7 +546,7 @@
         "spinner"
       ],
       "engineDependencies": {
-        "@mlola-ui/motion": "^1.1.25"
+        "@mlola-ui/motion": "^1.1.26"
       },
       "options": [
         {
@@ -714,8 +714,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -784,7 +784,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -839,7 +839,7 @@
         "modal"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -903,8 +903,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -993,7 +993,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -1218,8 +1218,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -1272,7 +1272,7 @@
           "path": "packages/components/modal/modal.tsx",
           "target": "{{aliases.components}}/modal.tsx",
           "type": "registry:ui",
-          "integrity": "sha256-gqrMncs7lEgUjsWXXEl5FYIUoYAxj93gcVh1pZTuatQ="
+          "integrity": "sha256-oxAjgygXXMPjL8+lXjW5LhAYBAmuPaBurWdplEYQiW4="
         }
       ],
       "themeContract": {
@@ -1370,7 +1370,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -1421,7 +1421,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -1683,7 +1683,7 @@
           "path": "packages/components/rating/rating.tsx",
           "target": "{{aliases.components}}/rating.tsx",
           "type": "registry:ui",
-          "integrity": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0="
+          "integrity": "sha256-prhfNzlCqLRWqURtq0MrX6MLdtuDpIOf5fA1Ie26L54="
         }
       ],
       "themeContract": {
@@ -1799,7 +1799,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -1852,8 +1852,8 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -1895,7 +1895,7 @@
           "path": "packages/components/select/select.tsx",
           "target": "{{aliases.components}}/select.tsx",
           "type": "registry:ui",
-          "integrity": "sha256-IInFSuCUOPVgNMdtEsnjpqwMeVYYk+4fx33K21z0xQE="
+          "integrity": "sha256-7u1sshW6KAQgjgwQ1siN1P5GkBxboOiOJOdgLanForE="
         }
       ],
       "themeContract": {
@@ -1931,8 +1931,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -1992,7 +1992,7 @@
           "path": "packages/components/sheet/sheet.tsx",
           "target": "{{aliases.components}}/sheet.tsx",
           "type": "registry:ui",
-          "integrity": "sha256-gmc8rZ87NHfN/bErEWHm6HlaAoeNT/Fw6y2PrW88WFI="
+          "integrity": "sha256-U5uuIle4HMkKILrxBqp+cimv7aKGurWa8s7RYhbuIM8="
         }
       ],
       "themeContract": {
@@ -2078,7 +2078,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -2223,7 +2223,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -2355,7 +2355,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -2443,8 +2443,8 @@
         "spinner"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -2599,7 +2599,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -2676,7 +2676,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -2758,7 +2758,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -2830,7 +2830,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -2900,7 +2900,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3098,8 +3098,8 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -3188,7 +3188,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3243,7 +3243,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3306,7 +3306,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -3334,7 +3334,7 @@
           "path": "packages/components/color-picker/color-picker.tsx",
           "target": "{{aliases.components}}/color-picker.tsx",
           "type": "registry:ui",
-          "integrity": "sha256-/UyEbxqknsHheX444Imc3WphyixZbvj8hGL+r+zyG5w="
+          "integrity": "sha256-Y0Wjx1ypiiKofe0vL1RpjgZG9uoa/a5RB0etmWW5d3A="
         },
         {
           "path": "packages/components/color-picker/color.ts",
@@ -3377,7 +3377,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -3496,8 +3496,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3561,7 +3561,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26"
       },
       "options": [
         {
@@ -3648,8 +3648,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3723,7 +3723,7 @@
         "sheet"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [],
       "variants": [],
@@ -3846,7 +3846,7 @@
         "button"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {
@@ -3950,8 +3950,8 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.25",
-        "@mlola-ui/icons": "^1.1.25"
+        "@mlola-ui/behavior": "^1.1.26",
+        "@mlola-ui/icons": "^1.1.26"
       },
       "options": [
         {

package/registry/source/packages/components/color-picker/color-picker.tsx

@@ -248,7 +248,7 @@ export const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>
             </div>
           ) : null}
           <p className="ml-color-picker-contrast">
-            <span className="ml-color-picker-sample" style={{ "--ml-color": solid, color: onWhite >= onBlack ? "#fff" : "#000" } as React.CSSProperties} aria-hidden="true">
+            <span className="ml-color-picker-sample" style={{ "--ml-color": solid, "--ml-color-ink": onWhite >= onBlack ? "#fff" : "#000" } as React.CSSProperties} aria-hidden="true">
               Aa
             </span>
             <span>

package/registry/source/packages/components/modal/modal.tsx

@@ -49,7 +49,6 @@ export function Modal({
     <div
       data-ml-portal=""
       className="ml-modal-overlay"
-      data-state="open"
       onMouseDown={(event) => {
         if (closeOnBackdrop && event.target === event.currentTarget) onClose();
       }}

package/registry/source/packages/components/rating/rating.tsx

@@ -57,38 +57,3 @@ export function Rating({
     </span>
   );
 }
-
-export default function Showcase() {
-  return (
-    <div className="ml-rating-showcase">
-      <section className="ml-showcase-group">
-        <h3 className="ml-showcase-group-label">Fractions</h3>
-        <p className="ml-showcase-note">
-          The fill is clipped to the exact percentage, so a half star is really half.
-        </p>
-        <div className="ml-showcase-stack">
-          {[5, 4.5, 4, 3.7, 3, 2.5, 1, 0].map((value) => (
-            <Rating key={value} value={value} showValue />
-          ))}
-        </div>
-      </section>
-
-      <section className="ml-showcase-group">
-        <h3 className="ml-showcase-group-label">With review count</h3>
-        <div className="ml-showcase-stack">
-          <Rating value={4.8} count={214} />
-          <Rating value={4.2} count={89} />
-          <Rating value={3.5} count={12} />
-        </div>
-      </section>
-
-      <section className="ml-showcase-group">
-        <h3 className="ml-showcase-group-label">Other scales</h3>
-        <div className="ml-showcase-stack">
-          <Rating value={7.5} max={10} showValue />
-          <Rating value={2.5} max={3} showValue />
-        </div>
-      </section>
-    </div>
-  );
-}

package/registry/source/packages/components/select/select.tsx

@@ -293,7 +293,7 @@ export const Select = React.forwardRef<HTMLButtonElement, SelectProps>(function
         ) : null}
       </div>
       {open && !disabled && portal ? createPortal(
-        <div ref={popoverRef} data-ml-portal="" className="ml-select-popover" data-state="open" data-side="bottom">
+        <div ref={popoverRef} data-ml-portal="" className="ml-select-popover" data-side="bottom">
           {searchable ? (
             <div className="ml-select-search-wrap">
               <input

package/registry/source/packages/components/sheet/sheet.tsx

@@ -46,7 +46,7 @@ function Sheet({
   if (!portal || !open) return null;
   const named = title ?? props["aria-label"] ?? props["aria-labelledby"];
   return createPortal(
-    <div data-ml-portal="" className="ml-sheet-layer" data-state="open">
+    <div data-ml-portal="" className="ml-sheet-layer">
       <div
         aria-hidden="true"
         className="ml-sheet-overlay"

package/registry/source-manifest.json

@@ -22,7 +22,7 @@
   "packages/components/card/card.tsx": "sha256-YNqJWotnswv0UiYGtmJV9KxylKopXC0EZD7hTt8eQ0E=",
   "packages/components/carousel/carousel.tsx": "sha256-WxvQoG9/u190ka4x6cpZT8ZS6XyhEaAlJZ/JyXG+ACU=",
   "packages/components/checkbox/checkbox.tsx": "sha256-hz4YbGwOxv/aJpJHrLXR4MKSWJGyjzoJEIGvdhyML9M=",
-  "packages/components/color-picker/color-picker.tsx": "sha256-/UyEbxqknsHheX444Imc3WphyixZbvj8hGL+r+zyG5w=",
+  "packages/components/color-picker/color-picker.tsx": "sha256-Y0Wjx1ypiiKofe0vL1RpjgZG9uoa/a5RB0etmWW5d3A=",
   "packages/components/color-picker/color.ts": "sha256-YqSgYjzn7XfPWAHuyzbwOhbg/ScaSfB7V73e9w+OjJs=",
   "packages/components/combobox/combobox.tsx": "sha256-YMQrR7HUd3aU6O5MqttPNphwtiVyPWIME+Qn/5kkIYM=",
   "packages/components/command-menu/command-menu.tsx": "sha256-wZnlj17zVlcfp5I08ziggHtchfdqjlvNl+MyiP+Rdbo=",
@@ -35,7 +35,7 @@
   "packages/components/hover-card/hover-card.tsx": "sha256-xLBQc3vVIfQbnN85F34r9SHMGQf8FubSYfk7uP+IS2g=",
   "packages/components/input/input.tsx": "sha256-K0YrpEsEJZTzw64t+Cyg/OGYwlU6LU1/yXTNUxYUIAI=",
   "packages/components/kbd/kbd.tsx": "sha256-e8EO2Gw6JiUyrU0YcEZOaQNMel1pe/EcJrxwwgd1Ggk=",
-  "packages/components/modal/modal.tsx": "sha256-gqrMncs7lEgUjsWXXEl5FYIUoYAxj93gcVh1pZTuatQ=",
+  "packages/components/modal/modal.tsx": "sha256-oxAjgygXXMPjL8+lXjW5LhAYBAmuPaBurWdplEYQiW4=",
   "packages/components/number-input/number-input.tsx": "sha256-mo7rVoOQ4p/I0Hhx5w+SwXUtl3sI4VOt3QX9FwdB2q4=",
   "packages/components/number-input/number.ts": "sha256-IrHCQrEhI5ein9ifMFuSViSoxQUBoT3tNmmCu/paGGM=",
   "packages/components/otp-input/otp-input.tsx": "sha256-0KeyDLCC27/GqOocMWXggJ255PCEpCOCcINAcabksSk=",
@@ -46,11 +46,11 @@
   "packages/components/priority-icon/priority-icon.tsx": "sha256-3D6hFRpht3YuWouLhakE2DFdldavmJx0B/povEDwrtQ=",
   "packages/components/progress/progress.tsx": "sha256-oDxj1Ccl1pKV4+e6A7aaJL1FThW8qs9r4Gb0hEmExeM=",
   "packages/components/radio-group/radio-group.tsx": "sha256-jhnSEBLkdpe8dv5us/Q1sMsQF4sKGRgDXWGKm2JSFew=",
-  "packages/components/rating/rating.tsx": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0=",
+  "packages/components/rating/rating.tsx": "sha256-prhfNzlCqLRWqURtq0MrX6MLdtuDpIOf5fA1Ie26L54=",
   "packages/components/resizable/resizable.tsx": "sha256-RFBpg/a2O82mmx+O5wT+um+y3y2w0rUMJJdBzRu9ONU=",
   "packages/components/segmented-control/segmented-control.tsx": "sha256-MCBG5XHFWCwbACctsYKbqe8mvSSR6pf60tyRgdCDKDA=",
-  "packages/components/select/select.tsx": "sha256-IInFSuCUOPVgNMdtEsnjpqwMeVYYk+4fx33K21z0xQE=",
-  "packages/components/sheet/sheet.tsx": "sha256-gmc8rZ87NHfN/bErEWHm6HlaAoeNT/Fw6y2PrW88WFI=",
+  "packages/components/select/select.tsx": "sha256-7u1sshW6KAQgjgwQ1siN1P5GkBxboOiOJOdgLanForE=",
+  "packages/components/sheet/sheet.tsx": "sha256-U5uuIle4HMkKILrxBqp+cimv7aKGurWa8s7RYhbuIM8=",
   "packages/components/skeleton/skeleton.tsx": "sha256-2Fk72NbLr3+CrXH7jGbHNsc3t+vskMqSyySe/UwbGCs=",
   "packages/components/slider/slider.tsx": "sha256-o37Xi4J8+d/fhWFf2LdpPluuKDVXECNl4quKTlrqCU4=",
   "packages/components/spinner/spinner.tsx": "sha256-FZQmcGkQ8N0485n9bYsLTpTnolbM729YKjkQrXriz9A=",

package/src/agents.js

@@ -37,7 +37,8 @@ This project's interface is built with Mlola UI. Before writing or changing UI:
   classes. \`data-theme\` and \`data-mode\` belong to the engine.
 - The \`mlola\` MCP server (\`npx mlola-ui mcp\`) searches components, explains
   tokens and checks markup against the contract. Check new markup with its
-  \`check_markup\` tool before finishing.`;
+  \`check_markup\` tool before finishing; without the server, run
+  \`npx mlola-ui check <files>\`.`;
 
 /** Replaces the marked section, or appends it; returns what happened. */
 function mergeSection(filename, body) {

package/src/check.js

@@ -0,0 +1,257 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { CONFIG_FILENAME } from "./config.js";
+import { checkMarkup, contractFrom } from "./knowledge.js";
+
+/**
+ * `mlola-ui check`: check_markup over a whole project. It reads every file
+ * with markup or CSS, reports each issue with its file and line, and counts
+ * drift: how many colors and spacing values were typed by hand instead of
+ * read from the tokens. It works in any project, Mlola or not.
+ */
+
+const MARKUP = new Set([".html", ".htm", ".jsx", ".tsx", ".js", ".mjs", ".vue", ".svelte", ".astro"]);
+const STYLES = new Set([".css"]);
+const SKIPPED = new Set(["node_modules", ".git", ".next", ".nuxt", ".svelte-kit", ".astro", ".output", ".vercel", ".turbo", ".cache", "dist", "build", "out", "coverage", "vendor"]);
+const LARGEST = 1024 * 1024;
+
+const checkable = (file) => {
+  const extension = path.extname(file).toLowerCase();
+  return (MARKUP.has(extension) || STYLES.has(extension)) && !/\.min\.(js|css)$/i.test(file);
+};
+const inSkipped = (file) => file.split(/[\\/]/).some((part) => SKIPPED.has(part));
+
+/** The files under each target, relative to cwd: git's list when there is one, so .gitignore holds; a walk otherwise. */
+function listFiles(cwd, targets) {
+  const git = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...targets], { cwd, encoding: "utf8" });
+  let files;
+  if (!git.error && git.status === 0) {
+    files = git.stdout.split("\0").filter(Boolean);
+  } else {
+    files = [];
+    const walk = (relative) => {
+      const absolute = path.join(cwd, relative);
+      const stat = fs.statSync(absolute);
+      if (stat.isFile()) return files.push(relative);
+      for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+        if (entry.isDirectory() && (SKIPPED.has(entry.name) || entry.name.startsWith("."))) continue;
+        if (entry.isDirectory() || entry.isFile()) walk(path.join(relative, entry.name));
+      }
+    };
+    for (const target of targets) walk(target);
+  }
+  return [...new Set(files.map((file) => path.normalize(file)))]
+    .filter((file) => checkable(file) && !inSkipped(file))
+    .filter((file) => {
+      const stat = fs.statSync(path.join(cwd, file), { throwIfNoEntry: false });
+      return stat?.isFile() && stat.size <= LARGEST;
+    })
+    .sort();
+}
+
+const readJsonIn = (cwd, name) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, name), "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/** The project's own theme ids: the one mlola.config.json names and the one mlola.theme.json builds. */
+export function projectThemes(cwd) {
+  const ids = [readJsonIn(cwd, CONFIG_FILENAME)?.theme, readJsonIn(cwd, "mlola.theme.json")?.id];
+  return [...new Set(ids.filter((id) => typeof id === "string" && id))];
+}
+
+/** The utility framework the project uses, if any: there, utility classes do something. */
+function utilityFramework(cwd) {
+  const manifest = readJsonIn(cwd, "package.json") ?? {};
+  const declared = { ...manifest.dependencies, ...manifest.devDependencies };
+  const name = ["tailwindcss", "unocss", "windicss"].find((entry) => entry in declared);
+  if (name) return name;
+  const config = fs.readdirSync(cwd).find((file) => /^(tailwind|uno)\.config\.[cm]?[jt]s$/.test(file));
+  return config ? (config.startsWith("uno") ? "unocss" : "tailwindcss") : null;
+}
+
+/**
+ * What the CLI fills from Mlola itself, from mlola.config.json: `generated`
+ * (<styles>/mlola, the engine entry and the built theme, which is where the
+ * tokens are defined) is never checked; `copied` source is, with --all.
+ */
+function installedByMlola(cwd) {
+  const targets = readJsonIn(cwd, CONFIG_FILENAME)?.targets;
+  if (!targets) return { generated: [], copied: [] };
+  const styles = typeof targets.styles === "string" && targets.styles ? targets.styles : null;
+  const copied = ["components", "blocks", "pages", "templates", "lib"].map((key) => targets[key]).filter((value) => typeof value === "string" && value);
+  if (styles) copied.push(path.join(styles, "mlola-pro"), path.join(styles, "mlola-pro.css"));
+  return { generated: styles ? [path.normalize(path.join(styles, "mlola"))] : [], copied: copied.map((place) => path.normalize(place)) };
+}
+
+const within = (file, place) => file === place || file.startsWith(`${place}${path.sep}`);
+
+/** Every file under a folder, relative to cwd; nothing when it is missing. */
+function filesUnder(cwd, place, pattern) {
+  const found = [];
+  const walk = (relative) => {
+    const stat = fs.statSync(path.join(cwd, relative), { throwIfNoEntry: false });
+    if (!stat) return;
+    if (stat.isFile()) {
+      if (pattern.test(relative)) found.push(relative);
+      return;
+    }
+    for (const entry of fs.readdirSync(path.join(cwd, relative), { withFileTypes: true })) {
+      if (entry.isDirectory() && SKIPPED.has(entry.name)) continue;
+      walk(path.join(relative, entry.name));
+    }
+  };
+  walk(place);
+  return found;
+}
+
+/**
+ * The classes and values of the Pro items this project installed: their
+ * stylesheets (a Pro component's in <styles>/mlola-pro/, a block's, page's
+ * or template's beside it) and what their copied source renders. Pro's
+ * classes are not published, so the check learns them here.
+ */
+export function projectContract(cwd) {
+  const targets = readJsonIn(cwd, CONFIG_FILENAME)?.targets ?? {};
+  const place = (key) => (typeof targets[key] === "string" && targets[key] ? targets[key] : null);
+  const read = (file) => fs.readFileSync(path.join(cwd, file), "utf8");
+  const stylesheets = [
+    ...(place("styles") ? filesUnder(cwd, path.join(place("styles"), "mlola-pro"), /\.css$/) : []),
+    ...["blocks", "pages", "templates"].map(place).filter(Boolean).flatMap((folder) => filesUnder(cwd, folder, /\.css$/)),
+  ].map(read);
+  if (!stylesheets.length) return contractFrom();
+  const markups = ["components", "blocks", "pages", "templates"].map(place).filter(Boolean).flatMap((folder) => filesUnder(cwd, folder, /\.(tsx|jsx|html)$/)).map(read);
+  return contractFrom({ stylesheets, markups });
+}
+
+/** Counts each value, most used first. */
+function tally(values) {
+  const counts = new Map();
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+  return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([value, count]) => ({ value, count }));
+}
+
+/**
+ * Checks a project. `targets` are paths relative to cwd (the whole project
+ * when empty); `all` includes the source Mlola copied in.
+ */
+export function checkProject(cwd, { targets = [], all = false } = {}) {
+  for (const target of targets) {
+    if (!fs.existsSync(path.join(cwd, target))) throw new Error(`${target} does not exist.`);
+  }
+  const installed = installedByMlola(cwd);
+  const skipped = [...installed.generated, ...(all ? [] : installed.copied)];
+  const files = listFiles(cwd, targets.length ? targets : ["."]).filter((file) => !skipped.some((place) => within(file, place)));
+  const themes = projectThemes(cwd);
+  const contract = projectContract(cwd);
+  const utilities = utilityFramework(cwd);
+  const issues = [];
+  for (const file of files) {
+    const text = fs.readFileSync(path.join(cwd, file), "utf8");
+    // A stylesheet is checked as a page's <style> block; its lines stay where they are.
+    const markup = STYLES.has(path.extname(file).toLowerCase()) ? `<style>${text}</style>` : text;
+    for (const issue of checkMarkup(markup, { themes, contract })) {
+      // Where a utility framework reads them, utility classes are not dead; the values typed into them still count.
+      if (utilities && issue.rule === "utility-class") continue;
+      issues.push({ file: file.split(path.sep).join("/"), ...issue });
+    }
+  }
+  // Files in order, and within a file, lines in order.
+  issues.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+  const errors = issues.filter((issue) => issue.severity === "error").length;
+  return {
+    files: files.length,
+    utilities,
+    skipped: skipped.filter((place) => fs.existsSync(path.join(cwd, place))).map((place) => place.split(path.sep).join("/")),
+    all,
+    errors,
+    warnings: issues.length - errors,
+    issues,
+    drift: {
+      colors: tally(issues.filter((issue) => issue.rule === "color").flatMap((issue) => issue.values ?? [])),
+      spacing: tally(issues.filter((issue) => issue.rule === "spacing").flatMap((issue) => issue.values ?? [])),
+    },
+  };
+}
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+const listed = (entries) => entries.slice(0, 6).map((entry) => (entry.count > 1 ? `${entry.value} ×${entry.count}` : entry.value)).join(", ") + (entries.length > 6 ? `, and ${entries.length - 6} more` : "");
+// GitHub reads ::error lines as annotations on the pull request; these characters would end one early.
+const escape = (text) => String(text).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escapeProperty = (text) => escape(text).replace(/:/g, "%3A").replace(/,/g, "%2C");
+
+/** Up to this many issues are listed one by one; past it, the report names the files with the most. */
+const LISTED = 60;
+const ANNOTATED = 50;
+const KINDS = [
+  [["color"], "colors typed by hand"],
+  [["spacing"], "spacing typed by hand"],
+  [["unknown-class", "variant-class"], "classes Mlola does not have"],
+  [["value", "no-effect"], "data-* values an element does not take"],
+  [["theme", "mode"], "theme and mode attributes"],
+  [["theme-token"], "theme tokens overridden"],
+  [["opacity"], "text faded with opacity"],
+  [["utility-class"], "utility classes"],
+];
+
+/** The report a person reads, and on GitHub Actions the annotations a pull request shows. */
+export function printReport(report, output, { github = false } = {}) {
+  const byFile = new Map();
+  for (const issue of report.issues) {
+    if (!byFile.has(issue.file)) byFile.set(issue.file, []);
+    byFile.get(issue.file).push(issue);
+  }
+  if (report.issues.length <= LISTED) {
+    for (const [file, issues] of byFile) {
+      output.log(file);
+      for (const issue of issues) {
+        output.log(`  ${String(issue.line).padStart(4)}  ${issue.severity.padEnd(7)}  ${issue.message}`);
+        if (issue.fix) output.log(`${" ".repeat(17)}${issue.fix}`);
+      }
+      output.log("");
+    }
+  } else {
+    output.log("By kind:");
+    for (const [rules, label] of KINDS) {
+      const count = report.issues.filter((issue) => rules.includes(issue.rule)).length;
+      if (count) output.log(`  ${String(count).padStart(6)}  ${label}`);
+    }
+    output.log("");
+    output.log("Most issues:");
+    for (const [file, issues] of [...byFile].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0])).slice(0, 12)) {
+      output.log(`  ${String(issues.length).padStart(6)}  ${file}`);
+    }
+    output.log("");
+    output.log("Every issue with its line and fix: add --json, or check one folder at a time (npx mlola-ui check src/components).");
+    output.log("");
+  }
+  if (github) {
+    for (const issue of report.issues.slice(0, ANNOTATED)) {
+      output.log(`::${issue.severity === "error" ? "error" : "warning"} file=${escapeProperty(issue.file)},line=${issue.line},title=${escapeProperty(`Mlola: ${issue.rule}`)}::${escape(issue.fix ? `${issue.message} ${issue.fix}` : issue.message)}`);
+    }
+    if (report.issues.length > ANNOTATED) output.log(`Annotated the first ${ANNOTATED} of ${report.issues.length} issues; --json lists every one.`);
+  }
+  if (!report.issues.length) {
+    output.log(`✓ Checked ${plural(report.files, "file")}: no issues.`);
+  } else {
+    output.log(`Checked ${plural(report.files, "file")}: ${plural(report.errors, "error")} and ${plural(report.warnings, "warning")} in ${plural(byFile.size, "file")}.`);
+  }
+  const { colors, spacing } = report.drift;
+  if (colors.length || spacing.length) {
+    output.log("Drift, typed by hand instead of read from the tokens:");
+    if (colors.length) output.log(`  ${plural(colors.length, "color")}: ${listed(colors)}`);
+    if (spacing.length) output.log(`  ${plural(spacing.length, "spacing value")}: ${listed(spacing)}`);
+  }
+  if (report.utilities) output.log(`Utility classes are left alone: this project uses ${report.utilities}. Values typed into them (bg-[#fafafa], p-[13px]) still count.`);
+  if (report.skipped.length) {
+    output.log(
+      report.all
+        ? `Left out the stylesheets Mlola generates (${report.skipped.join(", ")}), where the tokens are defined.`
+        : `Left out what Mlola installed (${report.skipped.join(", ")}); --all checks the copied source too.`,
+    );
+  }
+}

package/src/cli.js

@@ -7,6 +7,7 @@ import {
   writeDefaultConfig,
 } from "./config.js";
 import { writeAgentFiles } from "./agents.js";
+import { checkProject, printReport } from "./check.js";
 import { addAssets, assetHint, loadAssetIndex } from "./assets.js";
 import { runDoctor } from "./doctor.js";
 import { collectEngineDependencies, installItems } from "./installer.js";
@@ -28,6 +29,7 @@ Usage:
   mlola-ui logout
   mlola-ui list [--kind component|block|template|asset] [--json]
   mlola-ui doctor
+  mlola-ui check [path...] [--json] [--strict] [--all]
   mlola-ui theme pull <theme-id | url> [--host <url>] [--overwrite]
   mlola-ui theme build [--file mlola.theme.json]
 
@@ -41,6 +43,7 @@ Examples:
   npx mlola-ui theme pull https://ui.mlola.com/t/th-4k2x9qf7wz3m
   npx mlola-ui theme build            (renders your mlola.theme.json, offline)
   npx mlola-ui mcp                    (an MCP server for Claude Code, Cursor, Codex…)
+  npx mlola-ui check src              (colors and spacing typed by hand, classes that do not exist)
 `;
 
 const CLI_VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -345,6 +348,15 @@ export async function run(argv, options = {}) {
       return 0;
     }
 
+    if (command === "check") {
+      const targets = args.filter((argument) => !argument.startsWith("--"));
+      const report = checkProject(cwd, { targets, all: hasFlag(args, "--all") });
+      if (hasFlag(args, "--json")) output.log(JSON.stringify(report, null, 2));
+      else printReport(report, output, { github: env.GITHUB_ACTIONS === "true" });
+      // A CI step fails on errors; with --strict, on warnings too.
+      return report.errors || (hasFlag(args, "--strict") && report.warnings) ? 1 : 0;
+    }
+
     if (command === "doctor") {
       const findings = runDoctor(cwd);
       for (const item of findings) {

package/src/knowledge.js

@@ -192,6 +192,13 @@ export function themes() {
 const SHARED = new Set(["data-tone", "data-variant", "data-size", "data-state", "data-status"]);
 const UTILITY = /^(-?(m|p)[trblxy]?-\d|flex$|grid$|block$|inline|hidden$|items-|justify-|gap-|w-|h-|min-|max-|text-(xs|sm|base|lg|xl|\d|[a-z]+-\d)|font-(bold|medium|semibold|light)|bg-|border-|rounded|shadow|ring-|space-[xy]-|leading-|tracking-|opacity-|z-\d|absolute$|relative$|fixed$|sticky$|overflow-|col-span|row-span|sm:|md:|lg:|xl:|hover:|focus:|dark:)/;
 const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
+/** A margin-left utility (ml-4, ml-auto), which only looks like a Mlola class. */
+const MARGIN_UTILITY = /^-?ml-(?:\d|auto$|px$|\[)/;
+/** An arbitrary value in a utility class: a color (bg-[#fafafa]) or a spacing length (p-[13px]) typed by hand. */
+const ARBITRARY_COLOR = /-\[(#[0-9a-f]{3,8}|(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\([^\]]*\))\]$/i;
+const ARBITRARY_SPACING = /^(?:[\w-]+:)*-?(?:[pm][trblxyse]?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left)-\[(-?(?:\d*\.)?\d+(?:px|rem|em))\]$/;
+const COLORS = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\([^)]*\)/gi;
+const LENGTH = /-?(?:\d*\.)?\d+(?:px|rem|em)\b/g;
 
 /*
  * Spacing written by hand: a padding, margin, gap or inset whose length is
@@ -201,7 +208,24 @@ const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
  */
 const SPACING_CSS = /(?:^|[;{\s])((?:padding|margin|inset)(?:-(?:top|right|bottom|left|inline|block)(?:-(?:start|end))?)?|(?:row-|column-)?gap)\s*:\s*([^;}]+)/gi;
 const SPACING_JS = /(?:^|[{,\s])((?:padding|margin|inset)(?:Top|Right|Bottom|Left|Inline|Block)?(?:Start|End)?|(?:row|column)?[gG]ap)\s*:\s*("[^"]*"|'[^']*'|`[^`]*`|-?\d+(?:\.\d+)?(?=\s*[,}]))/g;
-const byHand = (value) => !/var\(--ml-/.test(value) && [...value.matchAll(/-?(?:\d*\.)?\d+(?:px|rem|em)\b/g)].some((length) => parseFloat(length[0]) !== 0);
+const byHand = (value) => !/var\(--ml-/.test(value) && [...value.matchAll(LENGTH)].some((length) => parseFloat(length[0]) !== 0);
+
+/** The lengths a hand-written spacing declaration uses (a bare JSX number is pixels), for counting drift. */
+const lengthsOf = (declarations) =>
+  declarations.flatMap((declaration) => {
+    const value = declaration.slice(declaration.indexOf(":") + 1).trim();
+    if (/^-?\d+(?:\.\d+)?$/.test(value)) return [`${Number(value)}px`];
+    return [...value.matchAll(LENGTH)].map((length) => length[0]).filter((length) => parseFloat(length) !== 0);
+  });
+
+/** Text of the same length with nothing in it, so what is left keeps its offsets. */
+const blank = (text) => text.replace(/[^\n]/g, " ");
+
+/** A color derived from a token (oklch(from var(--ml-primary-text) l c h / 50%)) follows the theme, so it is not written by hand. */
+const underived = (text) => text.replace(/\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(\s*from\s+var\(--ml-[\w-]+\)[^)]*\)/gi, blank);
+
+/** The colors a declaration writes by hand, lower-cased so #FFF and #fff count once. */
+const colorsOf = (text) => [...underived(text).matchAll(COLORS)].map((match) => match[0].toLowerCase().replace(/\s+/g, " "));
 
 /** Each spacing property in a style string, a JSX style object or a stylesheet whose length is written by hand. */
 function handSpacing(text) {
@@ -218,7 +242,7 @@ function handSpacing(text) {
 const SPACING_FIX = "Measure with the scale: var(--ml-space-2), var(--ml-space-4)… (get_tokens spacing). A calc() or clamp() of scale steps is fine; a value invented between them is not.";
 
 /** Every opening tag in HTML or JSX, with its string-valued attributes. */
-function tagsOf(markup) {
+export function tagsOf(markup) {
   const tags = [];
   for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)((?:\s+(?:[^\s"'>={}]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}))?))*)\s*\/?>/g)) {
     const attributes = new Map();
@@ -231,7 +255,7 @@ function tagsOf(markup) {
       if (expression) attributes.set(`${name}:raw`, expression);
     }
     const classValue = attributes.get("class") ?? attributes.get("className");
-    tags.push({ tag: match[0], attributes, classes: typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [] });
+    tags.push({ tag: match[0], index: match.index, attributes, classes: typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [] });
   }
   return tags;
 }
@@ -282,23 +306,93 @@ function valuesByElement() {
   return knownValues;
 }
 
+/**
+ * The classes some stylesheets define and the data-* values each element
+ * takes: the ones the CSS draws, and the ones the markup renders itself (a
+ * default such as data-tone="primary" is drawn by the base rule, and as
+ * correct as any other). Pro's classes are not published, so a check learns
+ * them this way from the Pro items a project has installed.
+ */
+export function contractFrom({ stylesheets = [], markups = [] } = {}) {
+  const classes = new Set();
+  const elements = new Map();
+  const add = (cls, attribute, value) => {
+    if (!elements.has(cls)) elements.set(cls, new Map());
+    if (!elements.get(cls).has(attribute)) elements.get(cls).set(attribute, new Set());
+    elements.get(cls).get(attribute).add(value);
+  };
+  for (const text of stylesheets) {
+    const css = text.replace(/\/\*[\s\S]*?\*\//g, "");
+    for (const match of css.matchAll(/\.(ml-[a-z0-9-]+)/g)) classes.add(match[1]);
+    for (const match of css.matchAll(/\.(ml-[a-z0-9-]+)((?:\[data-[a-z-]+(?:=["']?[^\]"']*["']?)?\])+)/g)) {
+      for (const [, attribute, value] of match[2].matchAll(/\[(data-[a-z-]+)=["']?([^\]"']*)["']?\]/g)) add(match[1], attribute, value);
+    }
+  }
+  for (const markup of markups) {
+    for (const { attributes, classes: rendered } of tagsOf(markup)) {
+      for (const [name, value] of attributes) {
+        if (!name.startsWith("data-") || typeof value !== "string" || !value) continue;
+        for (const cls of rendered) if (classes.has(cls)) add(cls, name, value);
+      }
+    }
+  }
+  return { classes, elements };
+}
+
 /**
  * Checks HTML or JSX against the element contract. It reads string-valued
  * class, className, style and data-* attributes; expressions in braces are
  * skipped, since their value is only known at runtime.
+ *
+ * Each issue names its line, the rule it breaks (`rule`) and, for a color or
+ * a spacing written by hand, the values themselves (`values`), which
+ * `mlola-ui check` counts as drift across a project.
+ *
+ * `themes` adds the project's own theme ids; `contract` (from contractFrom)
+ * adds the classes and values of the Pro items the project installed.
  */
-export function checkMarkup(markup) {
+export function checkMarkup(markup, { themes: ownThemes = [], contract: installed } = {}) {
   const contract = bundled("contract.json");
-  const known = new Set(contract?.classes ?? []);
+  const known = new Set([...(contract?.classes ?? []), ...(installed?.classes ?? [])]);
   const proPrefixes = (bundled("catalog.json")?.items ?? []).map((item) => `ml-${item.name}`);
-  const themeIds = new Set(themes().map((theme) => theme.id));
+  // The five themes, and the project's own (mlola.theme.json) when the caller knows the project.
+  const themeIds = new Set([...themes().map((theme) => theme.id), ...ownThemes]);
   const tokenNames = new Set((designData()?.tokens ?? []).flatMap((group) => group.names));
-  const values = valuesByElement();
+  const shared = valuesByElement();
+  const values = {
+    get: (cls) => {
+      const own = installed?.elements.get(cls);
+      if (!own) return shared.get(cls);
+      const merged = new Map(shared.get(cls) ?? []);
+      for (const [attribute, list] of own) merged.set(attribute, new Set([...(merged.get(attribute) ?? []), ...list]));
+      return merged;
+    },
+  };
   const issues = [];
-  const note = (severity, tag, message, fix) => issues.push({ severity, element: tag.slice(0, 120), message, ...(fix ? { fix } : {}) });
+  const breaks = [];
+  for (let index = markup.indexOf("\n"); index !== -1; index = markup.indexOf("\n", index + 1)) breaks.push(index);
+  const lineAt = (offset) => {
+    let low = 0;
+    let high = breaks.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if (breaks[middle] < offset) low = middle + 1;
+      else high = middle;
+    }
+    return low + 1;
+  };
+  let at = 0;
+  const note = (severity, tag, message, fix, rule, values) =>
+    issues.push({ severity, line: lineAt(at), rule, element: tag.slice(0, 120), message, ...(fix ? { fix } : {}), ...(values?.length ? { values } : {}) });
 
-  for (const { tag, attributes, classes } of tagsOf(markup)) {
-    const mlola = classes.filter((cls) => cls.startsWith("ml-"));
+  for (const { tag, index, attributes, classes } of tagsOf(markup)) {
+    // An issue points at its attribute, so a tag written over several lines reports the right one.
+    const attributeAt = (pattern) => {
+      const found = tag.search(pattern);
+      at = index + Math.max(0, found);
+    };
+    attributeAt(/\sclass(?:Name)?\s*=/);
+    const mlola = classes.filter((cls) => cls.startsWith("ml-") && !MARGIN_UTILITY.test(cls));
 
     for (const cls of mlola) {
       if (known.has(cls) || proPrefixes.some((prefix) => cls === prefix || cls.startsWith(`${prefix}-`))) continue;
@@ -308,28 +402,39 @@ export function checkMarkup(markup) {
         tag,
         `"${cls}" is not a Mlola class.`,
         base ? `Mlola has no variant classes: use "${base}" with a data-* attribute (data-variant, data-tone, data-size).` : "Search with search_components, or name your own element with your own prefix (not ml-).",
+        base ? "variant-class" : "unknown-class",
       );
     }
-    const utilities = classes.filter((cls) => !cls.startsWith("ml-") && UTILITY.test(cls));
+    const utilities = classes.filter((cls) => (!cls.startsWith("ml-") || MARGIN_UTILITY.test(cls)) && UTILITY.test(cls));
     if (utilities.length) {
-      note("warning", tag, `Utility classes (${utilities.slice(0, 4).join(" ")}) do nothing here: Mlola ships no utility framework.`, "Use a component or composition primitive; for your own CSS, read --ml-* tokens.");
+      note("warning", tag, `Utility classes (${utilities.slice(0, 4).join(" ")}) do nothing here: Mlola ships no utility framework.`, "Use a component or composition primitive; for your own CSS, read --ml-* tokens.", "utility-class");
+    }
+    // Values typed into utility classes are drift whichever framework reads them.
+    const arbitraryColors = classes.map((cls) => ARBITRARY_COLOR.exec(cls)).filter(Boolean);
+    if (arbitraryColors.length) {
+      note("error", tag, `A color is written by hand in a class (${arbitraryColors.map((match) => match.input).slice(0, 4).join(" ")}).`, "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).", "color", arbitraryColors.map((match) => match[1].toLowerCase()));
+    }
+    const arbitrarySpacing = classes.map((cls) => ARBITRARY_SPACING.exec(cls)).filter(Boolean);
+    if (arbitrarySpacing.length) {
+      note("warning", tag, `Spacing is written by hand in a class (${arbitrarySpacing.map((match) => match.input).slice(0, 4).join(" ")}).`, SPACING_FIX, "spacing", arbitrarySpacing.map((match) => match[1]));
     }
 
     for (const [name, value] of attributes) {
       if (!name.startsWith("data-") || typeof value !== "string") continue;
+      attributeAt(new RegExp(`\\s${name}\\s*=`));
       if (name === "data-theme" && value && !themeIds.has(value) && !/^th-[0-9a-z]{12}$/.test(value)) {
-        note("error", tag, `data-theme="${value}" is not a theme.`, `Use one of: ${[...themeIds].join(", ")}, or a Studio theme id.`);
+        note("error", tag, `data-theme="${value}" is not a theme.`, `Use one of: ${[...themeIds].join(", ")}, or a Studio theme id.`, "theme");
       }
       if (name === "data-mode" && !["light", "dark", "system"].includes(value)) {
-        note("error", tag, `data-mode is "light", "dark" or "system"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.");
+        note("error", tag, `data-mode is "light", "dark" or "system"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.", "mode");
       }
       if (!SHARED.has(name) || !mlola.length) continue;
       const allowed = new Set();
       for (const cls of mlola) for (const entry of values.get(cls)?.get(name) ?? []) allowed.add(entry);
       if (allowed.size && !allowed.has(value)) {
-        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} takes.`, `Allowed: ${[...allowed].sort().join(", ")}.`);
+        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} takes.`, `Allowed: ${[...allowed].sort().join(", ")}.`, "value");
       } else if (!allowed.size && mlola.every((cls) => known.has(cls))) {
-        note("warning", tag, `${name} has no effect on ${mlola.join(" ")}.`, `See get_component for the attributes it reacts to.`);
+        note("warning", tag, `${name} has no effect on ${mlola.join(" ")}.`, `See get_component for the attributes it reacts to.`, "no-effect");
       }
     }
 
@@ -338,45 +443,63 @@ export function checkMarkup(markup) {
     // theme token set inline overrides the theme and is flagged too.
     const style = attributes.get("style") ?? attributes.get("style:raw");
     if (typeof style === "string") {
-      const overridden = [...style.matchAll(/(--ml-[\w-]+)\s*:/g)].map((match) => match[1]).filter((token) => tokenNames.has(token));
-      const declarations = style.replace(/--[\w-]+\s*:[^;,}]*/g, "");
+      attributeAt(/\sstyle\s*=/);
+      // A custom property is named bare in CSS and quoted in a JSX style object ("--ml-color": …).
+      const overridden = [...style.matchAll(/(--ml-[\w-]+)["']?\s*:/g)].map((match) => match[1]).filter((token) => tokenNames.has(token));
+      const declarations = underived(style.replace(/["']?--[\w-]+["']?\s*:[^;,}]*/g, ""));
       if (COLOR.test(declarations)) {
-        note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).");
+        note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).", "color", colorsOf(declarations));
       }
       if (overridden.length) {
-        note("error", tag, `${overridden.join(", ")} is a theme token; setting it inline overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of one element's tokens.");
+        note("error", tag, `${overridden.join(", ")} is a theme token; setting it inline overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of one element's tokens.", "theme-token");
       }
       const spacing = handSpacing(style);
-      if (spacing.length) note("warning", tag, `Spacing is written by hand in style (${spacing.join("; ")}).`, SPACING_FIX);
+      if (spacing.length) note("warning", tag, `Spacing is written by hand in style (${spacing.join("; ")}).`, SPACING_FIX, "spacing", lengthsOf(spacing));
     }
   }
 
   // The page's own stylesheet: the same rules hold in a <style> block.
-  for (const [, css] of markup.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
-    for (const rule of css.replace(/\/\*[\s\S]*?\*\//g, "").split("}")) {
+  for (const block of markup.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    // Comments become blanks of the same length, so every offset still points into the markup.
+    const css = block[1].replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "));
+    let offset = block.index + block[0].indexOf(">") + 1;
+    for (const rule of css.split("}")) {
+      const start = offset;
+      offset += rule.length + 1;
       const open = rule.lastIndexOf("{");
       if (open < 0) continue;
+      const bodyAt = start + open + 1;
+      at = bodyAt;
       const selector = rule.slice(0, open).split("{").pop().trim();
       // A keyframe (from, to, 50%) is a step of an animation, not a rule for text at rest.
       if (/^(from|to|\d+(\.\d+)?%)(\s*,\s*(from|to|\d+(\.\d+)?%))*$/i.test(selector)) continue;
-      const body = rule.slice(open + 1).replace(/url\([^)]*\)/g, "");
+      // url() and custom properties are blanked, not removed, so a match's index is its place in the markup.
+      const body = rule.slice(open + 1).replace(/url\([^)]*\)/g, blank);
+      const own = underived(body.replace(/--[\w-]+\s*:[^;]*/g, blank));
+      const pointAt = (found) => {
+        at = bodyAt + Math.max(0, found);
+      };
       const where = `<style> ${selector}`;
       const overridden = [...body.matchAll(/(--ml-[\w-]+)\s*:/g)].map((match) => match[1]).filter((token) => tokenNames.has(token));
-      if (COLOR.test(body.replace(/--[\w-]+\s*:[^;]*/g, ""))) {
-        note("error", where, "A color is written by hand in the stylesheet.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens). The theme then keeps its contrast in every mode.");
+      if (COLOR.test(own)) {
+        pointAt(own.search(COLOR));
+        note("error", where, "A color is written by hand in the stylesheet.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens). The theme then keeps its contrast in every mode.", "color", colorsOf(own));
       }
       if (overridden.length) {
-        note("error", where, `${overridden.join(", ")} is a theme token; setting it here overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of redefining its tokens.");
+        pointAt(body.indexOf(overridden[0]));
+        note("error", where, `${overridden.join(", ")} is a theme token; setting it here overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of redefining its tokens.", "theme-token");
       }
       const spacing = handSpacing(body);
-      if (spacing.length) note("warning", where, `Spacing is written by hand (${spacing.join("; ")}).`, SPACING_FIX);
+      if (spacing.length) pointAt(body.search(new RegExp(`(?:^|[;{\\s])${spacing[0].slice(0, spacing[0].indexOf(":"))}\\s*:`)) + 1);
+      if (spacing.length) note("warning", where, `Spacing is written by hand (${spacing.join("; ")}).`, SPACING_FIX, "spacing", lengthsOf(spacing));
       // Faded text: its contrast now depends on the theme behind it.
       // opacity: 0 hides; only a value between 0 and 1 fades what is still read.
       const opacity = /(?:^|;)\s*opacity\s*:\s*(0?\.\d+)\s*(?:;|$)/.exec(body);
       // A shape (an SVG area, line or mark, painted with fill or stroke) holds no text to fade.
       const shape = /(?:^|;)\s*(?:fill|stroke)\s*:/.test(body) || /\b(?:path|rect|circle|ellipse|line|polyline|polygon|svg)\b/.test(selector);
       if (opacity && Number(opacity[1]) > 0 && !shape && !/disabled|:empty|::?placeholder|\[hidden\]|inert/.test(selector)) {
-        note("warning", where, `opacity: ${opacity[1]} fades whatever text is inside, and how far it falls below the contrast floor depends on the theme and the fill behind it.`, "For quieter text use color: var(--ml-text-muted); on a filled control, its -foreground role. Keep opacity for disabled or decorative parts.");
+        pointAt(opacity.index + opacity[0].indexOf("opacity"));
+        note("warning", where, `opacity: ${opacity[1]} fades whatever text is inside, and how far it falls below the contrast floor depends on the theme and the fill behind it.`, "For quieter text use color: var(--ml-text-muted); on a filled control, its -foreground role. Keep opacity for disabled or decorative parts.", "opacity");
       }
     }
   }

package/src/mcp.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
+import { projectContract, projectThemes } from "./check.js";
 import { checkMarkup, describeItem, designData, designGuide, searchItems, suggest, themes, tokens } from "./knowledge.js";
 
 /**
@@ -45,7 +46,7 @@ export function noBuildSetup(version) {
 }
 
 /** Tools that only read the registry: the local and the remote server share them. */
-function readTools({ cwd, version }) {
+function readTools({ cwd, version, project = false }) {
   return [
     {
       name: "get_design_rules",
@@ -104,11 +105,12 @@ function readTools({ cwd, version }) {
     {
       name: "check_markup",
       title: "Check markup against the Mlola contract",
-      description: "Checks HTML or JSX: classes that do not exist, variant classes, data-* values a class does not react to, utility classes, misuse of data-theme or data-mode, and in style attributes and <style> blocks hand-written colors, spacing written by hand instead of the --ml-space-* scale, overridden theme tokens and text faded with opacity. Run it on markup you wrote before finishing: pass the whole page or file, <style> blocks included, not an excerpt, since it only checks what it is given.",
+      description: "Checks HTML or JSX: classes that do not exist, variant classes, data-* values a class does not react to, utility classes, misuse of data-theme or data-mode, and in style attributes, <style> blocks and utility classes (bg-[#fafafa]) hand-written colors, spacing written by hand instead of the --ml-space-* scale, overridden theme tokens and text faded with opacity. Each issue names its line. Run it on markup you wrote before finishing: pass the whole page or file, <style> blocks included, not an excerpt, since it only checks what it is given.",
       inputSchema: { type: "object", properties: { markup: { type: "string" } }, required: ["markup"], additionalProperties: false },
       annotations: { readOnlyHint: true },
       handler: ({ markup }) => {
-        const issues = checkMarkup(markup);
+        // The local server knows the project: its own theme is a theme, and the Pro items it installed exist.
+        const issues = checkMarkup(markup, project ? { themes: projectThemes(cwd), contract: projectContract(cwd) } : {});
         return text(issues.length ? issues : "No issues: every Mlola class exists and every data-* value is one its element reacts to.");
       },
     },
@@ -125,7 +127,7 @@ function tools({ cwd, run, version }) {
     return { code, output: lines.join("\n") };
   };
   return [
-    ...readTools({ cwd, version }),
+    ...readTools({ cwd, version, project: true }),
     {
       name: "add_components",
       title: "Install Mlola components",