SCSS 스타일 가이드
유틸리티 클래스
사이트가 커짐에 따라 CSS를 더 생성하는 것을 줄이기 위해, 새로운 CSS를 추가하는 대신 유틸리티 클래스를 사용하는 것을 선호합니다. 복잡한 경우에는 CSS를 추가하는 대신 컴포넌트 클래스를 추가함으로써 해결할 수 있습니다.
Tailwind CSS
우리는 CSS 유틸리티 클래스 설정을 Tailwind CSS로 이관 중입니다. 동기, 제안 및 구현 세부 정보는 Tailwind CSS 청사진을 참조하세요.
Tailwind CSS 번들 빌드
GitLab Development Kit으로 Vite 또는 Webpack을 사용할 때, Tailwind CSS는 파일 변경을 감지하여 감지된 유틸리티를 빌드합니다.
새로운 Tailwind CSS 번들을 빌드하려면 yarn tailwindcss:build를 실행하세요. 이 스크립트는 bundle exec rake gitlab:assets:compile로 프로덕션 자산을 빌드할 때 내부적으로 호출됩니다.
그러나 번들이 빌드되는 방식에 상관없이 출력물은 app/assets/builds/tailwind.css에 저장됩니다.
유틸리티 클래스는 어디에 정의되어 있나요?
유틸리티 클래스는 Tailwind CSS에서 생성됩니다. 사용 가능한 유틸리티 클래스를 보려면 VS Code Tailwind CSS IntelliSense 플러그인을 설치하거나 RubyMine을 사용하는 경우 자동 완성이 기본적으로 가능해야 합니다.
또한 config/helpers/tailwind/css_in_js.js에 레거시 유틸리티 클래스가 정의되어 있습니다. 이러한 유틸리티 클래스는 Tailwind 네이밍 규칙을 준수하지 않으며, 점진적으로 Tailwind와 동등한 유틸리티로 이관될 예정입니다. 이러한 유틸리티 클래스의 새로운 인스턴스를 추가하지 말고 Tailwind와 동등한 유틸리티를 사용하세요.
utilities.scss 및 common.scss에 정의된 클래스는 폐기되고 있습니다.
비디오에서 사용되어 기존 디자인 시스템 값을 사용하는 common.scss의 클래스는 피하세요. 대신 일치하는 값의 클래스를 사용하세요.
Bootstrap의 유틸리티 클래스를 피하세요.
ml-1이 gl-ml-2로 변환됨).새로운 유틸리티 클래스를 어디에 추가해야 하나요?
대부분의 CSS 기능을 지원하는 Tailwind CSS에서 유틸리티 클래스가 생성됩니다. 사용할 수 없는 기능이 있는 경우 GitLab UI의 tailwind.defaults.js를 업데이트해야 합니다.
컴포넌트 클래스를 생성해야 하는 시점은 언제인가요?
“유틸리티 우선” 접근 방식을 권장합니다.
- 유틸리티 클래스부터 시작하세요.
- 유틸리티 클래스를 컴포넌트 클래스로 결합하여 코드 중복을 제거하고 명확한 책임을 캡슐화하는 경우에만 수행하세요.
이는 컴포넌트 클래스의 유기적인 성장을 장려하고 일회성으로 재사용할 수 없는 클래스의 생성을 방지합니다. 또한, “유틸리티 우선”에서 나오는 클래스는 .button, .alert, .card와 같은 설계 중심(예: .security-report-widget, .commit-header-icon와 같은 도메인 중심) 클래스보다 설계 중심 클래스를 보다 선호합니다.
유틸리티 믹스인
우리는 현재 Tailwind로 이관 중입니다. 이 이관으로 유틸리티 믹스인이 제거되었으므로 새로운 유틸리티 믹스인을 추가하지 마세요. 대신에 @apply 지시문을 사용하여 CSS 선택기에 Tailwind 스타일을 추가할 수 있습니다. @apply는 디자인 시스템에 의존하는 CSS 속성(예: margin, padding)에 사용되어야 합니다. 단위가 없는 CSS 속성(예: display: flex)에 대해서는 CSS 속성을 직접 사용하는 것이 괜찮습니다.
// 나쁨
.my-class {
@include gl-mt-3;
}
// 나쁨
.my-class {
margin-top: 0.5rem;
}
// 괜찮음
.my-class {
display: flex;
}
// 좋음
.my-class {
@apply gl-mt-5 gl-flex;
}
네이밍
파일명은 snake_case를 사용해야 합니다.
CSS 클래스는 snake_case나 camelCase 대신에 lowercase-hyphenated 형식을 사용해야 합니다.
// 나쁨
.class_name {
color: #fff;
}
// 나쁨
.className {
color: #fff;
}
// 좋음
.class-name {
color: #fff;
SCSS의 & 기능을 사용하여 복합 클래스 이름을 만드는 것을 피하세요. 검색이 어려워지고 제한적인 이점을 제공하기 때문입니다.
// 나쁨
.class {
&-name {
color: orange;
}
}
// 좋음
.class-name {
color: #fff;
태그 이름 선택기 대신 클래스 이름을 사용하세요. 태그 이름 선택기를 사용하는 것은 의도하지 않은 요소에 영향을 줄 수 있으므로 권장되지 않습니다.
// 나쁨
ul {
color: #fff;
}
// 좋음
.class-name {
color: #fff;
}
// 최상
// 기존 스타일을 추가하는 대신 기존 유틸리티 클래스를 사용하세요
클래스 이름은 ID보다 우선해야 합니다. ID를 사용하는 규칙은 재사용할 수 없으며 페이지에서 영향을 받는 요소는 하나뿐입니다.
// 나쁨
#my-element {
padding: 0;
}
// 좋음
.my-element {
padding: 0;
}
중첩
불필요한 중첩을 피하세요. 래퍼 컴포넌트의 추가적인 구체성은 오버라이딩을 어렵게 만듭니다.
// 나쁨
.component-container {
.component-header {
/* ... */
}
.component-body {
/* ... */
}
}
// 좋음
.component-container {
/* ... */
}
.component-header {
/* ... */
}
.component-body {
/* ... */
}
js- 접두어가 있는 선택기
스타일링 목적으로 js- 접두어가 있는 선택기를 사용하지 마세요. 이러한 선택기는 JavaScript에서만 사용되도록 되어 있으며 스타일에 영향을 준다는 것을 기억하세요.
extend at-rule 사용
extend at-rule의 사용은 메모리 누수 때문에 금지되어 있으며 원하는 대로 작동하지 않음을 주의하세요.
린팅
우리는 스타일 가이드 준수 여부를 확인하기 위해 stylelint를 사용합니다. .stylelintrc의 규칙 세트와 우리의 SCSS 구성에서 규칙을 사용합니다. .stylelintrc는 프로젝트의 홈 디렉터리에 위치합니다.
변경 사항에서 경고가 발생하는지 확인하려면 GitLab 디렉터리에서 yarn lint:stylelint를 실행하세요. Stylelint는 또한 GitLab CI/CD에서 경고를 잡기 위해 실행됩니다.
이해하기 어려운 경고가 Rake task에서 발생하는 경우, SCSS Lint의 문서에 전체 규칙 디렉터리이 포함되어 있습니다.
도움말