문법

추출

정적 후보 추출, 소스 경계, 분류, 공유 소스의 소유 범위입니다.

이 페이지의 내용

추출은 애플리케이션을 실행하지 않고 소스에서 가능한 클래스 이름을 찾습니다. 잠재 클래스라고도 하는 이 후보들은 매칭과 후보 정책의 입력입니다. 문자열을 찾았다고 해서 규칙 생성, 유효한 CSS 값, 특정 브라우저에서의 동작이 보장되지는 않습니다.

이 페이지는 소스 경계, 정적 추출, 후보 분류, 소스 소유 관계를 정의합니다. 클래스 이름 스캔은 발견 가능한 클래스 작성법과 누락된 스타일 진단을 설명합니다. 경로와 클래스 패턴의 문법은 스캔 지시문에서 정의합니다.

완전한 정적 문자열

추출기는 소스 언어의 구조를 사용합니다. JavaScript와 TypeScript 문자열은 className 밖에서도 후보를 제공할 수 있습니다. 표시 텍스트로 컴포넌트에 전달한 클래스도 발견될 수 있습니다. 스캐너는 어느 분기가 실행되거나 함수가 런타임에 무엇을 반환할지 추론하지 않습니다.

소스 형식	추출로 확인할 수 있는 내용
HTML `class="p-md shadow-md"`	완전한 클래스 두 개
JSX `className="p-md"`	완전한 클래스
`error ? 'bg-red-60' : 'bg-green-60'`	두 정적 분기
`{ compact: 'p-sm', roomy: 'p-lg' }`	객체 안의 완전한 값
완전한 정적 클래스 부분이 있는 템플릿 리터럴	해당하는 완전한 부분
`'bg-' + tone` 또는 클래스 이름 안의 템플릿 보간	`bg-red-60` 같은 완성된 결과를 추론하지 않음
런타임에 API에서만 반환하는 클래스	추출할 소스 문자열이 없음

예를 들어 다음 소스는 두 색상과 고정된 padding 및 반경을 포함합니다. 객체에 이미 있는 완전한 클래스를 찾는 데 tone 보간을 평가할 필요는 없습니다.

const tones = {  neutral: 'bg-surface-base fg-text-neutral',  destructive: 'bg-red-70 fg-white'}const className = `px-md r-md ${tones.destructive}`

추출된 클래스 집합은 bg-surface-base, fg-text-neutral, bg-red-70, fg-white, px-md, r-md입니다. 이 예제가 destructive 분기를 선택하더라도 스캐너가 출력을 해당 분기로만 제한하지는 않습니다.

후보 분류

추출 후에는 활성 manifest와 스타일시트 등록 내용이 후보의 역할을 결정합니다. 알 수 없는 일반 애플리케이션 클래스가 자동으로 Master CSS 오류가 되는 것은 아닙니다.

후보	결과
`p-md` 같은 등록된 프리셋 유틸리티	일치하는 유틸리티 규칙과 의존 항목 생성
프로젝트가 정의한 `@utility` 클래스	프로젝트의 컴파일된 manifest에 등록된 규칙 생성
`.card` 같은 등록된 네이티브 클래스	네이티브 사용을 기록하며 새 유틸리티를 생성하지 않음
정의와 일치하지 않는 애플리케이션 클래스	Master가 생성하는 규칙 없음
형식이 잘못된 Master 클래스	규칙 없음. 검사에서 구문 진단을 보고할 수 있음
매칭되었지만 CSS 값이 유효하지 않거나 알 수 없는 클래스	CSS를 출력할 수 있음. 매칭만으로 값의 유효성이나 브라우저 지원이 보장되지 않음

<article class="card p-md shadow-md">Release notes</article>

여기서 p-md와 shadow-md는 프리셋으로 해석됩니다. card가 네이티브 규칙을 유지하려면 프로젝트가 실제로 해당 규칙을 제공하고 가지치기 정책이 사용 여부를 고려해야 합니다. 네이티브 스타일시트는 기본적으로 유지되며 스캔 자체가 가지치기를 활성화하지는 않습니다.

생성된 CSS

@layer theme {  :root,  :host {    --spacing-md: 1rem  }  :root,  :host {    --shadow-md: 0 0 0 1px light-dark(oklch(0% 0 none / .05), oklch(100% 0 none / .06)), 0 1px 1px -.5px light-dark(oklch(0% 0 none / .045), oklch(0% 0 none / .3)), 0 2px 2px -1px light-dark(oklch(0% 0 none / .04), oklch(0% 0 none / .26)), 0 4px 4px -2px light-dark(oklch(0% 0 none / .04), oklch(0% 0 none / .24)), 0 8px 8px -4px light-dark(oklch(0% 0 none / .045), oklch(0% 0 none / .26))  }}@layer utilities {  .shadow-md {    box-shadow: var(--shadow-md)  }  .p-md {    padding: var(--spacing-md)  }}

컴파일러 매칭, CSS 구문 검증, CSS 값 검증, 브라우저 지원은 서로 다른 확인 항목입니다. 클래스 검사로 구분하세요. 매칭된 클래스에도 브라우저의 캐스케이드와 계산값 규칙이 적용됩니다.

소스 경계

빌드 통합과 CLI는 HTML, JavaScript, TypeScript, JSX, TSX, 지원하는 프레임워크 소스, Markdown, MDX, PHP 같은 일반적인 프로젝트 소스 파일을 탐색합니다. 일반 앱 파일에는 광범위한 @source 지시문이 필요하지 않습니다.

자동 탐색은 프로젝트와 상위 워크스페이스의 .gitignore를 따르며 Git 전역 무시 설정은 사용하지 않습니다. 의존 패키지, 선언 파일, 바이너리, VCS 데이터, 생성 출력은 제외됩니다. Master 출력과 현재 번들러 출력은 스캔 입력이 아니며 Next.js는 설정된 distDir을 사용합니다.

지시문	탐색에 미치는 영향
`@source`	자동 탐색이나 `.gitignore`에서 제외된 파일을 포함해 추가 경로를 명시적으로 포함
`@source not`	경로를 제외하며 포함보다 우선함

이 예외는 공유 워크스페이스 소스, 외부 콘텐츠, 범위가 지정된 가지치기 루트에 사용합니다. 상대 경로 규칙과 지원 형식은 스캔 지시문을 참고하세요.

프레임워크 통합은 컴파일된 표시 문자열을 다시 스캔하기보다 원본 MDX, Vue, Svelte 소스를 우선합니다. 추출기의 언어 종류는 중요합니다. 의도적인 일반 텍스트 입력에는 kind: 'raw'를 사용할 수 있지만 파싱에 실패한 소스의 폴백으로 사용해서는 안 됩니다.

Markdown과 MDX

Markdown과 MDX 추출은 구문 트리를 사용합니다. 실제 HTML/JSX, ESM, 표현식은 참여하지만 본문, 인라인 코드, 일반 코드 펜스, frontmatter는 참여하지 않습니다. 따라서 문서의 코드 펜스에 클래스를 보여 줘도 자동으로 실행 가능한 예제가 되지는 않습니다.

호스트는 parentSource로 실행 가능한 예제를 가상 소스로 등록하거나 한정된 클래스를 명시적으로 safelist에 추가할 수 있습니다. 가상 입력은 실행 가능한 콘텐츠의 소유 관계를 명확히 하며 호스트가 실제 예제 소스와 언어 종류를 제공합니다.

잘못된 소스는 SOURCE_PARSE_ERROR를 보고합니다. 개발에서는 이전에 성공한 결과를 유지하고 프로덕션 빌드는 실패합니다. 파싱이나 읽기 실패는 빈 소스로 업데이트하는 것과 같지 않습니다.

소스 위치

추출은 문자열뿐 아니라 후보의 출현 위치도 보고할 수 있습니다. 원본 UTF-16 범위, 추출기, 콘텐츠 종류, owner, 포함 또는 제외 이유가 이에 해당합니다. 인코딩된 속성도 원본 소스 범위를 유지합니다. 완전한 URL 리터럴은 제외되며 알 수 없는 네이티브 선언은 나중에 검증할 후보로 남을 수 있습니다.

소스 소유 관계

스캐너 세션은 과거에 본 모든 클래스가 아니라 현재 각 소스가 제공하는 결과를 추적합니다. 소스를 업데이트하면 해당 소스의 결과를 대체합니다. 소스 하나를 제거해도 다른 현재 소스나 safelist가 유지하는 클래스는 제거되지 않습니다.

이 세션 작업은 @master/css-tooling/scanner/node의 MasterCSSScanner에서 사용할 수 있습니다. 소스 소유 관계를 다루는 작업이며 통합 사용자는 보통 빌드 플러그인이 이를 수행하도록 맡깁니다.

작업	소유 관계에 미치는 영향
`collectCandidates`	추출만 수행하며 소스 결과를 유지하지 않음
`scanSource`	빈 문자열을 포함해 소스 하나의 내용을 대체
`removeSource`	해당 소스와 가상 하위 소스를 제거
`reconcileSources`	owner 하나의 다음 전체 소스 집합을 제공
`registerNativeClasses`	스타일시트 소스에 네이티브 클래스 식별 정보 등록
`removeOwner`	해당 owner의 소스와 네이티브 등록 제거

await scanner.scanSource('page.mdx', content, { owner: 'pages' })await scanner.scanSource('page.mdx#live', html, {  owner: 'pages', parentSource: 'page.mdx', kind: 'html'})scanner.removeSource('page.mdx', { owner: 'pages' })

page.mdx를 제거하면 가상 예제도 제거됩니다. 다른 owner의 참조는 독립적으로 유지됩니다. 조정 작업은 해당 owner에 제공한 입력만 유지합니다. 명시적으로 유지한 가상 입력은 부모가 외부에서 관리되더라도 해당 집합에 남습니다.

changed는 생성 출력이나 가지치기 입력의 변경을 나타냅니다. sourceChanged는 출처만 바뀐 업데이트도 포함합니다. 두 번째 소스가 CSS를 바꾸지 않고 소유 관계만 추가할 수 있습니다. sources 뷰는 빈 입력과 가상 관계를 포함해 현재 성공한 소스 집합을 보여 줍니다.

런타임 값

클래스 이름을 바꾸지 않고 값을 바꿀 수 있습니다. 완전한 네이티브 선언 클래스는 마크업이나 스크립트가 제공하는 사용자 지정 속성을 참조할 수 있습니다.

<h1 class="(font-size:var(--headline-size))" style="--headline-size: 2rem">Launch notes</h1>

스캐너는 완전한 클래스 하나를 봅니다. --headline-size를 업데이트하면 새 유틸리티 규칙 없이 브라우저의 값이 바뀝니다. 변하는 값 예제를 참고하세요.

같은 계약은 (width:var(--progress))에도 적용됩니다. 스크립트가 element.style.setProperty('--progress', '40%')를 호출해도 클래스는 그대로 유지됩니다.

클래스 이름 자체가 시작 후에 처음 생긴다면 정적 빌드는 이를 발견할 수 없습니다. 한정된 safelist를 제공하거나 런타임 또는 점진적 렌더링을 사용하세요.

후보 정책

지시문	용도	제약
`@safelist`	CMS 상태나 위젯 클래스 같은 한정된 외부 클래스를 유지	매칭을 건너뛰거나 없는 유틸리티를 정의하지 않음
`@blocklist`	잘못 감지한 후보가 CSS를 생성하지 않도록 함	소스를 다시 쓰거나 임의의 네이티브 CSS를 제거하지 않음

클래스 패턴, 우선순위, 네이티브 사용은 스캔 지시문을 참고하세요. 네이티브 규칙과 키프레임 제거는 네이티브 CSS 가지치기를 참고하세요. 후보 탐색과 네이티브 유지는 별도 정책입니다.

스타일이 없다면 작성 구문을 바꾸기 전에 완전한 클래스, 파일의 탐색 경계, 후보 정책을 확인하세요. 가이드 진단 체크리스트가 실제 상황에서 이 확인 절차를 안내합니다.