{"record":{"id":"d77339b8d70b3fea","repo":"tailwindlabs/tailwindcss","slug":"files-imported-with-import-theme-reference","errorCode":null,"errorMessage":"Files imported with `@import \"…\" theme(reference)` must only contain `@theme` blocks.\nUse `@reference \"…\";` instead.","messagePattern":"Files imported with `@import \"…\" theme\\(reference\\)` must only contain `@theme` blocks\\.\nUse `@reference \"…\";` instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/index.ts","lineNumber":492,"sourceCode":"          })\n        }\n\n        // Handle `@media theme(…)`\n        //\n        // We support `@import \"tailwindcss\" theme(reference)` as a way to\n        // import an external theme file as a reference, which becomes `@media\n        // theme(reference) { … }` when the `@import` is processed.\n        else if (param.startsWith('theme(')) {\n          let themeParams = param.slice(6, -1)\n          let hasReference = themeParams.includes('reference')\n\n          walk(node.nodes, (child) => {\n            if (child.kind === 'context') return\n            if (child.kind !== 'at-rule') {\n              if (hasReference) {\n                throw new Error(\n                  `Files imported with \\`@import \"…\" theme(reference)\\` must only contain \\`@theme\\` blocks.\\nUse \\`@reference \"…\";\\` instead.`,\n                )\n              }\n\n              return WalkAction.Continue\n            }\n\n            if (child.name === '@theme') {\n              child.params += ' ' + themeParams\n              return WalkAction.Skip\n            }\n          })\n        }\n\n        // Handle `@media prefix(…)`\n        //\n        // We support `@import \"tailwindcss\" prefix(ident)` as a way to\n        // configure a theme prefix for variables and utilities.\n        else if (param.startsWith('prefix(')) {\n          let prefix = param.slice(7, -1)","sourceCodeStart":474,"sourceCodeEnd":510,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/index.ts#L474-L510","documentation":"Thrown while processing an `@import \"...\" theme(reference)` (or any `theme(...)` import that includes `reference`) when the imported file contains any node that is not an `@theme` at-rule. Reference-theme imports are a special narrow channel for pulling in design tokens, so non-theme content (rules, declarations, other at-rules) is rejected with a pointer to `@reference` as the correct alternative.","triggerScenarios":"Importing a CSS file via `@import \"./tokens.css\" theme(reference);` where `tokens.css` contains selectors, plain rules, or at-rules other than `@theme`.","commonSituations":"Migrating a tokens file that also contains base styles or component CSS; misunderstanding that `theme(reference)` is strictly for theme variables.","solutions":["Move only the `@theme { ... }` block(s) into the imported file and keep other CSS elsewhere.","If you want to import non-theme CSS without it contributing candidates, use `@reference \"...\";` instead of `theme(reference)`.","Audit the imported file with the error's walk logic in mind: every top-level node must be an `@theme` at-rule (comments and `context` nodes are allowed; everything else is rejected)."],"exampleFix":"/* before — tokens.css mixes theme + base */\n@theme { --color-brand: #007; }\nbody { margin: 0; }\n/* main.css */\n@import \"./tokens.css\" theme(reference);\n\n/* after — tokens.css contains only @theme */\n@theme { --color-brand: #007; }\n/* main.css: use @reference for non-theme CSS */\n@reference \"./base.css\";","handlingStrategy":"validation","validationCode":"// Before importing a file as theme(reference), verify it contains only @theme (and comments).\nimport postcss from 'postcss'\n\nasync function validateReferenceThemeFile(content: string): Promise<string[]> {\n  const errors: string[] = []\n  const root = postcss.parse(content)\n  root.each((node) => {\n    if (node.type === 'comment') return\n    if (node.type === 'atrule' && (node as postcss.AtRule).name === 'theme') return\n    errors.push(`Non-@theme node of type ${node.type} is not allowed in a theme(reference) import`)\n  })\n  return errors\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep token files pure: only `@theme { ... }` blocks and comments.","Use `@reference \"...\";` for non-theme CSS that should not contribute candidates.","Add a CI check that parses imported token files and fails on any non-`@theme` top-level node."],"tags":["at-import","theme-reference","at-reference","validation"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}