/extracting-design-system

name: extracting-design-system
description: Use when the user says "setup", "setup bridge", "extract", "extract DS", "onboard", "build knowledge base", "initialize bridge", or is starting Bridge in a project for the first time. Handles the complete bootstrap: pre-flight checks, scaffolding (docs.config.yaml, cron workflow, .bridge/mcp.json), Figma token management (stdin-only), DS extraction via MCP (preferred) or REST (fallback), guide generation, and first commit proposal.

Extracting Design System

Overview

Single-entry-point skill for Bridge's initial setup AND subsequent re-extracts. Orchestrates the complete flow from empty repo to "docs shipped" via 8 procedural steps. Uses the `setup-orchestrator` module (Bash tool) + MCP tools (figma-console-mcp) + user prompts.

When to Use

Invoke when the user:

• says "setup bridge", "setup", "init", "extract", "extract DS", "onboard", "build KB", "refresh registries"
• has just installed the Bridge plugin and wants to bootstrap a repo
• wants to re-extract after an upstream Figma change

Do NOT use if:

• the user is designing a component — use `generating-figma-design`
• the user is processing manual corrections — use `learning-from-corrections`
• the user is shipping a design — use `shipping-and-archiving`

Procedure

**Before starting, load:**

• `references/transport-adapter.md` (repo-root) — for MCP transport detection

Step 1 — Pre-flight checks

Run via Bash tool:

node --version
git rev-parse --is-inside-work-tree
gh auth status

Then Node:

const { runPreflight } = require("/path/to/node_modules/@noemuch/bridge-ds/dist/lib/cli/setup-orchestrator.js");
const { gitRemote, figmaKey } = await runPreflight();

Report to user in conversation:

✓ Node 20 · git repo · gh auth OK
📍 Detected git remote: {gitRemote or "(none)"}
📍 Detected Figma URL in README: {figmaKey or "(none)"}

Step 2 — Ask for Figma file URL (skip if auto-detected and user confirms)

If `figmaKey` is null from pre-flight:

Paste the Figma DS file URL:

Extract the key via the regex `figma\.com\/(?:design|file)\/([a-zA-Z0-9_-]+)`.

Step 3 — Ask for Figma Personal Access Token

**IMPORTANT**: token must be stdin-masked. Use Claude Code's native password prompt (`AskUserQuestion` tool with type=password if available, otherwise instruct the user via terminal).

Paste your Figma PAT (hidden, never logged).
Press Enter to skip — we'll use the plugin path (interactive extraction only).

If provided:

• Validate via `validateFigmaToken(token)` — if 401, abort
• Probe via `probeVariablesEndpoint(token, fileKey)` — note plan tier

If skipped: plan to use MCP path only (no cron support until token added later).

Step 4 — Scaffold the repo

Via Bash:

node -e "
const { scaffold } = require('@noemuch/bridge-ds/dist/lib/cli/setup-orchestrator.js');
(async () => {
  const created = await scaffold({
    dsName: '$DS_NAME',
    figmaFileKey: '$FIGMA_KEY',
    cronCadence: 'daily',
    cronTime: '06:00',
  });
  console.log(JSON.stringify(created, null, 2));
})();
"

Report:

✓ Scaffolded files/directories:
  - bridge-ds/knowledge-base/registries/
  - bridge-ds/knowledge-base/recipes/
  - .bridge/
  - docs.config.yaml
  - .github/workflows/bridge-kb-cron.yml

Step 5 — Store token in GitHub Secrets (if provided)

Via Bash:

node -e "
const { storeTokenInGitHubSecret } = require('@noemuch/bridge-ds/dist/lib/cli/setup-orchestrator.js');
(async () => {
  const result = await storeTokenInGitHubSecret({
    token: process.env._FIGMA_TOKEN_TEMP,
    repo: '$GITHUB_REPO',
    fileKey: '$FIGMA_KEY',
  });
  console.log(JSON.stringify(result));
})();
" 2>&1

Where `_FIGMA_TOKEN_TEMP` is set for the duration of this single command invocation ONLY, then unset.

Step 6 — Detect transport + extract via MCP (preferred)

Per `references/transport-adapter.md`:

• `figma_get_status` via MCP → if available and `setup.valid: true`, use console transport
• Otherwise, fall back to REST (headless) with graceful 403 handling for non-Enterprise

**During extract**, Claude Code should display progress events from the MCP tool calls. Pattern:

• After each `figma_get_design_system_kit` / `figma_get_variables` / `figma_search_components` batch, report to user:

  ⠋ Extracted: 42/156 components · 130/856 variables · 12/49 text styles

Step 7 — Validate extracted data + write registries

Sample import probe (3–5 keys per registry type). If any fail, re-extract the failing entries (max 3 attempts).

Write to `bridge-ds/knowledge-base/registries/{components,variables,text-styles,icons,logos,illustrations}.json`.

Report:

✓ Registries validated. Keys verified.
  - Components: 156 (100%)
  - Variables: 856 (100%)
  - ...

Step 8 — Propose initial commit

Propose initial commit? [Y/n]

If Y, Bash:

git add .
git commit -m "feat: bootstrap Bridge KB via setup bridge"
git push origin $(git rev-parse --abbrev-ref HEAD)

Finally, propose first cron run:

Trigger first cron run now to verify the workflow? [Y/n]

If Y, Bash:

gh workflow run bridge-kb-cron.yml --repo $GITHUB_REPO
gh run watch

Final report

✨ Setup complete in Xm Ys.

Your DS:
  Repo:      https://github.com/{repo}
  KB:        bridge-ds/knowledge-base/registries/
  Cron:      .github/workflows/bridge-kb-cron.yml (daily sync)

Next steps:
  • Say "make <description>" to design a new component/screen
  • Say "fix" after manual Figma edits
  • Say "done" to ship + extract recipes
  • Daily cron runs at 06:00 UTC automatically

<HARD-GATE> NEVER write a registry entry without a `key` field (hex hash for components/icons/logos; name path for variables).

NEVER mark setup complete without validating a sample of keys (3–5 per registry) via a live import probe.

NEVER echo or log the Figma PAT. Token goes from stdin → validate → `setGitHubSecret` (stdin pipe to gh CLI). Wipe buffer af