---
{"id":"text-input","title":"텍스트 입력·텍스트 영역","category":"컴포넌트","order":32,"summary":"자유로운 한 줄·여러 줄 데이터 입력의 사용·상태·접근성 계약.","status":"문서 기준 · UI 미검증","references":["components/text-input/usage"]}
---

# 텍스트 입력·텍스트 영역

## 목적과 사용

자유로운 한 줄·여러 줄 데이터 입력에 사용합니다. 선택 가능한 값이 정해져 있다면 선택 컨트롤을 검토합니다.

## 구성과 변형

영구 라벨, 입력, 도움말, 오류, 선택적 글자 수. 변형의 외형은 각 제품의 기존 [토큰](tokens.md)을 사용합니다. Carbon의 크기·색·모서리·아이콘을 가져오지 않습니다.

## 동작 규칙

- TXT-01 MUST: placeholder와 라벨을 구분합니다.
- TXT-02 MUST: 입력 길이·형식의 서버 제한과 브라우저 안내를 맞춥니다.
- TXT-03 MUST: 실패 후 비밀값을 제외한 유효한 입력을 보존합니다.
- TXT-04 SHOULD: 긴 본문·공개 키에는 textarea와 적절한 줄바꿈·높이를 사용합니다.

## 접근성

label for/id, aria-invalid, aria-describedby를 연결합니다. 비밀번호 붙여넣기를 차단하지 않습니다. 공통 [접근성 기준](accessibility.md)도 함께 적용합니다.

## 콘텐츠 예시

좋음: ‘서버 이름 — 최대 40자’처럼 실제 제한을 안내 / 피함: placeholder만 있는 필드.

## 우리 구현과 연결

VPS 공개 키 제한은 vps-forms 문서와 입력/모델 검증을 함께 봅니다. 40자 이름·10,000자 키는 SSH 키 문맥에만 해당합니다.

제품별 소유 경로는 [WICKEDVPS](product-vps.md), [Panel](product-panel.md), [Blesta](product-blesta.md)와 [소스 근거](source-evidence.md)를 확인합니다. 코드 존재와 모든 사용처의 준수는 다르며, 별도 표시가 없는 제품별 준수 상태는 미검증입니다.

## 코드 계약 예시

다음은 의미 구조 설명용이며 운영 API에 연결된 완성 구현이 아닙니다.

```html
<label for="server-name">서버 이름</label>
<input id="server-name" name="name" aria-describedby="name-error" aria-invalid="true">
<p id="name-error">서버 이름을 입력해 주세요.</p>
```

## 상태와 검증

빈 값·경계 길이·한글 조합 중·서버 오류·수정 후 재제출을 확인합니다.

일반·hover·focus·실행 중·실패·성공·disabled·read-only 중 해당하는 상태를 기록합니다. 해당하지 않는 상태를 임의로 만들지 말고 이유를 남깁니다. [검증 체크리스트](testing.md)에 증거를 연결합니다.