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

name, description, triggers, role

name	description	triggers	role
frontend	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.	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 前端 组件 页面 样式 按钮 表单 弹窗 模态框 输入框 导航 菜单 卡片 下拉 标签页 界面 交互 切图 响应式	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.

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:

## 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

## 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