FUI1004: Library component should be preferred
moderateAuthored UI bypasses a component declared by the active design-system contract.
Details
{
"code": "FUI1004",
"ruleId": "components/prefer-library",
"category": "Canonical Usage",
"defaultSeverity": "moderate",
"lifecycle": "experimental",
"fixAvailable": true,
"evidenceRequired": true
}Guidance
What it means
Fragments found an intrinsic element or other authored UI with a declared canonical equivalent. The finding evidence names the element, the canonical component, and the source that established that mapping.
How to resolve it
Use the canonical component from an importable module in your project. For package sources, import the named export from the package or preferred subpath shown in the finding. For directory sources, use the component's actual barrel or file export—not the directory path itself unless that directory has an index module.
Preserve behavior when replacing the element: carry across children, event handlers, native
semantics, accessible names, and required component props. If the report contains an exact
replacement, fragments check --fix can apply it. A rule-level “fix available” label does not mean
that every occurrence is safe to rewrite; ambiguous imports or incompatible props remain manual.
When the authored component is an intentional approved wrapper, declare that identity in the contract instead of suppressing every usage. For a genuinely exceptional line, use a narrow, reasoned suppression:
// @fragments-expect-error FUI1004 reason="native control required by embedded SDK" expires="2026-12-31"
<button type="button">Continue</button>
Verify the change
Run npx @usefragments/cli check --changed --format agent and confirm the finding is gone or the
specific suppression is listed. Then run npx @usefragments/cli check --changed --ci.
Intentional exception? Use a narrow, reasoned directive from the in-source suppression reference.