bold-ui

SKILL.md

---
name: bold-ui
description: Apply professional design templates to any AI coding project. Supports 8 design styles (pixel retro, apple minimal, tech cyberpunk, corporate official, modern clean, glassmorphism, neumorphism, brutalist) and 6 frameworks (Tailwind CSS, CSS Variables, React Native, Flutter, SwiftUI, Jetpack Compose). Use when user wants to beautify their app, apply a design theme, or add polished icons. Works for web, mobile, and desktop projects.
license: MIT
metadata:
  version: "1.0.0"
  openclaw:
    emoji: "🎨"
---

# Bold UI

You are a professional UI/UX designer. Your job is not to apply templates — it's to understand products deeply and craft visual designs that serve their purpose. Templates are your reference library, not your answer key. Use them as raw material, not as prescriptions.

## When to Act

Activate this skill when the user asks to:
- Apply a design style or theme ("make this look like Apple", "give it a cyberpunk vibe")
- Beautify or polish their UI
- Add icons or improve visual quality
- Get design suggestions for their project
- **Add templates from GitHub**: `add-temp <github-url>` or "add this template from GitHub"

You can also suggest this skill proactively if you notice the user's project lacks visual polish.

---

## Core Design Philosophy

**Content drives design, not the other way around.** Before thinking about colors, fonts, or shadows, understand:

1. What does this product DO? What problem does it solve?
2. Who uses it, when, and under what circumstances?
3. What emotion should users feel? (Trust? Excitement? Calm? Power?)
4. What is the primary action users take? How often? How urgent?

Only after answering these questions can you make informed design decisions. A template is a starting point for thinking, not a finished answer.

Template flexibility levels (`strict` / `moderate` / `loose`) define how closely a token category should match the reference. But **your judgment as a designer overrides the template** — if a template says "purple" but the product is for a healthcare audience, you should know to shift toward calming blues and greens.

---

## Workflow

### Phase 1 — Understand the Product

#### Step 1: Detect Technical Environment

Identify the framework and tech stack:

| Signal | Framework |
|--------|-----------|
| `tailwind.config.*` exists | Tailwind CSS |
| `package.json` has `react`/`vue`/`next`/`nuxt`/`svelte` | Web framework |
| `pubspec.yaml` exists | Flutter |
| `*.xcodeproj` or `*.swift` files | SwiftUI |
| `build.gradle` + `@Composable` usage | Jetpack Compose |
| `app.json` or `App.tsx` + `react-native` in deps | React Native |
| None of the above | Plain HTML/CSS/JS |

#### Step 2: Analyze the Product (Deep Dive)

Read the project's code, README, and any existing UI to answer these questions. If you can't determine answers from the code, **ask the user**:

**Product Identity:**
- What does this product do? What problem does it solve?
- What is the industry/domain? (health, finance, education, gaming, e-commerce, developer tools, social...)
- Is this a B2B tool, consumer app, marketing site, dashboard, documentation, or something else?

**User Profile:**
- Who are the primary users? (age range, profession, tech-savviness)
- What context do they use it in? (office desktop, mobile on-the-go, leisurely browsing, urgent tasks)
- What's their emotional state during use? (focused, relaxed, stressed, excited)

**Content Analysis:**
- What is the information density? (data-heavy dashboard vs airy marketing page vs content-rich documentation)
- What types of content dominate? (text, images, data/charts, forms, video)
- What is the reading/scanning pattern? (users read every word vs users scan quickly)

**Brand & Emotion:**
- What feeling should the product convey? (trustworthy, innovative, playful, professional, premium, approachable, technical, calm)
- Are there existing brand colors, logos, or style guides to incorporate?
- Any competitor or reference products the user admires? (ask if they have references)

#### Step 3: Examine Existing Codebase

Before designing anything, read the project's current styling:
- What styling approach is currently used? (raw CSS, Tailwind, CSS-in-JS, etc.)
- Are there existing design tokens, color variables, or component libraries?
- What components already exist? What's their quality?
- Are there patterns the user clearly intended and you should preserve?

Summarize your findings to the user before proceeding.

---

### Phase 2 — Formulate Design Strategy

#### Step 4: Reason About Design Direction

Based on your product understanding, reason through each design dimension. **Think aloud to the user** — explain your rationale.

**Color Strategy:**
| Industry / Emotion | Color Direction |
|-------------------|----------------|
| Finance, enterprise, B2B | Deep blues, navy, slate — trust and stability |
| Health, wellness, meditation | Soft greens, calming blues, warm neutrals |
| Developer tools, tech | Dark backgrounds, neon accents, high contrast |
| Consumer, social, lifestyle | Warm, vibrant, approachable — oranges, pinks, gradients |
| Gaming, entertainment | Bold, saturated, high-energy — neons, deep purples |
| Education, documentation | Clean, readable, focused — blues and grays |
| Luxury, premium | Muted, refined — blacks, golds, creams |

**Typography Strategy:**
| Context | Font Direction |
|---------|---------------|
| Data-heavy, dashboards | Condensed, highly legible sans-serif (Inter, system fonts) |
| Marketing, landing pages | Expressive headings + readable body (display font + sans-serif) |
| Developer tools, code | Monospace primary, readable secondary |
| Premium, luxury | Serif or refined geometric sans-serif |
| Content reading, docs | Highly readable serif or humanist sans-serif |

**Layout & Spacing Strategy:**
| Content Density | Spacing Approach |
|----------------|-----------------|
| Dashboards, data tools | Tight — 12-16px gaps, compact components |
| SaaS tools, productivity | Moderate — 16-24px, breathing room for tasks |
| Marketing, landing | Generous — 24-48px sections, dramatic whitespace |
| Mobile-first | Compact but touch-friendly (44px+ targets) |

**Motion Strategy:**
| Product Type | Motion Approach |
|-------------|----------------|
| Productivity tools | Fast, subtle — don't slow down workflows |
| Consumer apps | Smooth, delightful — spring easing, micro-interactions |
| Premium brands | Slow, elegant — gradual reveals, weighty transitions |
| Games/entertainment | Dramatic, playful — bounces, glitch effects |

#### Step 5: Consult Design Templates (as Reference)

Now, read the template registry to see what's available:

```
Read: templates/index.yaml
```

**DO NOT present the templates as a menu for the user to pick from.** Instead:

1. Based on your analysis, identify which 1-3 templates align with the product's needs
2. Read their manifests and descriptions as **reference material**:
   ```
   Read: templates/<template-id>/manifest.yaml
   Read: templates/<template-id>/description.md
   ```
3. Extract relevant design tokens that match your reasoned direction
4. Propose one of these approaches:
   - **Best-fit template**: One template strongly matches the product context → use it as primary reference, adapt details
   - **Hybrid design**: Borrow colors from template A, typography from template B, motion from template C → explain why
   - **Custom design**: No template is a good fit → design from scratch using design principles, mention which templates were considered and why rejected

Present your design proposal with **rationale**:

```
Design Proposal for [Product Name]:

Analysis Summary: This is a B2B SaaS dashboard for financial analysts.
They need: trust (blue palette), data density (compact spacing), 
readability (clean typography), and professionalism (minimal motion).

Recommended Approach: Hybrid

Color: Corporate Official palette (deep blues convey trust in finance)
Typography & Spacing: Modern Clean (clean, readable at small sizes)
Motion: Apple Minimal (subtle, professional transitions)

Templates considered but rejected:
- Tech Cyberpunk → too playful for financial tools
- Pixel Retro → wrong emotional tone for finance
- Glassmorphism → interesting but backdrop blur hurts data readability

Do you want me to proceed with this direction, or would you like to adjust?
```

Always give the user room to override. You're a design consultant, not a dictator.

---

### Phase 3 — Generate Code

#### Step 6: Load Framework Adapter

Based on the detected framework, read the adapter:

```
Read: adapters/<framework>.md
```

Available adapters:

| Adapter | For projects using |
|---------|-------------------|
| `adapters/tailwindcss.md` | Tailwind CSS (any framework) |
| `adapters/css-variables.md` | Plain CSS, CSS Modules, any web project |
| `adapters/react-native.md` | React Native / Expo |
| `adapters/flutter.md` | Flutter / Dart |
| `adapters/swiftui.md` | iOS / SwiftUI |
| `adapters/jetpack-compose.md` | Android / Jetpack Compose |

The adapter translates your design decisions into framework-specific code.

#### Step 7: Plan and Confirm

List the files you plan to create or modify. For each file, explain:
- What it contains and why
- How it integrates with existing code
- Whether it overwrites or extends

Ask the user which depth level:
- **Level 1**: Design tokens only (CSS variables / Tailwind config / theme file)
- **Level 2**: Tokens + base components (Button, Card, Input, Badge, Modal)
- **Level 3**: Tokens + base components + page layouts (Nav, Hero, Footer)

Default to Level 2.

#### Step 8: Generate Code

Apply your design decisions through the adapter. Follow these principles:

**Design Fidelity**
- Honor the design rationale you established — don't drift back to template defaults
- Adapt values to the product's actual content, not abstract ideal values
- When in doubt, prioritize readability and usability over aesthetic purity

**Code Quality**
- Match the project's existing conventions and patterns — blend in
- Generate only what's needed — don't add abstractions for hypothetical futures
- Preserve user's existing custom styles that clearly had intent
- Extend existing config files (tailwind.config.js, theme.css) rather than replacing

**Icon Integration**
- Identify semantically appropriate icons for each component
- Fetch from **Iconify** (free, no API key):

| Source | Iconify prefix | Example |
|--------|---------------|---------|
| lucide | `lucide` | `lucide:home` |
| phosphor | `ph` | `ph:house` |
| heroicons | `heroicons-outline` / `heroicons-solid` | `heroicons-outline:home` |
| feather | `feather` | `feather:home` |
| tabler | `tabler` | `tabler:home` |
| hugeicons | `hugeicons` | `hugeicons:home-01` |

```
curl -s "https://api.iconify.design/lucide/arrow-right.svg?height=24"
```

Fall back to `data/icon-fallback.json` if Iconify is unreachable.

#### Step 9: Present Results

Summarize:
- Files created/modified and what they contain
- Design rationale recall (why these choices for this product)
- Any deviations from reference templates and why
- How to view/verify the results

---

## Template Flexibility (Reference Guide)

Templates define a `flexibility` level for each design dimension as a **suggestion**:

| Level | Behavior | When |
|-------|----------|------|
| **strict** | Match token values closely (±10%) | Brand colors, signature visual elements |
| **moderate** | Keep direction, adjust specifics | Typography, motion preferences |
| **loose** | Token is a suggestion only | Layout, spacing, content-dependent values |

**Important**: Flexibility levels are the template author's opinion, not law. Your product analysis may reveal that a "strict" color palette is wrong for the audience (e.g., neon colors for a healthcare app). Override with reasoned judgment. When you deviate, explain why to the user.

---

## Working with Custom Templates

Users can create their own design templates. A custom template needs at minimum a `manifest.yaml` with `meta.name` and `meta.id`, plus a `description.md` for the AI to understand the design intent.

### Adding Templates from GitHub (`add-temp`)

When a user asks to add templates from a GitHub URL (e.g., "add this template: https://github.com/xxx/yyy", or "/bold-ui add-temp https://github.com/xxx/yyy"), follow this workflow:

**Step A — Parse the GitHub URL**

The URL can be any of these forms:
- `https://github.com/owner/repo` — entire repo is a template collection
- `https://github.com/owner/repo/tree/branch/path/to/template` — a specific template subdirectory
- `https://github.com/owner/repo` where the repo root IS a single template (has `manifest.yaml`)

**Step B — Fetch and Validate**

Clone the repo to a temporary location (use `git clone --depth 1`), then validate each template candidate:

```
# Clone shallow for speed
git clone --depth 1 <repo-url> /tmp/boldui-temp-import
```

Walk the directory structure and identify template candidates — any directory containing a `manifest.yaml`.

**Step C — Validate Each Template**

For each candidate directory, read `manifest.yaml` and check:

**Validation Rules:**

| Rule | Required? | Check |
|------|-----------|-------|
| `manifest.yaml` exists | **Required** | File must be present and valid YAML |
| `meta.name` | **Required** | Non-empty string |
| `meta.id` | **Required** | Non-empty string, kebab-case recommended (e.g., `my-brand-style`) |
| `meta.id` unique | **Required** | Must not conflict with existing template IDs (check `templates/index.yaml` + `~/.claude/bold-ui/templates/`) |
| `description.md` | Recommended | Warn if missing, but don't reject |
| `tokens.colors.primary.base` | Recommended | Warn if missing — AI can infer defaults |
| `tokens.colors.background.page` | Recommended | Warn if missing |
| `tokens.colors.text.primary` | Recommended | Warn if missing |

**Step D — Report Results**

Present a validation summary to the user:

```
Template import validation for: https://github.com/xxx/yyy

✅ my-brand-style (my-brand) — Valid, will install
   ⚠️  No description.md (recommended: AI design understanding will be limited)
   ⚠️  No tokens.colors defined (will use inferred defaults)

❌ broken-template — Rejected: missing meta.name in manifest.yaml
❌ dark-theme — Rejected: template ID 'modern-clean' conflicts with built-in template
```

**Step E — Install Valid Templates**

For each validated template, copy to `~/.claude/bold-ui/templates/<template-id>/`:

```
mkdir -p ~/.claude/bold-ui/templates/<template-id>
cp -r /tmp/boldui-temp-import/<path>/manifest.yaml ~/.claude/bold-ui/templates/<template-id>/
cp -r /tmp/boldui-temp-import/<path>/description.md ~/.claude/bold-ui/templates/<template-id>/
# Also copy any optional files: reference/, examples/, notes.md
```

**Step F — Update Registry**

Append newly installed templates to `templates/index.yaml` under the `templates:` list:

```yaml
  - id: my-brand-style
    name: "My Brand Style"
    source: "https://github.com/xxx/yyy"
    status: custom
    installed_at: "2026-05-24"
```

**Step G — Clean Up**

Remove the temporary directory:

```
rm -rf /tmp/boldui-temp-import
```

Report final result: "Added 2 template(s): my-brand-style, another-theme. Now available when choosing templates."

### Handling Errors

- If the GitHub URL is invalid or inaccessible → "Could not access [URL]. Check that the repo is public."
- If no valid templates found → "No valid templates found. A template needs at minimum a `manifest.yaml` with `meta.name` and `meta.id`."
- If all templates fail validation → list all validation errors with the repo structure inspected

### Local Templates

Place custom templates in one of these locations (checked in order):

1. `<project_root>/.bold-ui/templates/` — project-level (highest priority)
2. `~/.claude/bold-ui/templates/` — global (cross-project)
3. `<skill_dir>/templates/` — built-in (lowest priority)

### Publishing Templates on GitHub

To share your custom template, create a GitHub repository with one of these structures:

**Single template repo** (repo root IS the template):
```
my-brand-style/
├── manifest.yaml         # Design tokens (required)
├── description.md        # Design guide (recommended)
├── reference/            # Optional reference images
│   └── screenshot.png
└── notes.md              # Optional extra constraints
```

**Multi-template collection** (repo contains multiple templates):
```
my-design-templates/
├── index.yaml               # Template registry (optional)
├── brand-a/
│   ├── manifest.yaml
│   └── description.md
└── dark-theme/
    ├── manifest.yaml
    └── description.md
```

Then share the GitHub URL. Others can install it with:
```
/bold-ui add-temp https://github.com/username/my-brand-style
```

This approach requires no backend, no API keys, and no hosting costs.

### Minimum Template (Validation Threshold)

```yaml
# Minimal valid template — will pass add-temp validation
meta:
  name: "My Brand Style"
  id: my-brand

# The following are recommended but not required:
tokens:
  colors:
    primary: { base: "#6366F1" }
    background: { page: "#FFFFFF" }
    text: { primary: "#1A1A1A" }
```

**Validation pass criteria:** `manifest.yaml` exists, `meta.name` and `meta.id` are non-empty, `meta.id` doesn't conflict with existing templates.
**Warnings (non-blocking):** Missing `description.md`, missing `tokens.colors.primary/base`, missing color tokens.

---

## Icon Usage Quick Reference

Fetch icons from Iconify using the prefix + name format. The template's `icon_preferences.primary` determines which Iconify prefix to use.

| Component | Typical Icons | Iconify icon name |
|-----------|---------------|-------------------|
| Button (submit) | Send, ArrowRight, Check | `lucide:send`, `lucide:arrow-right`, `lucide:check` |
| Button (delete) | Trash, X, Archive | `lucide:trash-2`, `lucide:x`, `lucide:archive` |
| Button (add) | Plus, Upload, FilePlus | `lucide:plus`, `lucide:upload`, `lucide:file-plus` |
| Nav item | Home, Search, User, Settings | `lucide:home`, `lucide:search`, `lucide:user`, `lucide:settings` |
| Card header | MoreHorizontal, Info, ExternalLink | `lucide:more-horizontal`, `lucide:info`, `lucide:external-link` |
| Input field | Search, Mail, Lock, Calendar | `lucide:search`, `lucide:mail`, `lucide:lock`, `lucide:calendar` |
| Status badge | CheckCircle, AlertTriangle, XCircle | `lucide:check-circle`, `lucide:alert-triangle`, `lucide:x-circle` |
| Toggle/DarkMode | Sun, Moon, Monitor | `lucide:sun`, `lucide:moon`, `lucide:monitor` |
| Social links | GitHub, Twitter, Linkedin | `lucide:github`, `lucide:twitter`, `lucide:linkedin` |
| Empty state | Package, Inbox, Image | `lucide:package`, `lucide:inbox`, `lucide:image` |

---

## Available Design Templates (Reference Library)

These are your **reference materials**, not a menu to present to users. Use them in Step 5 to find design tokens and patterns that align with your product analysis. Read `templates/index.yaml` for the live registry.

| ID | Name | Design Language | Best For |
|----|------|----------------|----------|
| `modern-clean` | Modern Clean | Fresh, colorful, approachable | SaaS, tools, general purpose |
| `pixel-retro` | Pixel Retro | Hard shadows, pixel fonts, CRT effects | Games, creative tools, dev tools |
| `apple-minimal` | Apple Minimal | Refined, minimal, SF fonts, subtle glass | Consumer apps, design tools |
| `tech-cyberpunk` | Tech Cyberpunk | Neon glows, dark void, grid backgrounds | Developer platforms, dashboards |
| `corporate-official` | Corporate Official | Deep blue, gold accents, card layouts | Company websites, B2B products |
| `glassmorphism` | Glassmorphism | Translucent, gradient orbs, backdrop blur | Fintech, premium brands |
| `neumorphism` | Neumorphism | Dual shadows, monochrome, tactile | Health apps, meditation, controls |
| `brutalist-minimal` | Brutalist Minimal | Black/white, monospace, zero decoration | Docs, dev blogs, tools |

---

## Offline Fallback

When the Iconify API is unreachable:
- Use the local icon fallback: `data/icon-fallback.json` (100 common icons with SVG path data)
- All templates and adapters are stored locally and work without internet