@symbo.ls/mcp 1.0.0

package/symbols_mcp/skills/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,257 @@
+# Symbols / DOMQL v3 — AI Agent Instructions
+
+You are working inside a **Symbols/DOMQL v3** project. These rules are absolute and override any general coding instincts. Violations cause silent failures (black page, nothing renders).
+
+---
+
+## 1. Components are OBJECTS — never functions
+
+```js
+// CORRECT
+export const Header = { extends: 'Flex', padding: 'A' }
+
+// WRONG — never
+export const Header = (el, state) => ({ padding: 'A' })
+```
+
+---
+
+## 2. NO imports between project files — EVER
+
+Components reference each other by PascalCase key name in the tree. No `import` statements between `components/`, `pages/`, `functions/`, etc.
+
+```js
+// WRONG
+import { Navbar } from './Navbar.js'
+
+// CORRECT — just use the key name in the tree
+Nav: { extends: 'Navbar' }
+```
+
+---
+
+## 3. `components/index.js` — use `export *` NOT `export * as`
+
+`export * as Foo` wraps everything in a namespace object and **breaks component resolution entirely**.
+
+```js
+// CORRECT
+export * from './Navbar.js'
+export * from './PostCard.js'
+
+// WRONG — this breaks everything
+export * as Navbar from './Navbar.js'
+```
+
+---
+
+## 4. Pages extend `'Page'`, not `'Flex'` or `'Box'`
+
+```js
+// CORRECT
+export const main = { extends: 'Page', ... }
+
+// WRONG
+export const main = { extends: 'Flex', ... }
+```
+
+---
+
+## 5. `pages/index.js` — imports ARE allowed here (it's the registry)
+
+```js
+import { main } from './main.js'
+export default { '/': main }
+```
+
+This is the **only** file where cross-file imports are permitted.
+
+---
+
+## 6. Tab / view switching — use DOM IDs + a function, NOT reactive `display` bindings
+
+Reactive `display: (el, s) => ...` on multiple full-page trees causes rendering failures. Use the DOM ID pattern instead:
+
+```js
+// In page definition — assign ids to views
+HomeView: { id: 'view-home', extends: 'Flex', ... },
+ExploreView: { id: 'view-explore', extends: 'Flex', display: 'none', ... },
+
+// In Navbar onClick
+onClick: (e, el) => { el.call('switchView', 'explore') }
+
+// functions/switchView.js
+export const switchView = function switchView(view) {
+  ['home', 'explore', 'profile'].forEach(function(v) {
+    const el = document.getElementById('view-' + v)
+    if (el) el.style.display = v === view ? 'flex' : 'none'
+  })
+}
+```
+
+---
+
+## 7. `el.call('fn', arg)` — element is `this` inside the function, NOT the first arg
+
+```js
+// functions/myFn.js
+export const myFn = function myFn(arg1) {
+  const node = this.node  // 'this' is the DOMQL element
+}
+
+// In component
+onClick: (e, el) => el.call('myFn', someArg)  // CORRECT
+onClick: (e, el) => el.call('myFn', el, someArg)  // WRONG — el passed twice
+```
+
+---
+
+## 8. Icon rendering — NEVER use `Icon` inside `Button` or `Flex+tag:button`
+
+Use `Svg` atom with `html` prop instead. Key MUST be named `Svg`.
+
+```js
+// CORRECT
+MyBtn: {
+  extends: 'Flex', tag: 'button', flexAlign: 'center center', cursor: 'pointer',
+  Svg: { viewBox: '0 0 24 24', width: '22', height: '22',
+    html: '<path d="..." fill="currentColor"/>' }
+}
+
+// WRONG — Icon will NOT render inside Button
+MyBtn: { extends: 'Button', Icon: { name: 'heart' } }
+```
+
+---
+
+## 9. Use `flexAlign` not `align` for Flex shorthand
+
+```js
+{ extends: 'Flex', flexAlign: 'center center' }  // CORRECT
+{ extends: 'Flex', align: 'center center' }       // WRONG — no effect
+```
+
+---
+
+## 10. State — use `s.update()`, never mutate directly
+
+```js
+onClick: (e, el, s) => s.update({ count: s.count + 1 })  // CORRECT
+onClick: (e, el, s) => { s.count = s.count + 1 }          // WRONG — no re-render
+```
+
+Root-level state (global): `s.root.update({ key: val })`
+
+---
+
+## 11. v3 syntax — never use v2
+
+| v3 ✅ | v2 ❌ |
+|---|---|
+| `extends: 'X'` | `extend: 'X'` |
+| `childExtends: 'X'` | `childExtend: 'X'` |
+| `onClick: fn` | `on: { click: fn }` |
+| props flattened at root | `props: { ... }` wrapper |
+
+---
+
+## 12. All folders are flat — no subfolders
+
+```
+components/Navbar.js       ✅
+components/nav/Navbar.js   ❌
+```
+
+---
+
+## 13. `onRender` — guard against double-init
+
+```js
+onRender: (el) => {
+  if (el.__initialized) return
+  el.__initialized = true
+  // imperative logic here
+}
+```
+
+---
+
+## 14. `childExtends` — MUST be a named component string, never an inline object
+
+Inline `childExtends` objects cause ALL property values to be concatenated as visible text content on every child element.
+
+```js
+// CORRECT — reference a named component
+childExtends: 'NavLink'
+
+// WRONG — dumps all prop values as raw text on every child
+childExtends: {
+  tag: 'button',
+  background: 'transparent',
+  border: '2px solid transparent',  // renders as visible text!
+  color: 'white'
+}
+```
+
+Define the shared style as a named component in `components/`, register it in `components/index.js`, then reference it by name.
+
+---
+
+## 15. Color tokens — NO opacity modifier syntax
+
+`color: 'white .7'` is NOT valid — Symbols renders it as raw text content.
+Define named tokens in `designSystem/COLOR.js` instead:
+
+```js
+// designSystem/COLOR.js
+export default {
+  whiteMuted: 'rgba(255,255,255,0.7)',
+  whiteSubtle: 'rgba(255,255,255,0.6)',
+  whiteFaint:  'rgba(255,255,255,0.5)',
+}
+
+// In component — CORRECT
+{ color: 'whiteMuted' }
+
+// WRONG — renders as literal text, not a style
+{ color: 'white .7' }
+{ color: 'black .5' }
+```
+
+---
+
+## 15. Border shorthand — split into individual props
+
+`border: '2px solid transparent'` in `childExtends` or any Symbols prop renders the raw string as text content. Always split:
+
+```js
+// CORRECT
+{ borderWidth: '2px', borderStyle: 'solid', borderColor: 'transparent' }
+
+// WRONG — raw string appears as visible text
+{ border: '2px solid transparent' }
+```
+
+`border: 'none'` is the only shorthand that works safely.
+
+---
+
+## Project structure quick reference
+
+```
+smbls/
+├── index.js                  # export * as components, export default pages, etc.
+├── state.js                  # export default { ... }
+├── dependencies.js           # export default { 'pkg': 'version' }
+├── components/
+│   ├── index.js              # export * from './Foo.js'  ← flat re-exports
+│   └── Navbar.js             # export const Navbar = { ... }
+├── pages/
+│   ├── index.js              # import + export default { '/': main }
+│   └── main.js               # export const main = { extends: 'Page', ... }
+├── functions/
+│   ├── index.js              # export * from './switchView.js'
+│   └── switchView.js         # export const switchView = function(...) {}
+└── designSystem/
+    └── index.js              # export default { COLOR, THEME, ... }
+```

package/symbols_mcp/skills/BRAND_INDENTITY.md

@@ -0,0 +1,69 @@
+The Brand Identity Creator
+
+You are the Creative Director at Pentagram, the world's most prestigious design firm.
+
+Develop a complete brand identity system for [COMPANY NAME], a [INDUSTRY] company targeting [AUDIENCE].
+
+Brand strategy foundation:
+
+- Mission: [STATEMENT]
+- Vision: [STATEMENT]
+- Values: [3-5 CORE VALUES]
+- Positioning: [HOW THEY'RE DIFFERENT]
+
+Deliverables:
+
+1. BRAND STRATEGY DOCUMENT
+   • Brand story (narrative arc: challenge → transformation → resolution)
+   • Brand personality (human traits using brand archetypes)
+   • Voice and tone matrix (4 dimensions: funny/serious, casual/formal, irreverent/respectful, enthusiastic/matter-of-fact)
+   • Messaging hierarchy (tagline, value proposition, key messages, proof points)
+
+2. VISUAL IDENTITY SYSTEM
+   • Logo concept (3 directions with strategic rationale for each):
+   - Wordmark approach
+   - Symbol/icon approach
+   - Combination approach
+
+   • Logo variations:
+   - Primary (full color)
+   - Secondary (simplified)
+   - Monochrome (black and white)
+   - Reversed (on dark backgrounds)
+   - Minimum size specifications
+   - Clear space requirements
+
+   • Logo usage rules:
+   - Correct applications (5 examples)
+   - Incorrect applications (5 examples with "do not" warnings)
+
+   • Color palette:
+   - Primary colors (2-3): Hex, Pantone, CMYK, RGB values
+   - Secondary colors (3-4): Supporting palette
+   - Neutral colors (4-5): Grays for UI
+   - Accent colors (2-3): For calls-to-action
+   - Color psychology rationale for each choice
+
+   • Typography:
+   - Primary typeface: [SPECIFY OR RECOMMEND]
+   - Secondary typeface: [SPECIFY OR RECOMMEND]
+   - Usage hierarchy (display, headlines, body, captions)
+
+   • Imagery style:
+   - Photography guidelines (mood, lighting, subjects, composition)
+   - Illustration style (if applicable)
+   - Iconography style (line weight, corner radius, fill rules)
+   - Graphic element patterns
+
+3. BRAND APPLICATIONS
+   • Business cards (front and back design)
+   • Letterhead and stationery system
+   • Email signature template
+   • Social media profile templates (avatar, cover images for 5 platforms)
+   • Presentation template (title slide, content slide, data slide, closing slide)
+
+4. BRAND GUIDELINES DOCUMENT
+   • 20-page brand book structure with all rules documented
+   • Asset library organization system
+
+Include a strategic rationale for every design decision. Show your work.

package/symbols_mcp/skills/BUILT_IN_COMPONENTS.md

@@ -0,0 +1,304 @@
+# Built-in atoms and property usage
+
+This document lists the built-in components (atoms and UI kit components) and how their properties are commonly used in Symbols/DOMQL v3.
+
+## Built-in atoms
+
+- `Text` -> <span>
+- `Box` -> <div>
+- `Flex` -> <div>
+- `Grid` -> <div>
+- `Link` -> <a>
+- `Input` -> <input>
+- `Radio` -> <input>
+- `Checkbox` -> <input>
+- `Svg` -> <svg>
+- `Icon` -> <svg> (icon sprite)
+- `IconText` -> <div>
+- `Button` -> <button>
+- `Img` -> <img>
+- `Iframe` -> <iframe>
+- `Video` -> <video>
+
+## Built-in components (UI kit)
+
+These are the higher-level components shipped in the UI kit. They are composed from atoms and share the same prop rules.
+
+- `Avatar`
+- `Button`
+- `Dialog`
+- `Dropdown`
+- `Icon`
+- `Input`
+- `Link`
+- `Notification`
+- `Range`
+- `Select`
+- `Tooltip`
+
+## Property usage by atom
+
+These components all use flattened props (no `props` wrapper) and `onX` events.
+
+### Text
+
+Primary use: inline text content.
+
+Common props:
+
+- `text`: string or binding (e.g. `'{{ title }}'`)
+- `color`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`
+- `textTransform`, `textDecoration`, `textAlign`
+- `maxWidth`, `overflow`, `whiteSpace`
+
+Example:
+
+```js
+Text: {
+  text: 'Hello',
+  fontSize: 'B',
+  color: 'title'
+}
+```
+
+### Box
+
+Primary use: generic container.
+
+Common props:
+
+- `padding`, `margin`, `border`, `borderRadius`, `background`, `shadow`
+- `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`
+- `position`, `inset`, `top`, `right`, `bottom`, `left`
+- `overflow`, `zIndex`
+
+Example:
+
+```js
+Box: {
+  padding: 'A B',
+  background: 'surface',
+  borderRadius: 'B'
+}
+```
+
+### Flex
+
+Primary use: layout container using flexbox.
+
+Common props:
+
+- `flow` or `flexFlow`
+- `align` or `flexAlign`
+- `alignItems`, `justifyContent`, `gap`
+- `flex`, `flexGrow`, `flexShrink`, `flexBasis`
+- `wrap`
+
+Example:
+
+```js
+Flex: {
+  flow: 'y',
+  align: 'center space-between',
+  gap: 'B'
+}
+```
+
+### Grid
+
+Primary use: layout container using CSS grid.
+
+Common props:
+
+- `columns` or `gridTemplateColumns`
+- `rows` or `gridTemplateRows`
+- `gap`, `columnGap`, `rowGap`
+- `gridAutoFlow`, `gridAutoColumns`, `gridAutoRows`
+
+Example:
+
+```js
+Grid: {
+  columns: 'repeat(3, 1fr)',
+  gap: 'A'
+}
+```
+
+### Link
+
+Primary use: navigation or external link.
+
+Common props:
+
+- `href`, `target`, `rel`
+- `text` or child content
+- `color`, `textDecoration`
+- `onClick`
+
+Example:
+
+```js
+Link: {
+  text: 'Docs',
+  href: '/docs'
+}
+```
+
+### Input
+
+Primary use: text input.
+
+Common props:
+
+- `type`, `name`, `value`, `placeholder`, `required`, `disabled`
+- `onInput`, `onChange`, `onKeydown`
+- `padding`, `background`, `border`, `round`
+
+Example:
+
+```js
+Input: {
+  type: 'text',
+  name: 'title',
+  placeholder: 'Enter title'
+}
+```
+
+### Radio and Checkbox
+
+Primary use: selectable inputs.
+
+Common props:
+
+- `name`, `value`, `checked`, `disabled`
+- `onChange`
+
+Example:
+
+```js
+Checkbox: { name: 'agree', checked: true }
+```
+
+### Svg
+
+Primary use: raw SVG container.
+
+Common props:
+
+- `html` (inline SVG markup)
+- `width`, `height`, `viewBox`, `fill`, `stroke`
+
+Example:
+
+```js
+Svg: { html: '<path d="..." />', viewBox: '0 0 24 24' }
+```
+
+### Icon
+
+Primary use: icon from sprite.
+
+Common props:
+
+- `name` (sprite symbol id)
+- `size` or `boxSize`
+- `color`
+
+Example:
+
+```js
+Icon: { name: 'chevronRight', boxSize: 'A' }
+```
+
+### IconText
+
+Primary use: icon + text combo.
+
+Common props:
+
+- `icon`, `text`
+- `gap`, `align`, `color`
+
+Example:
+
+```js
+IconText: { icon: 'search', text: 'Search', gap: 'Z' }
+```
+
+### Button
+
+Primary use: actionable control.
+
+Common props:
+
+- `text`, `icon`, `type`, `disabled`
+- `theme`, `padding`, `round`
+- `onClick`, `onSubmit`
+
+Example:
+
+```js
+Button: { text: 'Save', theme: 'primary', type: 'submit' }
+```
+
+### Img
+
+Primary use: image element.
+
+Common props:
+
+- `src`, `alt`, `loading`
+- `width`, `height`, `boxSize`, `objectFit`
+
+Example:
+
+```js
+Img: { src: '/logo.png', alt: 'Logo', boxSize: 'B' }
+```
+
+### Iframe
+
+Primary use: embedded content.
+
+Common props:
+
+- `src`, `title`, `allow`, `sandbox`
+- `width`, `height`, `border`
+
+Example:
+
+```js
+Iframe: { src: 'https://example.com', width: '100%', height: '300px' }
+```
+
+### Video
+
+Primary use: video player.
+
+Common props:
+
+- `src`, `poster`, `controls`, `autoplay`, `muted`, `loop`
+- `width`, `height`, `objectFit`
+
+Example:
+
+```js
+Video: { src: '/demo.mp4', controls: true, width: '100%' }
+```
+
+## Cross-cutting props
+
+All atoms can also use:
+
+- `@media` keys (e.g. `@mobile`)
+- pseudo selectors (e.g. `:hover`, `:active`)
+- conditional cases (e.g. `.isActive`, `!isActive`)
+- `childProps` for one-level child overrides
+- `children` arrays or nested object trees
+- `onInit`, `onRender`, `onUpdate`, `onStateUpdate`
+
+---
+
+## Symbols Feedback Conventions
+
+Supplemental conventions are merged into [CLAUDE.md](CLAUDE.md).