@atomixstudio/mcp 1.0.15 → 1.0.17

package/README.md

@@ -1,21 +1,6 @@
 # @atomixstudio/mcp
 
-MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens directly from AI coding tools like Cursor, Claude Desktop, Windsurf, and more.
-
-## Quick Start (CLI)
-
-The easiest way to use Atomix is via the CLI:
-
-```bash
-# Sync tokens + AI rules (default behavior)
-npx heyatomix sync
-
-# Sync tokens only (skip AI rules)
-npx heyatomix sync --no-rules
-
-# Create config file
-npx heyatomix init
-```
+MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens from AI coding tools (Cursor, Claude Desktop, Windsurf, etc.) or from the command line.
 
 ## Getting Your Credentials
 
@@ -24,79 +9,9 @@ npx heyatomix init
 3. Click **Publish** to make your DS available via API
 4. Your `ds-id` is in the URL: `atomixstudio.eu/ds/[ds-id]`
 
-## CLI Commands
-
-### `heyatomix sync`
-
-Sync design tokens and AI rules to your project. **Both tokens and AI guidance rules sync by default** since the rules reference tokens.
-
-```bash
-npx heyatomix sync                    # Sync tokens + AI rules
-npx heyatomix sync --no-rules         # Sync tokens only
-npx heyatomix sync -o src/tokens.css  # Custom output path
-npx heyatomix sync --format scss      # Output as SCSS
-npx heyatomix sync -y                 # Auto-confirm changes
-```
-
-**⚠️ Important: File Structure**
-
-The output file (e.g., `tokens.css`) is **completely rewritten** on each sync:
-
-- ✅ **Preserved**: CSS custom properties (variables) - both design system tokens and custom variables
-- ❌ **Lost**: Regular CSS rules (selectors, classes, media queries, etc.)
-
-**Best Practice**: Keep your tokens file separate from custom CSS. Use a separate file (e.g., `custom.css` or `styles.css`) for custom styles.
-
-### `heyatomix init`
-
-Create a `.atomixrc` config file:
-
-```bash
-npx heyatomix init
-```
-
-This creates:
-
-```json
-{
-  "dsId": "your-design-system-id",
-  "output": "./tokens.css",
-  "format": "css"
-}
-```
-
-### CLI Options
-
-| Option | Description |
-|--------|-------------|
-| `--ds-id` | Design system ID (or set in .atomixrc) |
-| `--api-key` | API key for private design systems |
-| `--output, -o` | Output file path [./tokens.css] |
-| `--format` | Output format (see below) |
-| `--no-rules` | Skip syncing AI rules (tokens + rules sync by default) |
-| `--rules-dir` | Directory for rules files [project root] |
-| `-y, --yes` | Auto-confirm changes |
-
-### Output Formats
-
-**Web:**
-- `css` — CSS custom properties (`:root { --var: value }`)
-- `scss` — CSS vars + SCSS variables (`$var: value`)
-- `less` — CSS vars + Less variables (`@var: value`)
-- `json` — Raw token JSON
-- `ts` — TypeScript with types
-- `js` — JavaScript module
-
-**Native:**
-- `swift` — Swift/SwiftUI for iOS
-- `kotlin` — Kotlin/Compose for Android
-- `dart` — Dart for Flutter
-
-All formats include **light and dark mode** values.
-
 ## MCP Server Setup
 
-For AI tools to query your design system directly:
+Connect your AI tool so it can query your design system directly.
 
 ### Cursor IDE
 
@@ -134,7 +49,7 @@ Create `.windsurf/mcp.json` in your project root (same format as Cursor).
 
 ## MCP Tools
 
-Once connected, AI tools can use these:
+Once connected, the AI can call these tools:
 
 | Tool | Description |
 |------|-------------|
@@ -146,55 +61,49 @@ Once connected, AI tools can use these:
 | `getAIToolRules(tool)` | Generate AI coding rules for your design system |
 | `exportMCPConfig(tool)` | Get MCP configuration for different tools |
 | `getSetupInstructions(tool)` | Get detailed setup guide |
-| `getDependencies(platform?, stack?)` | Get suggested dependencies (icons, fonts, SKILL.md, MCP config, tokens). Optional: `platform` (web, ios, android), `stack` (e.g. react, vue, next). Use with **--setup** prompt. |
+| `getDependencies(platform?, stack?)` | Get suggested dependencies (icons, fonts, SKILL.md, token files). Optional: `platform` (web, ios, android), `stack` (e.g. react, vue, next). Use with **/--getstarted** prompt. |
 
 ### getDependencies
 
-Returns DS-derived suggestions so the client's AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.
+Returns DS-derived suggestions so the AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.
 
-**Parameters (optional):**
-
-| Parameter | Description |
-|-----------|-------------|
-| `platform` | `web`, `ios`, or `android` |
-| `stack` | e.g. `react`, `vue`, `next`, `swift`, `kotlin` |
+**Parameters (optional):** `platform` — `web`, `ios`, or `android`; `stack` — e.g. `react`, `vue`, `next`, `swift`, `kotlin`.
 
 **Returns (JSON):**
 
-- **iconLibrary** — `package`, `nativePackage`, and a **performance hint:** use individual SVG imports for tree-shaking; avoid loading entire icon libraries or icon fonts.
-- **fonts** — Font family names from typography tokens + **performance hint:** implement self-hosted fonts and local `@font-face`; avoid external CDN links; use `font-display: swap`.
+- **iconLibrary** — `package`, `nativePackage`, and a performance hint (use individual imports; apply the DS icon sizing/weight token when rendering icons).
+- **fonts** — Font family names from typography tokens + hint to link fonts via URL (e.g. Google Fonts); no need to download or add font files to the repo.
 - **skill** — `path` (e.g. `.cursor/skills/atomix-ds/SKILL.md`) and `content` (generic, platform-agnostic SKILL.md).
-- **mcpConfig** — Path and content for MCP configuration.
-- **tokenFiles** — e.g. `["tokens.css", "tokens.json"]` with short copy instructions.
+- **tokenFiles** — e.g. `["tokens.css", "tokens.json"]` with copy instructions.
 
-If the design system or MCP is not available (e.g. no `--ds-id`), the tool may fail; the client should tell the user to configure MCP with `--ds-id` and try again.
+If the design system is unavailable, the tool may fail; the client should tell the user the design system could not be reached.
 
 ## MCP Prompts
 
-Once connected, your AI tool can run these prompts (e.g. **/--hello**, **/--setup**):
+Run these prompts from your AI tool (e.g. **/--hello**, **/--getstarted**):
 
 | Prompt | Description |
 |--------|-------------|
 | **/--hello** | Get started — overview, tokens, and tools. Run this first. |
-| **/--setup** | Setup design system in project. Three phases; creates files only after you approve. |
+| **/--getstarted** | Get started with design system in project. Three phases; creates files only after you approve. |
 | **/--rules** | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). |
 | **/--sync** | Sync tokens to a local file. Use **/--refactor** to migrate deprecated tokens. |
 | **/--refactor** | Migrate deprecated tokens in codebase. Run after **/--sync**. |
 
-## --setup (design system setup)
+## --getstarted (get started)
 
-The **--setup** prompt suggests dependencies for your design system so you can get up and running quickly. It does **not** install anything by default; the client's AI presents a list and asks before making changes.
+The **/--getstarted** prompt suggests dependencies for your design system so you can get up and running quickly. It does **not** install anything by default; the AI presents a list and asks before making changes.
 
 **Flow (phased instructions):**
 
 1. **Resolve platform and stack** — Infer from the project (e.g. `package.json`, `build.gradle`) or **ask the user** if the project gives no hint (e.g. blank repo). Do not assume web or any default.
-2. **Get suggested dependencies** — Call `getDependencies(platform, stack)`. If the call fails (e.g. MCP not connected or no ds-id), tell the user: "Atomix MCP is not connected or design system ID is missing. Configure MCP with --ds-id and try again."
+2. **Get suggested dependencies** — Call `getDependencies(platform, stack)`. If the call fails, tell the user the design system could not be reached and stop.
 3. **Scan codebase and build suggestion list** — Scan for `package.json` (or equivalent), existing skill path, token files, font/icon usage. Build **Suggested dependencies** (from getDependencies minus what's present) and **Already present**. Do not install or copy anything in this phase.
 4. **Present list and ask before install** — Reply with "Suggested dependencies: …" and "Already present: …" and state: "Do not install or copy anything until you confirm. Would you like me to install or add these?" Only perform steps the user approves.
-5. **Optional: suggest global styles** — If the project has no global styles that use the design system tokens, ask verbatim: "Your project doesn't appear to have global styles that use the design system tokens (e.g. semantic typography scale or semantic color classes). Would you like me to suggest or generate a minimal set (e.g. typography scale + semantic utilities) so you can develop consistently with the DS?"
-6. **Report what was created** — After any install/copy steps, list what was created or updated (e.g. "Installed: lucide-react. Added: .cursor/skills/atomix-ds/SKILL.md. Updated: .cursor/mcp.json. Copied: tokens.css.").
+5. **Optional: suggest global typeset** — If the project has no global styles that use the design system tokens, offer to build a full typeset (Display, Heading, body, caption) from the DS typography tokens via getToken/listTokens, including fontFamily, fontSize, fontWeight, lineHeight, letterSpacing—not just font imports.
+6. **Report what was created** — After any install/copy steps, list what was created or updated (e.g. "Installed: lucide-react. Added: .cursor/skills/atomix-ds/SKILL.md. Synced: tokens.css.").
 
-**Single SKILL.md:** The setup flow suggests adding a generic, coding-platform agnostic SKILL at `.cursor/skills/atomix-ds/SKILL.md`. It instructs the AI to call `getAIToolRules({ tool: "<tool>" })` where `<tool>` matches the current environment (cursor, windsurf, copilot, cline, continue, zed, generic).
+**Single SKILL.md:** The getstarted flow suggests adding a generic, coding-platform agnostic SKILL at `.cursor/skills/atomix-ds/SKILL.md`. It instructs the AI to call `getAIToolRules({ tool: "<tool>" })` where `<tool>` matches the current environment (cursor, windsurf, copilot, cline, continue, zed, generic).
 
 ## Token Categories
 
@@ -208,9 +117,91 @@ The **--setup** prompt suggests dependencies for your design system so you can g
 - **motion** — Duration and easing tokens
 - **zIndex** — Layer tokens
 
-## AI Rules Files
+## Example Usage (MCP)
+
+Once MCP is connected, you can say:
+
+> "Sync my design tokens to tokens.css"
+
+> "What color tokens are available?"
+
+> "Use the correct spacing token for 16px padding"
+
+> "Validate this: style={{ backgroundColor: '#007061' }}"
+
+---
+
+## CLI
+
+Use the CLI when you prefer commands over the AI, or in scripts/CI.
+
+### Quick Start (CLI)
 
-By default, `sync` also updates AI rules files based on which AI tools you use:
+```bash
+# Sync tokens + AI rules (default behavior)
+npx heyatomix sync
+
+# Sync tokens only (skip AI rules)
+npx heyatomix sync --no-rules
+
+# Create config file
+npx heyatomix init
+```
+
+### `heyatomix sync`
+
+Sync design tokens and AI rules to your project. **Both tokens and AI guidance rules sync by default** since the rules reference tokens.
+
+```bash
+npx heyatomix sync                    # Sync tokens + AI rules
+npx heyatomix sync --no-rules         # Sync tokens only
+npx heyatomix sync -o src/tokens.css  # Custom output path
+npx heyatomix sync --format scss     # Output as SCSS
+npx heyatomix sync -y                 # Auto-confirm changes
+```
+
+**File structure:** The output file (e.g., `tokens.css`) is **completely rewritten** on each sync. Preserved: CSS custom properties (variables). Lost: regular CSS rules (selectors, classes, media queries). Keep your tokens file separate from custom CSS (e.g. use `custom.css` for custom styles).
+
+### `heyatomix init`
+
+Create a `.atomixrc` config file:
+
+```bash
+npx heyatomix init
+```
+
+Creates:
+
+```json
+{
+  "dsId": "your-design-system-id",
+  "output": "./tokens.css",
+  "format": "css"
+}
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--ds-id` | Design system ID (or set in .atomixrc) |
+| `--api-key` | API key for private design systems |
+| `--output, -o` | Output file path [./tokens.css] |
+| `--format` | Output format (see below) |
+| `--no-rules` | Skip syncing AI rules (tokens + rules sync by default) |
+| `--rules-dir` | Directory for rules files [project root] |
+| `-y, --yes` | Auto-confirm changes |
+
+### Output Formats
+
+**Web:** `css`, `scss`, `less`, `json`, `ts`, `js`  
+**Native:** `swift`, `kotlin`, `dart`
+
+All formats include **light and dark mode** values.
+
+### AI Rules Files (CLI)
+
+By default, `sync` also updates AI rules files:
 
 | File | AI Tool |
 |------|---------|
@@ -221,25 +212,13 @@ By default, `sync` also updates AI rules files based on which AI tools you use:
 | `.github/copilot-instructions.md` | Copilot |
 | `AI_GUIDELINES.md` | Generic |
 
-The rules include your design system's governance guidelines and token usage instructions.
-
-## Example Usage
-
-**CLI:**
+### Example Usage (CLI)
 
 ```bash
 npx heyatomix sync
 ```
 
-**Natural language (via MCP):**
-
-> "Sync my design tokens to tokens.css"
-
-> "What color tokens are available?"
-
-> "Use the correct spacing token for 16px padding"
-
-> "Validate this: style={{ backgroundColor: '#007061' }}"
+---
 
 ## Package Aliases
 

package/dist/index.js

@@ -1345,7 +1345,7 @@ var TOKEN_CATEGORIES = ["colors", "typography", "spacing", "sizing", "shadows",
 var server = new Server(
   {
     name: "atomix-mcp-user",
-    version: "1.0.15"
+    version: "1.0.17"
   },
   {
     capabilities: {
@@ -1490,7 +1490,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "getDependencies",
-        description: "Get suggested dependencies for this design system (icon package, fonts, SKILL.md, token files). Use with atomix-setup prompt. Optional platform and stack for tailored suggestions.",
+        description: "Get suggested dependencies for this design system (icon package, fonts, SKILL.md, token files). Use with /--getstarted prompt. Optional platform and stack for tailored suggestions.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2053,11 +2053,13 @@ Last updated: ${lastUpdated}`
           iconLibrary: {
             package: iconPkgs.web,
             nativePackage: iconPkgs.native,
-            performanceHint: "Use individual SVG imports for tree-shaking; avoid loading entire icon libraries or icon fonts."
+            strokeWidthToken: icons?.strokeWidth != null ? "icons.strokeWidth" : void 0,
+            strokeWidthValue: icons?.strokeWidth,
+            performanceHint: "Use individual SVG imports for tree-shaking. Apply the design system's icon tokens: sizing via getToken('sizing.icon.sm') or listTokens('sizing'), and stroke width via getToken('icons.strokeWidth') when the DS defines it. Do not use hardcoded sizes or stroke widths."
           },
           fonts: {
             families: fontNames,
-            performanceHint: "Implement self-hosted fonts and local @font-face declarations; avoid external CDN links; use font-display: swap."
+            performanceHint: "Link fonts via URL (e.g. Google Fonts <link> or CSS @import); no need to download font files or add them to the repo. Prefer font-display: swap when possible. You must also build a typeset: CSS rules (e.g. .typeset-display, .typeset-heading, .typeset-body) that use var(--atmx-typography-*) for font-family, font-size, font-weight, line-height, letter-spacing from getToken/listTokens(typography). Do not create a file that only contains a font import."
           },
           skill: {
             path: ".cursor/skills/atomix-ds/SKILL.md",
@@ -2067,6 +2069,11 @@ Last updated: ${lastUpdated}`
             files: ["tokens.css", "tokens.json"],
             copyInstructions: "Call the syncTokens MCP tool to create the token file; do not only suggest the user run sync later."
           },
+          showcase: platform === "web" || !platform ? {
+            path: "atomix-setup-showcase.html",
+            template: SHOWCASE_HTML_TEMPLATE,
+            substitutionInstructions: "Replace placeholders with values from the synced token file. MCP/sync/export use the --atmx- prefix. {{TOKENS_CSS_PATH}} = path to the synced token file (e.g. ./tokens.css, same as syncTokens output). {{DS_NAME}} = design system name. {{BRAND_PRIMARY_VAR}} = var(--atmx-color-brand-primary). {{BRAND_PRIMARY_FOREGROUND_VAR}} = var(--atmx-color-brand-primary-foreground). {{HEADING_FONT_VAR}} = var(--atmx-typography-font-family-heading) or var(--atmx-typography-font-family-display). {{FONT_FAMILY_VAR}} = var(--atmx-typography-font-family-body). {{FONT_LINK_TAG}} = Google Fonts <link> for the font, or empty string. Do not invent CSS variable names; use only vars that exist in the export."
+          } : void 0,
           meta: { dsName: data.meta.name, platform: platform ?? void 0, stack: stack ?? void 0 }
         };
         return {
@@ -2126,35 +2133,109 @@ Last updated: ${lastUpdated}`
 });
 var GENERIC_SKILL_MD = `---
 name: atomix-ds
-description: Use this design system when editing UI, design system files, or when the user asks to follow the project's design system. Fetch rules dynamically via MCP.
+description: Use the Atomix design system for UI, tokens, and styles. Fetch rules and tokens via MCP tools; never hardcode design values.
 ---
 
 # Atomix Design System
 
+Use this skill when editing UI, design system files, or when the user asks to follow the project's design system. Your job is to **get the relevant data from the design system via MCP** and apply it\u2014not to guess or invent values.
+
+## Goal
+
+Complete the user's task using the design system as the single source of truth. Every color, spacing, typography, radius, shadow, or sizing value must come from the MCP tools (tokens or governance rules). Do not hardcode hex codes, pixel values, or font names.
+
 ## When to use
 
-- Editing UI components, pages, or styles
-- Working in design system or token files
-- User asks to follow the project's design system
+- Building or editing UI components, pages, or styles
+- Working in design system or token files (e.g. \`tokens.css\`, theme files)
+- User asks to "follow the design system", "use tokens", or "match the DS"
+- Validating or refactoring existing code, UI or visual design for token compliance
 
-## How to use
+## How to get design system data
 
-1. Call MCP tool **getAIToolRules** with the tool id that matches your **current AI coding environment**:
-   - **cursor** (Cursor IDE)
-   - **windsurf** (Windsurf)
-   - **copilot** (Copilot)
-   - **cline** (Cline)
-   - **continue** (Continue)
-   - **zed** (Zed)
-   - **generic** (other tools)
+**1. Governance rules (how to use tokens in code)**  
+Call **getAIToolRules** with the tool id for your current environment: \`cursor\`, \`windsurf\`, \`copilot\`, \`cline\`, \`continue\`, \`zed\`, or \`generic\`.  
+Example: \`getAIToolRules({ tool: "cursor" })\`.  
+Alternatively use the **/--rules** prompt or the resource \`atomix://rules/<tool>\`.
 
-   Example: \`getAIToolRules({ tool: "cursor" })\` when in Cursor.
+**2. Token values (what to use in code)**  
+- **getToken(path)** \u2014 One token by path (e.g. \`colors.brand.primary\`, \`typography.fontSize.lg\`, \`sizing.icon.sm\`, \`icons.strokeWidth\`). Icon stroke width is at \`icons.strokeWidth\` when the design system defines it.
+- **listTokens(category)** \u2014 All tokens in a category: \`colors\`, \`typography\`, \`spacing\`, \`sizing\`, \`shadows\`, \`radius\`, \`borders\`, \`motion\`, \`zIndex\`. For icon config (e.g. stroke width), use \`getToken("icons.strokeWidth")\` since \`icons\` is not a list category.
+- **searchTokens(query)** \u2014 Find tokens by name or value.
 
-2. Alternatively use the **design-system-rules** prompt or the resource \`atomix://rules/<tool>\` with the same tool id.
+**3. Validation**  
+- **validateUsage(value, context)** \u2014 Check if a CSS/value should use a token instead (e.g. \`validateUsage("#007061", "color")\`).
 
-3. Apply the returned rules (tokens, governance) when generating or editing code.
+**4. Syncing tokens to a file**  
+- **syncTokens({ output, format })** \u2014 Writes the current design system tokens to a file (e.g. \`./tokens.css\`). Use when the user wants a local token file.
 
-4. Ensure Atomix MCP is configured with the project's \`--ds-id\` (config path varies by platform: e.g. \`.cursor/mcp.json\`, \`.windsurf/mcp.json\`).
+Use the returned rules and token paths/values when generating or editing code. Prefer CSS variables (e.g. \`var(--atmx-*)\`) or the exact token references from the tools.
+
+## Best practices
+
+- **Fetch first:** Before writing UI or styles, call getAIToolRules and/or getToken/listTokens so you know the exact tokens and conventions.
+- **Icons:** Apply the design system's icon tokens when rendering icons: sizing via \`getToken("sizing.icon.sm")\` or \`listTokens("sizing")\`, and stroke width via \`getToken("icons.strokeWidth")\` when the DS defines it; do not use hardcoded sizes or stroke widths.
+- **Typography:** Use typography tokens (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) from the DS for any text; build typesets (Display, Heading, body) from those tokens when creating global styles.
+- **No guessing:** If a value is not in the rules or token list, use searchTokens or listTokens to find the closest match rather than inventing a value.
+`;
+var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Setup complete \u2014 {{DS_NAME}}</title>
+  {{FONT_LINK_TAG}}
+  <link rel="stylesheet" href="{{TOKENS_CSS_PATH}}">
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
+      background: {{BRAND_PRIMARY_VAR}};
+      color: {{BRAND_PRIMARY_FOREGROUND_VAR}};
+      min-height: 100vh;
+      padding: 2rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      text-align: center;
+    }
+    .wrap { width: 375px; max-width: 100%; }
+    .icon { width: 2rem; height: 2rem; margin: 0 auto 1rem; }
+    h1 {
+      font-family: {{HEADING_FONT_VAR}}, {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
+      font-size: clamp(1.5rem, 4vw, 2.25rem);
+      font-weight: 700;
+      margin: 0 0 0.75rem;
+      line-height: 1.25;
+    }
+    .lead { margin: 0 0 1.5rem; font-size: 1rem; line-height: 1.5; opacity: 0.95; }
+    .now { margin: 1.5rem 0 0; font-size: 0.875rem; line-height: 1.6; opacity: 0.95; text-align: left; }
+    .now strong { display: block; margin-bottom: 0.5rem; }
+    .now ul { margin: 0; padding-left: 1.25rem; }
+    .tips { margin-top: 1.5rem; font-size: 0.875rem; line-height: 1.6; opacity: 0.9; }
+    .tips a { color: inherit; text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="icon" aria-hidden="true">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="32" height="32"><path d="M20 6L9 17l-5-5"/></svg>
+    </div>
+    <h1>You're all set with {{DS_NAME}}</h1>
+    <p class="lead">This page uses your design system: brand primary as background, headline and body typesets, and an icon. Token file is linked above.</p>
+    <div class="now">
+      <strong>What you can do now:</strong>
+      <ul>
+        <li>Ask your agent to build your designs using the design system tokens</li>
+        <li>Build components and pages that use <code>var(--atmx-*)</code> for colors, spacing, and typography</li>
+        <li>Run <code>/--rules</code> to load governance rules; run <code>/--sync</code> and <code>/--refactor</code> after you change tokens in Atomix Studio</li>
+      </ul>
+    </div>
+    <p class="tips">Keep the source of truth at <a href="https://atomixstudio.eu" target="_blank" rel="noopener">atomixstudio.eu</a> \u2014 avoid editing token values in this repo.</p>
+  </div>
+</body>
+</html>
 `;
 var AI_TOOLS = ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic"];
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
@@ -2240,21 +2321,8 @@ Get your DS ID from: https://atomixstudio.eu/ds/[your-ds-id]`
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
   const prompts = [
     { name: "--hello", description: "Get started with this design system - overview, tokens, and tools. Run this first!" },
-    {
-      name: "--setup",
-      description: "Setup design system in project. Three phases: scan, report and ask, then create only after you approve.",
-      arguments: [
-        { name: "platform", description: "Target platform (web, ios, android). Optional.", required: false },
-        { name: "stack", description: "Stack or framework (e.g. react, vue, next, swift, kotlin). Optional.", required: false }
-      ]
-    },
-    {
-      name: "--rules",
-      description: "Get the design system governance rules for your AI coding tool",
-      arguments: [
-        { name: "tool", description: "AI tool (cursor, copilot, windsurf, cline, continue, zed, generic). Optional.", required: false }
-      ]
-    },
+    { name: "--getstarted", description: "Get started with design system in project. Three phases: scan, report and ask, then create only after you approve." },
+    { name: "--rules", description: "Get the design system governance rules for your AI coding tool (default: cursor)." },
     { name: "--sync", description: "Sync tokens to a local file. Safe: adds new, updates existing, marks deprecated. Use /--refactor to migrate." },
     { name: "--refactor", description: "Migrate deprecated tokens in codebase. Run after /--sync." }
   ];
@@ -2262,7 +2330,7 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
 });
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  const canonicalName = name === "--hello" ? "hello" : name === "--setup" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name;
+  const canonicalName = name === "--hello" ? "hello" : name === "--getstarted" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name;
   const shouldForceRefresh = canonicalName === "sync";
   let data = null;
   let stats = null;
@@ -2694,49 +2762,45 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
       };
     }
     case "atomix-setup": {
-      const setupInstructions = `You are running **atomix-setup** (design system setup). Three phases only.
+      const setupInstructions = `You are running **/--getstarted** (get started with design system). Three phases only.
 
-**Rule:** Do not create, write, or modify any file until Phase 3 and only after the user has explicitly approved (e.g. replied "Yes", "Yes for all", "Go ahead"). Creating or modifying files before the user approves is a rule violation.
+**Rule:** Do not create, write, or modify any file until Phase 3 and only after the user has explicitly approved (e.g. "Yes", "Yes for all", "Go ahead").
 
 ## Todo list (required)
 
-- **Create a todo list** at the start with items for Phase 1, Phase 2, and Phase 3 (e.g. "Phase 1: Scan", "Phase 2: Report and ask", "Phase 3: Create after approval").
-- Work **step by step**: complete Phase 1, then Phase 2; do not run Phase 3 until the user has replied with approval.
-- Mark todo items completed as you finish each phase. Use this pattern so the user and you can track progress.
+- Create a todo list at the start: Phase 1, Phase 2, Phase 3. Work step by step; do not run Phase 3 until the user has replied with approval. Mark items completed as you go.
 
 ## Phase 1 \u2013 Scan
 
-- Resolve platform/stack: infer from the project (e.g. package.json, build.gradle, Xcode) or ask the user once: "Which platform? (e.g. web, Android, iOS)" and if relevant "Which stack? (e.g. React, Vue, Next, Swift, Kotlin)." Do not assume a default.
-- Call MCP tool **getDependencies** with \`platform\` and optional \`stack\`. If it fails, tell the user: "Atomix MCP is not connected or design system ID is missing. Configure MCP with --ds-id and try again."
-- Scan the repo for what already exists: .cursor/skills/atomix-ds/SKILL.md, a tokens file (e.g. tokens.css or src/tokens.css), icon package from getDependencies, font setup. Do **not** include or check for MCP config; MCP is already configured for this session.
-- **Web:** Scan for any existing CSS (e.g. globals.css, main.css, App.css, index.css, Tailwind entry, framework styles). Note whether at least one CSS file exists.
-- **Native (iOS/Android):** Scan for existing theme or style files (e.g. SwiftUI theme/asset catalog, Android themes.xml/styles.xml, Compose theme). Note whether the project already has a theme or style setup.
-- Build two lists: **Suggested** (from getDependencies minus what exists) and **Already present**. Only include: icon package, fonts, skill (.cursor/skills/atomix-ds/SKILL.md), token files. No MCP.
+- Resolve platform/stack: infer from the project (e.g. package.json, build.gradle, Xcode) or ask once: "Which platform? (e.g. web, Android, iOS)" and if relevant "Which stack? (e.g. React, Vue, Next, Swift, Kotlin)." Do not assume a default.
+- Call **getDependencies** with \`platform\` and optional \`stack\`. If it fails, tell the user the design system could not be reached and stop.
+- Scan the repo for: .cursor/skills/atomix-ds/SKILL.md, a tokens file (e.g. tokens.css or src/tokens.css), icon package from getDependencies, font links. **Web:** note any existing CSS (globals.css, main.css, Tailwind, etc.). **Native:** note any theme/style files (SwiftUI, Android themes, Compose).
+- Build two lists: **Suggested** (from getDependencies minus what exists) and **Already present**. Include: icon package, font links, skill (.cursor/skills/atomix-ds/SKILL.md), token files; for web, also include the **showcase page** (atomix-setup-showcase.html) if getDependencies returned a \`showcase\` object.
 - Do not write, create, or add anything in Phase 1.
 
-## Phase 2 \u2013 Report and ask for permission
+## Phase 2 \u2013 Report and ask
 
 - Reply with: **Suggested:** [list] and **Already present:** [list].
-- Ask exactly once: "Do you want me to add the suggested items? (Yes for all, or say which ones.)" (Integration with existing CSS or theme is recommended after Phase 3; new global CSS/theme is only suggested when none exists.)
-- **Stop.** Do not run Phase 3 in this response. Wait for the user to reply.
+- Ask exactly once: "Do you want me to add the suggested items? (Yes for all, or say which ones.)"
+- **Stop.** Wait for the user to reply. Do not run Phase 3 in this response.
 
-## Phase 3 \u2013 Create or add (only after user approval)
+## Phase 3 \u2013 Create (only after user approval)
 
 - Run only when the user has said yes (all or specific items).
 - For each approved item:
   - **Skill:** Write the skill content from getDependencies to .cursor/skills/atomix-ds/SKILL.md.
-  - **Token file:** Call the **syncTokens** MCP tool with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css"). You must call syncTokens; do not only suggest the user run sync later.
-  - **Icon package / fonts:** Add per getDependencies (e.g. install package, add font config). Do not overwrite existing.
-- Report only what you actually created or updated (e.g. "Added: .cursor/skills/atomix-ds/SKILL.md. Synced: src/tokens.css."). Do not claim the token file was added if you did not call syncTokens.
-- **After reporting \u2013 styles/theme (per platform):**
-  - **Web:** If the project **already has** at least one CSS file: recommend how to integrate Atomix (e.g. import the synced tokens file, use \`var(--atomix-*)\` or semantic classes). Do **not** suggest creating a new global CSS. Only if the project has **no** CSS file at all, ask once: "There are no CSS files yet. Do you want a minimal global CSS (typography + semantic utilities from the design system)?" and add it only if the user says yes.
-  - **iOS/Android:** If the project **already has** theme or style files: recommend how to integrate Atomix tokens (e.g. use synced DesignTokens.swift / Kotlin tokens in existing theme). Do **not** suggest creating a new global theme file. Only if the project has **no** theme/style setup at all, ask once: "There's no theme/style setup yet. Do you want a minimal token-based theme (colors, typography, spacing from the design system)?" and add it only if the user says yes.
-
----
-
-Create your todo list first, then execute Phase 1 (resolve platform/stack, call getDependencies, scan, build lists). Then Phase 2 (report lists and ask). Do not perform Phase 3 until the user replies.`;
+  - **Token file:** Call **syncTokens** with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css"). You must call syncTokens; do not only suggest the user run it later.
+  - **Icon package:** Install per getDependencies. When rendering icons, apply the design system's icon tokens: use getToken(\`sizing.icon.*\`) or listTokens(\`sizing\`) for size, and getToken(\`icons.strokeWidth\`) for stroke width when the DS defines it; do not use hardcoded sizes or stroke widths.
+  - **Fonts and typeset:** Add font links (e.g. \`<link>\` or \`@import\` from Google Fonts). Then build a **typeset** in CSS: use **getToken** / **listTokens** (category \`typography\`) to get fontFamily, fontSize, fontWeight, lineHeight, letterSpacing for display, heading, and body, and write CSS rules (e.g. \`.typeset-display\`, \`.typeset-heading\`, \`.typeset-body\`, or \`h1\`/\`h2\`/\`p\`) that set those properties to \`var(--atmx-typography-*)\`. The typeset file (or section) must define the full type scale\u2014not only a font import. Do not create a CSS file that contains only a font import.
+  - **Showcase page (web only):** If platform is web and getDependencies returned a \`showcase\` object, create the file at \`showcase.path\` using \`showcase.template\`. Replace every placeholder per \`showcase.substitutionInstructions\`: TOKENS_CSS_PATH, DS_NAME, BRAND_PRIMARY_VAR (page background), BRAND_PRIMARY_FOREGROUND_VAR (text on brand), HEADING_FONT_VAR (h1), FONT_FAMILY_VAR (body), FONT_LINK_TAG. Use only CSS variable names that exist in the synced token file. Do not change the HTML structure. After creating the file, launch it in the default browser (e.g. \`open atomix-setup-showcase.html\` on macOS, \`xdg-open atomix-setup-showcase.html\` on Linux, or the equivalent on Windows).
+- Report only what you actually created or updated. Do not claim the token file was added if you did not call syncTokens.
+- **After reporting \u2013 styles/theme:**
+  - **Web:** If the project already has at least one CSS file: recommend how to integrate Atomix (e.g. import the synced tokens file, use \`var(--atmx-*)\`). Do not suggest a new global CSS. Only if there is **no** CSS file at all, ask once: "There are no CSS files yet. Do you want me to build a global typeset from the design system?" If yes, create a CSS file that includes: (1) font \`@import\` or document that a font link is needed, and (2) **typeset rules**\u2014CSS classes or element rules that set font-family, font-size, font-weight, line-height, letter-spacing using \`var(--atmx-typography-*)\` from the token file (e.g. \`.typeset-display\`, \`.typeset-heading\`, \`.typeset-body\`). You must call getToken/listTokens to get the exact typography token paths and write the corresponding var() references. The output must not be only a font import; it must define the full typeset (Display, Heading, body) with every style detail from the design system.
+  - **iOS/Android:** If the project already has theme/style files: recommend how to integrate Atomix tokens. Do not suggest a new global theme. Only if there is **no** theme/style at all, ask once: "There's no theme/style setup yet. Do you want a minimal token-based theme?" and add only if the user says yes.
+
+Create your todo list first, then Phase 1 (resolve platform/stack, call getDependencies, scan, build lists), then Phase 2 (report and ask). Do not perform Phase 3 until the user replies.`;
       return {
-        description: "Setup design system in project (atomix-setup). Create todo list; Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
+        description: "Get started with design system in project (/--getstarted). Create todo list; Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
         messages: [
           {
             role: "user",
@@ -2807,12 +2871,12 @@ ${tokenSummary}
 | Command | What to expect |
 |---------|----------------|
 | **/--hello** | Get started - overview, tokens, and tools. Run this first! |
-| **/--setup** | Setup design system in project. Three phases; creates files only after you approve. |
+| **/--getstarted** | Get started with design system in project. Three phases; creates files only after you approve. |
 | **/--rules** | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). |
 | **/--sync** | Sync tokens to a local file. Safe: adds new, updates existing, marks deprecated. |
 | **/--refactor** | Migrate deprecated tokens in codebase. Run after /--sync. |
 
-**Suggested next step:** Run **/--setup** to set up global styles, icons, fonts, and token files; the AI will list options and ask before adding anything.
+**Suggested next step:** Run **/--getstarted** to set up global styles, icons, fonts, and token files; the AI will list options and ask before adding anything.
 
 ---