Master CSS 설치하기

프로젝트에 맞는 설정 방법을 선택하세요. 통합은 Master CSS를 프레임워크나 빌드 도구에 연결하고 CLI는 번들러가 없는 프로젝트의 스타일시트를 생성합니다. CDN은 기본 프리셋을 사용하는 일반 HTML 설정을 제공합니다.

#통합

기존 앱에는 통합을 사용하세요. 기본값은 정적 렌더링으로, 빌드 시 소스에서 완전한 클래스 이름을 찾아 브라우저에 스타일시트를 전달합니다. 프레임워크를 선택해 설정 파일과 안내를 확인하거나 아래 자동 설치 프로그램을 사용하세요.

런타임 및 서버 렌더링 설정은 통합별 렌더링 지원을 참고하세요.

#시작하기 전에

Node.js 24를 사용하고 package.json이 있는 앱 루트 디렉터리를 여세요. 설치 프로그램은 기존 프로젝트를 갱신하며 프레임워크 시작 프로젝트를 만들지 않습니다. 앱에는 정상적으로 작동하는 개발 명령이 이미 있어야 합니다.

#패키지 버전

설치 프로그램, 통합 및 다른 Master CSS 패키지에는 이 문서에 표시된 버전을 사용하세요. 수동으로 설치하거나 업데이트할 때도 이 패키지들의 버전을 같게 유지하세요. 다른 npm 태그에 패키지가 있다고 해서 이 설정과의 호환성이 보장되지는 않습니다.

로컬에서 런타임을 평가하려면 빌드한 체크아웃을 사용하는 CDN 예제를 사용하세요. 스크립트, 컴파일된 프로그램, 기본 스타일시트는 같은 빌드의 것을 유지해야 합니다.

수동 설정이나 프레임워크별 파일은 통합 가이드를 참고하세요. 프로젝트에 맞는 빌드 통합이 없다면 독립형 CLI 설정을 따르세요.

1. #Master CSS 추가하기

   프로젝트 루트에서 설치 프로그램을 실행하세요. 프레임워크와 패키지 관리자를 감지하고 설정 파일을 갱신하며 설치 프로그램과 같은 버전의 Master CSS 패키지를 설치합니다.

   npm create @master/css@2.0.0 -- --yes

   설정 내용 검토 또는 제한하기

   --yes는 핵심 통합, ESLint 설정, MCP 패키지, AGENTS.md의 Master CSS 안내를 포함한 권장 기본값을 수락합니다. 출력되는 MCP 등록 및 스킬 설치 명령은 코딩 도구를 위한 선택적 후속 단계이며 설치 프로그램이 실행하지는 않습니다.

   --dry-run을 추가하면 프로젝트 파일을 바꾸거나 예정된 의존성을 설치하지 않고 계획을 확인할 수 있습니다:

   npm create @master/css@2.0.0 -- --yes --dry-run

   핵심 프레임워크 설정만 필요하다면 설치 명령에 --minimal을 추가하세요. ESLint, MCP, 에이전트 안내 추가를 건너뜁니다. 의존성을 직접 설치하려면 --no-install을 추가하세요.

2. #스타일시트 연결 확인하기

   설정 요약을 읽고 출력된 프레임워크별 안내를 완료하세요. 일부 통합에는 후속 설정 명령이나 별도의 CSS 생성 프로세스가 필요합니다. 해당 단계는 프레임워크 가이드를 참고하세요.

   앱이 설치 프로그램에서 만들거나 갱신한 스타일시트를 불러오는지 확인하세요. 해당 스타일시트에는 다음 내용이 있어야 합니다:

   @import '@master/css';

   예를 들어 일반 Vite 앱은 보통 src/main.js에서 ./style.css를 가져옵니다. CSS 파일 이름과 가져오기 위치는 프레임워크에 따라 다릅니다. 패키지를 설치하는 것만으로는 페이지에 스타일시트가 로드되지 않습니다.

   

   통합은 소스에서 클래스 이름을, 스타일시트에서 정의를 읽습니다. 생성된 CSS가 페이지에 도달하려면 앱이 해당 스타일시트를 불러와야 합니다.

   텍스트 설명

   1. 소스. p-md 같은 완전한 클래스가 통합이 스캔하는 소스 파일에 나타납니다. 앱 스타일시트는 @master/css를 가져와 프리셋 정의를 제공합니다.
   2. 빌드 통합. 두 소스가 설정된 통합에 전달되어 인식된 클래스의 CSS를 생성합니다. 설치 프로그램은 이 연결을 설정하고 통합은 이후의 개발 및 빌드 작업을 수행합니다.
   3. 페이지. 앱이 스타일시트를 불러와 생성된 CSS를 브라우저에 전달합니다. 프리셋의 p-md 규칙은 1rem 안쪽 여백을 적용합니다. 패키지 설치만으로는 스타일시트 가져오기가 연결되지 않습니다.

3. #Master CSS 사용 시작하기

   npm run dev 같은 앱의 기존 명령으로 개발 서버를 시작하거나 재시작하세요. 다음 마크업을 화면에 보이는 페이지나 컴포넌트에 넣습니다. JSX에서는 class 대신 className을 사용하세요.

   <p class="w-fit mx-auto my(0) p-md r-md b(1) b-solid b-line-divider bg-surface-raised text-sm fg-text-strong">Hello World</p>

   생성된 CSS

   @layer theme {  :root,  :host {    --color-zinc-90: oklch(24.6% .0022 265);    --color-zinc-100: oklch(15% .0016 265)  }  :root,  :host {    --color-surface-raised: light-dark(var(--color-white), var(--color-zinc-90));    --color-line-divider: light-dark(oklch(0% 0 none / .12), oklch(100% 0 none / .12));    --color-text-strong: light-dark(var(--color-zinc-100), var(--color-white))  }  :root,  :host {    --color-white: oklch(100% 0 none)  }  :root,  :host {    --font-size-sm: .875rem;    --text-sm: var(--font-size-sm);    --text-sm--line-height: 1.5;    --text-sm--letter-spacing: 0;    --radius-md: .375rem;    --spacing-md: 1rem  }}@layer utilities {  .text-sm {    font-size: var(--text-sm);    line-height: var(--text-sm--line-height, normal);    letter-spacing: var(--text-sm--letter-spacing, normal)  }  .bg-surface-raised {    background-color: var(--color-surface-raised)  }  .b-line-divider {    border-color: var(--color-line-divider)  }  .r-md {    border-radius: var(--radius-md)  }  .b-solid {    border-style: solid  }  .b\(1\) {    border-width: calc(1 * 1px)  }  .fg-text-strong {    color: var(--color-text-strong)  }  .my\(0\) {    margin-block: calc(0 * 1px)  }  .mx-auto {    margin-inline: auto  }  .p-md {    padding: var(--spacing-md)  }  .w-fit {    width: fit-content  }}

   프리셋에서 p-md는 텍스트 사방에 1rem의 안쪽 여백을 추가합니다.

   테두리가 있는 작은 표면 안에 텍스트가 보여야 합니다. p-md를 p-lg로 바꾸고 저장하면 사방의 안쪽 여백이 1rem에서 1.5rem으로 늘어나야 합니다. 이는 설치 프로그램이 성공적으로 끝났다는 것뿐 아니라 소스 변경이 페이지에 전달되는지도 확인합니다.

설치 성공은 첫 단계일 뿐입니다. 클래스 변경으로 발견, 생성, 스타일시트 전달을 함께 확인할 수 있습니다.

텍스트 설명

소스의 p-md를 p-lg로 바꾸면 컴파일된 안쪽 여백이 바뀌고 브라우저의 상자가 눈에 띄게 커집니다.

#CDN

CDN 설치는 빌드 도구 없이 브라우저에서 Master CSS를 실행합니다. 일반 HTML 프로토타입에 적합하지만 생성된 스타일은 JavaScript에 의존합니다. JavaScript 없이도 스타일이 필요한 페이지에는 통합이나 CLI를 사용하세요.

런타임 스크립트, 컴파일된 프로그램, 프리셋 스타일시트는 같은 Master CSS 버전을 사용해야 합니다. 이 템플릿의 URL은 서로 같은 버전을 지정합니다. 통합과 CLI에도 같은 패키지 버전 요건이 적용됩니다.

이 템플릿을 index.html로 저장하세요:

<!DOCTYPE html><html lang="en" hidden><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <link rel="preload" as="style" href="https://cdn.master.co/css-preset@2.0.0/src/base.css">  <link rel="preload" as="script" href="https://cdn.master.co/css-runtime@2.0.0">  <link rel="preload" as="fetch" crossorigin href="https://cdn.jsdelivr.net/npm/@master/css-runtime@2.0.0/dist/default-program.bin">  <link rel="stylesheet" href="https://cdn.master.co/css-preset@2.0.0/src/base.css">  <script src="https://cdn.master.co/css-runtime@2.0.0"></script></head><body>  <h1 class="m-2xl italic font-5xl font-heavy fg-text-strong">Hello World</h1></body></html>

제목에는 3rem 바깥 여백, 크기 2.5rem의 기울임 글꼴, 굵기 900, 프리셋의 강조 텍스트 색상이 적용되어야 합니다. font-5xl을 font-6xl로 바꾸면 텍스트가 3rem으로 커집니다. 런타임은 JavaScript로 발생한 클래스 변경도 관찰합니다.

스타일시트는 기본 규칙과 레이어 순서를 제공합니다. 일반 스크립트는 자동으로 시작해 대응하는 컴파일된 프로그램을 불러오고 문서 파싱이 끝난 뒤 초기 클래스를 생성합니다. 규칙이 준비되면 hidden을 제거합니다. 세 프리로드 링크는 스타일시트, 스크립트, 프로그램 요청을 일찍 시작합니다. 런타임은 모듈이 아닌 데이터를 가져오므로 바이너리는 as="fetch" crossorigin를 사용합니다. Master CDN 리디렉션에는 CORS 헤더가 없으므로 바이너리 프리로드와 런타임 가져오기는 jsDelivr 목적지를 직접 사용합니다. CDN 설정은 기본 프리셋을 사용하며, 사용자 지정 @theme이나 @utility 정의는 통합으로 컴파일해야 합니다.

hidden은 선택 사항으로, 스타일이 없는 첫 화면 그리기를 방지합니다. 처리된 프로그램 로딩 오류나 런타임의 3초 시작 시간 초과가 발생하면 내용을 표시합니다. JavaScript를 끄거나 스크립트 자체를 다운로드하지 못하면 이 속성을 제거할 수 없습니다. 이런 경우에도 내용을 읽을 수 있어야 한다면 hidden을 생략하거나 정적 CSS를 제공하세요.

콘텐츠 보안 정책에서는 스크립트, 스타일시트 로딩, 프로그램 가져오기(connect-src)에 CDN과 jsDelivr 리디렉션 대상을 허용하고 런타임이 생성하는 스타일시트도 허용하세요. Wasm은 가져오지 않습니다. 로딩과 하이드레이션 동작은 런타임 렌더링을 참고하세요.

#CLI

번들러를 추가하지 않고 HTML에서 정적 스타일시트를 생성합니다. CLI는 완전한 클래스 이름을 스캔해 CSS를 쓰고, 이를 일반 스타일시트 링크로 불러옵니다. 프로젝트에 맞는 프레임워크 통합이 없다면 이 설정을 사용하세요.

1. #Master CSS 설치하기

   Master CSS CLI를 개발 의존성으로 설치하세요.

   npm install -D @master/css-cli@2.0.0

2. #CSS 진입점 만들기

   기본 Master CSS 진입점을 가져오는 스타일시트를 만드세요.

   main.css

   @import "@master/css";

3. #빌드 명령 실행하기

   명령을 실행해 소스를 스캔하고 master.css를 작성하세요.

   npx @master/css-cli generate "index.html" --output master.css --watch

4. #생성된 스타일시트 불러오기

   아래 문서를 index.html로 저장하세요. 감시 프로세스가 클래스 이름으로 master.css를 생성합니다. 디렉터리를 제공하고 페이지를 열면 스타일이 적용된 문단을 볼 수 있습니다.

   index.html

   <!DOCTYPE html><html lang="en"><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1">  <link rel="stylesheet" href="./master.css"> </head><body>  <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">Hello World</p></body></html>

   중립적인 표면, 얇은 테두리, 작은 모서리 반경과 네 면 각각 1rem의 패딩입니다.

#배포용 빌드하기

감시 명령은 계속 실행되며 선택한 소스가 바뀌면 출력을 갱신합니다. 프로덕션 빌드에서는 --watch를 생략해 명령이 출력을 작성한 뒤 종료되도록 하세요:

npx @master/css-cli generate "index.html" --output master.css

index.html, master.css, 생성된 스타일시트가 참조하는 인접 CSS 자산을 배포하세요. 상대 경로를 유지해야 합니다. master.css만 복사하면 가져온 스타일이 누락될 수 있습니다. 새 빌드를 게시할 때마다 생성된 자산 묶음을 함께 유지하세요.

배포된 페이지를 불러와 모든 스타일시트 요청이 성공하는지 확인하세요. JavaScript를 꺼도 문단의 생성된 안쪽 여백, 테두리, 표면 색상이 유지되어야 합니다. 클래스 이름 스캔에서는 일반 애플리케이션 범위 밖의 소스를 포함하는 방법을 설명합니다.

#스타일이 나타나지 않을 때

페이지가 편집한 마크업을 렌더링하고 앱 스타일시트를 불러오는지 확인하세요. 이어서 빌드 통합이 활성화되어 해당 소스 파일을 스캔하는지 확인합니다. p-lg처럼 완전한 클래스 이름을 유지하세요. p-${size} 같은 조각으로 조합하면 정적 스캔이 최종 클래스를 볼 수 없습니다.

설치 프로그램이 인식하지 못한 프레임워크나 불완전한 설정을 보고하면 해당 통합 가이드 또는 CLI 가이드를 따르세요. 일반 앱 범위 밖의 파일은 클래스 이름 스캔을 참고하세요.

간격 변경이 정상 동작하면 문법 튜토리얼로 진행해 상호작용 상태와 반응형 조건을 갖춘 카드를 만들어 보세요.