라우트 단위 스타일

#개요

페이지 레이아웃과 일회성 스타일은 해당 페이지 옆에 두고 라우트나 컴포넌트가 스타일시트를 불러오게 하세요. 값은 공유 토큰을 계속 사용할 수 있습니다. 정의를 공유한다고 모든 네이티브 규칙을 전역으로 전달할 필요는 없습니다.

먼저 프레임워크의 설치 가이드를 완료하세요. Vite, Next.js, Webpack 통합에서는 이 로컬 스타일에 프로젝트 토큰, 믹스인, 사용자 정의 미디어를 사용할 수 있습니다:

일반 선택자와 선언을 작성하세요. 페이지 간에 값을 일관되게 유지해야 하면 공유 토큰을 참조하세요:

.home-section {  padding-block: var(--spacing-5xl);}

해당 스타일을 소유한 라우트, 페이지 모듈, 컴포넌트 진입점에서 라우트 스타일시트를 불러오세요:

import "./home.css"

앱 셸에서는 레이어 순서와 공유 스타일을 위해 전역 스타일시트를 계속 불러오세요. 전역 스타일시트는 기존 @import '@master/css'로 시작하며 이 전체 import를 home.css에 추가하지 마세요.

라우트 import가 제어하는 것은 전달이며 선택자 범위가 아닙니다. 불러온 뒤 .home-section은 문서 안에서 해당 클래스가 있는 모든 요소에 일치할 수 있습니다. 소유 범위를 드러내는 이름을 사용하고 로컬 범위의 클래스 이름이 필요하면 프레임워크의 CSS Modules 지원을 사용하세요. 라우트 CSS의 로드 시점과 탐색 후 유지 여부도 프레임워크가 결정합니다.

import는 CSS 전달 시점을 제어합니다. 불러온 뒤 네이티브 클래스 선택자는 문서 전체에서 일치할 수 있습니다.

텍스트 설명

라우트 파일이 .note 규칙을 불러옵니다. 문서의 두 영역에 일치하는 .note 요소가 있고 둘 다 강조됩니다.

#프로젝트 정의 사용하기

정의 맥락은 전역 네이티브 규칙을 불러오지 않습니다. 라우트 CSS는 프레임워크가 전달하며 import가 선택자를 격리하지는 않습니다.

텍스트 설명

1. 참조. 컴파일 시점에 프로젝트 토큰과 공유 어휘를 읽습니다.
2. 컴파일. 라우트의 네이티브 규칙과 사용하는 변수 또는 관리 키프레임을 출력하며 관련 없는 전역 네이티브 규칙은 복사하지 않습니다.
3. 로드. 프레임워크나 번들러가 라우트 CSS 출력을 전달하게 합니다.

통합은 로컬 스타일시트에 프로젝트 정의 맥락을 제공합니다. 일반 네이티브 CSS에서 해당 토큰, 믹스인, 이름 있는 조건을 사용하고 출력 스타일시트의 로드는 프레임워크가 계속 담당합니다.

.pricing-card {  padding: var(--spacing-lg);  border-radius: var(--radius-lg);  background-color: var(--color-surface-raised);}

라우트 출력에는 이 네이티브 규칙과 규칙이 사용하는 테마 변수 또는 관리 키프레임이 포함됩니다. 다른 진입점이 같은 리소스를 사용해도 이 출력은 자체적으로 필요한 리소스를 갖습니다. 전역 네이티브 규칙과 유틸리티 클래스는 복사되지 않습니다.

#네이티브 규칙을 불러오지 않고 정의 참조하기

정의가 앱 진입점 그래프 밖에 있다면 @reference를 사용하세요. 예를 들어 로컬 마케팅 스타일시트가 색상 토큰과 자체 컴포넌트를 함께 제공할 수 있습니다:

@theme {  --color-campaign: var(--color-blue-60);}@layer components {  .campaign-root { color: var(--color-campaign); }}

라우트 스타일시트에서 해당 파일을 참조한 뒤 라우트가 소유한 규칙에 토큰을 사용하세요:

@reference "../../styles/marketing.css";@layer components {  .campaign-banner {    border-color: var(--color-campaign);  }}

라우트 출력에는 .campaign-banner와 필요한 색상 리소스가 포함되며 .campaign-root는 포함되지 않습니다. 해당 네이티브 컴포넌트도 필요하면 적절한 앱 또는 라우트 import로 마케팅 스타일시트를 불러오세요. 패키지가 내보낸 스타일시트도 같은 구분을 따릅니다. 정의만 참조하는 동작은 참조 지시문을 참고하세요.

#네이티브 선택자 작성하기

라우트의 네이티브 규칙은 app/home/home.css에 작성하고 라우트 마크업에서 해당 클래스를 사용하세요. 유틸리티 클래스가 개별 선택을 덮어쓸 수 있어야 한다면 규칙을 @layer components에 두세요.

네이티브 규칙을 불러와도 새 Master CSS 유틸리티가 등록되지는 않습니다. 아래 두 카드는 같은 네이티브 클래스를 사용합니다. 두 번째에는 p-md를 추가하므로 유틸리티가 컴포넌트의 var(--spacing-lg) padding을 덮어씁니다. 이 클래스 이름에 @utility를 등록할 필요는 없습니다.

@layer components {  .home-bento {    display: grid;    gap: var(--spacing-md);    grid-template-columns: minmax(0, 1fr);    overflow-wrap: anywhere;  }  .home-bento-card {    border-radius: var(--radius-lg);    padding: var(--spacing-lg);    border: 1px solid var(--color-line-divider);    background-color: var(--color-surface-raised);    color: var(--color-text-body);  }  .home-bento-card > h2 {    font-size: var(--font-size-lg);    line-height: 1.4;    font-weight: var(--font-weight-regular);    margin-block: 0 0.5rem;  }  .home-bento-card > p {    color: var(--color-text-muted);    line-height: var(--leading-lg);    margin: 0;  }}

<section class="home-bento" aria-label="Workspace options">  <article class="home-bento-card">    <h2>Team workspace</h2>    <p>Shared route styles set the card's surface, typography and spacing.</p>  </article>  <article class="home-bento-card p-md">    <h2>Compact workspace</h2>    <p>A utility adjusts padding without another native class.</p>  </article></section>

@layer components {  .home-bento {    gap: var(--spacing-md);    overflow-wrap: anywhere;    grid-template-columns: minmax(0, 1fr);    display: grid;  }  .home-bento-card {    border-radius: var(--radius-lg);    padding: var(--spacing-lg);    border: 1px solid var(--color-line-divider);    background-color: var(--color-surface-raised);    color: var(--color-text-body);  }  .home-bento-card > h2 {    font-size: var(--font-size-lg);    line-height: 1.4;    font-weight: var(--font-weight-regular);    margin-block: 0 .5rem;  }  .home-bento-card > p {    color: var(--color-text-muted);    line-height: var(--leading-lg);    margin: 0;  }}@layer theme {  :root,  :host {    --color-zinc-30: oklch(78% .0025 265);    --color-zinc-40: oklch(68.6% .0028 265);    --color-zinc-60: oklch(48.6% .003 265);    --color-zinc-70: oklch(39.8% .0028 265);    --color-zinc-90: oklch(24.6% .0022 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-body: light-dark(var(--color-zinc-70), var(--color-zinc-30));    --color-text-muted: light-dark(var(--color-zinc-60), var(--color-zinc-40))  }  :root,  :host {    --color-white: oklch(100% 0 none)  }  :root,  :host {    --leading-lg: 1.8;    --font-weight-regular: 400;    --font-size-lg: 1.125rem;    --radius-lg: .5rem;    --spacing-md: 1rem;    --spacing-lg: 1.5rem  }}@layer utilities {  .p-md {    padding: var(--spacing-md)  }}

규칙을 @layer components에 두면 클래스로 덮어쓸 수 있습니다. 캐스케이드 레이어를 참고하세요.

이 네이티브 규칙은 기본적으로 스타일시트와 함께 출력됩니다. 소스가 네이티브 CSS 가지치기를 활성화하면 감지된 클래스 사용 정보가 유지할 규칙을 결정합니다. 선택자를 여러 페이지에서 재사용하게 된다면 공유 역할을 전역 스타일로 옮기세요.

#로컬에서 변형 사용하기

프로젝트 사용자 정의 미디어는 일반 미디어 쿼리와 함께 네이티브 규칙 안에서 사용할 수 있습니다:

.home-note {  color: var(--color-blue-60);  @media (--dark) {    color: var(--color-blue-40);  }  @media (width < 52.125rem) {    width: 100%;  }}

--dark는 시스템의 prefers-color-scheme 설정을 따릅니다. 수동 data-theme 속성은 이 쿼리를 바꾸지 않습니다. 수동으로 선택한 색상 모드를 따라야 하는 표면에는 적응형 색상 토큰을 사용하세요.

#라우트 전달 검증하기

라우트를 직접 연 뒤 다른 페이지에서 해당 라우트로 이동하세요. 스타일시트가 로드되고 네이티브 선택자가 일치하며 예상 토큰 값이 있는지 확인하세요. 공유 페이지도 검사하세요. 로컬 소스 소유 구조로 인해 라우트 전용 CSS가 의도치 않게 앱 진입점으로 이동하면 안 됩니다.

출력이 없으면 라우트 CSS import와 통합의 프로젝트 맥락을 확인하세요. 규칙은 있지만 결과가 다르면 일치하는 선택자, 레이어, 계산값을 검사하세요. 전체 @master/css import를 하나 더 추가해도 선택자나 캐스케이드 문제는 해결되지 않습니다.

페이지 간 변경 전후 측정, 선택적 가지치기, 프로젝트 예산은 CSS 전달 최적화에서 이어서 다룹니다.