octopus-workflow/core/skills/frontend/SKILL.md

---
name: frontend
description: >
  Use ONLY when doing frontend development work — building or modifying UI
  components, pages, styles, and client-side interactions. Detects the
  project's framework and styling approach, then implements with a plan
  template, mandatory loading/empty/error/success state coverage, and an
  accessibility + self-check pass against core/checklists/frontend.md.
  For full pipeline features (a new page/route, ≥3 new components, new API
  contracts or a new data model, a new state-management pattern, or work
  spanning ≥5 files), use the `implement` skill and apply these templates
  within it.
triggers:
  # English — phrases + UI-element nouns (short nouns are safe here: they
  # rarely embed in non-frontend words, and the description gates false fires).
  - create component
  - build ui
  - implement frontend
  - add page
  - add screen
  - implement page
  - frontend
  - UI component
  - style this
  - add styles
  - make it responsive
  - component
  - button
  - modal
  - dropdown
  - tooltip
  - navbar
  - checkbox
  - toggle
  # Chinese — high-frequency bare nouns only. Because matching is substring,
  # a bare noun (组件) subsumes every verb-noun combo (写组件 / 做个组件 /
  # 创建组件 / 改组件), so listing phrases is redundant. Chinese substrings
  # do not collide with English words, so bare nouns are safe + maximal-recall.
  - 前端
  - 组件
  - 页面
  - 样式
  - 按钮
  - 表单
  - 弹窗
  - 模态框
  - 输入框
  - 导航
  - 菜单
  - 卡片
  - 下拉
  - 标签页
  - 界面
  - 交互
  - 切图
  - 响应式

role: Producer
---

# Frontend

Surgically implement frontend UI — components, pages, styles, and client-side
interactions — guided by framework conventions, with mandatory state-coverage
and accessibility checks before code review.

## Scope & Routing

This skill covers **standalone** frontend work: one or two components, a style
tweak, a single page or UI element. The user's description plus the existing
codebase is the specification.

Escalate to the `implement` skill (full pipeline: analyze-dag → review-dag →
implement → review-code → verify) when the work involves ANY of:

- ≥ 3 new components, or a new page/route
- new API contracts or a new data model
- a new state-management pattern
- ≥ 5 files changed

For pipeline work, still apply this skill's **Framework Detection**, **plan &
report templates**, and **self-check** within the `implement` workflow.

## Agent Role

Owned by the **Developer** (Worker). Responsibilities:

- Detect framework + styling from the existing code; match conventions exactly.
- Read ≥ 3 neighbor components before writing (brownfield).
- Implement all UI states: loading, empty, error, success, and edge cases.
- Ensure accessibility: semantic HTML, ARIA, keyboard nav, focus, contrast.
- Self-check against `core/checklists/frontend.md` before handoff.
- Write no more and no less than the scope — no opportunistic refactoring.

The Builder validates output and passes it to code review; it MUST NOT write
implementation code.

<!-- inject: ../_shared/large-prompts.md -->

> **Context compaction**: this skill is a pipeline stage boundary. The main
> session (orchestrator) compacts at this clean boundary ONLY when a
> capacity/projection trigger holds, per the L1 rule `core/rules/compact.md`
> §"Stage-boundary compaction" (long multi-stage runs — DAG Epic orchestration — keep the legacy
> every-boundary compaction; short runs — bugfix / DAG task — and standalone
> runs default to NOT compacting). The
> sub-agent this skill dispatches persists its artifacts to the Gitea wiki
> under `{slug}/` as it goes, so a mid-run compaction loses nothing — re-read
> the stage's wiki index to resume.

## Framework Detection

Before writing any code, detect the project's frontend framework:

| Signal                            | Framework  |
| --------------------------------- | ---------- |
| `package.json` has `react`        | React      |
| `package.json` has `vue`          | Vue        |
| `package.json` has `svelte`       | Svelte     |
| `package.json` has `solid-js`     | SolidJS    |
| `package.json` has `@angular/core`| Angular    |
| `.tsx`/`.jsx` files present       | React or SolidJS (check package.json) |
| `.vue` files present              | Vue        |
| `.svelte` files present           | Svelte     |

Detect the styling approach:

| Signal                                    | Approach          |
| ----------------------------------------- | ----------------- |
| `tailwind.config.*` or `postcss.config.*` with tailwind | Tailwind CSS      |
| `.module.css` or `.module.scss` files     | CSS Modules       |
| `styled-components` in package.json       | styled-components |
| `@emotion/*` in package.json              | Emotion           |
| `uno.config.*`                            | UnoCSS            |
| Plain `.css` or `.scss` imports           | Plain CSS/SCSS    |

Follow the detected convention exactly. Do NOT introduce a new styling
approach unless the work item explicitly requires it.

## Greenfield vs. Brownfield

**Greenfield** (new project): Create new files following the design. Use the
framework's standard conventions (`create-vite`, `create-next-app`, etc.) as
the baseline. Prefer functional components, TypeScript, and the framework's
current recommended patterns.

**Brownfield** (existing project + new UI):

- **Read neighbors first.** Before writing code, read at least 3 existing
  files in the same module (component files for UI work) to absorb the
  project's patterns: component structure, prop
  typing, styling approach, state management, and file organization.
  (Shared brownfield rule — canonical statement:
  `core/skills/review-code/SKILL.md` §"Greenfield vs. Brownfield".)
- Match existing conventions exactly: component declaration style, export
  pattern, file naming, directory structure, import ordering, and CSS
  organization.
- New code MUST follow existing conventions consistently — no style drift.
- No opportunistic refactoring of unrelated components. If you see a pattern
  violation, log it in the implementation report — do not fix it.

---

## Workflow

### Preconditions

- [ ] Task description exists (component name, props, behavior).
- [ ] Existing codebase is accessible for convention discovery.
- [ ] `core/checklists/frontend.md` is accessible.

If the task is vague ("make it look better"), ask for specifics:

1. What component/page needs work? (name or path)
2. What should it look like or do? (screenshot, description, or reference)
3. What states should it handle? (loading, empty, error, success)
4. Any accessibility requirements?

### Phase 1 — Parse Context

1. Detect framework and styling approach (see Framework Detection).
2. Read ≥ 3 neighbor components to absorb patterns.
3. Check existing tests — follow the same test pattern.
4. Check existing routes if adding a page.
5. Check design tokens (theme, spacing, palette) if the project has them.

### Phase 2 — Plan UI Implementation

Before writing code, produce a brief implementation plan:

```markdown
## Frontend Implementation Plan

**Component(s)**: {ComponentName} at {path}
**Framework**: {React / Vue / Svelte / SolidJS / Angular}
**Styling**: {Tailwind / CSS Modules / styled-components / plain CSS}
**State variants**: loading | empty | error | success | {edge case}

**Files to create**:
- `path/to/Component.tsx` — {purpose}

**Files to modify**:
- `path/to/existing.tsx` — {what changes, why}

**Component API**:
- Props: {prop}: {type} — {description}
- Events/Callbacks: {onX}: {signature} — {description}
- Slots/Children: {description if applicable}

**Accessibility checklist**:
- [ ] Semantic HTML elements used
- [ ] ARIA labels for icon-only buttons/images
- [ ] Keyboard navigation (Tab order, Enter/Space for actions)
- [ ] Focus management (auto-focus, focus trapping for modals)
- [ ] Color contrast ≥ 4.5:1 for text, ≥ 3:1 for large text
```

### Phase 3 — Implement

Implement in layers:

1. **Structure first** — scaffold the component with correct HTML semantics
   and prop types. No styling yet.
2. **Add styling** — apply styles following the project's convention. Handle
   responsive breakpoints if the design specifies them.
3. **Add state variants** — implement loading, empty, error, and edge case
   states before the happy path. This forces you to handle all conditions.
4. **Wire interactivity** — add event handlers, form validation, keyboard
   shortcuts, and focus management.
5. **Accessibility pass** — audit every interactive element for keyboard
   access, every image/icon for alt text, every form control for labels.

**Rules**:

- Use the project's existing component library (Kobalte, Radix, Headless UI,
  etc.) where applicable — do not reinvent accessible primitives.
- Every component MUST render gracefully in all four states: loading, empty,
  error, and success.
- If the project uses TypeScript, all props must be typed — no `any`.
- Image `alt` text must be meaningful, not decorative if the image conveys
  information.
- Form inputs must have associated `<label>` elements (not just placeholders).

### Phase 4 — Self-Check

Run the project's verification commands:

1. **Typecheck**: `bun typecheck` (or project equivalent). Fix all errors.
2. **Lint**: `bun oxlint --deny-warnings` (repo root; `bun lint` is the package-script alias). Fix all errors.
3. **Tests**: `bun run test:changed` (or project equivalent). All affected tests pass.

Then self-check against `core/checklists/frontend.md`:

- Verify every PRE item was satisfied before coding.
- Verify every POST item is satisfied now.
- For any failed item, fix before reporting.

### Phase 5 — Report

```markdown
## Frontend Implementation Report

**Component(s)**: {ComponentName}
**Framework**: {framework}
**Styling**: {approach}

### Files Changed

| File               | Action   | Purpose        |
| ------------------ | -------- | -------------- |
| `path/to/file.tsx` | created  | {purpose}      |
| `path/to/file.css` | created  | {purpose}      |

### State Coverage

| State   | Handled | How                              |
| ------- | ------- | -------------------------------- |
| loading | ✅      | Skeleton/spinner while fetching  |
| empty   | ✅      | "No items" message with CTA      |
| error   | ✅      | Error message with retry button  |
| success | ✅      | Renders data as designed         |

### Accessibility

| Check                       | Status | Notes          |
| --------------------------- | ------ | -------------- |
| Semantic HTML               | ✅     |                |
| Keyboard navigation         | ✅     |                |
| Focus management            | ✅     |                |
| Color contrast              | ✅     |                |
| Screen reader labels        | ✅     |                |

### Verification

- Typecheck: {pass / fail}
- Lint: {pass / fail}
- Tests: {N} passed, {M} failed

### Open Items

{anything incomplete with reason, or "None"}

---

**Handoff**: {if > 20 lines or ≥ 3 files → run review-code | else → complete}
```

### Phase 6 — Approval

Present the report to the user. Route to code review if > 20 lines or ≥ 3 files.

---

## References

- `core/checklists/frontend.md` — Frontend self-check checklist
- `core/skills/implement/SKILL.md` — General + pipeline implementation workflow
- `core/skills/review-code/SKILL.md` — Code review (next step)
- `<instance-root>/archive/skills/design/SKILL.md` — Design document production (legacy upstream, archived [org-internal #3072] phase 3)
- `core/skills/browser-debug/SKILL.md` — Interactive browser verification (invoke during Phase 3 / 4 for visual + interaction evidence)
- `core/rules/testing.md`, `core/rules/type-checking.md` — Repository conventions (test commands, typecheck)
- `core/rules/code-graph.md` — Code graph first
- `core/adapters/gitea/reading.md` — Read SDLC artifacts from wiki