프론트엔드 스타일 가이드 및 코딩 규칙
이 문서는 Guessimate Angular 프론트엔드의 코딩 표준, 아키텍처 패턴 및 디자인 시스템을 정의합니다.
1. 기술 스택
- 프레임워크: Angular 20+
- 스타일링: Tailwind CSS 4
- 상태 관리: Angular Signals 및 RxJS
- 빌드 시스템: Angular CLI (Esbuild)
2. 프로젝트 구조
기능 기반(Feature-Based) 디렉토리 구조를 따릅니다. 코드는 기술 유형이 아닌 도메인 기능별로 구성됩니다.
src/app/
├── core/ # 전역 싱글톤 (가드, 인터셉터, 전역 서비스)
├── layout/ # 레이아웃 컴포넌트 (내비게이션, 푸터, 쉘)
├── features/ # 기능 모듈 (도메인 로직)
│ ├── home/
│ ├── session/
│ │ ├── components/ # 멍청한/프레젠테이션 컴포넌트
│ │ ├── pages/ # 스마트/컨테이너 컴포넌트 (라우팅됨)
│ │ ├── services/ # 기능별 상태/로직
│ │ └── models/ # 기능별 타입
│ └── ...
├── websocket/ # WebSocket 인프라
└── shared/ # 공유 유틸리티 (파이프, 디렉티브, 일반 UI)
명명 규칙
- 파일: 케밥 케이스 (예:
session-page.component.ts,auth.service.ts). - 클래스: 파스칼 케이스 (예:
SessionPageComponent,AuthService). - 선택자:
app-접두사, 케밥 케이스 (예:app-user-profile). - 시그널: 접미사 없음, 설명적인 명사/동사 (예:
user(),isLoading()). - 옵저버블:
$접미사 (예:user$).
3. 컴포넌트 표준
정의
- 독립형 컴포넌트(Standalone Components) 사용 (
standalone: true는 v19+에서 기본값). - 대부분의 컴포넌트에 인라인 템플릿(Inline Templates) 을 선호하여 로직과 뷰를 함께 배치합니다.
- 외부 CSS 파일을 피하고 템플릿에서 직접 Tailwind CSS 유틸리티 클래스를 사용합니다.
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // 명시적 임포트
template: `
<div class="p-4 bg-surface-100 rounded-lg">
<h1 class="text-2xl font-bold text-gray-900">{{ title() }}</h1>
</div>
`
})
export class ExampleComponent {
title = signal('Hello World');
}
제어 흐름
새로운 내장 Angular 제어 흐름 구문을 사용합니다.
<!-- 좋음 -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
의존성 주입
더 나은 타입 추론과 깔끔한 코드를 위해 생성자 주입보다 inject() 함수를 선호합니다.
// 좋음
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// 가능하면 피할 것
constructor(private
route: ActivatedRoute
)
{
}
4. 상태 관리
- 로컬 상태: 기본 상태에
signal()사용. - 공유 상태: 적절한 수준(루트 또는 컴포넌트)에서 제공되는 Signal Store(시그널을 사용하는 서비스) 사용.
- 반응형 데이터: 파생 상태에
computed()사용, 부수 효과는effect()를 제한적으로 사용.
@Injectable()
export class SessionStore {
// 상태
private readonly _state = signal<SessionState>(initialState);
// 선택자
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// 액션
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. 스타일링 및 디자인 시스템
Tailwind CSS 4를 사용하며 styles.css에 정의된 의미론적 색상 팔레트를 사용합니다.
사용 규칙
- 유틸리티 우선: HTML에 직접 클래스를 작성합니다.
- 매직 넘버 금지: 테마 값 사용 (예:
p-[16px]대신p-4). - 다크 모드: 모든 색상 관련 클래스에
dark:수정자를 사용합니다.
색상 팔레트
애플리케이션은 Tailwind 색상에 매핑된 의미론적 명명 규칙을 사용합니다.
핵심 색상
| 카테고리 | 의미론적 이름 | 라이트 모드 | 다크 모드 | 용도 |
|---|---|---|---|---|
| 배경 | background | gray-50 | gray-950 | 주요 애플리케이션 배경 |
| 표면 | surface | white | gray-900 | 카드, 모달, 섹션 |
| 대체 표면 | surface-alt | gray-100 | gray-800 | 보조 배경, 입력 필드 |
| 기본/브랜드 | brand | blue-600 | blue-600 | 주요 동작, 버튼, 하이라이트 |
| 기본/브랜드 흐림 | brand-muted | blue-50 | blue-900/30 | 선택된 상태, 약한 하이라이트 |
| 성공 | success | emerald-500 | emerald-600 | 성공 상태, 확인 |
| 성공 흐림 | success-muted | emerald-50 | emerald-900/30 | 성공 배경 |
| 위험 | danger | red-600 | red-600 | 오류, 파괴적 동작 |
| 위험 흐림 | danger-muted | red-50 | red-900/30 | 오류 배경 |
| 경고 | warning | amber-500 | amber-600 | 경고, 보류 상태 |
| 경고 흐림 | warning-muted | amber-50 | amber-900/30 | 경고 배경 |
타이포그래피 및 테두리
| 카테고리 | 라이트 모드 | 다크 모드 | 용도 |
|---|---|---|---|
| 기본 | gray-900 | white | 주요 제목 및 본문 텍스트 |
| 보조 | gray-500 | gray-400 | 부제목, 레이블, 보조 정보 |
| 흐림 | gray-400 | gray-500 | 비활성화된 텍스트, 플레이스홀더 |
| 테두리 | gray-200 | gray-800 | 표준 구분선 및 카드 테두리 |
styles.css에서의 구현
색상은 @theme 블록 내에서 CSS 변수를 사용하여 정의됩니다:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. 일반 컴포넌트 패턴
카드 및 컨테이너
콘텐츠 컨테이너(예: 추정 카드, 목록)의 표준 스타일:
<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
<!-- 내용 -->
</div>
- 배경:
bg-surface-100/60(라이트) /dark:bg-gray-900/40(다크) - 테두리:
border border-surface-200(라이트) /dark:border-gray-800/60(다크) - 둥글기:
rounded-md(표준) - 구분선:
divide-y divide-surface-300 dark:divide-gray-800
타이포그래피 헤더
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">제목</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">부제목 설명</span>
</div>