# 시작하기 · 소개

기존 색상, 레이아웃과 상호작용을 유지하면서 UI에 은은한 하이라이트를 더하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/

<a id="one-shared-light"></a>

## 조금 더 생동감 있게.

같은 조명에 반응할 요소를 묶고, 그 안에서 하이라이트를 표시할 서피스를 선택하세요. 독립적으로 반응할 영역에는 별도의 조명을 사용하면 됩니다.

<a id="choose-your-framework"></a>

## Edge 시작하기

[설치](https://edge.bolerish.com/ko/docs/installation/)에서 패키지를 설치한 다음, [사용법](https://edge.bolerish.com/ko/docs/usage/)에서 기본 개념을 살펴보세요. [React](https://edge.bolerish.com/ko/docs/react/usage/)에는 컴포넌트 연결 방법이, [API 레퍼런스](https://edge.bolerish.com/ko/docs/react/api/)에는 옵션별 설명이 있습니다.

---

# 시작하기 · 설치

Edge를 설치하고 React에서 사용하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/installation/

<a id="installation"></a>

## 설치

React 어댑터는 React 18 또는 19가 필요합니다. 다른 프레임워크용 어댑터는 아직 제공하지 않습니다.

npm

```bash
npm install @bolerish/edge
```

pnpm

```bash
pnpm add @bolerish/edge
```

Yarn

```bash
yarn add @bolerish/edge
```

Bun

```bash
bun add @bolerish/edge
```

<a id="stylesheet"></a>

## 기본 스타일

React는 서피스를 연결할 때 기본 CSS를 자동으로 준비합니다. Edge.Provider 없이 훅만 사용할 때도 별도의 CSS 불러오기가 필요하지 않습니다. SSR에서는 애플리케이션 스타일 앞에 Edge.Styles를 문서당 한 번 렌더링하세요. CSP에서 nonce를 요구하면 서버와 하이드레이션에 같은 요청의 nonce를 전달하세요.

```tsx
<Edge.Styles nonce={nonce} />
```

```css
@import "@bolerish/edge/style.css";
```

기존 CSS 불러오기도 계속 지원합니다. 프레임워크 독립 사용을 위한 CSS 파일도 제공합니다. 직접 불러올 때는 애플리케이션·유틸리티 스타일보다 먼저 두세요. 리셋은 그보다 앞에 둘 수 있습니다. 패키지 경로로 CSS를 불러오려면 해당 경로를 해석하는 빌드 도구가 필요합니다.

<a id="next-steps"></a>

## Edge 시작하기

[사용법](https://edge.bolerish.com/ko/docs/usage/)에서 조명을 공유할 영역과 서피스를 정하고, [React](https://edge.bolerish.com/ko/docs/react/usage/)에 따라 연결하세요.

---

# 시작하기 · 사용법

컴포넌트를 연결하기 전에 조명과 서피스의 개념을 살펴보세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/usage/

<a id="share-one-light"></a>

## 영역 선택하기

하나의 조명은 함께 반응할 서피스들을 관리합니다. 섹션 전체나 일부 요소가 같은 조명을 공유하도록 구성할 수 있습니다.

서피스(surface)는 조명에 연결된 HTML 요소입니다. 연결한 서피스만 하이라이트를 표시합니다. 독립적으로 반응할 영역에는 별도의 조명을 사용하세요.

<a id="keep-your-styles"></a>

## 기존 UI 유지하기

Edge는 컴포넌트의 배경, 글자, 여백과 기본 테두리를 유지합니다. 하이라이트에는 각 서피스의 글자색과 border-radius를 사용합니다. 기존 상호작용과 키보드 포커스 표시도 유지하세요.

서피스의 반응은 [스타일](https://edge.bolerish.com/ko/docs/styles/)에서, 조명의 움직임은 [움직임](https://edge.bolerish.com/ko/docs/motion/)에서 선택할 수 있습니다.

input을 감싸는 방법과 기존 하이라이트와의 충돌은 [적용 시 고려사항](https://edge.bolerish.com/ko/docs/integration/#wrap-inputs-you-own)을 참고하세요.

애플리케이션에서 요소의 위치를 직접 바꾼다면 [레이아웃 변경](https://edge.bolerish.com/ko/docs/integration/#refresh-after-layout-changes)을 참고하세요.

<a id="connect-existing-components"></a>

## 프레임워크 선택하기

사용하는 프레임워크에 맞는 가이드를 확인하세요.

[

### React





](https://edge.bolerish.com/ko/docs/react/usage/)

---

# React · 사용법

기본적으로 Edge.Provider와 Edge.Surface를 사용하세요. 기존 컴포넌트에 직접 연결할 때는 useSurface를 사용할 수 있습니다.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/usage/

<a id="share-one-light"></a>

## 영역 연결하기

먼저 [설치](https://edge.bolerish.com/ko/docs/installation/)를 마치세요. 서버 컴포넌트를 사용하는 프레임워크에서는 `"use client"`를 선언한 클라이언트 모듈 안에서 Edge를 사용하세요.

조명을 공유할 영역을 `Edge.Provider`로 감싸고, 반응할 요소에만 `Edge.Surface`를 사용하세요. 아래 두 카드는 같은 조명에 반응합니다. Edge.Provider를 중첩하면 독립적인 조명이 만들어집니다.

기존 컴포넌트로 조명 공유하기

```tsx
<Edge.Provider>
  <Edge.Surface>Example card</Edge.Surface>
  <Edge.Surface>Another example card</Edge.Surface>
</Edge.Provider>
```

<a id="keep-your-styles"></a>

## 기존 스타일과 이벤트 유지하기

`as`로 렌더링할 HTML 태그를 선택하세요. 해당 요소의 HTML 속성, 이벤트, ref를 그대로 사용할 수 있고, `className`과 `style`으로 기존 스타일을 적용할 수 있습니다. Edge.Provider는 DOM 요소를 추가하지 않으며 각 Edge.Surface는 요소 하나를 렌더링합니다.

```tsx
<Edge.Surface as="button" type="button" onClick={handleExampleClick}>
  Example button
</Edge.Surface>
```

input 요소에는 래퍼가 필요합니다. 기존 하이라이트나 가상 요소와 충돌하면 [적용 시 고려사항](https://edge.bolerish.com/ko/docs/integration/)을 참고하세요. 스타일은 [스타일](https://edge.bolerish.com/ko/docs/styles/), 움직임은 [움직임](https://edge.bolerish.com/ko/docs/motion/)에서 설정할 수 있습니다.

<a id="connect-existing-components"></a>

## 기존 컴포넌트 연결하기

Card나 Button이 자체 HTML 요소를 렌더링하고 있다면 컴포넌트 안에서 [useSurface(options)](https://edge.bolerish.com/ko/docs/react/use-surface/#use-surface)을 호출하고, 반환된 ref를 해당 요소에 연결하세요. 컴포넌트는 Edge.Provider 안에 두면 됩니다. React 18의 함수 컴포넌트는 `forwardRef`로 ref를 전달해야 합니다.

위치가 바뀌는 경우에는 [레이아웃 갱신](https://edge.bolerish.com/ko/docs/integration/#refresh-after-layout-changes)을 참고하세요.

---

# React · Edge.Provider

하위 서피스가 공유할 조명 영역을 만듭니다.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/provider/

<a id="styles"></a>

## Edge.Styles

SSR 문서마다 애플리케이션 스타일 앞에 한 번 렌더링하세요. React는 서피스를 연결할 때 이 스타일을 재사용합니다. Edge를 사용하는 동안 이 컴포넌트를 유지하고, CSP에서 요구하면 nonce를 전달하세요. 이 컴포넌트나 명시적인 CSS 불러오기가 없으면 서피스를 연결할 때 클라이언트에서 기본 CSS를 추가합니다.

```tsx
<Edge.Styles nonce={nonce} />
```

| Prop / 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `nonce` | `string` | `undefined` | 스타일 요소에 전달할 요청별 nonce입니다. 서버와 하이드레이션에서 같은 값을 사용하세요. CSP가 nonce를 가진 인라인 스타일 요소만 허용한다면 필요합니다. |

<a id="lighting"></a>

## Edge.Provider

추가 DOM 요소 없이 하위 Edge.Surface가 같은 조명을 공유하도록 합니다. 중첩된 Edge.Provider는 독립적인 조명을 만듭니다.

```tsx
<Edge.Provider motion="system" range={480} intensity={0.75}>
  {/* Your surfaces */}
</Edge.Provider>
```

| Prop / 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `motion` | `'system' \| 'dynamic' \| 'static'` | `'system'` | system은 동작 줄이기와 입력 장치 설정을 따릅니다. dynamic은 동작 줄이기가 켜져 있어도 마우스나 펜을 따라갑니다. static은 고정 방향을 유지합니다. 터치하면 화면 기준 조명 위치를 갱신합니다. 스크롤하거나 손가락을 떼도 마지막 위치를 유지하고, 그 아래로 이동하는 서피스가 반응합니다. 다시 터치하면 위치를 갱신합니다. 터치 추적도 선택한 모션 모드를 따릅니다. static은 고정되고 system은 동작 줄이기가 켜져 있으면 고정됩니다. |
| `staticDirection` | `number \| 'random'` | `315` | 고정 조명의 방향을 도 단위로 지정합니다. random은 마운트할 때 공유 방향 하나를 선택하고 재렌더링 시에는 유지합니다. 숫자는 유한한 값이어야 합니다. |
| `direction` | `'toward' \| 'away'` | `'toward'` | toward는 하이라이트가 포인터를 향하게 하고, away는 방향을 180도 반전합니다. 모든 서피스 스타일이 이 선택을 유지합니다. 포인터를 따르는 조명에만 적용되며, 고정 조명은 staticDirection으로 방향을 정합니다. |
| `range` | `number` | `480` | 서피스 바깥에서 조명이 희미해지는 거리입니다. 동적 조명에만 적용되며, 뷰포트 기준 CSS 픽셀 단위의 유한한 양수를 지정하세요. |
| `intensity` | `number` | `0.75` | 공유 조명의 강도입니다. 0~1 사이의 유한한 값을 지정하세요. 범위를 벗어나거나 유한하지 않은 값은 RangeError를 발생시킵니다. |
| `children` | `ReactNode` | `Required` | 조명을 공유할 영역입니다. 일반 자식 요소는 그대로 유지되며, 명시적으로 연결한 서피스만 반응합니다. |
| `ref` | `Ref<Light>` | `Unset` | 조명 핸들을 받을 ref입니다. 핸들의 참조는 유지됩니다. 요소의 위치만 바뀐 경우 refresh()를 호출할 수 있습니다. |

포인터 입력은 문서 전체에서 받습니다. Edge.Provider는 입력 범위를 제한하는 대신 어떤 서피스가 반응할지 정합니다. 고정 조명에는 `staticDirection`이 적용되며, `motion="system"`이 동작 줄이기 설정을 따르는 경우에도 마찬가지입니다.

---

# React · Edge.Surface

DOM 요소에 조명 효과를 적용합니다.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/surface/

<a id="lighting-surface"></a>

## Edge.Surface

가장 가까운 Edge.Provider에 연결된 HTML 요소 하나를 렌더링합니다. `as`로 태그를 선택하면 해당 요소의 HTML 속성, 이벤트, ref를 사용할 수 있습니다.

```tsx
<Edge.Surface as="article" edgeStyle="raised">
  Your content
</Edge.Surface>
```

| Prop / 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | 하이라이트를 그릴 가상 요소입니다. 기존 ::after를 유지하려면 before를 선택하세요. 두 가상 요소를 모두 사용 중이거나 input 요소라면 바깥에 래퍼를 두세요. 잘못된 값은 RangeError를 발생시킵니다. |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | 테두리가 조명에 반응하는 방식입니다. 어떤 값을 선택해도 컴포넌트의 기존 스타일은 유지됩니다. |
| `color` | `string` | `currentColor` | 하이라이트 색상입니다. 기본값은 연결된 DOM 요소의 글자색입니다. CSS 변수를 포함한 모든 CSS 색상 문자열을 사용할 수 있습니다. |
| `shadowColor` | `string` | `#0008` | 조명 반대쪽 테두리의 색상입니다. CSS 색상 문자열을 사용할 수 있습니다. 밝은 서피스에서 이 그림자를 없애려면 transparent를 지정하세요. |
| `borderWidth` | `number` | `1` | 하이라이트의 두께를 픽셀 단위로 지정합니다. 실제 DOM 요소의 테두리는 바꾸지 않습니다. 음수는 0으로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다. |
| `intensity` | `number` | `1` | 공유 조명의 강도에 곱할 값입니다. 유한한 값은 0~1로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다. |
| `as` | `HTML tag name` | `'div'` | 렌더링할 HTML 태그입니다. 해당 요소의 HTML 속성과 ref를 사용할 수 있습니다. 커스텀 React 컴포넌트는 지정할 수 없습니다. |
| `children` | `ReactNode` | `Unset` | 렌더링하는 요소 안에 표시할 콘텐츠입니다. input처럼 가상 요소를 직접 표시할 수 없는 요소에는 래퍼를 사용하세요. |
| `ref` | `Ref<HTMLElement for the chosen tag>` | `Unset` | Edge의 등록용 ref와 함께 렌더링된 DOM 요소에 전달됩니다. React 19의 콜백 ref 클린업도 유지됩니다. |
| `className` | `string` | `Unset` | Edge의 하이라이트 클래스와 함께 적용할 클래스입니다. |
| `style` | `CSSProperties` | `Unset` | Edge의 스타일 뒤에 병합할 인라인 스타일입니다. 의도적으로 덮어쓰는 경우가 아니라면 Edge가 관리하는 CSS 변수는 유지하세요. |

`Edge.Surface`는 반드시 `Edge.Provider` 안에서 사용하세요. 밖에서 렌더링하면 오류가 발생합니다. input 요소에 적용하거나 기존 가상 요소와 충돌하는 경우에는 [적용 시 고려사항](https://edge.bolerish.com/ko/docs/integration/)을 참고하세요.

하이라이트는 DOM 요소의 테두리 바깥쪽에 맞춰 표시됩니다. 기존 컴포넌트가 렌더링하는 DOM 요소에 연결하려면 [useSurface](https://edge.bolerish.com/ko/docs/react/use-surface/#use-surface)를 사용하세요.

---

# React · useLight

조명 핸들을 만들고 설정합니다.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/use-light/

<a id="use-light"></a>

## useLight(options?)

Edge.Provider 없이 조명을 직접 관리할 때 사용할 `Light` 핸들을 반환합니다. 핸들의 참조는 유지되며, 옵션이 바뀌면 기존 조명이 갱신됩니다. 이 핸들을 `useSurface(light, options)`에 전달하세요. 일반적인 컴포넌트 트리에서는 `Edge.Provider`를 사용하면 됩니다.

```tsx
function useLight(options?: LightOptions): Light;
```

| Prop / 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `motion` | `'system' \| 'dynamic' \| 'static'` | `'system'` | system은 동작 줄이기와 입력 장치 설정을 따릅니다. dynamic은 동작 줄이기가 켜져 있어도 마우스나 펜을 따라갑니다. static은 고정 방향을 유지합니다. 터치하면 화면 기준 조명 위치를 갱신합니다. 스크롤하거나 손가락을 떼도 마지막 위치를 유지하고, 그 아래로 이동하는 서피스가 반응합니다. 다시 터치하면 위치를 갱신합니다. 터치 추적도 선택한 모션 모드를 따릅니다. static은 고정되고 system은 동작 줄이기가 켜져 있으면 고정됩니다. |
| `staticDirection` | `number \| 'random'` | `315` | 고정 조명의 방향을 도 단위로 지정합니다. random은 마운트할 때 공유 방향 하나를 선택하고 재렌더링 시에는 유지합니다. 숫자는 유한한 값이어야 합니다. |
| `direction` | `'toward' \| 'away'` | `'toward'` | toward는 하이라이트가 포인터를 향하게 하고, away는 방향을 180도 반전합니다. 모든 서피스 스타일이 이 선택을 유지합니다. 포인터를 따르는 조명에만 적용되며, 고정 조명은 staticDirection으로 방향을 정합니다. |
| `range` | `number` | `480` | 서피스 바깥에서 조명이 희미해지는 거리입니다. 동적 조명에만 적용되며, 뷰포트 기준 CSS 픽셀 단위의 유한한 양수를 지정하세요. |
| `intensity` | `number` | `0.75` | 공유 조명의 강도입니다. 0~1 사이의 유한한 값을 지정하세요. 범위를 벗어나거나 유한하지 않은 값은 RangeError를 발생시킵니다. |

`range`는 동적 조명에만 적용됩니다. 고정 조명은 거리에 따라 감쇠하지 않으며 `staticDirection`로 방향을 정합니다.

<a id="refresh"></a>

## light.refresh()

다음 프레임에서 서피스의 위치와 크기를 다시 측정합니다. 크기 변경 알림 없이 요소의 위치나 테두리 두께만 바뀌었다면 React가 변경을 반영한 뒤 호출하세요. 포인터가 멈춰 있어도 갱신됩니다.

```tsx
interface Light {
  refresh(): void;
}
```

크기 변경과 스크롤은 자동으로 감지합니다. 자세한 내용은 [레이아웃 갱신](https://edge.bolerish.com/ko/docs/integration/#refresh-after-layout-changes)을 참고하세요.

---

# React · useSurface

기존 DOM 요소를 조명에 연결할 ref를 반환합니다.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/use-surface/

<a id="use-surface"></a>

## useSurface(options?)

기존 HTML 요소를 가장 가까운 Edge.Provider에 연결하는 콜백 ref를 반환합니다. 테두리가 표시되는 요소에 ref를 연결하세요. 기존 `className`과 `style`은 그대로 사용할 수 있습니다.

```tsx
const ref = useSurface<HTMLElement>(options);
```

```tsx
function Area() {
  return <Edge.Provider><ExistingCard /><ExistingCard /></Edge.Provider>;
}

function ExistingCard() {
  const ref = useSurface<HTMLDivElement>();
  return <Card ref={ref}>Your existing component</Card>;
}
```

React 18의 함수 컴포넌트는 `forwardRef`를 사용해 ref를 HTML 요소로 전달해야 합니다. React 19에서는 ref를 prop으로 받을 수도 있습니다.

조명을 직접 지정하지 않으면 Edge.Provider가 필요합니다. 조명을 직접 관리할 때는 `useLight`가 반환한 핸들을 `useSurface(light, options)`에 전달하세요. 직접 지정한 조명이 Edge.Provider의 조명보다 우선합니다.

| Prop / 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | 하이라이트를 그릴 가상 요소입니다. 기존 ::after를 유지하려면 before를 선택하세요. 두 가상 요소를 모두 사용 중이거나 input 요소라면 바깥에 래퍼를 두세요. 잘못된 값은 RangeError를 발생시킵니다. |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | 테두리가 조명에 반응하는 방식입니다. 어떤 값을 선택해도 컴포넌트의 기존 스타일은 유지됩니다. |
| `color` | `string` | `currentColor` | 하이라이트 색상입니다. 기본값은 연결된 DOM 요소의 글자색입니다. CSS 변수를 포함한 모든 CSS 색상 문자열을 사용할 수 있습니다. |
| `shadowColor` | `string` | `#0008` | 조명 반대쪽 테두리의 색상입니다. CSS 색상 문자열을 사용할 수 있습니다. 밝은 서피스에서 이 그림자를 없애려면 transparent를 지정하세요. |
| `borderWidth` | `number` | `1` | 하이라이트의 두께를 픽셀 단위로 지정합니다. 실제 DOM 요소의 테두리는 바꾸지 않습니다. 음수는 0으로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다. |
| `intensity` | `number` | `1` | 공유 조명의 강도에 곱할 값입니다. 유한한 값은 0~1로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다. |

DOM 요소 하나에는 조명 하나만 연결할 수 있습니다. 크기가 다른 부모 요소에 ref를 연결하지 마세요.

옵션이 바뀌어도 요소는 교체되지 않습니다. 훅으로 연결한 하이라이트는 하이드레이션 이후에 적용됩니다. 서버 HTML에도 관련 클래스와 CSS 변수를 포함하려면 `Edge.Surface`를 사용하세요.

---

# 스타일 · 스타일

기존 스타일을 유지하면서 서피스가 조명에 반응하는 방식을 선택하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/styles/

<a id="compare-styles"></a>

## 테두리 반응 비교하기

스타일을 선택하고 카드 주변에서 포인터를 움직여 보세요. 선택한 설정은 이 사이트의 카드, 코드 블록과 내비게이션 요소에도 적용됩니다.

테두리 스타일 비교

```tsx
const light = useLight();
const surface = useSurface(light, { edgeStyle: "raised" });

<Card ref={surface}>
  Your component
</Card>
```

<a id="options"></a>

## 스타일 값

| 값 | 동작 |
| --- | --- |
| `raised` | 조명을 향한 테두리에 하이라이트를 표시합니다. 기본값입니다. |
| `recessed` | 하이라이트를 장식 테두리 두께만큼 안쪽에 그립니다. 선택한 조명 방향은 유지합니다. |
| `matte` | 테두리 반응을 부드럽게 표현합니다. |

추가 옵션은 [API 레퍼런스](https://edge.bolerish.com/ko/docs/react/surface/#lighting-surface)를 참고하세요.

<a id="raised"></a>

## Raised

바깥으로 도드라지는 테두리를 표현하려면 `edgeStyle: 'raised'`를 사용하세요.

<a id="recessed"></a>

## Recessed

input 래퍼처럼 하이라이트를 장식 테두리 두께만큼 안쪽에 그리려면 `edgeStyle: 'recessed'`를 사용하세요. 선택한 조명 방향은 유지합니다.

<a id="matte"></a>

## Matte

더 부드럽고 은은한 테두리를 원하면 `edgeStyle: 'matte'`를 사용하세요.

<a id="customize-the-highlight"></a>

## 하이라이트 조정하기

서피스는 중첩 여부와 관계없이 자신의 글자색을 사용하며, 연결된 DOM 요소의 border-radius를 따릅니다. `color`로 하이라이트 색상을 바꾸고, `intensity`로 공유 조명의 강도를 조절할 수 있습니다. 반대쪽 테두리의 그림자를 없애려면 `shadowColor="transparent"`를 사용하세요. `borderWidth`는 하이라이트의 두께만 바꾸며 실제 테두리에는 영향을 주지 않습니다. 이 옵션들은 [Edge.Surface](https://edge.bolerish.com/ko/docs/react/surface/#lighting-surface)에 전달하면 됩니다. CSS 변수를 따로 선언할 필요는 없습니다.

이 효과는 좌표축에 정렬된 직사각형을 기준으로 조명 방향을 근사합니다. 물리적으로 정확한 점광원을 재현하지는 않습니다. 서피스 중심부에서는 크기에 비례한 영역에 걸쳐 하이라이트 강도가 줄어듭니다.

기존 가상 요소와 함께 사용하거나 input을 감싸는 경우에는 [적용 시 고려사항](https://edge.bolerish.com/ko/docs/integration/)을 참고하세요.

---

# 스타일 · 움직임

공유 조명이 포인터를 따라갈지 고정 방향을 유지할지 선택하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/motion/

<a id="choose-an-input-mode"></a>

## 움직임 방식 선택하기

`system`을 사용하면 동작 줄이기 설정을 따릅니다. 터치하면 화면 기준 조명 위치를 갱신합니다. 스크롤하거나 손가락을 떼도 마지막 위치를 유지하고, 그 아래로 이동하는 서피스가 반응합니다. 다시 터치하면 위치를 갱신합니다. `dynamic`은 동작 줄이기 설정을 무시하므로 사용자가 직접 선택할 수 있게 제공하세요. 자세한 내용은 [움직임](https://edge.bolerish.com/ko/docs/motion/)을 참고하세요.

<a id="compare-motion"></a>

## 움직임 방식 선택하기

아래에서 각 모드를 사용해 보세요. 선택한 설정은 예제 카드를 포함한 사이트 전체의 공유 조명에 적용됩니다.

움직임 비교하기

```tsx
const light = useLight({ motion: "dynamic" });
const surface = useSurface(light, { edgeStyle: "raised" });

<Card ref={surface}>
  Your component
</Card>
```

<a id="pointer-lighting"></a>

## 포인터 조명

toward는 포인터 쪽, away는 반대쪽 테두리를 강조합니다. range는 서피스 바깥에서 조명이 사라지는 거리입니다. 예를 들어 range: 40이면 포인터가 카드 바깥으로 40 CSS 픽셀 이상 떨어졌을 때 효과가 사라집니다. 마우스 주위 40픽셀만 밝히는 설정은 아닙니다. 포인터를 카드 바깥으로 옮겨 값을 비교해 보세요. 고정 조명에는 적용되지 않습니다.

포인터 조명

```tsx
const light = useLight({ motion: 'dynamic', direction: "toward", range: 480 });
```

<a id="options"></a>

## 움직임 값

| 값 | 동작 |
| --- | --- |
| `system` | 동작 줄이기와 입력 환경 설정을 따릅니다. 라이브러리 기본값입니다. |
| `dynamic` | 동작 줄이기가 켜져 있어도 마우스·펜 입력이나 터치 접촉을 따라갑니다. |
| `static` | 고정 방향을 유지하며 포인터 움직임을 무시합니다. |

추가 옵션은 [API 레퍼런스](https://edge.bolerish.com/ko/docs/react/provider/#lighting)를 참고하세요.

<a id="system"></a>

## System

정밀한 호버 장치가 없으면 고정 조명으로 시작합니다. 동작 줄이기가 꺼져 있으면 마우스나 펜 입력으로 추적을 시작할 수 있습니다. 터치하면 화면 기준 조명 위치를 갱신합니다. 스크롤하거나 손가락을 떼도 마지막 위치를 유지하고, 그 아래로 이동하는 서피스가 반응합니다. 다시 터치하면 위치를 갱신합니다.

<a id="dynamic"></a>

## Dynamic

이 모드는 동작 줄이기를 무시하므로 사용자가 명시적으로 선택하게 하세요. 마우스·펜 입력이나 터치 접촉이 들어오기 전에는 효과가 숨겨집니다.

<a id="static"></a>

## Static

`staticDirection`에 유한한 각도 또는 `"random"`을 지정하세요. 예제에서는 0°, 90°, 180°, 270°, 315°를 선택할 수 있습니다. random은 마운트할 때 공유 방향 하나를 고르고, 재렌더링이나 스타일 변경 시에는 유지합니다. 새 방향을 고르려면 다시 마운트하세요.

Static

```tsx
const light = useLight({ motion: 'static', staticDirection: "random" });
```

<a id="accessibility"></a>

## 사용자 설정 존중하기

포커스, 선택 상태, 유효성 검사 결과는 조명 없이도 알아볼 수 있어야 합니다. 입력 방식과 강제 색상 모드에서의 동작은 [접근성](https://edge.bolerish.com/ko/docs/integration/#preserve-native-interactions)을 참고하세요.

---

# 가이드 · 적용 시 고려사항

기존 가상 요소, input 요소, 레이아웃 변경과 함께 사용하는 방법을 확인하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/integration/

<a id="choose-an-input-mode"></a>

## 움직임 방식 선택하기

system은 동작 줄이기와 입력 장치 설정을 따릅니다. dynamic은 동작 줄이기가 켜져 있어도 마우스나 펜을 따라갑니다. static은 고정 방향을 유지합니다. 터치하면 화면 기준 조명 위치를 갱신합니다. 스크롤하거나 손가락을 떼도 마지막 위치를 유지하고, 그 아래로 이동하는 서피스가 반응합니다. 다시 터치하면 위치를 갱신합니다. 터치 추적도 선택한 모션 모드를 따릅니다. static은 고정되고 system은 동작 줄이기가 켜져 있으면 고정됩니다.

<a id="understand-rendering-cost"></a>

## 렌더링 비용 이해하기

각 조명은 한 번에 프레임 하나만 예약합니다. 스타일을 쓰기 전에 위치와 크기를 읽고, 결과가 같으면 다시 쓰지 않습니다. 다만 그라데이션 변경에는 브라우저의 렌더링 작업이 필요하므로 특정 프레임 속도나 배터리 사용량을 보장하지는 않습니다.

<a id="preserve-native-interactions"></a>

## 기존 상호작용 유지하기

레이블, 텍스트 대비, 기본 테두리와 키보드 포커스 표시를 유지하세요. 하이라이트는 포인터 이벤트를 가로채지 않습니다. 입력값, 선택 상태, 키보드 처리와 포털은 기존 방식대로 관리할 수 있습니다.

강제 색상 모드에서는 하이라이트가 숨겨집니다. 선택 상태, 유효성 검사 결과, 사용 가능 여부는 하이라이트 없이도 알아볼 수 있어야 합니다.

<a id="existing-decorations"></a>

## 기존 가상 요소와 함께 사용하기

Edge는 기본적으로 `::after`에 하이라이트를 그립니다. 이미 사용 중인 `::after`를 유지하려면 `pseudoElement: 'before'`를 설정하세요. 두 가상 요소를 모두 사용하고 있다면 바깥에 래퍼를 두고 적용하세요.

기존 가상 요소 유지하기

```tsx
import { Edge } from '@bolerish/edge';

<Edge.Provider>
  <Edge.Surface as="article" pseudoElement="before" className="existing-after">
    Your existing ::after stays intact.
  </Edge.Surface>
</Edge.Provider>
```

<a id="wrap-inputs-you-own"></a>

## input 요소 감싸기

input 요소에서는 가상 요소를 안정적으로 표시할 수 없습니다. 대신 바깥의 `label`이나 `div`에 연결하고 border-radius를 맞추세요. input의 레이블, 포커스, 유효성 검사와 키보드 동작은 유지하세요. 안쪽으로 들어간 느낌을 주려면 `recessed`를 사용하면 됩니다.

<a id="refresh-after-layout-changes"></a>

## 레이아웃 변경 후 갱신하기

크기 변경, 중첩 스크롤, 뷰포트 크기 변경, 폰트와 리소스 로딩은 자동으로 감지해 위치와 크기 정보를 갱신합니다. 크기 변경 알림 없이 요소의 위치나 테두리 두께만 바뀐 경우에는 새 레이아웃이 반영된 뒤 `light.refresh()`를 호출하세요. 포인터가 멈춰 있어도 갱신됩니다.

React에서 호출하는 방법은 [light.refresh()](https://edge.bolerish.com/ko/docs/react/use-light/#refresh)를 참고하세요.

<a id="geometry-limits"></a>

## 지원하는 도형과 문서 범위

Edge는 좌표축에 정렬된 직사각형을 기준으로 동작합니다. 회전, 원근 변환과 다른 문서로 연결되는 포털은 지원하지 않습니다. 같은 문서 안의 포털은 조명을 공유할 수 있습니다. 포커스, 선택 상태, 유효성 검사는 [접근성](https://edge.bolerish.com/ko/docs/integration/#preserve-native-interactions)을 참고하세요.

---

# 가이드 · AI 연동

AI로 UI를 수정하기 전에 Edge 문서를 읽도록 요청하세요.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/ai-integration/

<a id="llms-txt"></a>

## 문서 읽기

[llms.txt](https://edge.bolerish.com/ko/llms.txt)에는 가이드와 API 레퍼런스의 Markdown 링크가 모여 있습니다. AI가 전체 문서를 참고해야 한다면 [llms-full.txt](https://edge.bolerish.com/ko/llms-full.txt)를 제공하세요.

이 파일은 사이트와 같은 콘텐츠에서 생성되며 대상 패키지 버전을 명시합니다. 파일을 공개한다고 도우미가 자동으로 읽는 것은 아니므로 요청에 URL을 포함하세요.

<a id="prompt"></a>

## 프롬프트 작성

수정할 컴포넌트 코드를 붙여 넣고, 어떤 요소에 효과를 적용할지 알려주세요. 아래처럼 요청할 수 있습니다.

```text
Read https://edge.bolerish.com/llms.txt and follow the relevant Markdown links.
Check the installed @bolerish/edge version and its types before choosing APIs.
Add Edge to the component below, preserving its markup, colors and interactions.
Connect only the surfaces I specify. Keep native controls and focus indicators.
Use the library's default motion="system" unless I ask for another mode.
```

<a id="installed-version"></a>

## 설치된 버전 확인하기

package.json이나 lockfile에서 설치된 버전을 확인하세요. 웹 문서는 더 최신 버전을 설명할 수 있습니다. 버전이 다르면 설치된 패키지의 타입 선언과 해당 버전의 문서를 기준으로 삼으세요. 예제에 맞추려고 의존성을 업데이트할 필요는 없습니다.