SCSS 스타일 가이드

유틸리티 클래스

참고: gl-deprecated-로 접두사가 붙은 유틸리티는 사용하지 말고 대신 Tailwind 유틸리티를 사용하십시오.

사이트가 성장함에 따라 CSS 생성을 줄이기 위해 새로운 CSS를 추가하는 대신 유틸리티 클래스를 사용하는 것을 선호합니다. 복잡한 경우에는 CSS를 추가하는 대신 컴포넌트 클래스를 추가함으로서 처리할 수 있습니다.

Tailwind CSS

CSS 유틸리티 클래스 설정을 Tailwind CSS로 마이그레이션 중에 있습니다. 동기, 제안 및 구현 세부 사항은 Tailwind CSS 블루프린트를 참조하십시오.

Tailwind CSS 번들 빌드

GitLab 개발 킷과 함께 Vite 또는 Webpack를 사용할 때 Tailwind CSS는 파일 변경을 감지하여 감지된 유틸리티를 동적으로 빌드하도록 합니다.

새로운 Tailwind CSS 번들을 빌드하려면 yarn tailwindcss:build를 실행하십시오. 이 스크립트는 bundle exec rake gitlab:assets:compile을 사용하여 프로덕션 자산을 빌드할 때 내부적으로 호출되는 스크립트입니다.

그러나 번들이 빌드되는 방식에 상관없이 출력물은 app/assets/builds/tailwind.css에 저장됩니다.

유틸리티 클래스가 어디에 정의되어 있나요?

GitLab UI에서 정의된 유틸리티 클래스를 사용하는 것을 선호합니다.

클래스의 쉬운 목록은 Unpkg에서 확인할 수도 있습니다.

또는 CSS Class completion과 같은 확장 프로그램을 사용할 수 있습니다.

utilities.scss와 common.scss에 있는 클래스는 폐기되고 있습니다. 비디자인 시스템 값이 아닌 값을 사용하는 common.scss 내의 클래스는 피하세요. 대신 일치하는 값을 가진 클래스를 사용하십시오.

부트스트랩의 유틸리티 클래스를 사용하지 마십시오.

참고: 부트스트랩의 유틸리티 클래스를 GitLab UI 유틸리티 클래스로 마이그레이션하는 동안 마진과 패딩에 대한 클래스가 서로 다르다는 점에 유의하십시오. GitLab에서 사용하는 크기 스케일은 부트스트랩 라이브러리에서 사용하는 스케일과 다릅니다. 부트스트랩 패딩 또는 마진 유틸리티의 경우, 동일한 시각적 결과를 얻으려면 적용된 유틸리티의 크기를 두 배로 할 필요가 있습니다(예: ml-1이 gl-ml-2가 됨).

새로운 유틸리티 클래스를 어디에 두어야 하나요?

우리는 Tailwind로 마이그레이션 중이기 때문에 필요한 유틸리티 클래스가 이미 사용 가능할 수 있습니다. VS Code 플러그인 IntelliSense을 사용하면 사용 가능한 유틸리티 클래스가 표시됩니다. 필요한 유틸리티 클래스가 Tailwind에서 사용할 수 없는 경우에는 계속해서 GitLab UI에서 정의된 유틸리티 클래스를 계속 사용하거나 Unpkg에서 확인할 수 있는 유틸리티 클래스를 계속 사용해야 합니다. 그래도 해당 유틸리티 클래스를 찾을 수 없는 경우 새로운 Tailwind 코어 플러그인을 활성화해야 합니다. 관련 코어 플러그인을 찾아 tailwind.defaults.js의 corePlugins 배열에 코어 플러그인을 추가하기 위한 MR을 엽니다(https://gitlab.com/gitlab-org/gitlab-ui/-/blob/bad526b4662f38868cfc3d89157b22f5cc9a94c5/tailwind.defaults.js).

언제 컴포넌트 클래스를 생성해야 하나요?

우리는 “유틸리티 우선” 접근 방식을 권장합니다.

  1. 유틸리티 클래스로 시작합니다.
  2. 유틸리티 클래스를 컴포넌트 클래스로 결합하여 코드 중복을 제거하고 명확한 책임을 캡슐화하는 경우에는 그렇게 하십시오.

이렇게 하면 컴포넌트 클래스의 유기적인 성장을 촉진하고 일회용으로 재사용할 수 없는 클래스를 만드는 것을 방지합니다. 또한 “유틸리티 우선”으로부터 나오는 클래스는 주로 디자인 중심임을 (예: .button, .alert, .card) 도메인 중심임을 (예: .security-report-widget, .commit-header-icon)보다는 임을 의미합니다.

인스피레이션:

유틸리티 믹스인

우리는 현재 Tailwind로 이전 중입니다. 이전은 유틸리티 믹스인을 제거하므로 새로운 유틸리티 믹스인 사용을 금지해주세요. 대신 SCSS 변수와 사전 정의된 CSS 키워드를 사용하세요. 

// 나쁨
.my-class {
  @include gl-mt-3;
}

// 매우 안 좋음
.my-class {
  @include gl-deprecated-mt-3;
}

// 나쁨
.my-class {
  margin-top: 0.5rem;
}

// 좋음
.my-class {
  margin-top: $gl-spacing-scale-3;
}

네이밍

파일 이름은 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;
}

// Best
// 기존의 스타일을 추가하는 대신 기존 유틸리티 클래스를 선호하세요

클래스 이름은 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 작업의 경고가 발생하는 경우, SCSS Lint의 문서에는 룰의 전체 목록이 포함되어 있습니다.