Skip to content

fix(parse/css): parse tailwind @utility with slash in the name #9043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dyc3 merged 1 commit into from
Mar 9, 2026
Merged

fix(parse/css): parse tailwind @utility with slash in the name #9043

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/fix-tailwind-utility-slash.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@biomejs/biome": patch
---

Fixed [#8897](https://github.com/biomejs/biome/issues/8897): Biome now parses `@utility` names containing `/` when Tailwind directives are enabled.
41 changes: 33 additions & 8 deletions crates/biome_css_parser/src/lexer/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ pub enum CssLexContext {
/// Applied when lexing Tailwind CSS utility classes.
/// Currently, only applicable to when we encounter a `@apply` rule.
TailwindUtility,
/// Applied when lexing Tailwind CSS utility names in `@utility`.
TailwindUtilityName,
}

impl LexContext for CssLexContext {
Expand Down Expand Up @@ -142,6 +144,9 @@ impl<'src> Lexer<'src> for CssLexer<'src> {
CssLexContext::Color => self.consume_color_token(current),
CssLexContext::UnicodeRange => self.consume_unicode_range_token(current),
CssLexContext::TailwindUtility => self.consume_token_tailwind_utility(current),
CssLexContext::TailwindUtilityName => {
self.consume_token_tailwind_utility_name(current)
}
},
None => EOF,
};
Expand Down Expand Up @@ -772,10 +777,16 @@ impl<'src> CssLexer<'src> {
fn consume_identifier(&mut self) -> CssSyntaxKind {
debug_assert!(self.is_ident_start());

self.consume_identifier_with_slash(false)
}

fn consume_identifier_with_slash(&mut self, allow_slash: bool) -> CssSyntaxKind {
debug_assert!(self.is_ident_start());

// Note to keep the buffer large enough to fit every possible keyword that
// the lexer can return
let mut buf = [0u8; 27];
let (count, only_ascii_used) = self.consume_ident_sequence(&mut buf);
let (count, only_ascii_used) = self.consume_ident_sequence(&mut buf, allow_slash);

if !only_ascii_used {
return IDENT;
Expand Down Expand Up @@ -1039,14 +1050,14 @@ impl<'src> CssLexer<'src> {
///
/// This function will panic if the first character to be consumed is not a valid
/// start of an identifier, as determined by `self.is_ident_start()`.
fn consume_ident_sequence(&mut self, buf: &mut [u8]) -> (usize, bool) {
fn consume_ident_sequence(&mut self, buf: &mut [u8], allow_slash: bool) -> (usize, bool) {
debug_assert!(self.is_ident_start());

let mut idx = 0;
let mut only_ascii_used = true;
// Repeatedly consume the next input code point from the stream.
while let Some(current) = self.current_byte() {
if let Some(part) = self.consume_ident_part(current) {
if let Some(part) = self.consume_ident_part(current, allow_slash) {
if only_ascii_used && !part.is_ascii() {
only_ascii_used = false;
}
Expand Down Expand Up @@ -1077,21 +1088,27 @@ impl<'src> CssLexer<'src> {
///
/// Returns the consumed character wrapped in `Some` if it is part of an identifier,
/// and `None` if it is not.
fn consume_ident_part(&mut self, current: u8) -> Option<char> {
fn consume_ident_part(&mut self, current: u8, allow_slash: bool) -> Option<char> {
let dispatched = lookup_byte(current);

if allow_slash && dispatched == SLH {
self.advance(1);
return Some(current as char);
}
if self.options.is_tailwind_directives_enabled()
&& current == b'-'
&& self.peek_byte() == Some(b'*')
&& dispatched == MIN
&& self.peek_byte().map(lookup_byte) == Some(MUL)
{
// HACK: handle `--*`
if self.prev_byte() == Some(b'-') {
if self.prev_byte().map(lookup_byte) == Some(MIN) {
self.advance(1);
return Some(current as char);
}
// otherwise, handle cases like `--color-*`
return None;
Comment on lines 1098 to 1108
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Please don’t make lexer output depend on is_tailwind_directives_enabled().

This branch still tokenises the same bytes differently depending on a parser option. That’s a nasty way to make disabled-mode diagnostics go sideways.

Based on learnings: "In the Biome CSS parser, lexer token emission should not be gated behind parser options like is_tailwind_directives_enabled(). The lexer must emit correct tokens regardless of parser options to enable accurate diagnostics and error messages when the syntax is used incorrectly."

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@crates/biome_css_parser/src/lexer/mod.rs` around lines 1098 - 1108, The lexer
branch currently gates handling of sequences like `--*` on
self.options.is_tailwind_directives_enabled(), which makes token emission
option-dependent; remove that option check so the logic always runs: whenever
dispatched == MIN and peek_byte().map(lookup_byte) == Some(MUL) perform the same
handling — if prev_byte().map(lookup_byte) == Some(MIN) then call advance(1) and
return Some(current as char), otherwise return None — while keeping the same
uses of dispatched, MIN, MUL, peek_byte, prev_byte, advance, and current so
token emission no longer depends on is_tailwind_directives_enabled().

}

let chr = match lookup_byte(current) {
let chr = match dispatched {
IDT | MIN | DIG | ZER => {
self.advance(1);
// SAFETY: We know that the current byte is a hyphen or a number.
Expand Down Expand Up @@ -1484,6 +1501,14 @@ impl<'src> CssLexer<'src> {
}
}

fn consume_token_tailwind_utility_name(&mut self, current: u8) -> CssSyntaxKind {
if self.is_ident_start() {
return self.consume_identifier_with_slash(true);
}

self.consume_token(current)
}

/// Consume a single tailwind utility as a css identifier.
///
/// This is intentionally very loose, and pretty much considers anything that isn't whitespace or semicolon.
Expand Down
2 changes: 1 addition & 1 deletion crates/biome_css_parser/src/syntax/at_rule/tailwind.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ pub(crate) fn parse_utility_at_rule(p: &mut CssParser) -> ParsedSyntax {
}

let m = p.start();
p.bump(T![utility]);
p.bump_with_context(T![utility], CssLexContext::TailwindUtilityName);

// Parse utility name - can be simple or functional
if !is_at_utility_identifier(p) {
Expand Down
3 changes: 3 additions & 0 deletions ...biome_css_parser/tests/css_test_suite/error/tailwind/when-disabled/utility-with-slash.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
@utility a/b {
color: red;
}
108 changes: 108 additions & 0 deletions ..._css_parser/tests/css_test_suite/error/tailwind/when-disabled/utility-with-slash.css.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
---
source: crates/biome_css_parser/tests/spec_test.rs
expression: snapshot
---

## Input

```css
@utility a/b {
color: red;
}

```


## AST

```
CssRoot {
bom_token: missing (optional),
items: CssRootItemList [
CssAtRule {
at_token: AT@0..1 "@" [] [],
rule: CssBogusAtRule {
items: [
UTILITY_KW@1..9 "utility" [] [Whitespace(" ")],
CssIdentifier {
value_token: IDENT@9..13 "a/b" [] [Whitespace(" ")],
},
CssDeclarationOrRuleBlock {
l_curly_token: L_CURLY@13..14 "{" [] [],
items: CssDeclarationOrRuleList [
CssDeclarationWithSemicolon {
declaration: CssDeclaration {
property: CssGenericProperty {
name: CssIdentifier {
value_token: IDENT@14..21 "color" [Newline("\n"), Whitespace("\t")] [],
},
colon_token: COLON@21..23 ":" [] [Whitespace(" ")],
value: CssGenericComponentValueList [
CssIdentifier {
value_token: IDENT@23..26 "red" [] [],
},
],
},
important: missing (optional),
},
semicolon_token: SEMICOLON@26..27 ";" [] [],
},
],
r_curly_token: R_CURLY@27..29 "}" [Newline("\n")] [],
},
],
},
},
],
eof_token: EOF@29..30 "" [Newline("\n")] [],
}
```

## CST

```
0: CSS_ROOT@0..30
0: (empty)
1: CSS_ROOT_ITEM_LIST@0..29
0: CSS_AT_RULE@0..29
0: AT@0..1 "@" [] []
1: CSS_BOGUS_AT_RULE@1..29
0: UTILITY_KW@1..9 "utility" [] [Whitespace(" ")]
1: CSS_IDENTIFIER@9..13
0: IDENT@9..13 "a/b" [] [Whitespace(" ")]
2: CSS_DECLARATION_OR_RULE_BLOCK@13..29
0: L_CURLY@13..14 "{" [] []
1: CSS_DECLARATION_OR_RULE_LIST@14..27
0: CSS_DECLARATION_WITH_SEMICOLON@14..27
0: CSS_DECLARATION@14..26
0: CSS_GENERIC_PROPERTY@14..26
0: CSS_IDENTIFIER@14..21
0: IDENT@14..21 "color" [Newline("\n"), Whitespace("\t")] []
1: COLON@21..23 ":" [] [Whitespace(" ")]
2: CSS_GENERIC_COMPONENT_VALUE_LIST@23..26
0: CSS_IDENTIFIER@23..26
0: IDENT@23..26 "red" [] []
1: (empty)
1: SEMICOLON@26..27 ";" [] []
2: R_CURLY@27..29 "}" [Newline("\n")] []
2: EOF@29..30 "" [Newline("\n")] []

```

## Diagnostics

```
utility-with-slash.css:1:2 parse ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

× Tailwind-specific syntax is disabled.

> 1 │ @utility a/b {
│ ^^^^^^^^^^^^^
> 2 │ color: red;
> 3 │ }
│ ^
4 │

i Enable `tailwindDirectives` in the css parser options, or remove this if you are not using Tailwind CSS.

```
3 changes: 3 additions & 0 deletions crates/biome_css_parser/tests/css_test_suite/ok/tailwind/utility/with-slash.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
@utility a/b {
color: red;
}
88 changes: 88 additions & 0 deletions crates/biome_css_parser/tests/css_test_suite/ok/tailwind/utility/with-slash.css.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
source: crates/biome_css_parser/tests/spec_test.rs
expression: snapshot
---

## Input

```css
@utility a/b {
color: red;
}

```


## AST

```
CssRoot {
bom_token: missing (optional),
items: CssRootItemList [
CssAtRule {
at_token: AT@0..1 "@" [] [],
rule: TwUtilityAtRule {
utility_token: UTILITY_KW@1..9 "utility" [] [Whitespace(" ")],
name: CssIdentifier {
value_token: IDENT@9..13 "a/b" [] [Whitespace(" ")],
},
block: CssDeclarationOrRuleBlock {
l_curly_token: L_CURLY@13..14 "{" [] [],
items: CssDeclarationOrRuleList [
CssDeclarationWithSemicolon {
declaration: CssDeclaration {
property: CssGenericProperty {
name: CssIdentifier {
value_token: IDENT@14..21 "color" [Newline("\n"), Whitespace("\t")] [],
},
colon_token: COLON@21..23 ":" [] [Whitespace(" ")],
value: CssGenericComponentValueList [
CssIdentifier {
value_token: IDENT@23..26 "red" [] [],
},
],
},
important: missing (optional),
},
semicolon_token: SEMICOLON@26..27 ";" [] [],
},
],
r_curly_token: R_CURLY@27..29 "}" [Newline("\n")] [],
},
},
},
],
eof_token: EOF@29..30 "" [Newline("\n")] [],
}
```

## CST

```
0: CSS_ROOT@0..30
0: (empty)
1: CSS_ROOT_ITEM_LIST@0..29
0: CSS_AT_RULE@0..29
0: AT@0..1 "@" [] []
1: TW_UTILITY_AT_RULE@1..29
0: UTILITY_KW@1..9 "utility" [] [Whitespace(" ")]
1: CSS_IDENTIFIER@9..13
0: IDENT@9..13 "a/b" [] [Whitespace(" ")]
2: CSS_DECLARATION_OR_RULE_BLOCK@13..29
0: L_CURLY@13..14 "{" [] []
1: CSS_DECLARATION_OR_RULE_LIST@14..27
0: CSS_DECLARATION_WITH_SEMICOLON@14..27
0: CSS_DECLARATION@14..26
0: CSS_GENERIC_PROPERTY@14..26
0: CSS_IDENTIFIER@14..21
0: IDENT@14..21 "color" [Newline("\n"), Whitespace("\t")] []
1: COLON@21..23 ":" [] [Whitespace(" ")]
2: CSS_GENERIC_COMPONENT_VALUE_LIST@23..26
0: CSS_IDENTIFIER@23..26
0: IDENT@23..26 "red" [] []
1: (empty)
1: SEMICOLON@26..27 ";" [] []
2: R_CURLY@27..29 "}" [Newline("\n")] []
2: EOF@29..30 "" [Newline("\n")] []

```