---
name: velin-design-surface-roles
description: Assign VelinStyle surface/theme roles using existing tokens after reuse.
---
# Surface Roles

## Purpose
Maps sections to base/raised/overlay surface roles.

## Domain
B · category `design`

## Capabilities
- `build.theme`

## Permission
`write` · **requiresApproval: true**

## Allowed actions
- READ
- WRITE

## Forbidden actions
- APPLY
- ROLLBACK
- ACCEPT
- DEFER
- NOTE
- ACKNOWLEDGE
- CATALOG
- MANIFEST
- CLASSIFY
- invent-target

## Stop conditions
- SR-11

## Agent role / risk
Builder · risk `med`

## Reuse (mandatory before build)

Follow `velin-reuse-gate` (BP-R01…R04):

1. **SEARCH** existing VelinStyle skills, components/Web Components, utilities, tokens, and patterns.
2. **EXISTING?** If a fit exists, document it.
3. **COMPATIBLE?** If yes → **REUSE** (or EXTEND). If no → document the incompatibility.
4. **NEW** only with evidenced gap — never "create because needed".
5. Skipping reuse on non-greenfield work → **STOP** (SR-12).

## Workflow
1. SEARCH theme tokens and surface roles already in the project.
2. Map roles only to **existing** tokens (BP-T01). Never invent colors by "similarity".
3. After theme changes, recommend contrast check (BP-T02).

## Best practices
- BP-R01–R04, BP-T01, BP-T02, BP-B03

## Anti-patterns
- Nearest-color / lookalike token mapping (BP-T03 / SR-01/09).

## Inputs / Outputs
- Inputs: html, tokens
- Outputs: html, report