Cyrus-terra/qilin-fit

Kylin / Qianxin Frontend Compatibility Development

Usage Principles

Treat compatibility as a constraint of the implementation, not something to patch after the page is done. This skill is applicable to new development, bug fixes, dependency upgrades, and code reviews; it does not require a specific framework. Only address risks relevant to the task at hand; do not unconditionally rewrite the entire project.

Cannot guarantee coverage for all Qianxin versions. Product numbers, distribution channels, and Chromium kernel versions differ; the same kernel can behave differently across CPUs, drivers, and enterprise policies. Unknown information must be marked as "pending confirmation"—do not fabricate verification records.

1. Determine the Support Contract First

1. Read existing project instructions, lock files, build configurations, compatibility tests, and support scope; preserve user modifications.
2. From the user, the browser's "About" page, and assets/browser-probe.html, collect: full product name, full product version, distribution channel, full Chromium version, Kylin version/SP, CPU architecture, DPR/zoom level, fonts/GPU, and key enterprise policies. UA is only a clue and cannot prove the actual kernel.
3. Establish or update the project's existing support matrix; if no file exists, you may use assets/support-matrix.example.json as a template. Fill in business-essential features, minimum actual kernel, real device, and degradation acceptance criteria. Do not record business device data in the installed skill directory.
4. When the baseline is unknown, ask first—do not default to Chromium 102. If the user asks to develop before confirming the baseline, you may adopt a conservative temporary baseline, but it must be marked as provisional / unverified and never claimed as "compatible with all versions."
5. Read the Browser Matrix. Different channels and architectures must be verified separately; both the minimum baseline and higher versions must be covered. It is not acceptable to test only the latest Chrome and claim it represents all Qianxin versions.

2. Read-Only Audit, Determine Minimal Changes

• Read actual source code and production build configuration to confirm CSS tools, UI libraries, browser/server entry points, third-party packages, and deployment method.
• Select reference documents based on the changes; you do not need to load all files every time:

Task	Required Reading
Styles, Tailwind, layout, themes, modals	CSS and Layout
JS/TS, syntax compilation, dependencies, Web APIs	JavaScript and Build
Fonts/IME, files, PDF, permissions, network, CPU/GPU	Kylin Platform and Delivery
Testing, screenshots, release verification, data boundaries	Verification and Acceptance
Verify feature support or version basis	Sources and Evidence Levels

• Run the checker from the skill's actual installation path; <skill-dir> represents the directory containing the current SKILL.md. Replace it with the confirmed real path—do not copy the placeholder verbatim:

python3 "<skill-dir>/scripts/compat_audit.py" ./src --min-chromium 102

Only use the example 102 when the support contract has been confirmed as 102; if uncertain, omit --min-chromium and the output will mark items as unknown. Replace the path with the real project path. The checker is read-only, zero third-party dependencies, and will not modify code; it performs lexical candidate detection, not AST/CSS compilation or compatibility certification.

3. Implementation Rules

CSS

• Prefer stable paths using regular hex/rgb/hsl colors, traditional transform, and gracefully falling back layouts; use modern features only when the target supports them or progressive enhancement can be proven.
• For 102: Focus on checking :has(), container queries, new viewport units, individual transforms, modern color functions, native CSS nesting, Popover API, and Tailwind-generated code. See the CSS reference for support thresholds and alternatives.
• Tailwind v4 officially requires Chrome 111 minimum; 102 is not in its support range. Do not claim that palette patches, Autoprefixer, or setting a JS target solve all v4 compatibility issues. Propose supported solutions or verified artifact transformations; migration/dependency degradation must be confirmed first—do not perform it unilaterally.
• A var() fallback does not equal a fallback for arbitrary modern color functions; CSS.supports() does not guarantee actual pixel correctness. Check parsing, computed values, and visual results separately.
• When modifying modal positioning, preserve the transform composition used for animations and dragging; check backdrop, focus, scrolling, keyboard interactions, portals, and stacking context—do not just verify a centered screenshot.

JS / Dependencies

• Distinguish between syntax transpilation, built-in object polyfills, and Web APIs that require permissions or native platform support. TypeScript target, lib, and build target cannot be used interchangeably.
• For browser-delivered code, configure the real minimum kernel and check dependencies, dynamic chunks, workers, third-party scripts, and CSS artifacts; Node server-side APIs must not be used as browser APIs.
• Implement capability detection at the entry point for new APIs, with an acceptable business degradation; syntax parsing failures occur before detection, so you cannot wrap new syntax in an if block as a substitute for transpilation.
• Do not blanket-disable already supported features like optional chaining, nor default to polyfilling everything. Do not compromise security by disabling CSP, certificate verification, sandbox, or other measures for the sake of compatibility.

Platform / Data

• Cover missing fonts, Chinese IME composition events, architecture differences, GPU, download/print, file names, proxy/certificates, offline deployment, and enterprise permission policies.
• When handling external/AI data, validate it at the boundary against the actual schema and present explicit failure/missing states; do not silently fill unknown scores with valid values, and do not force a specific validation library. Business changes unrelated to the browser are out of scope.

4. Verification Order

1. Source code risk scanning, existing unit tests and lint; document unscanned directories, false positives, and reasons for manual exemptions.
2. Production build; scan the actually deployed CSS/JS (use --include-build and confirm the path is not a source map or Node server-side package). Record the actual output of transformation/degradation—do not infer validity from configuration alone.
3. Open the offline probe in the target browser, manually verify visual areas, then step through the project's critical flows. The probe is not a substitute for project testing and must not collect accounts or business input.
4. Against the minimum baseline, existing versions, and the current version on real Kylin hardware, perform the functional/screenshot/keyboard/IME/zoom/print acceptance checks described in the reference documents. Ordinary Chrome, Playwright with a recent Chromium, or a forged UA cannot replace the target real device.
5. When no real device is available, no dependency installation permission exists, or the build fails, clearly write out blockers and unverified items—do not generate fake screenshots or success conclusions.

# Example only: replace with the project's real browser artifact directory
python3 "<skill-dir>/scripts/compat_audit.py" ./dist --include-build --min-chromium 102 --format json
# Optionally, set a CI gate for all candidate risks; handle false positives and evidence-backed progressive enhancements first
python3 "<skill-dir>/scripts/compat_audit.py" ./src --min-chromium 102 --fail-on warning

5. Delivery Format

Short output:

• Support Contract: Actual version/architecture, minimum kernel; unknown/provisional must be noted.
• Changes and Rationale: Issues, location, degradation/transformation method; reference code with path:line.
• Verification Results: Source code, artifacts, normal browser, real Kylin device—each with pass/fail/not-run, do not merge into a single "passed" status.
• Residual Risks: Versions that cannot be verified, policy/hardware limitations, and trade-offs that require user confirmation.

The skill description is used for automatic matching; if it must be triggered every time, the agent instructions for the project should explicitly require loading this skill before related development. This skill itself cannot replace the host discovery mechanism, bypass permissions, or force model invocation.