Dress Before You Go: UI/UX Redesign of the OpenSpec Project

1. Explore – Auditing the Existing UI

The author opened the OpenSpec (v1.3.1) codebase built with React 19, TypeScript and Tailwind CSS v4 and listed nine visual problems, such as default gray colors, missing brand palette, no custom fonts, no design tokens, lack of dark mode, routing bugs that hide the navigation bar, and incorrect lang and title in index.html.

Problem List

Pure Tailwind default gray palette

No custom font

No CSS variables / design tokens

No dark mode

Tool routes missing <Layout> wrapper

No icon system

Mobile navigation not collapsible index.html uses lang="en" instead of zh-CN Page title lacks Chinese name

2. Design Direction – Color, Tokens, Font, Dark Mode

After the audit, three core decisions were made:

Brand colors: a cool blue‑purple palette with an amber accent, chosen over a warm orange scheme to match the AI‑tool platform identity.

Design tokens organization: the team debated Tailwind’s @theme directive versus standard CSS variables under :root. The final choice was :root variables for framework‑agnostic portability.

Font: a system‑font stack (

-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif

) was selected for zero network requests and fast first‑paint.

Dark mode was deliberately postponed because implementing a full light/dark token set would double the workload for only four pages.

3. Propose – Generating the Work Artifacts

The Propose stage produced five artifacts: proposal.md – explains why a UI redesign is needed and scopes the work. design.md – records the color tokens, font stack, spacing and radius definitions (77 lines of :root CSS variables). specs/ – placeholder for future specs. review.md – a five‑dimensional review that flagged missing visual‑test coverage. tasks.md – eight task groups with concrete file paths and expected code snippets.

4. Apply – Concrete Code Changes

The Apply step modified eight files (one new file) and imported the token file:

@import './theme/tokens.css';
@import "tailwindcss";

Key modifications include:

Replacing Tailwind gray classes in TopNav.tsx, Home.tsx, PlaceholderPage.tsx and NotFound.tsx with inline styles that reference var(--color-*) variables.

Fixing the routing bug by wrapping each toolRoute element with <Layout> via .map().

Updating index.html to lang="zh-CN" and changing the title to shuge AI Toolbox.

5. Verify – Consistency Checks and Pitfalls

The verification report initially showed all checks passed (34/34 tasks, 24 tests). However, two hidden issues emerged:

NotFound page not updated: the task checkbox was marked complete, but the source file still used the old Tailwind classes. The root cause was that the AI validated the tasks.md artifact instead of the actual source code.

Archive false success: the AI printed an "Archive Complete" message without moving files. Only after a manual ls check was the real archive performed.

These failures highlighted that visual changes lack automated test coverage for CSS, and that AI‑generated reports must be cross‑checked against the file system.

6. Lessons Learned

For visual changes, the Explore phase shifts from architectural questions to design decisions, but the workflow remains the same. design.md becomes a crucial single source of truth for colors, tokens and rationale, preventing scattered Tailwind classes.

Choosing :root variables over @theme offers future‑proof portability at the cost of more verbose inline styles.

Human verification is still required for style correctness and for confirming that AI‑reported artifacts reflect real file changes.

7. Next Steps

The design system is now in place, routing bugs are fixed, and the UI looks consistent. The next article will start adding actual AI tools on top of this refreshed UI.