# CSS @import and url() references resolve to existing files

- **Pattern:** `ab-000046` (`ai-slop-hallucinations.asset-references.css-references-resolve`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000046
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000046)

## Why it matters

An `@import './variables.css'` or `url('/fonts/Inter.woff2')` pointing at a file that does not exist produces no build error in most setups — the bundler emits a warning, the missing font falls back to the system default, and the broken background shows as a color block. The regression is invisible in code review and invisible in the build log, but the rendered page loses the typography and visuals the design system intended. AI-generated CSS especially drifts this way when the model hallucinates font filenames.

## Severity rationale

Medium because broken CSS references silently degrade fonts and layouts without a build-time error.

## Remediation

Open the flagged CSS file and for each unresolved reference either create the file at the path or correct the path to an existing one. A typical Next.js `src/app/globals.css` layout:

```css
@import "tailwindcss";
@import './design-tokens.css';

@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Regular.woff2') format('woff2');
}
```

Confirm the font file sits at `public/fonts/Inter-Regular.woff2`.

## Detection

- **ID:** `css-references-resolve`
- **Severity:** `medium`
- **What to look for:** Walk all `.css`, `.scss`, `.sass`, `.less` files in the project (excluding `node_modules/`, `dist/`, `build/`, `.next/`, `coverage/`). For each file, extract references from two patterns: (1) `@import '...'`, `@import "..."`, `@import url('...')`, `@import url("...")` — file import statements. (2) `url(...)` in property values (background, background-image, font-face src, cursor, list-style-image, border-image, mask-image, content). For each reference, determine its type and resolve: **Relative paths** (starting with `./` or `../` or no prefix) — resolve relative to the CSS file's own directory, then verify the file exists. **Absolute paths** (starting with `/`) — check under `public/` (Next.js, Remix, Astro) or `static/` (Nuxt, SvelteKit). **SKIP these patterns entirely** — do not attempt to resolve them: data URIs (`data:...`), external URLs (`http://`, `https://`, `//`), CSS custom property references (`var(--...)`), fragment-only references (`#id`), Tailwind/PostCSS directives (`@tailwind`, `@apply`, `@config`, `@plugin`, `@theme`, `@layer`, `@utility`, `@variant`, `@source`, `@import "tailwindcss"`), empty `url()` calls. Count all CSS file references inspected, total resolved, total skipped (external/data/directive), total unresolved.
- **Pass criteria:** 100% of local CSS file references (after skipping external/data/directives) resolve to existing files. Report: "X CSS references inspected, Y resolved, Z skipped (external/directives), 0 unresolved."
- **Fail criteria:** At least 1 local CSS reference does not resolve to an existing file.
- **Skip (N/A) when:** Project has zero `.css`/`.scss`/`.sass`/`.less` files, OR all CSS files contain only Tailwind directives and framework imports with no local `url()` or file-referencing `@import` statements.
- **Detail on fail:** `"2 unresolved CSS references: @import './variables.css' in src/app/globals.css (file src/app/variables.css does not exist), url('/fonts/Inter.woff2') in src/styles/typography.css (file public/fonts/Inter.woff2 does not exist)"`
- **Remediation:** Broken CSS references cause missing fonts, broken backgrounds, and layout regressions — all silent failures with no build error. Fix each one:

  ```css
  /* Bad: file doesn't exist */
  @import './variables.css';
  @font-face { src: url('/fonts/Inter.woff2'); }

  /* Good: create the file or fix the path */
  @import './design-tokens.css';  /* actual file name */
  @font-face { src: url('/fonts/Inter-Regular.woff2'); }  /* actual file */
  ```

  For Next.js projects using Tailwind, most CSS files should only contain `@import "tailwindcss"` and custom properties — if you see broken `url()` references, the AI likely generated CSS patterns from a different framework.

---

Taxons: reference-integrity

HTML version: https://auditbuffet.com/patterns/ab-000046