Skip to content

docs: add workspaces product area #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
srosenbauer merged 4 commits into from
Mar 16, 2026
Merged

docs: add workspaces product area #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e2e4303
docs: add workspaces product area document
zrosenbauer Mar 16, 2026
1c54b40
docs: improve workspaces overview and faq clarity
zrosenbauer Mar 16, 2026
91ece6c
docs: update workspace svg with correct cli api and joggr.gg urls
zrosenbauer Mar 16, 2026
aff0a61
docs: add product-area skill for creating new product areas
zrosenbauer Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions .claude/skills/product-area/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
name: Product Area
description: This skill should be used when the user asks to "add a product area", "create a product area", "new product area", "add area to docs", "create area page", or mentions adding a new area to docs/areas/. Creates the area markdown document with SVG banner and registers the area in project configuration if it does not already exist.
---

# Product Area Creation

Create new product-area documents in `docs/areas/` with an SVG banner, shields.io badge, and project configuration registration. Each product area represents a top-level category of product functionality (e.g., Workspaces, Coding Standards, Developer Tools).

## Workflow

### Step 1: Load Existing Product Areas

Read `scripts/conf/project.json` and extract the `Product Area` field options to get the current list of registered areas. Also read `scripts/lib/product-area-colors.ts` to get the `PRODUCT_AREA_COLORS` map and `PRODUCT_AREAS` record.

### Step 2: Gather Information

Collect the following from the user:

| Field | Required | Notes |
| --- | --- | --- |
| Area Title | Yes | Human-readable name (e.g., "Workspaces") |
| Emoji | Yes | Single emoji for the area identifier |
| Description | Yes | One-sentence description of the area |
| Color | Yes | One of the `PRODUCT_AREA_COLORS` keys (BLUE, CYAN, PURPLE, GREEN, ORANGE, PINK, GRAY, YELLOW, RED) |
| Overview | Yes | 1-2 paragraphs for the Overview section |
| Features | Recommended | Feature list, optionally grouped by category |
| FAQ | Optional | Question-and-answer pairs |

Ask the user for any missing fields. Present the available colors from `PRODUCT_AREA_COLORS` as options.

### Step 3: Check if Area Exists in Project Config

Derive the area identifier as `<emoji> <kebab-case-label>` (e.g., `🔧 agent-setup`). Search the `Product Area` options in `scripts/conf/project.json` for a match.

- If the area already exists, skip to Step 5
- If the area does not exist, proceed to Step 4

### Step 4: Register the Product Area

When the area is new, update three files:

**4a. Update `scripts/conf/project.json`**

Add a new entry to the `fields[].options` array for the `Product Area` field:

```json
{
"name": "<emoji> <kebab-case-label>",
"description": "<description>",
"color": "<COLOR_NAME>"
}
```

**4b. Update `scripts/lib/product-area-colors.ts`**

Add a new entry to the `PRODUCT_AREAS` record:

```typescript
"<emoji> <kebab-case-label>": {
name: "<emoji> <kebab-case-label>",
emoji: "<emoji>",
label: "<Human Label>",
color: PRODUCT_AREA_COLORS.<COLOR_NAME>,
},
```

**4c. Run lint and format**

After editing TypeScript files, run `pnpm lint:fix` and `pnpm format` to ensure consistency.

### Step 5: Create the SVG Banner

Use the **SVG Banner** skill to create the banner SVG at `docs/areas/<area-name>.svg`. The banner should:

- Use a single-pane or split-pane layout appropriate to the area content
- Include the area title and a short subtitle in the title bar
- Show representative CLI output or feature highlights as panel content
- Follow the Catppuccin Mocha theme and inline-attribute conventions from the SVG Banner skill

Reference `docs/areas/workspaces.svg` as an example of a completed area banner.

### Step 6: Create the Area Document

Write the markdown file to `docs/areas/<area-name>.md` using the template in `references/area-template.md`. Include:

- Centered `<div align="center">` block containing the SVG banner, H1 title, and shields.io product-area badge (color and label from Step 2/4) — all grouped together under the banner
- Overview section (required)
- Features section with content from Step 2
- FAQ section if provided
- Any additional sections the user requests

### Step 7: Confirm

Display a summary of all changes:

- Area document path (`docs/areas/<area-name>.md`)
- SVG banner path (`docs/areas/<area-name>.svg`)
- Whether project config was updated (new area) or already existed
- Product area badge preview

## File Locations

| File | Purpose |
| --- | --- |
| `docs/areas/<name>.md` | Product area document |
| `docs/areas/<name>.svg` | SVG banner asset |
| `scripts/conf/project.json` | Product area registration |
| `scripts/lib/product-area-colors.ts` | Product area color/label mapping |

## Additional Resources

### Reference Files

- **`references/area-template.md`** — Complete markdown template with badge format and section guidelines

### Examples

Working product areas in the repository:

- **`docs/areas/workspaces.md`** — Full product area document with all sections
- **`docs/areas/workspaces.svg`** — Split pane SVG banner example
97 changes: 97 additions & 0 deletions .claude/skills/product-area/references/area-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Product Area Template

This is the reference template for product-area documents in `docs/areas/`. Adapt sections as needed per area — the Overview is required, all others are optional.

## File Structure

Each product area consists of two files in `docs/areas/`:

```
docs/areas/
├── <area-name>.md # Product area document
└── <area-name>.svg # SVG banner (Catppuccin Mocha terminal style)
```

The `<area-name>` is the kebab-case version of the area title (e.g., "Workspaces" becomes `workspaces`).

## Markdown Template

```markdown
<div align="center">

<img src="./<area-name>.svg" alt="<Area Title> Banner" width="100%" />

# <Area Title>

![<Product Area Label>](https://img.shields.io/badge/<Encoded Label>-<hex color>?style=flat-square)

</div>

## Overview

<1-2 paragraphs describing the product area: what it is, why it exists, and who it serves.>

## Features

### <Category Name>

- **<Feature name>** - <one-line description of the feature>
- **<Feature name>** - <one-line description of the feature>

### <Category Name>

- **<Feature name>** - <one-line description of the feature>

---

## FAQ

### <Question?>

<Answer — 1-3 paragraphs.>

### <Question?>

<Answer — 1-3 paragraphs.>
```

## Product Area Badge

Each area doc includes a shields.io badge below the H1 title. The badge color and label come from `scripts/conf/project.json` (Product Area field options) and `scripts/lib/product-area-colors.ts`.

Badge format: `![<Label>](https://img.shields.io/badge/<URL-encoded Label>-<hex color>?style=flat-square)` — hex color without the `#` prefix

Available colors from `PRODUCT_AREA_COLORS`:

| Color Name | Hex | Example Usage |
| --- | --- | --- |
| BLUE | 0969da | agent-setup |
| CYAN | 1f6feb | agent-sandbox |
| PURPLE | 8250df | coding-standards |
| GREEN | 1a7f37 | gg-workflow |
| ORANGE | d4660b | developer-tools |
| PINK | d15593 | context-integration |
| GRAY | 6e7781 | documentation |
| YELLOW | bf8700 | skills-agents |
| RED | cf222e | platform |

Use `encodeURIComponent` logic for the label in the URL (spaces become `%20`, `&` becomes `%26`, etc.).

## Section Guidelines

| Section | Required | Notes |
| --- | --- | --- |
| Banner + Title | Yes | SVG banner centered above the H1 title |
| Product Area Badge | Yes | shields.io badge matching project.json color |
| Overview | Yes | 1-2 paragraphs, no bullet lists |
| Features | Recommended | Group by category with H3 headings, or use a flat list |
| FAQ | Optional | Question-and-answer pairs addressing common concerns |
| Additional sections | Optional | Add as needed (e.g., Architecture, API, Integrations) |

## Writing Style

- Write for a technical audience familiar with developer tools
- Lead with the value proposition in the Overview
- Feature descriptions should be concise — one line per feature, bold name + dash + description
- FAQ answers should be direct and substantive, not marketing fluff
- Use present tense throughout
138 changes: 138 additions & 0 deletions .claude/skills/svg-banner/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
---
name: SVG Banner
description: This skill should be used when the user asks to "create an SVG banner", "make a terminal SVG", "generate a banner image", "create a workspace SVG", "make a split pane SVG", "design a CLI screenshot SVG", or mentions creating SVG assets for README files or documentation. Provides templates and guidance for creating Catppuccin Mocha-themed terminal-style SVG banners.
---

# SVG Banner Creation

Create terminal-style SVG banners using the Catppuccin Mocha color palette. These banners simulate a macOS terminal window and are used as visual assets in README files and documentation.

## Layout Options

Three layout types are available:

| Layout | Description | Example |
| --- | --- | --- |
| **Single pane** | One full-width content panel | Product overview, ASCII art hero |
| **Split pane** | Two side-by-side vertical panels | Comparing features, before/after |
| **Split pane + bottom** | Two vertical panels with a bottom CLI bar | Split content with shared terminal |

## PNG Compatibility

All SVGs must be convertible to PNG via tools like `rsvg-convert`, `sharp`, Inkscape, or Puppeteer. To ensure this:

- **Always set explicit `width` and `height`** on the `<svg>` element (not just `viewBox`)
- **Use inline attributes instead of CSS classes** — apply `fill`, `font-family`, and `font-size` directly on each `<text>` and `<tspan>` element. Do NOT use a `<style>` block or CSS classes, as many PNG converters ignore them
- **Use system-available monospace fonts** — the font stack `'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace` works well as a fallback chain
- **Avoid external resources** — no `<image>`, `<use>`, `xlink:href`, or external font imports

## Core Structure

Every SVG banner follows this skeleton:

1. **Outer frame** — rounded `<rect>` with `fill="#1e1e2e"` (Mocha base)
2. **Title bar** — `<rect>` with `fill="#181825"` (Mocha mantle) + three traffic-light circles
3. **Title text** — centered dim text in the title bar
4. **Content area** — title/subtitle block, then layout-specific panels
5. **Dividers** — `<line>` elements with `stroke="#313244"` (Mocha surface0)

## Color Palette (Catppuccin Mocha)

| Class | Hex | Usage |
| --- | --- | --- |
| `.brand` | `#a78bfa` | Brand/accent text, command flags |
| `.dim` | `#6c7086` | Muted labels, comments, prompts |
| `.st` | `#a6e3a1` | Success checkmarks, "running" |
| `.tx` | `#cdd6f4` | Primary body text |
| `.op` | `#9399b2` | Failure marks, operators |
| `.prompt` | `#89b4fa` | Shell prompt `~`, links |
| `.warn` | `#f9e2af` | Warnings, activity dots |
| `.fn` | `#89b4fa` | Function names, paths, URLs |
| `.peach` | `#fab387` | Status dots |

Background colors:

| Element | Hex | Catppuccin name |
| --- | --- | --- |
| Main background | `#1e1e2e` | Base |
| Title bar / tabs | `#181825` | Mantle |
| Dividers | `#313244` | Surface0 |
| Input borders | `#45475a` | Surface1 |
| Traffic light red | `#f38ba8` | Red |
| Traffic light yellow | `#f9e2af` | Yellow |
| Traffic light green | `#a6e3a1` | Green |

## Dimensions & Spacing

| Property | Value |
| --- | --- |
| Width | `1120` |
| Default height (single/split) | `510`-`520` |
| Height with bottom pane | `620`-`680` (adjust to content) |
| Corner radius | `rx="10" ry="10"` |
| Title bar height | `36` |
| Content x-padding | `18` (left panel), `578` (right panel) |
| Line spacing | `16`-`22` between text lines |
| Divider inset | `x1="16"` to `x2="1104"` |
| Vertical divider x | `560` (center) |
| Horizontal bottom divider y | Varies — placed above bottom pane |

## Building a Banner

### Step 1: Determine Layout

Ask the user which layout to use (single, split, or split + bottom) and what content belongs in each panel. Gather:

- Title bar label (centered in macOS-style bar)
- Title and subtitle (shown below title bar, above panels)
- Content for each panel (typically CLI output, code, or tool UI)
- Tab labels for each panel (e.g., "terminal", "claude code", "remote")

### Step 2: Assemble the SVG

Start from the shared boilerplate in `references/svg-template.md`. Select the appropriate layout section and populate with content.

Key rules:

- Use `xml:space="preserve"` on any `<text>` element that has leading whitespace
- Use `&#x2713;` for checkmarks, `&#x2588;` for cursor block, `&#x25CF;` for status dot, `&#x2192;` for arrow
- Apply `fill` and `font-family`/`font-size` as inline attributes on every `<text>` and `<tspan>` — never use CSS classes
- Tab labels use `<rect>` with `fill="#181825"` + `<text>` with inline font styling
- Indent continuation lines by increasing the `x` attribute (usually +8 per indent level)
- The shared monospace font stack is: `font-family="'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace"`

### Step 3: Size the SVG

Calculate height based on content:

- Title bar: 36px
- Title + subtitle area: ~60px
- Horizontal divider: ~16px gap
- Each text line: ~16-22px
- Bottom pane (if used): ~80-100px
- Bottom padding: ~10px

Set `viewBox="0 0 1120 <height>"` and match the outer `<rect>` height.

### Step 4: Validate

- Confirm `<svg>` has both `width`, `height`, and `viewBox` attributes
- Confirm no `<style>` block or `class` attributes exist — all styling is inline
- Confirm all `<tspan>` tags are closed
- Confirm `xml:space="preserve"` is on lines with leading spaces
- Confirm no raw `<`, `>`, or `&` in text content (use entities)
- Confirm traffic lights are at `cx="20"`, `cx="40"`, `cx="60"`, `cy="18"`
- Confirm viewBox height matches outer rect height and the `height` attribute

## Additional Resources

### Reference Files

- **`references/svg-template.md`** — Complete SVG boilerplate for all three layouts with inline comments

### Examples

Working SVGs in the repository:

- **`.github/assets/banner.svg`** — Split pane layout (terminal + Claude Code UI)
- **`.github/assets/workspace.svg`** — Split pane layout (containerized + remote)
Loading