@symbo.ls/mcp 1.0.24 → 1.0.26

package/README.md

@@ -105,16 +105,50 @@ No API keys required for documentation tools. Project management tools require a
 pip install symbols-mcp
 ```
 
-Or with `uv`:
+Or with `uv` (no install needed):
 
 ```bash
 uvx symbols-mcp
 ```
 
+Or via npm:
+
+```bash
+npx @symbo.ls/mcp
+```
+
 ## Configuration
 
-Add to your MCP client config (e.g. `mcp.json`):
+### Recommended (auto-updates on every launch)
 
+```json
+{
+  "mcpServers": {
+    "symbols": {
+      "command": "uvx",
+      "args": ["--refresh", "symbols-mcp"]
+    }
+  }
+}
+```
+
+The `--refresh` flag checks PyPI for a newer version each time the server starts. Adds ~1-2s to startup but ensures you always have the latest rules and documentation.
+
+### Alternative configs
+
+**npm (also auto-updates):**
+```json
+{
+  "mcpServers": {
+    "symbols": {
+      "command": "npx",
+      "args": ["-y", "@symbo.ls/mcp"]
+    }
+  }
+}
+```
+
+**Pinned version (manual updates):**
 ```json
 {
   "mcpServers": {
@@ -126,6 +160,19 @@ Add to your MCP client config (e.g. `mcp.json`):
 }
 ```
 
+### Manual update
+
+```bash
+# pip
+pip install --upgrade symbols-mcp
+
+# uv (clear cache and re-run)
+uv cache clean symbols-mcp && uvx symbols-mcp
+
+# npm
+npm update -g @symbo.ls/mcp
+```
+
 ### Transport modes
 
 By default, the server runs over **stdio**. For SSE transport:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "Symbols.app MCP — docs, code generation, publishing, CLI/SDK reference",
   "mcpName": "io.github.symbo-ls/symbols-mcp",
   "files": [

package/symbols_mcp/skills/AUDIT.md

@@ -6,8 +6,6 @@ Follow this protocol exactly. Execute each phase in order. Do not skip steps.
 
 ## 1. Install the MCP Server
 
-Run the following command to install:
-
 ```bash
 pip install symbols-mcp
 ```
@@ -16,14 +14,14 @@ pip install symbols-mcp
 
 ## 2. Configure the MCP Server
 
-Add this configuration to your MCP settings:
+Add this configuration to your MCP settings (uses `--refresh` to auto-update on every launch):
 
 ```json
 {
   "mcpServers": {
     "symbols": {
       "command": "uvx",
-      "args": ["symbols-mcp"]
+      "args": ["--refresh", "symbols-mcp"]
     }
   }
 }

package/symbols_mcp/skills/COMMON_MISTAKES.md

@@ -298,3 +298,33 @@ Dropdown: {
 ```
 
 Use `show` only for elements that should be fully removed from layout with no animation. For modals, dropdowns, tooltips, drawers — always use the opacity pattern.
+
+---
+
+## 17. CSS selectors — nest media and pseudo, never chain into one string
+
+```js
+// ❌ WRONG — chained selector string
+'@dark :hover': { background: 'blue' }
+'@mobileL :focus': { outline: 'none' }
+
+// ✅ CORRECT — nested objects
+'@dark': { ':hover': { background: 'blue' } }
+'@mobileL': { ':focus': { outline: 'none' } }
+```
+
+---
+
+## 18. Colors — define once, shade with modifiers, not Tailwind-style palettes
+
+```js
+// ❌ WRONG — multiple shade definitions
+color: {
+  blue50: '#eff6ff', blue100: '#dbeafe', blue200: '#bfdbfe',
+  blue300: '#93c5fd', blue400: '#60a5fa', blue500: '#3b82f6',
+}
+
+// ✅ CORRECT — single base, use modifiers in components
+color: { blue: '#0474f2' }
+// Then: 'blue.7' (opacity), 'blue+20' (lighten), 'blue-30' (darken)
+```

package/symbols_mcp/skills/DEFAULT_STYLES.md

@@ -64,7 +64,7 @@ export default {
 }
 ```
 
-**Note:** Array values like `['--gray 1 -168', '--gray 1 +168']` are `[@dark, @light]` theme pairs. Use semantic names (`title`, `caption`, `paragraph`, `disabled`, `line`) for text colors.
+**Note:** Array values are `[@dark, @light]` theme pairs. Format: `'--colorName opacity tone'` where `--` is the color reference prefix, opacity is 0-1, and tone is `+N`/`-N` (RGB delta) or `=N` (HSL lightness %). Use semantic names (`title`, `caption`, `paragraph`, `disabled`, `line`) for text colors.
 
 ---
 

package/symbols_mcp/skills/DESIGN_SYSTEM.md

@@ -53,28 +53,63 @@ Card: {
 
 ### Adaptive semantic colors
 
-Array syntax `[darkValue, lightValue]` with relative tone shifts from gray:
+Array syntax `[darkValue, lightValue]` — values prefixed with `--` are resolved as color references using space-separated format: `'--colorName opacity tone'`.
+
+The `--` prefix tells the parser to resolve the value as a color reference (strip `--`, split by space, look up the color, apply opacity and tone). This is NOT a CSS variable — it's the Symbols color reference syntax.
+
+```js
+title: ['--gray 1 -168', '--gray 1 +168'],
+//       ↑name  ↑alpha ↑tone
+// Dark: gray at full opacity, darkened 168 RGB
+// Light: gray at full opacity, lightened 168 RGB
+```
 
 | Token | Dark | Light | Use |
 |---|---|---|---|
-| `title` | near-white (+168) | near-black (-168) | Primary text |
-| `caption` | mid-gray (+68) | mid-gray (-68) | Secondary/meta |
-| `paragraph` | lighter-gray (+42) | darker-gray (-42) | Body copy |
-| `disabled` | dimmer-gray (+26) | dimmer-gray (-26) | Disabled state |
-| `line` | subtle-gray (+16) | subtle-gray (-16) | Borders/dividers |
+| `title` | `'--gray 1 -168'` | `'--gray 1 +168'` | Primary text |
+| `caption` | `'--gray 1 -68'` | `'--gray 1 +68'` | Secondary/meta |
+| `paragraph` | `'--gray 1 -42'` | `'--gray 1 +42'` | Body copy |
+| `disabled` | `'--gray 1 -26'` | `'--gray 1 +26'` | Disabled state |
+| `line` | `'--gray 1 -16'` | `'--gray 1 +16'` | Borders/dividers |
 
-### Color modifier syntax (dot-notation)
+### Color modifier syntax — the Symbols shading system
 
-Dot = opacity. `+`/`-` = relative tone shift. `=` = absolute lightness.
+**Define each color ONCE as a single base value.** Generate all shades dynamically using modifiers — never define multiple shade variants of the same color (no `blue100`, `blue200`, `blue300` etc.).
 
-```
-'gray.95-68'      // 95% opacity, darkened 68 steps
-'gray+168'        // full opacity, lightened 168 steps
-'white-78'        // white darkened 78 steps
-'primary.5'       // primary at 50% opacity
-'primary+5'       // shifted tone
-'gray=90'         // absolute 90% lightness
-'gray.5+15'       // 50% opacity + 15 lighter
+| Modifier | Syntax | Example | Effect |
+|----------|--------|---------|--------|
+| Opacity | `.XX` | `'blue.7'` | 70% opacity (0.7) |
+| Lighten | `+N` | `'gray+50'` | Add N to each RGB channel (0-255) |
+| Darken | `-N` | `'gray-68'` | Subtract N from each RGB channel |
+| Absolute | `=N` | `'gray=90'` | Set HSL lightness to N% |
+| Combined | `.XX+N` | `'gray.85+8'` | 85% opacity + lighten by 8 RGB |
+
+```js
+// ✅ CORRECT — one base color, shades via modifiers
+color: {
+  blue: '#0474f2',
+  gray: '#4e4e50',
+}
+
+// Use in components:
+background: 'blue'       // base
+background: 'blue.8'     // 80% opacity
+background: 'blue+20'    // lightened
+background: 'blue-30'    // darkened
+color: 'gray.5+15'       // 50% opacity + 15 lighter
+borderColor: 'gray+100'  // light gray border
+
+// ❌ WRONG — Tailwind-style shade palette (DO NOT DO THIS)
+color: {
+  blue50: '#eff6ff',
+  blue100: '#dbeafe',
+  blue200: '#bfdbfe',
+  blue300: '#93c5fd',
+  blue400: '#60a5fa',
+  blue500: '#3b82f6',
+  blue600: '#2563eb',
+  // ... redundant — just use 'blue+N' / 'blue-N' modifiers
+}
 ```
 
 Opacity rules:
@@ -250,18 +285,32 @@ Title: { fontWeight: 700 }
 
 Golden Ratio scale (1.618 default). Applies to `padding`, `margin`, `gap`, `width`, `height`, `boxSize`, `borderRadius`/`round`, `inset`, `top`, `left`, `right`, `bottom`, etc.
 
-| Token | Approx value | Use |
+### Token stepping system
+
+Each letter is a major step. Sub-numbers are minor increments between letters. The sequence flows continuously — each sub-step is one tone increase:
+
+```
+... X < X1 < X2 < Z < Z1 < Z2 < A < A1 < A2 < A3 < B < B1 < B2 < B3 < C ...
+```
+
+How many sub-steps exist between letters depends on the range — smaller ranges (W, X) have only 1-2 sub-steps, larger ranges (A, B, C) have up to 3.
+
+**To increase slightly:** go up one sub-step (e.g. `A` → `A1`, or `B2` → `B3`)
+**To increase moderately:** go up one letter (e.g. `A` → `B`)
+**To decrease:** reverse direction (e.g. `B` → `A3`, or `A` → `Z2`)
+
+| Token range | Approx px | Use |
 |---|---|---|
-| `W`-`W2` | 2-4 px | Micro gaps, offsets |
-| `X`-`X2` | 4-6 px | Icon padding, tight gaps |
-| `Z`-`Z2` | 10-16 px | Compact padding |
-| `A`-`A2` | 16-26 px | Default padding, gutters |
-| `B`-`B2` | 26-42 px | Section padding |
-| `C`-`C2` | 42-68 px | Container padding, avatar sizes |
-| `D`-`D2` | 68-110 px | Large sections |
-| `E`-`F` | 110-178 px | Hero padding, max-widths |
-
-Sub-sequence rules: `W` and `X` only have `W`, `W1`, `W2` and `X`, `X1`, `X2`. Sub-tokens like `W4`, `X4` do NOT exist. Sub-steps `3` and `4` (e.g. `A3`, `A4`, `B3`, `B4`) only appear from `A` and above.
+| `W`-`W2` | 2-4 | Micro gaps, offsets |
+| `X`-`X2` | 4-6 | Icon padding, tight gaps |
+| `Z`-`Z2` | 10-16 | Compact padding |
+| `A`-`A3` | 16-26 | Default padding, gutters |
+| `B`-`B3` | 26-42 | Section padding |
+| `C`-`C3` | 42-68 | Container padding, avatar sizes |
+| `D`-`D3` | 68-110 | Large sections |
+| `E`-`F` | 110-178 | Hero padding, max-widths |
+
+Typography tokens use the same letter system for `fontSize`.
 
 ### Shorthand spacing
 

package/symbols_mcp/skills/RULES.md

@@ -1213,3 +1213,42 @@ When creating new apps, always base the design system on the default template at
 
 Never use font sizes smaller than what the default template defines. The default template enforces recommended, readable sizing for all new projects.
 
+---
+
+## Rule 45 — Define each color ONCE — use modifier syntax for shades, not Tailwind-style palettes
+
+Never define multiple shade variants of the same color (`blue100`, `blue200`, `blue300`). Define one base value and use the Symbols shading system: `.XX` (opacity), `+N` (lighten), `-N` (darken), `=N` (absolute lightness).
+
+```js
+// ✅ CORRECT — single base, shades via modifiers in components
+color: { blue: '#0474f2' }
+// → 'blue', 'blue.7', 'blue+20', 'blue-30', 'blue.5+15'
+
+// ❌ WRONG — Tailwind-style shade palette
+color: { blue50: '#eff6ff', blue100: '#dbeafe', blue200: '#bfdbfe', blue300: '#93c5fd' }
+```
+
+---
+
+## Rule 44 — Never chain CSS selectors — use nesting instead
+
+Media queries (`@dark`, `@mobileL`) and pseudo-classes (`:hover`, `:active`) must be nested as separate objects, never chained into a single key string.
+
+```js
+// ❌ WRONG — chained selector string
+Button: {
+  '@dark :hover': { background: 'blue' },
+  '@mobileL :active': { opacity: '0.5' },
+}
+
+// ✅ CORRECT — nested objects
+Button: {
+  '@dark': {
+    ':hover': { background: 'blue' },
+  },
+  '@mobileL': {
+    ':active': { opacity: '0.5' },
+  },
+}
+```
+