• 유틸리티 클래스
  • CSS 유틸리티 클래스는 어디에 정의되어 있나요?
  • Tailwind CSS
    • Tailwind CSS 기본 사항
      • 접두사
      • 반응형 CSS 유틸리티 클래스
      • hover, focus 및 기타 상태 수정자
      • !important 수정자
      • 간격 및 크기 CSS 유틸리티 클래스
      • 색상 CSS 유틸리티 클래스
    • Tailwind CSS 번들 빌드하기
    • Tailwind CSS 자동 완성
      • VS Code
      • RubyMine
    • 설정 뷰어
  • 새로운 유틸리티 클래스를 어디에 두어야 하나요?
  • 컴포넌트 클래스를 언제 만들어야 하나요?
  • HTML 및 스타일시트에서 Tailwind CSS 활용하기
    • 1. HTML에 유틸리티 클래스를 직접 사용합니다 (선호하는 접근 방식)
    • 2. 필요할 경우 컴포넌트 클래스에 유틸리티 클래스를 적용합니다
• 네이밍
• 중첩
• js- 접두사가 있는 선택자
• 유틸 CSS 클래스가 있는 선택자
• ARIA 속성이 있는 선택자
• extend at-rule 사용
• 린트

SCSS 스타일 가이드

유틸리티 클래스

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

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

유틸리티 클래스는 Tailwind CSS에 의해 생성됩니다.

사용 가능한 CSS 유틸리티 클래스를 보려면 Tailwind CSS 자동 완성 또는 설정 뷰어를 사용하세요.

utilities.scss와 common.scss에서 정의된 클래스는 더 이상 사용되지 않습니다.

비디자인 시스템 값을 사용하는 common.scss 클래스는 피해야 합니다. 대신 준수하는 값으로 클래스 사용하세요.

Bootstrap의 유틸리티 클래스를 피하세요.

Tailwind CSS

2024년 8월 기준으로, 우리는 CSS 유틸리티 제공자로 Tailwind CSS를 사용하고 있습니다. 이는 이전의 맞춤형 솔루션을 대체합니다. 동기 부여, 제안 및 구현 세부정보에 대한 내용은 Tailwind CSS 디자인 문서를 참조하세요.

Tailwind CSS 기본 사항

아래는 Tailwind CSS 기본 사항과 Pajamas 디자인 시스템을 사용하는 방법에 대한 정보입니다. 보다 심층적인 가이드는 공식 Tailwind CSS 문서를 참조하세요.

접두사

Tailwind CSS를 사용하여 모든 유틸리티 클래스에 gl- 접두사를 사용하도록 설정했습니다. 응답형 유틸리티 또는 상태 수정자를 사용할 때는 접두사가 콜론(:) 뒤에 붙습니다.

예시: gl-mt-5, lg:gl-mt-5.

반응형 CSS 유틸리티 클래스

반응형 CSS 유틸리티 클래스는 브레이크포인트 이름과 그 뒤에 : 문자를 붙여 접두사가 붙습니다.

사용 가능한 브레이크포인트는 tailwind.defaults.js#L44에서 설정되어 있습니다.

예시: lg:gl-mt-5

hover, focus 및 기타 상태 수정자

상태 수정자는 조건부로 Tailwind CSS 클래스를 적용하는 데 사용할 수 있습니다. CSS 유틸리티 클래스 앞에 수정자 이름을 붙이고 : 문자를 연결하세요.

예시: hover:gl-underline

!important 수정자

CSS 유틸리티 클래스의 시작 부분에 !를 추가하여 important modifier를 사용할 수 있습니다. 반응형 유틸리티 클래스나 상태 수정자와 함께 사용할 때는 !가 : 문자 뒤에 옵니다.

예제: !gl-mt-5, lg:!gl-mt-5, hover:!gl-underline

간격 및 크기 CSS 유틸리티 클래스

간격 및 크기 CSS 유틸리티 클래스(예: margin, padding, width, height)는 src/tokens/build/tailwind/tokens.cjs에서 정의된 간격 스케일을 사용합니다.

그들은 공식 Tailwind CSS 문서에 문서화된 명명 규칙을 사용하지만 스케일은 일치하지 않습니다. Tailwind CSS autocomplete를 사용할 때 구성된 간격 스케일이 표시됩니다.

예제: gl-mt-5는 margin-top: 1rem;입니다.

색상 CSS 유틸리티 클래스

색상 CSS 유틸리티 클래스(예: color 및 background-color)는 src/tokens/build/tailwind/tokens.cjs에서 정의된 색상을 사용합니다.

그들은 공식 Tailwind CSS 문서에 문서화된 명명 규칙을 사용하지만 색상 이름은 일치하지 않습니다. Tailwind CSS autocomplete를 사용할 때 구성된 색상이 표시됩니다.

예제: gl-text-red-500은 color: var(--red-500, #dd2b0e);입니다.

Tailwind CSS 번들 빌드하기

Vite 또는 Webpack을 GitLab Development Kit와 함께 사용할 때, Tailwind CSS는 파일 변경 사항을 감시하여 감지된 유틸리티를 즉시 빌드합니다.

새 Tailwind CSS 번들을 빌드하려면 yarn tailwindcss:build를 실행하세요. 이는 생산 자산을 bundle exec rake gitlab:assets:compile로 빌드할 때 내부적으로 호출되는 스크립트입니다.

번들이 어떻게 빌드되든, 출력은 app/assets/builds/tailwind.css에 저장됩니다.

Tailwind CSS 자동 완성

Tailwind CSS 자동 완성은 코드 편집기에서 사용 가능한 모든 클래스를 나열합니다.

VS Code

참고: 자동 완성이 느린 경우, TS 서버가 사용할 수 있는 메모리 양을 늘려야 할 수도 있습니다.

Tailwind CSS IntelliSense 확장 프로그램을 설치하세요. HAML 및 사용자 정의 *-class prop 지원을 위해 추천되는 설정은 다음과 같습니다:

{
  "tailwindCSS.experimental.classRegex": [
    ["class: [\"|']+([^\"|']*)[\"|']+", "([a-zA-Z0-9\\-:!/]+)"],
    ["(\\.[\\w\\-.]+)[\\n\\=\\{\\s]", "([\\w\\-]+)"],
    ["[a-z]+-class(?:es)?=\"([^'\"]*)\""]
  ],
  "tailwindCSS.emmetCompletions": true
}

RubyMine

Tailwind CSS 자동 완성은 기본적으로 활성화되어 있습니다.

전체 HAML 및 사용자 정의 *-class prop 지원을 위해 기본 설정에 대한 권장 업데이트는 다음과 같습니다:

{
  "includeLanguages": {
    "haml": "html"
  },
  "emmetCompletions": true,
  "experimental": {
    "classRegex": [
      ["class: [\"|']+([^\"|']*)[\"|']+", "([a-zA-Z0-9\\-:!/]+)"],
      ["(\\.[\\w\\-.]+)[\\n\\=\\{\\s]", "([\\w\\-]+)"],
      ["[a-z]+-class(?:es)?=\"([^'\"]*)\""]
    ]
  }
}

설정 뷰어

GitLab은 tailwind.defaults.js에서 자체 Tailwind CSS 구성을 정의하여 Pajamas 디자인 시스템과 일치시키고 CSS 유틸리티 클래스를 gl-로 접두어 붙입니다.

이는 공식 Tailwind CSS 문서에서 간격, 크기 및 색상 CSS 유틸리티 클래스가 일치하지 않을 수 있음을 의미합니다. 또한, gl- 접두어는 표시되지 않을 것입니다.

우리는 우리가 구성에서 사용자 정의한 내용을 개괄적으로 보여주는 Tailwind Config Viewer의 인스턴스를 호스팅합니다.

어쨌든, 우리는 Tailwind CSS 유틸리티에 대한 자동 완성을 받기 위해 IDE를 설정할 것을 권장합니다 이는 최신의 포괄적인 데이터 소스에서 가져올 수 있음을 보장합니다.

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

유틸리티 클래스는 Tailwind CSS에 의해 생성되며, 대부분의 CSS 기능을 지원합니다. 사용할 수 없는 것이 있다면 GitLab UI에서 tailwind.defaults.js를 업데이트해야 합니다.

컴포넌트 클래스를 언제 만들어야 하나요?

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

1. 유틸리티 클래스부터 시작합니다.
2. 유틸리티 클래스를 조합하여 컴포넌트 클래스를 만드는 것이 코드 중복을 제거하고 명확한 책임을 캡슐화한다면 그렇게 합니다.

이는 컴포넌트 클래스의 유기적 성장을 촉진하고 재사용할 수 없는 클래스의 생성을 방지합니다. 또한 “유틸리티 중심”에서 발생하는 클래스 종류는 도메인 중심(예: .security-report-widget, .commit-header-icon)보다 디자인 중심(예: .button, .alert, .card) 경향이 있습니다.

영감:

• https://tailwindcss.com/docs/utility-first
• https://tailwindcss.com/docs/extracting-components

HTML 및 스타일시트에서 Tailwind CSS 활용하기

컴포넌트 클래스를 작성할 때 Tailwind CSS의 유틸리티 클래스를 효과적으로 통합하여 디자인 시스템과 일관성을 유지하고 CSS 번들을 작게 유지하는 것이 중요합니다.

HTML의 유틸리티 CSS 클래스 대 스타일시트의 유틸리티 CSS 클래스:

HTML에서 유틸리티 클래스를 직접 사용함으로써 CSS 파일 크기를 작게 유지하고 유틸리티 중심 철학을 준수할 수 있습니다. 절대 필요하지 않는 한 사용자 정의 스타일과 유틸리티 클래스를 하나의 컴포넌트 클래스에 결합하지 않음으로써 혼란과 잠재적인 충돌을 방지할 수 있습니다.

• 선호 이유:
  • 더 작은 CSS 파일 크기: 유틸리티 클래스를 직접 사용하면 더 간결한 CSS 파일로 이어질 수 있으며, 보다 일관된 디자인 시스템을 촉진합니다.
  • 명확성 및 유지 관리 용이: HTML에서 유틸리티 클래스를 사용하면 스타일 적용 방식이 명확해져서 충돌 및 회귀 위험이 줄어듭니다.
• 스타일 결합의 잠재적 문제:
  • 충돌: 유틸리티 클래스와 사용자 정의 스타일이 하나의 클래스에 결합되면, 특히 스타일 간의 의존성이 있을 때 충돌이 발생할 수 있습니다.
  • 회귀: 스타일 해결 방식이 덜 명확해져서, 가능한 회귀 또는 예기치 않은 동작으로 이어질 수 있습니다.

이러한 가이드라인을 따르면 Tailwind CSS를 효과적으로 활용하는 깔끔하고 유지 관리 가능한 스타일 시트를 만들 수 있습니다.

1. HTML에 유틸리티 클래스를 직접 사용합니다 (선호하는 접근 방식)

유지 보수성을 높이고 유틸리티 우선 원칙에 따르기 위해, 유틸리티 클래스를 HTML 요소에 직접 추가합니다.

컴포넌트 클래스는 주로 비 유틸리티 CSS 스타일만 포함해야 합니다.

다음 예제에서는 position: fixed; right: 0; left: 0;를 SCSS 파일에 추가하는 대신 유틸리티 클래스 gl-fixed와 gl-inset-x-0를 추가합니다:

<!-- 나쁨 -->
<div class="my-class"></div>

<style>
  .my-class {
    top: $header-height;
    z-index: 999;
    position: fixed;
    left: 0px;
    right: 0px;
 }
</style>

<!-- 좋음 -->
<div class="my-class gl-fixed gl-inset-x-0"></div>

<style>
  .my-class {
    top: $header-height;
    z-index: 999;
  }
</style>

2. 필요할 경우 컴포넌트 클래스에 유틸리티 클래스를 적용합니다

때때로 HTML에 유틸리티 클래스를 직접 사용할 수 없는 경우가 있으며, 이럴 때는 커스텀 SCSS 파일에 포함해야 할 수도 있습니다.

그런 다음, 관련 속성이나 값에 대한 판단 없이 디자인 시스템에서 스타일 정의를 상속받고 싶을 수 있습니다.

이 과정을 간소화하기 위해, Tailwind CSS의 @apply 지시어를 사용하여 유틸리티의 스타일 정의를 커스텀 스타일에 포함할 수 있습니다.

@apply를 사용하는 것은 디자인 시스템에 따라 달라지는 CSS 속성(예: margin, padding)을 적용하는 데 _권장_됩니다.

단위가 없는 CSS 속성(예: display: flex)에 대해서는 CSS 속성을 직접 사용하는 것이 좋습니다.

// 나쁨
.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와 함께 사용하기 위해 설계되었으며, 스타일링을 깨뜨리지 않도록 제거하거나 이름을 변경할 수 있습니다.

유틸 CSS 클래스가 있는 선택자

스타일시트에서 선택자로 유틸리티 CSS 클래스를 사용하지 마세요. 이러한 클래스는 변경될 가능성이 높아 선택자를 업데이트해야 하며, 구현 유지 관리가 더 어려워질 수 있습니다. 대신 다른 기존 CSS 클래스를 사용하거나 요소의 스타일링을 위해 새로운 커스텀 CSS 클래스를 추가하세요. 이 접근 방식은 유지 관리성을 개선하고 버그 발생 위험을 줄입니다.

// ❌ 나쁜 예
.gl-mb-5 {
  /* ... */
}

// ✅ 좋은 예
.component-header {
  /* ... */
}

ARIA 속성이 있는 선택자

스타일링 목적으로 ARIA 속성 선택자를 사용하지 마세요. 이러한 속성과 역할은 보조 기술을 지원하기 위해 설계되었습니다. ARIA로 주석이 달린 컴포넌트의 구조는 변경될 수 있으며, 이에 따라 스타일링도 변경될 수 있습니다. 스타일링을 손상시키지 않고 이러한 역할과 속성을 다른 요소로 이동할 수 있어야 합니다.

// 나쁜 예
&[aria-expanded=false] &-header {
  border-bottom: 0;
}

// 좋은 예
&.is-collapsed &-header {
  border-bottom: 0;
}

extend at-rule 사용

extend at-rule의 사용은 메모리 누수 및 규칙이 제대로 작동하지 않음으로 인해 금지됩니다.

린트

우리는 stylelint를 사용하여 스타일 가이드 일치를 검사합니다. 이 도구는 .stylelintrc의 규칙 집합과 우리의 SCSS 구성에서 규칙을 사용합니다. .stylelintrc는 프로젝트의 홈 디렉토리에 위치합니다.

변경 사항으로 인해 경고가 발생하는지 확인하려면 GitLab 디렉토리에서 yarn lint:stylelint를 실행하세요. Stylelint는 또한 GitLab CI/CD에서 실행되어 경고를 포착합니다.

Rake 작업에서 이해할 수 없는 경고가 발생하면 SCSS Lint의 문서에 규칙에 대한 전체 목록이 포함되어 있습니다.