name

windows-cleartype-review

description

Audit and improve Windows ClearType-friendly typography in Electron, React, Vite, Tailwind, or other cross-platform desktop/web apps. Use when a user reports blurry, fuzzy, jagged, thin, or poorly rendered Windows text; when adapting a macOS-first app to Windows; when reviewing Electron BrowserWindow, DPI manifest, font stack, backdrop-filter, transform scaling, small text, tracking, or CJK typography issues; or when adding CI guardrails for Windows font rendering.

Windows ClearType Review

Overview

Use this skill to review Windows-specific font rendering hazards in Electron and cross-platform web apps. The goal is to separate platform-specific Windows fixes from general design changes, then patch only the issues that are actually supported by source evidence.

Workflow

Establish scope: confirm whether the request is Windows-only, Electron-specific, or a broader cross-platform typography issue.
Run the scanner when the repository includes this project or a copied checkout:
```
node ./bin/cleartype-guard.mjs --root <project> --fail-on off
```
For monorepos, add repeated --exclude <path> options for unrelated packages, demos, or generated output. Tests and docs are skipped by default unless they are explicitly in scope.

From inside the skill directory, use:
```
node skills/windows-cleartype-review/scripts/check-windows-typography.mjs --root <project> --fail-on off
```
The skill script first uses the repository CLI when the full checkout is present. If only the skill folder is copied, it falls back to the bundled scripts/cleartype-guard-core.mjs.
Read the highest-severity findings first. Classify each finding before editing:
- valid: source evidence clearly supports the risk.
- partial: the risk exists, but ownership or UI scope is uncertain.
- not supported: the scanner matched text, but the surrounding source does not support a change.
Prefer Windows-scoped fixes for Windows-only rendering risks. If the same issue affects macOS, Linux, or mobile, tell the user before changing shared behavior.
Patch conservatively: use existing tokens, platform selectors, and design-system conventions where available.
Prefer the smallest patch that removes the rendering risk. Avoid stylistic redesign.
Do not rewrite the global design system unless the finding is confirmed to be cross-platform and the user approves.
Re-run the scanner plus the target project's relevant typecheck, lint, or test commands.
Report what changed, what remains a Windows platform limitation, and what still needs visual QA.

Review Checklist

Check these areas before proposing fixes:

Electron declares Windows per-monitor DPI awareness, preferably PerMonitorV2.
Electron is at least 34 / Chromium 132 before spending time on CSS-only tuning. Older Chromium builds can have materially different Windows text contrast/gamma behavior.
BrowserWindow text surfaces are opaque by default; transparent windows are justified and tested.
Electron webPreferences.defaultFontFamily uses native Windows stacks such as Segoe UI and Consolas/Cascadia Mono.
Preload or theme boot code exposes a reliable win32 platform hook before CSS applies, commonly data-platform="win32".
CSS does not use -webkit-font-smoothing or similar hacks for Windows.
App code does not use Chromium/Electron switches that disable DirectWrite, LCD text, GPU compositing, or force a device scale factor.
Text-bearing surfaces avoid backdrop-filter on Windows or provide opaque fallbacks.
UI CJK text avoids fake italic/oblique styling. Keep italic only for user-authored content such as markdown or rich text.
Readable UI text has a Windows floor of roughly 12px. Treat 9-11px as high risk at 125%, 150%, and 175% scaling.
Negative tracking and very wide tracking are removed or reduced for Windows UI labels.
Text-bearing UI is not persistently scaled with CSS transforms; use real font-size and spacing tokens instead.
Text-heavy containers avoid persistent compositor hints such as translateZ(0), will-change: transform, filter: blur(0), and near-1 opacity.
Canvas, WebGL, editor, terminal, PDF preview, and graph surfaces use a devicePixelRatio-aware backing store and redraw on resize or DPR changes.
Fractional scale factors are explicitly checked: 125%, 150%, and 175%, with 150% as the most important manual QA point.

Fix Priorities

Use this order unless the repository evidence points elsewhere:

Remove rendering pipeline hacks and establish DPI/platform foundations.
Make Windows text surfaces opaque where readable text is drawn.
Normalize Windows font stacks, font sizes, tracking, and fake italic.
Replace transform scaling with real layout/font tokens.
Update tests, docs, and CI guardrails so regressions are caught.

References

Load references/patterns.md when you need concrete remediation examples or selector patterns.
Load references/visual-qa-prompt.md when the user provides Windows screenshots or asks for manual visual review criteria.

Output Expectations

When reporting back to the user:

Lead with whether each provided report item is valid, partially valid, or not supported by source evidence.
Mention files changed and tests run.
Call out limitations clearly. Static scanning cannot prove a glyph is crisp; Windows screenshot QA is still required.
If a finding is not Windows-specific, say so before changing shared behavior.
Avoid replacing Electron, installing system-wide font hooks, changing OS font settings, or recommending a Chromium fork unless the user explicitly asks for architectural alternatives.

Windows ClearType Review

Overview

Workflow

Establish scope: confirm whether the request is Windows-only, Electron-specific, or a broader cross-platform typography issue.

Run the scanner when the repository includes this project or a copied checkout:

node ./bin/cleartype-guard.mjs --root <project> --fail-on off

For monorepos, add repeated --exclude <path> options for unrelated packages, demos, or generated output. Tests and docs are skipped by default unless they are explicitly in scope.

From inside the skill directory, use:

node skills/windows-cleartype-review/scripts/check-windows-typography.mjs --root <project> --fail-on off

The skill script first uses the repository CLI when the full checkout is present. If only the skill folder is copied, it falls back to the bundled scripts/cleartype-guard-core.mjs.

Read the highest-severity findings first. Classify each finding before editing:

valid: source evidence clearly supports the risk.
partial: the risk exists, but ownership or UI scope is uncertain.
not supported: the scanner matched text, but the surrounding source does not support a change.

Prefer Windows-scoped fixes for Windows-only rendering risks. If the same issue affects macOS, Linux, or mobile, tell the user before changing shared behavior.

Patch conservatively: use existing tokens, platform selectors, and design-system conventions where available.

Prefer the smallest patch that removes the rendering risk. Avoid stylistic redesign.

Do not rewrite the global design system unless the finding is confirmed to be cross-platform and the user approves.

Re-run the scanner plus the target project's relevant typecheck, lint, or test commands.

Report what changed, what remains a Windows platform limitation, and what still needs visual QA.

Review Checklist

Check these areas before proposing fixes:

Electron declares Windows per-monitor DPI awareness, preferably PerMonitorV2.

Electron is at least 34 / Chromium 132 before spending time on CSS-only tuning. Older Chromium builds can have materially different Windows text contrast/gamma behavior.

BrowserWindow text surfaces are opaque by default; transparent windows are justified and tested.

Electron webPreferences.defaultFontFamily uses native Windows stacks such as Segoe UI and Consolas/Cascadia Mono.

Preload or theme boot code exposes a reliable win32 platform hook before CSS applies, commonly data-platform="win32".

CSS does not use -webkit-font-smoothing or similar hacks for Windows.

App code does not use Chromium/Electron switches that disable DirectWrite, LCD text, GPU compositing, or force a device scale factor.

Text-bearing surfaces avoid backdrop-filter on Windows or provide opaque fallbacks.

UI CJK text avoids fake italic/oblique styling. Keep italic only for user-authored content such as markdown or rich text.

Readable UI text has a Windows floor of roughly 12px. Treat 9-11px as high risk at 125%, 150%, and 175% scaling.

Negative tracking and very wide tracking are removed or reduced for Windows UI labels.

Text-bearing UI is not persistently scaled with CSS transforms; use real font-size and spacing tokens instead.

Text-heavy containers avoid persistent compositor hints such as translateZ(0), will-change: transform, filter: blur(0), and near-1 opacity.

Canvas, WebGL, editor, terminal, PDF preview, and graph surfaces use a devicePixelRatio-aware backing store and redraw on resize or DPR changes.

Fractional scale factors are explicitly checked: 125%, 150%, and 175%, with 150% as the most important manual QA point.

Fix Priorities

Use this order unless the repository evidence points elsewhere:

Remove rendering pipeline hacks and establish DPI/platform foundations.

Make Windows text surfaces opaque where readable text is drawn.

Normalize Windows font stacks, font sizes, tracking, and fake italic.

Replace transform scaling with real layout/font tokens.

Update tests, docs, and CI guardrails so regressions are caught.

References

Load references/patterns.md when you need concrete remediation examples or selector patterns.

Load references/visual-qa-prompt.md when the user provides Windows screenshots or asks for manual visual review criteria.

Output Expectations

When reporting back to the user:

Lead with whether each provided report item is valid, partially valid, or not supported by source evidence.

Mention files changed and tests run.

Call out limitations clearly. Static scanning cannot prove a glyph is crisp; Windows screenshot QA is still required.

If a finding is not Windows-specific, say so before changing shared behavior.

Avoid replacing Electron, installing system-wide font hooks, changing OS font settings, or recommending a Chromium fork unless the user explicitly asks for architectural alternatives.