firstrun

# First Run

Configure your Figma template library for uSpec. This skill verifies your MCP connection, navigates your Figma template library, extracts template component keys, detects the font family, and writes everything to `uspecs.config.json`.

## Prerequisite

`uspecs.config.json` must already exist with `mcpProvider` and `environment` set. These are written by `npx uspec-skills init`. If the config is missing, abort with:

> Run `npx uspec-skills init` first to install uSpec and choose your platform. Then run this skill to configure your Figma template library.

Read `mcpProvider` and `environment` from `uspecs.config.json` and use those values throughout this skill instead of asking the user.

## Inputs Expected

This skill collects inputs interactively — do not require them up front.

## Workflow

Copy this checklist and update as you progress:

```
Task Progress:
- [ ] Step 1: Read MCP provider from uspecs.config.json
- [ ] Step 1b: Verify MCP connection
- [ ] Step 4: Ask "Uber employee?" — Yes (use internal library) or No (paste link)
- [ ] Step 4a (Yes only): Write Uber template keys + fontFamily to config, then jump to Step 9
- [ ] Step 5 (No only): Navigate to the library file / extract fileKey
- [ ] Step 6 (No only): Search for template components
- [ ] Step 7 (No only): Extract component keys
- [ ] Step 7b (No only): Detect font family from template
- [ ] Step 8 (No only): Write config to uspecs.config.json
- [ ] Step 9: Display success message
```

### Step 1: Read MCP Provider from Config

Read `mcpProvider` from `uspecs.config.json`. It will be one of `figma-console` or `figma-mcp`. Save this value as `MCP_PROVIDER` for use in later steps.

If `mcpProvider` is missing, abort and tell the user to re-run `npx uspec-skills init`.

### Step 1b: Verify MCP Connection

Verify the selected MCP is connected before continuing — catching a broken connection early avoids wasting time on setup that will fail later.

**If `MCP_PROVIDER` = `figma-console`:**
- Call `figma_get_status` — Confirm Desktop Bridge plugin is active

If connection fails:
> Please open Figma Desktop and run the Desktop Bridge plugin. Then try again.

**If `MCP_PROVIDER` = `figma-mcp`:**
- Make a lightweight `use_figma` call to verify connectivity:
  - `fileKey`: any valid fileKey (you can use `"test"` — the call will fail with a clear error if the MCP itself is not connected, vs. a file-not-found error which confirms the MCP works)
  - `code`: `return "ok";`
  - `description`: `Verify MCP connection`

If the MCP itself is not reachable (tool not found, server error):
> The native Figma MCP is not responding. Please check your MCP configuration and ensure the Figma MCP server is running.

If the call returns a file-not-found error, that's fine — it means the MCP is connected. Proceed.

### Step 4: Ask Whether the User Is a Uber Employee

Ask the user exactly this:

> **Are you a Uber employee?**
> - **Yes** — uSpec will use the built-in Uber template library (no link needed).
> - **No** — paste the link to your Figma template library file.

Wait for the user's answer.

- If the answer is **Yes** (or any clear affirmative such as "yes", "y", "skip", "uber"), proceed to **Step 4a** and skip Steps 5, 6, 7, and 7b entirely.
- If the answer is **No** or the user pastes a Figma URL, save the URL as `LIBRARY_URL` and continue with Step 5. **For `figma-mcp` only:** extract `FILE_KEY` from the URL. Figma URLs follow the pattern `figma.com/design/:fileKey/:fileName`. For branch URLs (`figma.com/design/:fileKey/branch/:branchKey/:fileName`), use `:branchKey` as the `FILE_KEY`. Save this for all subsequent `use_figma` / `search_design_system` / `get_screenshot` calls.

### Step 4a: Write Built-in Uber Template Config (Yes branch only)

When the user answers Yes in Step 4, the agent already has the correct template keys and font family for the Uber-internal library. Write them to `uspecs.config.json`, preserving every existing field (`mcpProvider`, `environment`, `cliVersion`, and any other unknown fields). The merged file should look like:

```json
{
  "mcpProvider": "...preserved...",
  "environment": "...preserved...",
  "cliVersion": "...preserved...",
  "fontFamily": "Uber Move",
  "templateKeys": {
    "screenReader": "6351e6a91a6785702ffa57f7e7ae085fe9f83f57",
    "colorAnnotation": "0b939a05e7b403b481d5221b08f33c97dc4acd39",
    "anatomyOverview": "a552bd211756add2661ed757a5aeafba24bd59a9",
    "apiOverview": "a182560cbe538de07f49f0aed5fadeea7d418e1c",
    "propertyOverview": "401fa98128d882dc93c3d5987ed094b1ec66b9f3",
    "structureSpec": "9f5f7bdc834004ea47e59bb1502aab66348f1c99",
    "motionSpec": "31bc00ff1f47b602cb7129b24b1f3271e7c7b5dd"
  }
}
```

Then **jump directly to Step 9** (Success Message). Do not run Steps 5, 6, 7, 7b, or 8 — no MCP calls or library navigation are needed for Uber employees.

### Step 5: Navigate to the Library File (No branch only)

**If `MCP_PROVIDER` = `figma-console`:**
- `figma_navigate` — Open the template library URL

**If `MCP_PROVIDER` = `figma-mcp`:**
- No navigation call needed — `use_figma` takes `fileKey` directly. The `FILE_KEY` extracted in Step 4 is used for all subsequent calls. Optionally, verify the file is accessible:
  - `use_figma` with `fileKey = FILE_KEY`, `code = "return figma.root.children.map(p => p.name);"`, `description = "List pages in template library"`

### Step 6: Search for Template Components (No branch only)

Required template names (case-insensitive search):
1. "Screen reader"
2. "Color Annotation"
3. "Anatomy"
4. "API"
5. "Property"
6. "Structure"
7. "Motion"

**If `MCP_PROVIDER` = `figma-console`:**
- `figma_search_components` with query for each template name

**If `MCP_PROVIDER` = `figma-mcp`:**
- `search_design_system` with `query` for each template name, `fileKey = FILE_KEY`, and `includeComponents: true`

### Step 7: Extract Component Keys (No branch only)

For each found component, extract its component key. The search results include the