From ebc7a25517c4fe9f9b0878c760ef24c4a714b867 Mon Sep 17 00:00:00 2001
From: Hermes BUILD <48018975+nujovich@users.noreply.github.com>
Date: Tue, 21 Jul 2026 17:41:12 +0200
Subject: [PATCH 1/4] chore(mint): scaffold BUILD-PLAN for @property type-check
 (card #8)

---
 BUILD-PLAN-issue-8.md | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 BUILD-PLAN-issue-8.md

diff --git a/BUILD-PLAN-issue-8.md b/BUILD-PLAN-issue-8.md
new file mode 100644
index 0000000..a5f3027
--- /dev/null
+++ b/BUILD-PLAN-issue-8.md
@@ -0,0 +1,11 @@
+# BUILD-PLAN-issue-8.md
+
+**Card:** https://github.com/nujovich/mint-radar/issues/8
+**Decision:** Nadia approved ready-to-build (2026-06-16 PLAN)
+
+## Milestones
+
+- [ ] Milestone 1 — Extend audit prompt in lib/prompts.mjs with @property analysis step: detect @property registrations, validate var() assignments against declared syntax, report type mismatches
+- [ ] Milestone 2 — Add @property type-check fields to AuditReport type in lib/types.ts
+- [ ] Milestone 3 — Wire @property results in the playground UI (app/page.tsx)
+- [ ] Milestone 4 — Add test fixture with @property examples in lib/**fixtures**/ and corresponding test in lib/**tests**/

From 626aa7901f36d01d30b287618332fff5e7232b21 Mon Sep 17 00:00:00 2001
From: Hermes BUILD <48018975+nujovich@users.noreply.github.com>
Date: Tue, 21 Jul 2026 17:47:25 +0200
Subject: [PATCH 2/4] feat(mint): add @property type-check analysis step to CSS
 audit prompt

---
 lib/prompts.mjs | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/lib/prompts.mjs b/lib/prompts.mjs
index 130236a..bd844fb 100644
--- a/lib/prompts.mjs
+++ b/lib/prompts.mjs
@@ -198,7 +198,49 @@ For each such case, record:
 - "severity": "suggestion"
 - "reason": a specific message identifying the overflow risk (e.g. "Grid container with fixed height but no overflow handling — content may be clipped if grid items exceed the container" or "Flex container with max-width and no overflow property — ensure overflow is handled explicitly")
 
-Only report up to 8 overflowSafetyIssues total. Prioritize flex-wrap-missing (warnings) first, then missing-overflow-wrap (suggestions).</instructions>
+Only report up to 8 overflowSafetyIssues total. Prioritize flex-wrap-missing (warnings) first, then missing-overflow-wrap (suggestions).
+
+STEP 13 — CSS @PROPERTY TYPE CHECKING
+Scan the CSS for @property at-rules. An @property registration defines a custom property's type contract via the syntax descriptor:
+
+@property --my-color {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #ff0000;
+}
+
+For each @property registration found:
+- Record the property name (e.g. "--my-color"), its declared syntax (e.g. "<color>", "<length>", "<number>"), and the initial-value if present.
+- Then scan all var() usages of that registered property throughout the CSS. A var() usage is any appearance of var(--prop-name) in a property value.
+- For each var() usage, check whether the assigned value or context is compatible with the declared syntax:
+  - <color>: accepts hex, rgb(), rgba(), hsl(), hsla(), named colors, currentColor, transparent
+  - <length>: accepts px, em, rem, vh, vw, vmin, vmax, ch, ex, cm, mm, in, pt, pc, 0, calc() expressions
+  - <number>: accepts plain numbers (1, 0.5, 2.3), calc() that evaluates to a number
+  - <integer>: accepts whole numbers (1, 0, -1), calc() that evaluates to an integer
+  - <percentage>: accepts percentage values (50%, 100%)
+  - <angle>: accepts deg, rad, grad, turn
+  - <time>: accepts s, ms
+  - <length-percentage>: accepts any length or percentage
+  - <transform-function>: accepts transform functions (rotate(), scale(), translate(), etc.)
+  - <custom-ident>: accepts any valid CSS identifier
+  - <string>: accepts quoted strings
+  - <url>: accepts url()
+  - "*": universal — accepts any value (no type checking possible)
+
+When the var(--prop-name) usage appears to contradict the declared syntax, record it. Examples:
+- var(--my-color, 14px) — <color> with a <length> fallback → type mismatch
+- var(--my-spacing) used inside background-color — suggests the property may be misused
+- var(--my-size, red) — <length> with a <color> fallback → type mismatch
+
+Focus on clear type mismatches: a <color> custom property receiving a length value, or a <length> receiving a color. Skip ambiguous cases where the type cannot be determined from the CSS alone (e.g., a var() whose value comes from a different stylesheet or JavaScript).
+
+For each type mismatch found, record:
+- "propertyName": the @property name (e.g. "--my-color")
+- "declaredSyntax": the declared syntax string
+- "location": selector and property name where the mismatch occurs
+- "issue": description of the mismatch (e.g. "<color> property receives a <length> value")
+
+Only report up to 8 propertyTypeIssues total. If no @property registrations exist in the CSS, record an empty array.</instructions>
 
 <output_format>
 Return ONLY a valid JSON object matching the structure in the example below. No markdown fences, no backticks, no text before or after the JSON.
@@ -267,6 +309,10 @@ Return ONLY a valid JSON object matching the structure in the example below. No
   "overflowSafetyIssues": [
     { "selector": ".nav-list", "rule": "flex-wrap-missing", "severity": "warning", "reason": "Flex container without \`flex-wrap\` — items will not wrap and may overflow on narrow viewports" },
     { "selector": ".dashboard-grid", "rule": "missing-overflow-wrap", "severity": "suggestion", "reason": "Grid container with fixed height but no overflow handling — content may be clipped if grid items exceed the container" }
+  ],
+  "propertyTypeIssues": [
+    { "propertyName": "--my-color", "declaredSyntax": "<color>", "location": ".button >> background-color", "issue": "<color> property receives a <length> value (14px)" },
+    { "propertyName": "--spacing-unit", "declaredSyntax": "<length>", "location": ".card >> color", "issue": "<length> property used in a color context, possible type mismatch" }
   ]
 }
 </example>

From bfa9a2265f9d32257dfae32e7c71bcfbef3841f6 Mon Sep 17 00:00:00 2001
From: Nadia Nujovich <nujovich@gmail.com>
Date: Mon, 27 Jul 2026 12:29:49 +0200
Subject: [PATCH 3/4] fix(mint): wire @property type checking into the shared
 lint contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

STEP 13 emitted its own field shape (propertyName / declaredSyntax /
location / issue), which neither the shared lint renderer nor the summary
registry can read. Findings were produced by the model and then silently
dropped: an empty severity badge, "—" as the anchor and a blank reason in
the playground, and no entry at all in the CLI summary.

- align propertyTypeIssues with the contract every other lint category
  follows: selector, property, rule, severity, reason (plus propertyName
  and declaredSyntax as extras)
- split STEP 13 into three named rules: invalid-initial-value,
  fallback-type-mismatch, property-type-mismatch
- detect invalid initial-value, where a syntax/initial-value mismatch (or
  a missing initial-value on a non-universal syntax) makes the browser
  reject the whole registration
- drop the ad-hoc ">>" location separator in favour of selector+property
- narrow the foreign-context rule to unambiguous cases to limit false
  positives
- register propertyTypeIssues in LINT_CATEGORIES so both the CLI summary
  and AuditView surface it
- add PropertyTypeIssue to AuditReport
- assert the shared severity/reason/anchor fields across all five lint
  categories by parsing the prompt's own output example
- add lib/__fixtures__/at-property.css covering one case per rule
- remove the BUILD-PLAN-issue-8.md scratch file
---
 BUILD-PLAN-issue-8.md                |  11 ---
 lib/__fixtures__/at-property.css     |  48 ++++++++++++
 lib/__tests__/audit-summary.test.mjs |  33 +++++++-
 lib/__tests__/css-auditor.test.mjs   | 110 +++++++++++++++++++++++++++
 lib/__tests__/prompts.test.mjs       |  84 +++++++++++++++++++-
 lib/audit-summary.mjs                |   5 ++
 lib/prompts.mjs                      |  39 +++++-----
 lib/types.ts                         |  11 +++
 8 files changed, 309 insertions(+), 32 deletions(-)
 delete mode 100644 BUILD-PLAN-issue-8.md
 create mode 100644 lib/__fixtures__/at-property.css

diff --git a/BUILD-PLAN-issue-8.md b/BUILD-PLAN-issue-8.md
deleted file mode 100644
index a5f3027..0000000
--- a/BUILD-PLAN-issue-8.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# BUILD-PLAN-issue-8.md
-
-**Card:** https://github.com/nujovich/mint-radar/issues/8
-**Decision:** Nadia approved ready-to-build (2026-06-16 PLAN)
-
-## Milestones
-
-- [ ] Milestone 1 — Extend audit prompt in lib/prompts.mjs with @property analysis step: detect @property registrations, validate var() assignments against declared syntax, report type mismatches
-- [ ] Milestone 2 — Add @property type-check fields to AuditReport type in lib/types.ts
-- [ ] Milestone 3 — Wire @property results in the playground UI (app/page.tsx)
-- [ ] Milestone 4 — Add test fixture with @property examples in lib/**fixtures**/ and corresponding test in lib/**tests**/
diff --git a/lib/__fixtures__/at-property.css b/lib/__fixtures__/at-property.css
new file mode 100644
index 0000000..ef4b28b
--- /dev/null
+++ b/lib/__fixtures__/at-property.css
@@ -0,0 +1,48 @@
+/* Fixture for STEP 13 — CSS @property type checking.
+   Covers one clean registration plus one case per reported rule. */
+
+/* Valid: initial-value parses as the declared syntax. */
+@property --brand-color {
+  syntax: '<color>';
+  inherits: false;
+  initial-value: #6366f1;
+}
+
+/* invalid-initial-value: declared <length>, initial-value is a color.
+   The browser rejects this registration outright. */
+@property --spacing-unit {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: red;
+}
+
+/* invalid-initial-value: non-universal syntax with no initial-value at all. */
+@property --card-radius {
+  syntax: '<length>';
+  inherits: true;
+}
+
+/* Universal syntax — not type-checkable, STEP 13 must skip it. */
+@property --anything {
+  syntax: '*';
+  inherits: false;
+}
+
+.button {
+  /* fallback-type-mismatch: <color> property falling back to a length. */
+  background-color: var(--brand-color, 14px);
+  padding: var(--spacing-unit, 8px);
+  border-radius: var(--card-radius, 4px);
+}
+
+.card {
+  /* property-type-mismatch: a <length> property used as a color value. */
+  color: var(--spacing-unit);
+  gap: var(--spacing-unit, 12px);
+}
+
+.badge {
+  /* Correct usage — must not be reported. */
+  background-color: var(--brand-color, #4f46e5);
+  border-radius: var(--card-radius, 6px);
+}
diff --git a/lib/__tests__/audit-summary.test.mjs b/lib/__tests__/audit-summary.test.mjs
index 31cef48..e0d43d4 100644
--- a/lib/__tests__/audit-summary.test.mjs
+++ b/lib/__tests__/audit-summary.test.mjs
@@ -13,10 +13,16 @@ describe('formatLintSummary', () => {
       modernPracticeIssues: [],
       adoptionSuggestions: [],
       overflowSafetyIssues: [],
+      propertyTypeIssues: [],
     }
     expect(formatLintSummary(audit)).toBe('')
   })
 
+  it('includes the @property type count when issues are present', () => {
+    const audit = { propertyTypeIssues: [{}, {}, {}] }
+    expect(formatLintSummary(audit)).toBe('3 property types')
+  })
+
   it('includes the layout a11y count when issues are present', () => {
     const audit = { layoutA11yIssues: [{}, {}] }
     expect(formatLintSummary(audit)).toBe('2 layout a11y')
@@ -34,15 +40,16 @@ describe('formatLintSummary', () => {
     )
   })
 
-  it('labels all four categories in a stable order', () => {
+  it('labels all five categories in a stable order', () => {
     const audit = {
       layoutA11yIssues: [{}],
       modernPracticeIssues: [{}],
       adoptionSuggestions: [{}],
       overflowSafetyIssues: [{}],
+      propertyTypeIssues: [{}],
     }
     expect(formatLintSummary(audit)).toBe(
-      '1 layout a11y · 1 modern-practice · 1 adoption · 1 overflow'
+      '1 layout a11y · 1 modern-practice · 1 adoption · 1 overflow · 1 property types'
     )
   })
 })
@@ -88,11 +95,33 @@ describe('collectLintGroups', () => {
       layoutA11yIssues: [{ selector: '.a', reason: 'r', severity: 'warning' }],
       modernPracticeIssues: [],
       adoptionSuggestions: [{ selector: '', reason: 'r', severity: 'info' }],
+      propertyTypeIssues: [
+        { selector: '.btn', reason: 'r', severity: 'warning' },
+      ],
     }
     expect(collectLintGroups(audit).map((g) => g.key)).toEqual([
       'layoutA11yIssues',
       'adoptionSuggestions',
       'overflowSafetyIssues',
+      'propertyTypeIssues',
+    ])
+  })
+
+  it('labels the @property category for display', () => {
+    const issue = {
+      selector: '.button',
+      property: 'background-color',
+      rule: 'fallback-type-mismatch',
+      severity: 'warning',
+      reason: '`<color>` property has a `<length>` fallback',
+      declaredSyntax: '<color>',
+    }
+    expect(collectLintGroups({ propertyTypeIssues: [issue] })).toEqual([
+      {
+        key: 'propertyTypeIssues',
+        label: '@property type safety',
+        issues: [issue],
+      },
     ])
   })
 })
diff --git a/lib/__tests__/css-auditor.test.mjs b/lib/__tests__/css-auditor.test.mjs
index d9f6abf..6f1c35b 100644
--- a/lib/__tests__/css-auditor.test.mjs
+++ b/lib/__tests__/css-auditor.test.mjs
@@ -549,3 +549,113 @@ describe('CssAuditor overflowSafetyIssues integration', () => {
     expect(result.overflowSafetyIssues).toBeUndefined()
   })
 })
+
+describe('buildAuditPrompt @property type checking', () => {
+  it('includes STEP 13 for @property type checking', () => {
+    const css = 'body { color: red; }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('STEP 13')
+    expect(prompt.content).toContain('@PROPERTY TYPE CHECKING')
+  })
+
+  it('instructs LLM to validate initial-value against the declared syntax', () => {
+    const css =
+      '@property --gap { syntax: "<length>"; initial-value: red; inherits: false; }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('invalid-initial-value')
+    expect(prompt.content).toContain('initial-value')
+  })
+
+  it('instructs LLM to detect var() fallbacks that contradict the syntax', () => {
+    const css = '.btn { color: var(--brand, 14px); }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('fallback-type-mismatch')
+  })
+
+  it('instructs LLM to flag registered properties used in a foreign context', () => {
+    const css = '.btn { background-color: var(--spacing-unit); }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('property-type-mismatch')
+  })
+
+  it('documents the syntax descriptors it can type-check', () => {
+    const css = 'body { color: red; }'
+    const prompt = buildAuditPrompt(css)
+    for (const syntax of [
+      '<color>',
+      '<length>',
+      '<number>',
+      '<integer>',
+      '<percentage>',
+      '<angle>',
+      '<time>',
+    ]) {
+      expect(prompt.content).toContain(syntax)
+    }
+  })
+
+  it('includes propertyTypeIssues in the output example', () => {
+    const css = 'body { color: red; }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('propertyTypeIssues')
+    expect(prompt.content).toContain('declaredSyntax')
+  })
+
+  it('caps the number of reported propertyTypeIssues', () => {
+    const css = 'body { color: red; }'
+    const prompt = buildAuditPrompt(css)
+    expect(prompt.content).toContain('up to 8 propertyTypeIssues')
+  })
+})
+
+describe('CssAuditor propertyTypeIssues integration', () => {
+  const baseReport = {
+    brand: 'test',
+    chaosScore: 3,
+    summary: '',
+    colorClusters: [],
+    fonts: [],
+    spacing: { found: [], suggestedScale: {}, nonScaleValues: [] },
+    lineHeights: { found: [], suggestedScale: {}, unitlessMix: false },
+    layoutA11yIssues: [],
+    modernPracticeIssues: [],
+    adoptionSuggestions: [],
+    overflowSafetyIssues: [],
+  }
+
+  const auditWith = async (report) => {
+    const sendPromptSpy = vi.fn().mockResolvedValue(JSON.stringify(report))
+    const auditor = new CssAuditor(
+      { sendPrompt: sendPromptSpy },
+      { maxTokens: { audit: 3000, parse: 4000, export: 6000 } }
+    )
+    return auditor.audit({ content: 'test', system: 'sys' })
+  }
+
+  it('audit parses response with propertyTypeIssues', async () => {
+    const issue = {
+      selector: '.button',
+      property: 'background-color',
+      rule: 'fallback-type-mismatch',
+      severity: 'warning',
+      reason: 'Registered as `<color>` but the fallback `14px` is a `<length>`',
+      propertyName: '--brand-color',
+      declaredSyntax: '<color>',
+    }
+    const result = await auditWith({
+      ...baseReport,
+      propertyTypeIssues: [issue],
+    })
+    expect(result.propertyTypeIssues).toEqual([issue])
+  })
+
+  it('audit handles empty propertyTypeIssues array', async () => {
+    const result = await auditWith({ ...baseReport, propertyTypeIssues: [] })
+    expect(result.propertyTypeIssues).toEqual([])
+  })
+
+  it('audit handles missing propertyTypeIssues gracefully', async () => {
+    const result = await auditWith(baseReport)
+    expect(result.propertyTypeIssues).toBeUndefined()
+  })
+})
diff --git a/lib/__tests__/prompts.test.mjs b/lib/__tests__/prompts.test.mjs
index 305caf1..f26e1ae 100644
--- a/lib/__tests__/prompts.test.mjs
+++ b/lib/__tests__/prompts.test.mjs
@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs'
 import { describe, it, expect } from 'vitest'
 import {
   resolveTarget,
@@ -144,7 +145,7 @@ describe('buildAuditPrompt', () => {
     expect(content).toContain('</example>')
   })
 
-  it('includes all twelve analysis steps', () => {
+  it('includes all thirteen analysis steps', () => {
     const content = buildAuditPrompt(css).content
     expect(content).toContain('STEP 1')
     expect(content).toContain('STEP 2')
@@ -158,6 +159,7 @@ describe('buildAuditPrompt', () => {
     expect(content).toContain('STEP 10')
     expect(content).toContain('STEP 11')
     expect(content).toContain('STEP 12')
+    expect(content).toContain('STEP 13')
   })
 
   it('covers all required JSON output fields in the example', () => {
@@ -170,6 +172,7 @@ describe('buildAuditPrompt', () => {
     expect(content).toContain('"spacing"')
     expect(content).toContain('"lineHeights"')
     expect(content).toContain('"motion"')
+    expect(content).toContain('"propertyTypeIssues"')
   })
 
   it('includes all allowed semantic color names', () => {
@@ -520,3 +523,82 @@ describe('buildExportPrompt', () => {
     expect(content).toContain('cubic-bezier')
   })
 })
+
+describe('buildAuditPrompt with the @property fixture', () => {
+  const fixture = readFileSync(
+    new URL('../__fixtures__/at-property.css', import.meta.url),
+    'utf8'
+  )
+
+  it('carries @property registrations through preprocessing into the prompt', () => {
+    const content = buildAuditPrompt(fixture).content
+    // Anchors unique to the fixture — the STEP 13 instructions carry their own
+    // `@property --my-color { syntax: "<color>" }` sample, so a generic assertion
+    // here would pass on the boilerplate alone.
+    expect(content).toContain('@property --brand-color')
+    expect(content).toContain("syntax: '<color>'")
+    expect(content).toContain('@property --anything')
+  })
+
+  it('preserves the declarations STEP 13 needs while dropping comments', () => {
+    const processed = preprocessCss(fixture)
+    expect(processed).not.toContain('/*')
+    // the invalid-initial-value case
+    expect(processed).toContain('initial-value: red')
+    // the fallback-type-mismatch case
+    expect(processed).toContain('var(--brand-color, 14px)')
+    // the foreign-context case
+    expect(processed).toContain('color: var(--spacing-unit)')
+  })
+})
+
+describe('buildAuditPrompt lint issue contract', () => {
+  // Every lint category is rendered by one shared component (components/AuditView.tsx)
+  // and summarized by one shared registry (lib/audit-summary.mjs), both of which read
+  // `severity`, `reason` and `selector`/`rule`. A category whose example drifts from
+  // that shape renders blank, so the example itself is the contract under test.
+  const LINT_CATEGORY_KEYS = [
+    'layoutA11yIssues',
+    'modernPracticeIssues',
+    'adoptionSuggestions',
+    'overflowSafetyIssues',
+    'propertyTypeIssues',
+  ]
+
+  const parseExample = (content) =>
+    JSON.parse(content.split('<example>')[1].split('</example>')[0].trim())
+
+  it('ships an output example that is parseable JSON', () => {
+    const example = parseExample(
+      buildAuditPrompt('body { color: red; }').content
+    )
+    expect(example.brand).toBeDefined()
+    expect(typeof example.chaosScore).toBe('number')
+  })
+
+  it.each(LINT_CATEGORY_KEYS)(
+    'demonstrates %s with at least one entry',
+    (key) => {
+      const example = parseExample(
+        buildAuditPrompt('body { color: red; }').content
+      )
+      expect(Array.isArray(example[key])).toBe(true)
+      expect(example[key].length).toBeGreaterThan(0)
+    }
+  )
+
+  it.each(LINT_CATEGORY_KEYS)(
+    'gives every %s entry the shared severity/reason/anchor fields',
+    (key) => {
+      const example = parseExample(
+        buildAuditPrompt('body { color: red; }').content
+      )
+      for (const issue of example[key]) {
+        expect(['warning', 'suggestion', 'info']).toContain(issue.severity)
+        expect(typeof issue.reason).toBe('string')
+        expect(issue.reason.length).toBeGreaterThan(0)
+        expect(issue.selector ?? issue.rule).toBeDefined()
+      }
+    }
+  )
+})
diff --git a/lib/audit-summary.mjs b/lib/audit-summary.mjs
index d20f777..e7bc6fc 100644
--- a/lib/audit-summary.mjs
+++ b/lib/audit-summary.mjs
@@ -22,6 +22,11 @@ const LINT_CATEGORIES = [
     shortLabel: 'overflow',
     label: 'Overflow & wrap safety',
   },
+  {
+    key: 'propertyTypeIssues',
+    shortLabel: 'property types',
+    label: '@property type safety',
+  },
 ]
 
 /**
diff --git a/lib/prompts.mjs b/lib/prompts.mjs
index bd844fb..884223d 100644
--- a/lib/prompts.mjs
+++ b/lib/prompts.mjs
@@ -209,10 +209,7 @@ Scan the CSS for @property at-rules. An @property registration defines a custom
   initial-value: #ff0000;
 }
 
-For each @property registration found:
-- Record the property name (e.g. "--my-color"), its declared syntax (e.g. "<color>", "<length>", "<number>"), and the initial-value if present.
-- Then scan all var() usages of that registered property throughout the CSS. A var() usage is any appearance of var(--prop-name) in a property value.
-- For each var() usage, check whether the assigned value or context is compatible with the declared syntax:
+Build a table of every registration found: the property name (e.g. "--my-color"), its declared syntax (e.g. "<color>", "<length>", "<number>"), and its initial-value when present. Type-check values against these descriptors:
   - <color>: accepts hex, rgb(), rgba(), hsl(), hsla(), named colors, currentColor, transparent
   - <length>: accepts px, em, rem, vh, vw, vmin, vmax, ch, ex, cm, mm, in, pt, pc, 0, calc() expressions
   - <number>: accepts plain numbers (1, 0.5, 2.3), calc() that evaluates to a number
@@ -225,22 +222,27 @@ For each @property registration found:
   - <custom-ident>: accepts any valid CSS identifier
   - <string>: accepts quoted strings
   - <url>: accepts url()
-  - "*": universal — accepts any value (no type checking possible)
+  - "*": universal — accepts any value, so no type checking is possible. Skip registrations declaring "*" entirely.
 
-When the var(--prop-name) usage appears to contradict the declared syntax, record it. Examples:
-- var(--my-color, 14px) — <color> with a <length> fallback → type mismatch
-- var(--my-spacing) used inside background-color — suggests the property may be misused
-- var(--my-size, red) — <length> with a <color> fallback → type mismatch
+Then apply the three rules below. Every entry you record uses the same field set:
+- "selector": the CSS selector containing the offending usage, or the at-rule written as "@property --name" for registration-level errors
+- "property": the CSS property the value is assigned to, or "initial-value" for registration-level errors
+- "rule": one of "invalid-initial-value", "fallback-type-mismatch", "property-type-mismatch"
+- "severity": "warning" for the first two rules, "suggestion" for the third
+- "reason": a specific message naming the declared syntax and the offending value
+- "propertyName": the registered custom property (e.g. "--my-color")
+- "declaredSyntax": the declared syntax string (e.g. "<color>")
 
-Focus on clear type mismatches: a <color> custom property receiving a length value, or a <length> receiving a color. Skip ambiguous cases where the type cannot be determined from the CSS alone (e.g., a var() whose value comes from a different stylesheet or JavaScript).
+13a. INVALID INITIAL-VALUE
+The initial-value must itself parse as the declared syntax. When it does not, the browser rejects the whole registration and the property silently falls back to unregistered behaviour — losing both the type contract and the ability to transition. This is a hard error, not a preference. Also flag any registration that declares a non-universal syntax but omits initial-value, which is invalid per spec. Record these with "rule": "invalid-initial-value" and "severity": "warning", e.g. "reason": "Registered as \`<length>\` but \`initial-value: red\` is a \`<color>\` — the browser rejects this registration entirely".
 
-For each type mismatch found, record:
-- "propertyName": the @property name (e.g. "--my-color")
-- "declaredSyntax": the declared syntax string
-- "location": selector and property name where the mismatch occurs
-- "issue": description of the mismatch (e.g. "<color> property receives a <length> value")
+13b. FALLBACK TYPE MISMATCH
+Scan every var() usage of a registered property for a fallback whose type contradicts the declared syntax — var(--my-color, 14px) is registered as <color> but falls back to a <length>, so the fallback can never apply. Record these with "rule": "fallback-type-mismatch" and "severity": "warning".
 
-Only report up to 8 propertyTypeIssues total. If no @property registrations exist in the CSS, record an empty array.</instructions>
+13c. FOREIGN CONTEXT USAGE
+A registered property assigned to a CSS property its declared syntax cannot satisfy — a <length> property used in \`color\`, or a <color> property used in \`width\`. Report only when the mismatch is unambiguous from this stylesheet alone; skip any var() whose value may come from another stylesheet or from JavaScript. Record these with "rule": "property-type-mismatch" and "severity": "suggestion".
+
+Only report up to 8 propertyTypeIssues total. Prioritize invalid-initial-value, then fallback-type-mismatch, then property-type-mismatch. If the CSS contains no @property registrations, record an empty array.</instructions>
 
 <output_format>
 Return ONLY a valid JSON object matching the structure in the example below. No markdown fences, no backticks, no text before or after the JSON.
@@ -311,8 +313,9 @@ Return ONLY a valid JSON object matching the structure in the example below. No
     { "selector": ".dashboard-grid", "rule": "missing-overflow-wrap", "severity": "suggestion", "reason": "Grid container with fixed height but no overflow handling — content may be clipped if grid items exceed the container" }
   ],
   "propertyTypeIssues": [
-    { "propertyName": "--my-color", "declaredSyntax": "<color>", "location": ".button >> background-color", "issue": "<color> property receives a <length> value (14px)" },
-    { "propertyName": "--spacing-unit", "declaredSyntax": "<length>", "location": ".card >> color", "issue": "<length> property used in a color context, possible type mismatch" }
+    { "selector": "@property --spacing-unit", "property": "initial-value", "rule": "invalid-initial-value", "severity": "warning", "reason": "Registered as \`<length>\` but \`initial-value: red\` is a \`<color>\` — the browser rejects this registration entirely", "propertyName": "--spacing-unit", "declaredSyntax": "<length>" },
+    { "selector": ".button", "property": "background-color", "rule": "fallback-type-mismatch", "severity": "warning", "reason": "\`--my-color\` is registered as \`<color>\` but falls back to \`14px\` — the fallback can never apply", "propertyName": "--my-color", "declaredSyntax": "<color>" },
+    { "selector": ".card", "property": "color", "rule": "property-type-mismatch", "severity": "suggestion", "reason": "\`--spacing-unit\` is registered as \`<length>\` but is used as a color value", "propertyName": "--spacing-unit", "declaredSyntax": "<length>" }
   ]
 }
 </example>
diff --git a/lib/types.ts b/lib/types.ts
index 69be8f5..7171834 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -159,6 +159,16 @@ export interface OverflowSafetyIssue {
   reason: string
 }
 
+export interface PropertyTypeIssue {
+  selector: string
+  property: string
+  rule: string // 'invalid-initial-value' | 'fallback-type-mismatch' | 'property-type-mismatch'
+  severity: 'warning' | 'suggestion'
+  reason: string
+  propertyName: string // the registered custom property, e.g. '--my-color'
+  declaredSyntax: string // the @property syntax descriptor, e.g. '<color>'
+}
+
 export interface AuditReport {
   brand: string
   chaosScore: number
@@ -172,6 +182,7 @@ export interface AuditReport {
   modernPracticeIssues?: ModernPracticeIssue[]
   adoptionSuggestions?: AdoptionSuggestion[]
   overflowSafetyIssues?: OverflowSafetyIssue[]
+  propertyTypeIssues?: PropertyTypeIssue[]
 }
 
 export interface ColorDecision {

From dbf0727e17e22fce1124dac1c17f21e1eee5a82d Mon Sep 17 00:00:00 2001
From: Nadia Nujovich <nujovich@gmail.com>
Date: Mon, 27 Jul 2026 14:27:17 +0200
Subject: [PATCH 4/4] docs(mint): document @property type safety in the README

The CSS layout linting section tables every lint category and its rules;
@property type checking was missing from it.

- add the three @property rules to the linting table
- add a subsection explaining why invalid-initial-value matters (the
  browser rejects the whole registration) and that universal syntax is
  skipped
- mention @property type contracts in the audit step and the section intro
- note that @property findings do not feed the chaos score
---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index c7fd0f1..6f7358d 100644
--- a/README.md
+++ b/README.md
@@ -15,29 +15,53 @@ Both share the same prompts and Claude pipeline.
 CSS / SCSS / HTML  →  Claude Audit  →  Review & curate  →  Clean tokens  →  Export  →  Apply
 ```
 
-1. **Audit** — Claude analyzes your CSS, groups near-duplicate colors into clusters, detects fonts, flags spacing values that don't fit a 4px grid, identifies duplicate transition/animation declarations, and lints layout patterns for accessibility and modern-CSS pitfalls (see [CSS layout linting](#css-layout-linting)).
+1. **Audit** — Claude analyzes your CSS, groups near-duplicate colors into clusters, detects fonts, flags spacing values that don't fit a 4px grid, identifies duplicate transition/animation declarations, and lints layout patterns for accessibility, modern-CSS pitfalls, and `@property` type mismatches (see [CSS layout linting](#css-layout-linting)).
 2. **Curate** — Review each cluster. Pick the canonical color, rename tokens, include or exclude entries, and select which fonts to keep. (CLI applies sensible defaults: include every cluster, keep non-system fonts, use the suggested 4px scale.)
 3. **Export** — Generate production-ready output in any format.
 4. **Apply** — Rewrite your source CSS in place so raw values reference the generated tokens (`#1976d2` → `var(--color-primary)`). Deterministic, no LLM — adoption becomes a reviewable git diff. See [`mint-ds apply`](#applying-tokens-to-source-css).
 
 ## CSS layout linting
 
-Beyond color, font, and spacing tokens, the audit also lints your CSS for layout accessibility issues and modern-CSS pitfalls. These findings are returned in the raw `AuditReport` (write it to disk with `--report`); the accessibility and overflow checks also feed the chaos score.
-
-| Category                   | Rule                                | Severity   | What it flags                                                                                                                   |
-| -------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| **Layout accessibility**   | `order` breaks DOM order            | warning    | A grid/flex child reordered with `order` so the visual order no longer matches the DOM — breaks keyboard navigation and SR flow |
-|                            | reordering without tabindex         | warning    | An element visually reordered via `order` with no matching `tabindex` adjustment, so keyboard users navigate in DOM order       |
-| **Modern best practices**  | `grid-when-flexbox-wrap-would-work` | suggestion | Single-column grid that a `flex` + `flex-wrap` layout would handle more simply                                                  |
-|                            | `legacy-centering`                  | suggestion | `margin: 0 auto` + fixed width, or absolute-position + `transform` centering, where modern `flex`/`grid` centering is cleaner   |
-|                            | `flex-min-width-zero-hack`          | suggestion | `min-width: 0` on a flex item — the classic overflow workaround that often hides a layout misunderstanding                      |
-|                            | `fragile-nested-selectors`          | suggestion | Selectors coupled to a brittle DOM shape (deep `>` / `+` chains) that a small HTML refactor would break                         |
-| **Feature adoption**       | `use-css-layers`                    | info       | Large stylesheets (20+ rules) with no `@layer` organization                                                                     |
-|                            | `use-container-queries`             | info       | Component-scoped width `@media` queries that a `@container` query would express better                                          |
-| **Overflow & wrap safety** | `flex-wrap-missing`                 | warning    | Flex container without `flex-wrap` — items can't wrap and may overflow on narrow viewports                                      |
-|                            | `missing-overflow-wrap`             | suggestion | Sized grid/flex container (fixed width/height) with no `overflow` handling, so content can be clipped                           |
-
-The chaos score gains **+1** when there are 3 or more layout-accessibility issues and **+1** when there are 4 or more overflow-safety issues. Adoption suggestions are informational only and never affect the score.
+Beyond color, font, and spacing tokens, the audit also lints your CSS for layout accessibility issues, modern-CSS pitfalls, and broken `@property` type contracts. These findings are returned in the raw `AuditReport` (write it to disk with `--report`); the accessibility and overflow checks also feed the chaos score.
+
+| Category                   | Rule                                | Severity   | What it flags                                                                                                                                           |
+| -------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Layout accessibility**   | `order` breaks DOM order            | warning    | A grid/flex child reordered with `order` so the visual order no longer matches the DOM — breaks keyboard navigation and SR flow                         |
+|                            | reordering without tabindex         | warning    | An element visually reordered via `order` with no matching `tabindex` adjustment, so keyboard users navigate in DOM order                               |
+| **Modern best practices**  | `grid-when-flexbox-wrap-would-work` | suggestion | Single-column grid that a `flex` + `flex-wrap` layout would handle more simply                                                                          |
+|                            | `legacy-centering`                  | suggestion | `margin: 0 auto` + fixed width, or absolute-position + `transform` centering, where modern `flex`/`grid` centering is cleaner                           |
+|                            | `flex-min-width-zero-hack`          | suggestion | `min-width: 0` on a flex item — the classic overflow workaround that often hides a layout misunderstanding                                              |
+|                            | `fragile-nested-selectors`          | suggestion | Selectors coupled to a brittle DOM shape (deep `>` / `+` chains) that a small HTML refactor would break                                                 |
+| **Feature adoption**       | `use-css-layers`                    | info       | Large stylesheets (20+ rules) with no `@layer` organization                                                                                             |
+|                            | `use-container-queries`             | info       | Component-scoped width `@media` queries that a `@container` query would express better                                                                  |
+| **Overflow & wrap safety** | `flex-wrap-missing`                 | warning    | Flex container without `flex-wrap` — items can't wrap and may overflow on narrow viewports                                                              |
+|                            | `missing-overflow-wrap`             | suggestion | Sized grid/flex container (fixed width/height) with no `overflow` handling, so content can be clipped                                                   |
+| **@property type safety**  | `invalid-initial-value`             | warning    | An `initial-value` that doesn't parse as the declared `syntax`, or a missing one on a non-universal syntax — the browser rejects the whole registration |
+|                            | `fallback-type-mismatch`            | warning    | A `var()` fallback that contradicts the registered syntax (`var(--my-color, 14px)` on a `<color>`), so the fallback can never apply                     |
+|                            | `property-type-mismatch`            | suggestion | A registered property used where its declared syntax can't apply — a `<length>` property assigned to `color`                                            |
+
+The chaos score gains **+1** when there are 3 or more layout-accessibility issues and **+1** when there are 4 or more overflow-safety issues. Adoption suggestions and `@property` findings are informational for the score and never affect it.
+
+### `@property` type safety
+
+An `@property` at-rule declares a type contract for a custom property. Mint reads every registration in your CSS and checks it — and its `var()` usages — against the declared `syntax` descriptor:
+
+<!-- prettier-ignore-start -->
+```css
+@property --spacing-unit {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: red;                          /* invalid-initial-value — the browser drops this registration */
+}
+
+.button {
+  background-color: var(--brand-color, 14px);  /* fallback-type-mismatch — <color> can't fall back to a length */
+  color: var(--spacing-unit);                  /* property-type-mismatch — <length> used as a color */
+}
+```
+<!-- prettier-ignore-end -->
+
+`invalid-initial-value` is the one worth fixing first: when the `initial-value` doesn't match the declared `syntax`, the browser rejects the registration outright and the property silently reverts to unregistered behaviour — losing both the type contract and the ability to animate or transition it. Registrations declaring the universal syntax (`*`) are skipped, since any value satisfies them. Findings land in `propertyTypeIssues` on the `AuditReport`.
 
 ## Example — Frankenstein