OpenSpec Project Walkthrough #5: UI Visual Polish and Template Tweaks to Guide AI‑Generated Tasks

UI Visual Polish

The previous UI used Tailwind’s default blue (#3B82F6), no icons, and minimal styling. The upgrade adds a brand‑specific blue‑violet palette, Lucide icons for each tool category, hover scale and shadow effects, staggered entrance animations, and a gradient header.

:root {
  /* brand colors */
  --color-primary-500: #8B5CF6;
  --color-primary-600: #7C3AED;
  --color-primary-700: #6D28D9;
  /* accent colors */
  --color-accent-500: #F59E0B;
}

Task Format Issue

Across the first four releases the generated tasks.md used the schema instruction format ### 任务 N：[组件名称] with a file list and a TDD five‑step structure, but the AI kept outputting the old template style ## 1. with checklist items, ignoring the required format.

## 1. 任务名称
- [x] 1.1 步骤描述
- [x] 1.2 步骤描述

Root‑Cause Analysis

OpenSpec reads two inputs when generating artifacts: a template (found under schemas/with-review/templates/) and an instruction (in schema.yaml). The LLM treats concrete template examples as higher‑priority cues, so it follows the template format even when the instruction demands a different one.

Template Refactor

Old template snippet:

## 1.
- [ ] 1.1 描述

Replaced with:

### 任务 1：<strong>涉及文件：</strong>
- 新建/修改：exact/path/to/file
- 测试：tests/exact/path/to/test
- [ ] 1.1 <strong>写失败测试</strong>
```bash
npm install lucide-react
```
- [ ] 1.2 <strong>更新 package.json 并验证 lockfile</strong>
```bash
cat package.json | grep lucide-react
```

Explore → Propose Workflow

The AI runs /opsx:explore to clarify requirements, then automatically creates a change and generates five artifacts without a separate /opsx:propose step.

AI: What's on your mind?
User: Upgrade UI visual polish, use brand colors, add icons, etc.
AI: Gap analysis …
User: Accept suggestions.
AI: Design doc generated.

Design Doc (Generated by AI)

## UI Visual Polish — Design Doc
### 1. 配色体系
品牌色：蓝紫 (Blue‑Violet)
Primary 500: #8B5CF6 …
### 2. 图标系统
Category Icons: 文本处理→Type, 数据转换→RefreshCw, 开发工具→Code2, 内容创作→Feather
Badge Icons: Beta→Beaker, Planned→ClipboardList
### 3. 动效
卡片 Hover: scale 1.02, shadow rgba(139,92,246,0.15), 200ms ease‑out
Stagger: fadeInUp 400ms …
### 4. Header
background: linear‑gradient(135deg, neutral‑50 → primary‑50)

Apply Phase

The AI executed 33 steps across 9 task groups. Three notable incidents were automatically detected and fixed:

Flask icon missing in lucide-react → switched to Beaker.

Accidental overwrite of index.css imports → restored.

NotFound page already used the CSS variable, so no code change was needed.

Task 1: npm install lucide-react + rebuild tokens.css primary palette
Task 4: Home.tsx stagger animation + hover effects
Task 9: All tests PASS + commit

Verification

Build output shows 1753 modules (up from 31 before adding Lucide) and successful Vite build. All 30 Vitest tests pass.

✓ src/router/index.test.tsx (3 tests) 2ms
✓ src/tool-registry/catalog.test.ts (7 tests) 7ms
…
30 passed (1.15s)

Before/after screenshots illustrate the visual change (home page, placeholder page, 404 page). The CSS variable system ensures the 404 page color updates automatically without code edits.

Archive & Git Push

Running /opsx:archive created a new spec file visual-identity/spec.md and moved the change to an archive folder. A subsequent /opsx:push updated the remote repository.

Archive Complete – specs synced to openspec/specs/visual-identity/spec.md
Pushed from 229e2a0 to 423723b, main branch updated.

Conclusions & Insights

Modifying the template successfully forced the AI to emit the desired task format, confirming that template priority outweighs instruction text. However, the strict TDD five‑step flow only applies to logic‑centric changes; visual updates tend to follow a simpler “code change → regression test” pattern.

For OpenSpec users encountering stubborn formatting, check the template files under openspec/schemas/<schema>/templates/ – adjusting the template fixes structural issues, while instruction edits affect content only.