diff --git a/.agent/workflows/pr-develop.md b/.agent/workflows/pr-develop.md new file mode 100644 index 00000000..53b56a77 --- /dev/null +++ b/.agent/workflows/pr-develop.md @@ -0,0 +1,28 @@ +--- +description: Create a PR from current branch to develop branch with automated title and body based on GitHub issue and branch changes. +--- + +1. Parse the current branch name to extract the issue number (e.g., `design/#16` → issue number `16`). + +2. Fetch issue information: `gh issue view {issue-number}` to get the issue title. + +3. Generate PR title: combine branch name and issue title. Format: `{branch-name} {issue-title-without-prefix}`. Remove category prefix like `[DESIGN]` from the issue title. + +4. Analyze branch changes: run `git log develop...HEAD` and `git diff develop...HEAD` to understand the work done. + +5. Generate PR body using `.github/PULL_REQUEST_TEMPLATE.md`: + - Fill `closed #{issue-number}` in the related issue section + - Summarize branch changes in the work description section + - Keep review requirements section empty + +6. Push current branch to remote if not already pushed. + +7. Create PR using heredoc to safely handle special characters in the body: + ``` + gh pr create --base develop --title "{title}" --body "$(cat <<'EOF' + {body} + EOF + )" + ``` + +8. Output the created PR URL to the user. diff --git a/.agent/workflows/speckits-analyze.md b/.agent/workflows/speckits-analyze.md new file mode 100644 index 00000000..df331e93 --- /dev/null +++ b/.agent/workflows/speckits-analyze.md @@ -0,0 +1,33 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse JSON for FEATURE_DIR. Derive paths: SPEC, PLAN, TASKS. Abort if any required file is missing. + +2. Load artifacts progressively: + - **spec.md**: Overview, Functional/Non-Functional Requirements, User Stories, Edge Cases + - **plan.md**: Architecture/stack, Data Model, Phases, Technical constraints + - **tasks.md**: Task IDs, Descriptions, Phase grouping, Parallel markers, File paths + - **constitution**: `.specify/memory/constitution.md` for principle validation + +3. Build semantic models (internal, not output): + - Requirements inventory with stable keys + - User story/action inventory with acceptance criteria + - Task coverage mapping (each task → requirements/stories) + - Constitution rule set (MUST/SHOULD normative statements) + +4. Run detection passes (limit 50 findings total): + - **Duplication**: near-duplicate requirements + - **Ambiguity**: vague adjectives lacking measurable criteria, unresolved placeholders + - **Underspecification**: requirements missing outcomes, stories missing acceptance criteria + - **Constitution Alignment**: conflicts with MUST principles (always CRITICAL) + - **Coverage Gaps**: requirements with zero tasks, tasks with no mapped requirement + - **Inconsistency**: terminology drift, entity mismatches, task ordering contradictions + +5. Assign severity: CRITICAL (constitution violations, missing core artifacts) / HIGH (conflicts, ambiguous security/performance) / MEDIUM (terminology drift, missing coverage) / LOW (style improvements). + +6. Produce Markdown analysis report with findings table, coverage summary, constitution alignment issues, unmapped tasks, and metrics (total requirements, total tasks, coverage %, ambiguity count, critical issues count). + +7. Provide next actions: if CRITICAL issues exist, recommend resolving before implementation. If only LOW/MEDIUM, user may proceed. Offer to suggest concrete remediation edits (do NOT apply automatically). + +**IMPORTANT**: This is STRICTLY READ-ONLY. Do NOT modify any files. diff --git a/.agent/workflows/speckits-checklist.md b/.agent/workflows/speckits-checklist.md new file mode 100644 index 00000000..064a90ce --- /dev/null +++ b/.agent/workflows/speckits-checklist.md @@ -0,0 +1,36 @@ +--- +description: Generate a custom requirements quality checklist — unit tests for requirements writing, validating completeness, clarity, and consistency. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root. Parse JSON for FEATURE_DIR and AVAILABLE_DOCS. + +2. Ask up to 3 clarifying questions about scope, depth, and audience. Generate questions dynamically from feature domain keywords, risk indicators, and stakeholder hints. Skip if already clear from user input. + +3. Load feature context from FEATURE_DIR: spec.md (requirements/scope), plan.md (technical details), tasks.md (implementation tasks). Load only portions relevant to focus areas. + +4. Generate checklist — "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if needed + - Use short descriptive filename based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Sequential IDs: CHK001, CHK002, ... + - Each run creates a NEW file (never overwrites existing checklists) + +5. Checklist items must test REQUIREMENT QUALITY, not implementation: + - **Completeness**: "Are all necessary requirements documented?" + - **Clarity**: "Are requirements specific and unambiguous?" + - **Consistency**: "Do requirements align without conflicts?" + - **Measurability**: "Can requirements be objectively verified?" + - **Coverage**: "Are all scenarios/edge cases addressed?" + - Include traceability: `[Spec §X.Y]`, `[Gap]`, `[Ambiguity]`, `[Conflict]` + - Minimum 80% of items must include traceability references + +6. PROHIBITED patterns (these test implementation, not requirements): + - "Verify the button clicks correctly" + - "Test error handling works" + - Any item starting with "Verify", "Test", "Confirm" + implementation behavior + +7. REQUIRED patterns (these test requirements quality): + - "Are [requirement type] defined/specified for [scenario]?" + - "Is [vague term] quantified with specific criteria?" + - "Are requirements consistent between [section A] and [section B]?" + +8. Follow template structure from `.specify/templates/checklist-template.md` if available. Report: output path, item count, focus areas, depth level. diff --git a/.agent/workflows/speckits-clarify.md b/.agent/workflows/speckits-clarify.md new file mode 100644 index 00000000..b577e3c8 --- /dev/null +++ b/.agent/workflows/speckits-clarify.md @@ -0,0 +1,30 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 targeted clarification questions and encoding answers back into the spec. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root. Parse JSON for FEATURE_DIR and FEATURE_SPEC. If parsing fails, instruct user to run `/speckits-specify` first. + +2. Load the current spec file. Perform a structured ambiguity and coverage scan using this taxonomy — mark each category as Clear / Partial / Missing: + - Functional Scope & Behavior (goals, out-of-scope, user roles) + - Domain & Data Model (entities, attributes, relationships, lifecycle) + - Interaction & UX Flow (user journeys, error/empty/loading states) + - Non-Functional Quality Attributes (performance, scalability, security) + - Integration & External Dependencies (APIs, data formats) + - Edge Cases & Failure Handling (negative scenarios, rate limiting) + - Constraints & Tradeoffs + - Terminology & Consistency + - Completion Signals (acceptance criteria testability) + +3. Generate a prioritized queue of max 5 clarification questions. Each must be answerable with multiple-choice (2-5 options) or short phrase (<=5 words). Only include questions whose answers materially impact architecture, data modeling, task decomposition, or test design. For multiple-choice, provide a recommended option with reasoning. + +4. Present exactly ONE question at a time. After user answers, validate and record. Stop when: all critical ambiguities resolved, user signals completion, or 5 questions asked. + +5. After each accepted answer, update the spec file immediately: + - Ensure `## Clarifications` section exists with `### Session YYYY-MM-DD` subheading + - Append `- Q: {question} → A: {answer}` + - Apply clarification to the most appropriate spec section + - If the clarification invalidates earlier text, replace it (no contradictions) + +6. Validate after each write: no duplicate bullets, no lingering vague placeholders, markdown structure valid, terminology consistent. + +7. Report completion: number of questions asked, path to updated spec, sections touched, coverage summary table, and suggested next command. diff --git a/.agent/workflows/speckits-constitution.md b/.agent/workflows/speckits-constitution.md new file mode 100644 index 00000000..95afdc11 --- /dev/null +++ b/.agent/workflows/speckits-constitution.md @@ -0,0 +1,35 @@ +--- +description: Create or update the project constitution at .specify/memory/constitution.md from interactive or provided principle inputs, keeping dependent templates in sync. +--- + +1. Load the existing constitution at `.specify/memory/constitution.md`. Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`. + +2. Collect/derive values for placeholders: + - Use values from user input if supplied + - Otherwise infer from repo context (README, docs, prior constitution) + - `RATIFICATION_DATE`: original adoption date + - `LAST_AMENDED_DATE`: today if changes are made + - `CONSTITUTION_VERSION`: increment with semver (MAJOR: principle removals/redefinitions, MINOR: new principles added, PATCH: clarifications/typos) + +3. Draft the updated constitution: + - Replace every placeholder with concrete text (no bracketed tokens left) + - Preserve heading hierarchy + - Each Principle section: succinct name, non-negotiable rules, explicit rationale + +4. Consistency propagation: read and verify alignment with: + - `.specify/templates/plan-template.md` (Constitution Check section) + - `.specify/templates/spec-template.md` (scope/requirements alignment) + - `.specify/templates/tasks-template.md` (task categorization) + - Command files in `.specify/templates/commands/*.md` + - Runtime docs (README.md, quickstart.md) + +5. Produce a Sync Impact Report (prepend as HTML comment in constitution file): + - Version change: old → new + - Modified/added/removed principles + - Templates requiring updates (with file paths) + +6. Validate: no unexplained bracket tokens, version matches report, dates in ISO format, principles are declarative and testable. + +7. Write completed constitution to `.specify/memory/constitution.md`. + +8. Output summary: new version, bump rationale, files flagged for follow-up, suggested commit message. diff --git a/.agent/workflows/speckits-implement.md b/.agent/workflows/speckits-implement.md new file mode 100644 index 00000000..091b88fd --- /dev/null +++ b/.agent/workflows/speckits-implement.md @@ -0,0 +1,31 @@ +--- +description: Execute the implementation plan by processing all tasks defined in tasks.md for this Vite + React SPA project. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS. All paths must be absolute. + +2. Check checklists status (if FEATURE_DIR/checklists/ exists). For each checklist, count total/completed/incomplete items. If any incomplete: STOP and ask user for confirmation. If all complete: proceed. + +3. Load implementation context: + - **Required**: tasks.md (task list), plan.md (tech stack, architecture) + - **Optional**: data-model.md, contracts/, research.md + +4. Verify project conventions before each task (Vite + React SPA): + - Pages: `src/page/{PageName}/` with local `components/` and `hooks/` + - API: Axios via `src/apis/primitives.ts`, functions in `src/apis/apis/`, types in `requests/` + `responses/` + - Hooks: `src/hooks/query/` for TanStack Query, `src/hooks/mutations/` for mutations + - Components: function declaration style (`export default function Component() {}`) + - i18n: `useTranslation()` for all user-facing text + - Variables: `const` by default, `let` only for reassignment, NEVER `var` + - Naming: Components PascalCase, hooks `use` prefix camelCase, utils camelCase + +5. Parse tasks.md structure: extract phases, dependencies, parallel markers [P]. + +6. Execute phase-by-phase: + - Complete each phase before moving to the next + - Respect dependencies: sequential tasks in order, parallel [P] tasks can run together + - File-based coordination: tasks affecting same files run sequentially + +7. Track progress: report after each completed task, mark as `- [x]` in tasks.md. Halt on non-parallel task failure. + +8. Validate completion: verify all tasks completed, features match spec, tests pass, project conventions followed. Report final status. diff --git a/.agent/workflows/speckits-plan.md b/.agent/workflows/speckits-plan.md new file mode 100644 index 00000000..cb61a927 --- /dev/null +++ b/.agent/workflows/speckits-plan.md @@ -0,0 +1,43 @@ +--- +description: Execute the TDD-driven implementation planning workflow to generate design artifacts including test contracts for a Vite + React SPA project. +--- + +1. Run `.specify/scripts/bash/setup-plan.sh --json` from repo root. Parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. + +2. Load context: read FEATURE_SPEC (spec.md), `.specify/memory/constitution.md`, `CLAUDE.md` or project rules if they exist, IMPL_PLAN template, and `package.json`. + +3. Explore the existing codebase before planning: + - Scan `src/page/` for page structure patterns + - Check `src/components/`, `src/hooks/` (query/, mutations/), `src/apis/` + - Check `src/util/`, `src/constants/`, `src/repositories/` + - Review 1-2 existing pages for patterns (TanStack Query hooks, Axios API functions, compound components) + - Scan existing `*.test.ts(x)` files for test patterns (Vitest, @testing-library/react, MSW, Korean descriptions) + +4. Fill Technical Context in the plan: + - TypeScript (strict), React 18 + Vite, React Router v7, TanStack React Query 5 + - Axios (custom `request` primitive), Tailwind CSS 3, i18next, Framer Motion + - Testing: Vitest + @testing-library/react + userEvent + MSW + - Test approach: **TDD (Red-Green-Refactor)** + +5. Run Constitution & Consistency Check from `.specify/memory/constitution.md`: verify folder structure, API layer patterns, hooks separation, page structure, no circular dependencies. + +6. Phase 0 — Research: extract unknowns, research each, write findings to `research.md`. + +7. Phase 1 — Design & Contracts (TDD-First): + - Extract entities → `data-model.md` + - Generate API contracts → `contracts/` + - Define project structure with test files (co-located `{module}.test.ts(x)`) + - Write test contracts to `test-contracts/`: behavior list per module, expected I/O, boundary conditions + - Test priority: `util/` → `apis/` (MSW) → `hooks/` → `components/` → `page/` + +8. Define TDD Implementation Order (Red-Green-Refactor cycle): + - Types (`type/`, `apis/requests/`, `apis/responses/`) + - Pure utilities (`util/`) + - MSW handlers (`mocks/handlers/`) + - API functions (`apis/apis/`) + - Query/Mutation hooks (`hooks/query/`, `hooks/mutations/`) + - Page/component hooks → UI components → Page components + +9. Create Architecture Decision Table: decision name, options, chosen option with rationale, impact, testability impact. + +10. Report: branch, spec path, IMPL_PLAN path, generated artifacts, TDD order summary, constitution check status. Suggest next: `/speckits-tasks`. diff --git a/.agent/workflows/speckits-specify.md b/.agent/workflows/speckits-specify.md new file mode 100644 index 00000000..b06951c8 --- /dev/null +++ b/.agent/workflows/speckits-specify.md @@ -0,0 +1,23 @@ +--- +description: Create or update a feature specification with GitHub issue tracking, branch setup, and auto-clarification loop. +--- + +1. Read `README.md` for project overview and domain context (debate timer service). + +2. Generate a concise slug (2-4 words, kebab-case) from the feature description. Use action-noun format (e.g., "social-login", "vote-results-calendar"). + +3. Ask user which TYPE of work this is: feat / fix / design / docs / refactor / chore / config / test / style / hotfix. Use the selection as `{TYPE}` (lowercase) and `{TYPE_UPPER}` (uppercase) throughout. + +4. Verify `gh` CLI is authenticated (`gh auth status`). Ask user whether to create a new GitHub issue or use an existing one. If new, run `gh issue create --title "[{TYPE_UPPER}] {SLUG}" --body "..." --label "{TYPE}"`. If existing, verify with `gh issue view`. + +5. Ask user which base branch to use: current branch or `develop` (recommended). Create feature branch: `git checkout -b "{TYPE}/#{ISSUE_NUMBER}-{SLUG}"`. + +6. Run `.specify/scripts/bash/create-new-feature.sh --json --no-branch --type-prefix {TYPE} --number {ISSUE_NUMBER} --short-name "{SLUG}" --issue-number {ISSUE_NUMBER} "{FEATURE_DESCRIPTION}"` to create spec directory structure. Parse JSON output for SPEC_FILE, FEATURE_DIR, FEATURE_NUM. + +7. Load `.specify/templates/spec-template.md`. Write the specification to SPEC_FILE following the template structure. Focus on WHAT users need and WHY — avoid implementation details. Make informed guesses for unclear aspects, document assumptions, limit to max 3 `[NEEDS CLARIFICATION]` markers. + +8. Run auto-clarification loop: scan spec across 6 categories (Functional Scope, Data Model, UX Flow, Edge Cases, Non-Functional, External Integration). Generate max 5 questions for Partial/Missing categories. Present one question at a time, update spec inline after each answer. + +9. Generate quality validation checklist at `FEATURE_DIR/checklists/requirements.md`. + +10. Report completion with spec path, GitHub issue link, branch name, clarification summary, and suggest next step: run `/speckits-plan`. diff --git a/.agent/workflows/speckits-tasks.md b/.agent/workflows/speckits-tasks.md new file mode 100644 index 00000000..6c38147f --- /dev/null +++ b/.agent/workflows/speckits-tasks.md @@ -0,0 +1,35 @@ +--- +description: Generate an actionable, dependency-ordered tasks.md for the feature based on spec, plan, and design artifacts. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. + +2. Load design documents from FEATURE_DIR: + - **Required**: plan.md (tech stack, structure), spec.md (user stories with priorities) + - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions) + +3. Execute task generation: + - Extract tech stack and libraries from plan.md + - Extract user stories with priorities (P1, P2, P3) from spec.md + - If data-model.md exists: map entities to user stories + - If contracts/ exists: map endpoints to user stories + - Generate tasks organized by user story + - Validate task completeness (each user story independently testable) + +4. Generate tasks.md using `.specify/templates/tasks-template.md` structure. Every task MUST follow the format: `- [ ] T001 [P] [US1] Description with file path`. + +5. Organize by phases: + - **Phase 1**: Setup (project initialization) + - **Phase 2**: Foundational (blocking prerequisites) + - **Phase 3+**: One phase per user story in priority order. Within each: Types → Utils → API → Hooks → Components → Page + - **Final Phase**: Polish & cross-cutting concerns + +6. Project path conventions for this Vite + React SPA: + - `src/page/{PageName}/` — Pages with local components/ and hooks/ + - `src/components/{Component}/` — Reusable UI components + - `src/hooks/query/` — TanStack Query hooks, `src/hooks/mutations/` — Mutation hooks + - `src/apis/apis/` — API functions, `src/apis/requests/` + `responses/` — Types + - `src/util/`, `src/constants/`, `src/type/`, `src/repositories/` + - `src/mocks/handlers/` — MSW handlers + +7. Report: output path to tasks.md, total task count, count per user story, parallel opportunities, suggested MVP scope. Suggest next: `/speckits-analyze` or `/speckits-implement`. diff --git a/.agent/workflows/speckits-taskstoissues.md b/.agent/workflows/speckits-taskstoissues.md new file mode 100644 index 00000000..b1287021 --- /dev/null +++ b/.agent/workflows/speckits-taskstoissues.md @@ -0,0 +1,13 @@ +--- +description: Convert existing tasks from tasks.md into actionable, dependency-ordered GitHub issues for the feature. +--- + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS. All paths must be absolute. + +2. Extract the path to tasks.md from the script output. Load and parse all tasks. + +3. Get the Git remote: `git config --get remote.origin.url`. **ONLY proceed if the remote is a GitHub URL.** + +4. For each task in the list, create a GitHub issue in the repository matching the Git remote. Include task ID, description, dependencies, and phase information. + +**CAUTION**: Under no circumstances create issues in repositories that do not match the remote URL. diff --git a/.agents/skills/frontend-fundamentals/SKILL.md b/.agents/skills/frontend-fundamentals/SKILL.md new file mode 100644 index 00000000..864caa74 --- /dev/null +++ b/.agents/skills/frontend-fundamentals/SKILL.md @@ -0,0 +1,80 @@ +--- +name: frontend-fundamentals +description: | + 토스(Toss) Frontend Fundamentals 기반의 프론트엔드 개발 종합 가이드. 코드 품질(가독성, 예측 가능성, 응집도, 결합도), 번들링(Webpack, 트리셰이킹, 코드 스플리팅), 접근성(A11y, 스크린 리더, ARIA), 디버깅(진단, 재현, 수정, 재발 방지) 4개 도메인을 포괄한다. + + 반드시 이 스킬을 사용해야 하는 상황: + - 프론트엔드 코드 리뷰, 리팩토링, 코드 품질 개선 요청 시 + - React/TypeScript 컴포넌트의 가독성, 응집도, 결합도 관련 질문 시 + - Webpack, Rollup, Vite 등 번들링 설정, 트리셰이킹, 코드 스플리팅 질문 시 + - 웹 접근성(a11y), ARIA, 스크린 리더, 키보드 내비게이션 관련 질문 시 + - 프론트엔드 디버깅 전략, 에러 메시지 분석, 버그 재현/수정/방지 질문 시 + - "좋은 코드란?", "변경하기 쉬운 코드", "클린 코드" 등의 추상적 질문 시 + - 면접 준비에서 프론트엔드 기초 개념을 정리하고 싶을 때 + - 컴포넌트 분리 전략, Props Drilling, 매직 넘버, 삼항 연산자 등 구체적 패턴 질문 시 + - ESM vs CJS, sideEffects, 번들 분석, HMR, 소스맵 등 빌드 관련 질문 시 + - 버튼 안에 버튼, 테이블 행 클릭, 폼 접근성 등 UI 접근성 안티패턴 질문 시 +--- + +# Frontend Fundamentals 스킬 + +토스(Toss)의 **Frontend Fundamentals** 프로젝트에서 다루는 프론트엔드 핵심 지식을 종합한 스킬이다. 4개 도메인으로 구성되어 있으며, 각 도메인의 상세 내용은 `references/` 디렉토리의 개별 파일에서 확인한다. + +## 도메인 구조 + +### 1. 코드 품질 (Code Quality) +좋은 프론트엔드 코드 = **변경하기 쉬운 코드**. 4가지 기준으로 판단한다: +- **가독성**: 맥락 줄이기, 이름 붙이기, 위에서 아래로 읽히게 하기 +- **예측 가능성**: 이름 겹침 방지, 반환 타입 통일, 숨은 로직 드러내기 +- **응집도**: 함께 수정되는 코드를 가까이 두기, 매직 넘버 제거 +- **결합도**: 책임 분리, 중복 허용, Props Drilling 제거 + +→ 상세: `references/code-quality.md`를 읽어라 + +### 2. 번들링 (Bundling) +여러 파일을 하나로 묶어 웹 성능을 최적화하는 과정: +- **기본 개념**: 번들링이란, 번들러란 +- **Webpack 튜토리얼**: 첫 번들 → 모듈 → TS → React → 스타일 → 에셋 → 플러그인 → 개발 서버 +- **심화**: 진입점, 경로 탐색, 로더, 플러그인, 출력 +- **최적화**: 코드 스플리팅, 트리 셰이킹, 번들 분석 +- **개발 환경**: 개발 서버, HMR, 소스맵 + +→ 상세: `references/bundling.md`를 읽어라 + +### 3. 접근성 (A11y) +모든 사용자가 웹을 편리하게 이용하도록 돕는 기본 원칙: +- **핵심 3요소**: 역할(Role), 레이블(Label), 상태(State) +- **4가지 원칙**: 올바른 구조, 정확한 의미 전달, 예측 가능한 동작, 시각 정보 보완 +- **UI별 접근성**: 탭, 아코디언, 모달, 라디오, 체크박스, 스위치 +- **실전 가이드**: 버튼 중첩 금지, 테이블 행 클릭, 레이블 필수, 폼 감싸기 +- **심화**: ESLint 접근성 규칙, 디자인 시스템 결합 + +→ 상세: `references/a11y.md`를 읽어라 + +### 4. 디버깅 (Debug) +버그를 찾고 해결하는 체계적 4단계 프로세스: +- **진단하기**: 에러 메시지 분석, 작업 지도 그리기 +- **재현하기**: 간단하게 재현, 디버거/콘솔 활용, 경계값 테스트, 자동화, 경로 추적 +- **수정하기**: 근본 원인 수정, 순수 함수 분리, 데드코드 제거 +- **재발 방지**: 에러 로그, 버그 리포트, 팀 공유 및 공통 유틸 반영 + +→ 상세: `references/debugging.md`를 읽어라 + +## 사용 방법 + +1. 사용자의 질문이 어떤 도메인에 해당하는지 파악한다 +2. 해당 도메인의 reference 파일을 읽는다 +3. reference 파일의 원칙과 예제를 기반으로 구체적이고 실용적인 답변을 제공한다 +4. 코드 예시가 필요하면 Before/After 패턴으로 보여준다 +5. 여러 도메인이 겹치는 질문이면 관련 reference를 모두 참고한다 + +## 핵심 철학 + +- 4가지 기준(가독성, 예측 가능성, 응집도, 결합도)은 서로 상충할 수 있다 +- 상황에 따라 어떤 가치를 우선할지 깊이 고민해야 한다 +- 응집도를 높이면 가독성이 떨어질 수 있고, 중복을 허용하면 결합도는 낮아지지만 응집도가 떨어질 수 있다 +- "정답"보다는 "트레이드오프를 이해하고 맥락에 맞게 결정하는 것"이 중요하다 + +## 출처 + +모든 내용은 [Frontend Fundamentals](https://frontend-fundamentals.com) 프로젝트 기반이다. diff --git a/.agents/skills/frontend-fundamentals/references/a11y.md b/.agents/skills/frontend-fundamentals/references/a11y.md new file mode 100644 index 00000000..1d82f7b2 --- /dev/null +++ b/.agents/skills/frontend-fundamentals/references/a11y.md @@ -0,0 +1,221 @@ +# 접근성 (A11y) 상세 가이드 + +출처: https://frontend-fundamentals.com/a11y/ + +## 접근성이란 + +접근성(Accessibility, A11y)은 모든 사용자가 더 쉽고 편리하게 웹을 사용할 수 있도록 돕는 기본 원칙이다. 프론트엔드 개발자는 HTML 구조를 만들고 인터랙션을 정의하므로 **접근성의 출발점이자 핵심 역할**을 맡고 있다. + +--- + +## 스크린 리더의 3요소 + +스크린 리더는 화면 속 요소와 정보를 음성으로 전달하는 보조 기술이다. 3가지 핵심 정보를 읽는다: + +1. **역할(Role)**: 요소가 어떤 종류인지 (예: 버튼, 입력창, 스위치) +2. **레이블(Label)**: 컴포넌트의 이름, 어떤 기능인지 설명 +3. **상태(State)**: 현재 상태 (예: 활성화됨, 꺼짐, 선택됨) + +### 읽는 순서 예시 +```html +
+``` +스크린 리더가 읽는 순서: +1. "마케팅 알림" (레이블) +2. "체크상자" (역할) +3. "선택됨" (상태) +4. "설정을 끄거나 켜려면 이중탭 하십시오" (자동 설명) + +### 탭 목록 예시 +```tsx +
+ + +
+``` +스크린 리더: "메뉴, 탭그룹 → 첫번째 항목, 탭, 선택됨 → 두번째 항목, 탭" + +--- + +## 접근성 개발 입문: 역할, 레이블, 상태 + +### 역할 (Role) +HTML 시맨틱 태그를 사용하면 역할이 자동으로 부여된다: +- ` +``` + +방법 2: `aria-label` +```html + +``` + +방법 3: `aria-labelledby` +```html +

알림 설정

+
...
+``` + +### 상태 (State) +동적으로 변하는 요소의 현재 상태를 전달한다: +- `aria-checked`: 체크박스/라디오/스위치의 선택 여부 +- `aria-selected`: 탭/옵션의 선택 여부 +- `aria-expanded`: 아코디언/드롭다운의 펼침 여부 +- `aria-disabled`: 비활성화 여부 +- `aria-hidden`: 스크린 리더에서 숨김 여부 + +--- + +## 4가지 핵심 원칙 + +### 원칙 1: 올바른 구조 만들기 + +#### 버튼 안에 버튼 넣지 않기 +HTML 명세상 ` + +``` + +**해결**: 카드 전체를 `
`로 만들고 내부 버튼만 ` +``` + +**Good**: +```html + +``` + +#### 같은 이름의 요소에는 설명 추가하기 +여러 "더보기" 버튼이 있으면 어떤 "더보기"인지 구별할 수 없다. `aria-describedby` 또는 더 구체적인 `aria-label`을 사용한다. + +### 원칙 3: 예측 가능한 동작 만들기 + +#### 버튼의 역할과 동작이 일치하게 만들기 +`
`으로 버튼을 흉내 내면 안 된다. 키보드 이벤트(`Enter`, `Space`)가 작동하지 않고, 스크린 리더가 버튼으로 인식하지 못한다. + +**Bad**: +```html +
클릭
+``` + +**Good**: +```html + +``` + +#### 입력 요소는 `
`으로 감싸기 +`` 태그로 감싸면 Enter 키로 제출, 자동완성, 스크린 리더의 폼 모드 등이 자동으로 작동한다. + +### 원칙 4: 시각 정보 보완하기 + +#### 이미지와 아이콘에 대체 텍스트 제공하기 +- 정보를 전달하는 이미지: `alt` 텍스트 필수 +- 장식적 이미지: `alt=""` (빈 문자열) 또는 `aria-hidden="true"` +- 아이콘 버튼: `aria-label` 사용 + +```html + +2024년 매출 추이 그래프 + + + + + + +``` + +--- + +## UI 요소별 접근성 기초 + +### 탭 (Tab) +```tsx +
+ + +
+
일반 설정 내용
+``` +키보드: 좌우 화살표로 탭 이동, Enter/Space로 선택 + +### 아코디언 (Accordion) +```html +

+ +

+
내용
+``` + +### 모달 (Modal) +- `role="dialog"` 또는 `role="alertdialog"` +- `aria-modal="true"` +- 포커스 트랩: 모달 내부에서만 Tab 이동 +- ESC로 닫기 +- 열릴 때 첫 번째 포커스 가능 요소로 포커스 이동 +- 닫힐 때 트리거 요소로 포커스 복원 + +### 라디오 (Radio) +```html +
+
카드
+
계좌이체
+
+``` +키보드: 화살표로 이동, 선택과 포커스가 동시에 이동 + +### 체크박스 (Checkbox) +- `aria-checked`: `"true"`, `"false"`, `"mixed"` (부분 선택) +- Space로 토글 + +### 스위치 (Switch) +```html + +``` + +--- + +## 심화: ESLint로 접근성 개선하기 + +### 주요 규칙 +`eslint-plugin-jsx-a11y` 플러그인의 주요 규칙: +- `alt-text`: ``에 `alt` 속성 필수 +- `anchor-is-valid`: ``에 유효한 `href` 필수 +- `click-events-have-key-events`: `onClick`에 키보드 이벤트 동반 +- `no-static-element-interactions`: 비인터랙티브 요소에 이벤트 핸들러 금지 +- `label-has-associated-control`: `