# SOCAR FRAME 2.0 - llms-full.txt (2026-03-16)
# LLM이 바로 읽기 좋은 텍스트 덤프. 핵심 섹션만 유지하고 불필요한 포맷/코드 제거.

## 프로젝트 개요
- 웹 컴포넌트 라이브러리: `@socar-inc/socar-frame-components` (React 18, framer-motion, Tailwind 3.4.1)
- 디자인 토큰: `@socar-inc/socar-frame-foundation`
- 문서: Docusaurus + Storybook. 링크: https://monorepo-storybook.socar.me/socar-frame-components/prod/?path=/docs/guide--docs
- Figma: https://www.figma.com/design/9BojhdnvhQSi1wpWpLwPnH/SOCAR-FRAME-2.0-%EB%94%94%EC%9E%90%EC%9D%B8-%EC%8B%9C%EC%8A%A4%ED%85%9C-%EA%B0%9C%EC%84%A0-24~--
- Node 20+, React 17~18, Tailwind v3.4.1 고정, `tw-` 프리픽스 사용.

## 설치·환경
- 루트 공유 모듈 없음: `cd components && pnpm install`, `cd foundation && pnpm install`.
- 컴포넌트 패키지 설치: `pnpm add @socar-inc/socar-frame-components @socar-inc/socar-frame-foundation @socar-inc/utils`.
  - 글로벌 CSS 예시: tailwind base/components/utilities 뒤에 `@socar-inc/socar-frame-foundation/font.css`, `@socar-inc/socar-frame-components/css/styles.css`.
- 파운데이션 설치: `pnpm add @socar-inc/socar-frame-foundation`.
  - tailwind.config.js: `import { tailwindConfig } from '@socar-inc/socar-frame-foundation'; tailwindConfig.theme.extend = {...}; export default tailwindConfig;`
  - PostCSS v3 예시: tailwindcss + autoprefixer. Tailwind v4는 `export default { plugins: ['@tailwindcss/postcss'] }` 가능하나 아직 보장되지 않음.
  - CSS: `@import '@socar-inc/socar-frame-foundation/base.css'; @import '@socar-inc/socar-frame-foundation/font.css';` 토큰만 쓸 때는 `token.css` 추가.
- 1.0 병행 시: `@socar-inc/frontend-design-system`은 1.0.0 고정 후 Foundation 폰트/토큰을 추가 로드.

## 스크립트
- components: `pnpm build`(아이콘+lint+build+CSS), `pnpm lint`, `pnpm lint:fix`, `pnpm test`(Vitest), `pnpm storybook`.
- foundation: `pnpm build`, `pnpm lint`.
- 배포: `pnpm changeset`, `pnpm changeset:version`.

## 코드 컨벤션
- 모든 컴포넌트 `forwardRef`; props 타입은 `types.ts`. JSDoc 스타일 코멘트.
- import 순서: builtin -> external -> parent -> sibling -> type. `src/*` alias 금지.
- Tailwind 접두사 `tw-`; 복잡한 클래스 로직은 `getClassName.ts`로 분리. `use client`는 개별 컴포넌트 파일에서만.

## Foundation 요약
- Colors: 브랜드 팔레트는 ColorTable 참고.
- Spacing: token화된 간격; SpacingTable 참고.
- Typography: Pretendard, 사이즈/웨이트는 TypographyTable 참고.
- Icons: IconWall로 전체 미리보기.

## 컴포넌트 요약 (문서/스토리 기준)
- Buttons
  - ActionButton: 주 CTA. styleType fill|outlined, variant primary|secondary|tertiary|outline, size large|medium|small|xSmall, label optional, 좌/우 아이콘, gap, loading(클릭 차단+로더), disabled, haptic 기본 REGULAR(pointerup).
  - TextButton: 텍스트 중심 보조 액션. label/size 필수, variant primary|secondary|tertiary, underline 옵션, gap 기본 0, 약한 haptic.
  - IconButton: 아이콘 전용 버튼. icon prop 필수, size xLarge|large|medium|small|xSmall. 접근성 위해 aria-label 필요.
- Alert
  - GraphicSlot/Title/Body/ButtonSlot 조합. `Alert.PortalProvider` 필요. `Alert.open/close`, `onAction`으로 클릭 버튼 식별. `hapticConfig` 기본 ALERT_WARNING(mount/unmount).
- Badge
  - variant content|dot, size medium|small. content는 숫자/텍스트, dot는 children 래핑. `hasBorder`, `visible`, `className`, `style`.
- BottomSheet
  - detent: hidden/tip/half/max. 제어형 state+onChange 또는 defaultState. 옵션: dimmed(true), showHandlebar(true), withoutTip(false; half<->hidden만), half/max/tip 숫자/함수, maxType '86%'| 'topAppBar'([data-id="socar-frame-top-app-bar"] 기준), portalContainer, withShadow. Footer 있으면 hidden/max만.
- DatePicker
  - DateManager + useDateManager hook. 메서드: setMonthCount, setCustomLabel, setSelectableRange, setPastSelectionDisable, setHolidays, setManualDisabledDates, setMaxRangeDays, select/selects. 뷰: WeekGroup/Week/DayCell, DayOfWeek, Title. 라벨/비활성/최대 선택일, 스크롤 헤더 싱크, 뷰포트 스플릿 지원.
- TimePicker
  - 시/분 리스트 드래그 선택. 루트 props: isExpand 기본 true, isBlockingWhenAnimating 기본 false, onClickWhenCollapse, selectedItemClassName. List props: items hour|minute|string[], value, onChange, disabledItems, onDisabledSelect, onAnimateChange, isExpand, isBlockingWhenAnimating, selectedItemClassName, className.
- Snackbar
  - variant Basic|Overlay|Action. 필수: isVisible, handleVisibility, positionType top|bottom|center, uiType. hideAfter 기본 3000ms, hideWithDrag 기본 false, extraPosition, onHideEnd, className. Slots: Text, IconSlot, GraphicSlot, Button(클릭 시 자동 닫힘).
- Skeleton
  - shape rectangle|circle|capsule, size 또는 width/height, radius 기본 14(rectangle), isActive 기본 true, div props.
- Accordion
  - 섹션을 접고 펼치는 아코디언. useAccordion으로 상태 제어. options single|multiple, defaultOpenValues, openValues(controlled), onOpenChange. Trigger behavior auto|manual. manual이면 자동 토글 끄고 toggleItem 직접 호출. data-open으로 상태별 스타일 적용.
- Checkbox
  - 다중 선택 입력. CheckboxGroup으로 그룹 레이아웃. label, checked(제어), defaultChecked, disabled, onChange, name, value. 그룹 내 동일 name으로 묶어 폼 제출.
- Radio
  - 단일 선택 입력. RadioGroup으로 그룹 레이아웃. label, checked(제어), defaultChecked, disabled, onChange, name, value. 그룹 내 동일 name 사용 시 단일 선택 동작.
- SelectionBox
  - 카드형 선택 UI. SelectionBoxGroup과 함께 단일/다중 선택. selectionType single|multiple. 단일은 radio, 다중은 checkbox 동작. value/defaultValue로 제어/비제어 모드.
- Input
  - 단일 행 텍스트 입력. label, helperText, leading/trailing 슬롯, clearable(기본 true), formatter 지원. variant filled|outlined|underlined(기본 filled). isError, disabled, readOnly. 내장 포맷터: inputFormatters.phone/date/dateRange/sequence. 커스텀 포맷터: InputFormatter 타입. data-slot selector로 스타일 커스터마이징. React Hook Form 호환(register/Controller).
- TextArea
  - 여러 행 텍스트 입력. label, helperText, aside/trailing 슬롯, clearable(기본 false), formatter(Input과 동일 타입). resizeType fixed|flexible(기본 fixed). variant filled|outlined|underlined(기본 filled). disabled, readOnly. flexible이면 입력량에 따라 높이 자동 조절.
- Chip
  - Selection Chip. label/size 필수. size medium|small|xsmall. selected(외부 관리), disabled, leftIcon, rightIcon, role button|option(기본 button). hapticType 기본 REGULAR. disabled 외 강제 스타일 없이 className으로 확장. role=button이면 aria-pressed, role=option이면 aria-selected 자동 설정.
- Tabs 패밀리
  - Tab: 긴 컨텐츠용. type slide|anchor(default slide), size large|medium|small(default large), value 기본 0, onChange, slideAnimated 기본 true, $root(HTMLElement|null, anchor 모드 스크롤 루트), anchorOffset(기본 0, 활성화 기준선 px), scrollOffset(클릭 시 스크롤 목표 px), className. Slots: Header/HeaderItem(Number, Badge), Content/ContentItem(targetId), Content.dynamicHeight(탭별 높이 자동 조절), Indicator. $root는 useState 패턴으로 element 직접 전달.
  - SegmentedControl: 짧은 필터/뷰 전환. type slide|anchor(default slide), size default medium, value 제어 가능, onChange, $root/anchorOffset/scrollOffset(Tab과 동일), className. Slots 동일. button 타입은 Content 없이 Header만 사용.
- Tag
  - backgroundColor/textColor 필수(토큰 키), borderColor 옵션, size large|medium|small|xsmall, shape capsule|rectangle, leftIcon, width, children 문자열, div props.
- Tips
  - InfoTip: 포털로 띄우는 짧은 설명. 트리거/닫기 버튼으로 토글. infoTipOffset{ x,y }, maxWidth 320, zIndex 10, className. 방향 bottom 고정, tip 없음.
  - AccentTip: 온보딩 툴팁. AccentTipPortal/AccentTipStatic로 제공. size 필수, direction top|bottom|left|right, variant always|controlled|disappear, visible, disappearInterval 기본 2000, onVisibleChange, withShadow, zIndex. portal: tooltipOffset, triangleOffset, maxWidth 320, useOverflow, containerRef. static: offset, tipOffset, withTip.
- TopAppBar
  - 상단 바: LeftSideIconSlot, BasicBackButton, Title(type general|scroll), ScrollDetectTitle, TrailingButtonSlot(최대 3), LoadingBar(url 기반 fetch 감지, render-prop). data-id로 BottomSheet maxType="topAppBar"에서 높이 계산에 사용.
- Carousel Pattern
  - Pattern type="carousel" + CarouselEngine/useCarousel. 옵션: items[], loop, draggable, gap, autoPlay, autoPlayInterval 4000, defaultIndex, animation{duration,easing}, onIndexChange. 메서드: move, scrollTo, updateOptions, setItemsPreservePosition, on(event), syncPosition, destroy. 드래그/도트/버튼/autoPlay/루프/갭 커스터마이즈, data-carousel-role 셀렉터로 스타일링.
- Haptic 헬퍼
  - `haptic(feedback, interfaceType)`. 피드백: ALERT_WARNING, HAPTIC_UNSPECIFIED, REGULAR, STRONG, WEAK. 용도: WEAK(Text/IconButton), REGULAR(tertiary/outlined ActionButton), STRONG(primary/secondary), ALERT_WARNING(에러/경고).

## 구조·아키텍처
- Atomic Design: Foundation -> Component -> Organism -> Page.
- Portal 사용: Alert, BottomSheet, Tips 등이 루트 외부에 렌더링; 스택/ z-index 고려.
- Tailwind v4 미지원, v3.4.1 고정.

## 테스트·스토리북
- Vitest + Testing Library; 렌더 헬퍼 `components/setup/render`.
- Storybook 예제/문서는 `components/src/**/__spec__/*`에 위치.

## 문서 경로
- 개발 문서: `docs/docs/development/*` (foundation, components, haptic).
- 이 llms export는 `docs/static/` 루트에서 서빙되며 `/llms.txt`, `/llms-full.txt`, `/llms-changelog.txt`와 `/components/*` 경로로 접근할 수 있습니다.

## 기여 가이드
- props 변경 시 `types.ts`, stories, mdx, figma.tsx 동기화.
- import 순서 준수, `src/*` 절대경로 금지.
- PR 전 `pnpm lint`, `pnpm test`; 변경사항은 changeset 추가; UI/props 변경 시 Storybook 문서 갱신.