@symbo.ls/mcp 1.0.0

package/symbols_mcp/skills/CLI_QUICK_START.md

@@ -0,0 +1,205 @@
+## `smbls` CLI Quick Start (practical starter guide)
+
+This guide matches the CLI commands implemented in `packages/cli/bin/*`.
+
+### What you’ll get
+
+- **A local starter project** (DOMQL) cloned from an official starter repo.
+- **A working dev server** you can run with `npm start` (or `yarn start`).
+- **Optional platform linking** so you can sync, collaborate, and manage project files with the Symbols platform.
+
+---
+
+## Install the CLI
+
+Install globally:
+
+```bash
+npm i -g @symbo.ls/cli
+smbls --help
+```
+
+---
+
+## Recommended flow: `smbls project create` → `npm start`
+
+### 1) Create a new project locally (fastest path)
+
+This creates a starter project and writes/updates `symbols.json` in the project root.
+
+```bash
+smbls project create my-app --local-only
+cd my-app
+npm start
+```
+
+### After `npm start`: what to do next
+
+- **Open the URL printed in your terminal** (the starter kit will tell you where it’s running).
+- **Follow the starter page + project README** for “what to edit first” and recommended structure.
+- **Develop with AI in your editor**: keep changes small, run the app, iterate quickly.
+
+### 2) Pick your framework template
+
+Currently the CLI scaffolding supports **DOMQL only**.
+
+```bash
+# DOMQL starter
+smbls project create my-app --local-only --domql
+```
+
+### 3) Choose a package manager
+
+```bash
+smbls project create my-app --local-only --package-manager npm
+# or
+smbls project create my-app --local-only --package-manager yarn
+```
+
+### 4) Skip dependency install (optional)
+
+```bash
+smbls project create my-app --local-only --no-dependencies
+cd my-app
+npm i
+npm start
+```
+
+---
+
+## Platform + community flow (optional, but unlocks collaboration)
+
+If you want the “Symbols platform” benefits (project page/canvas, sharing, collaboration, etc.), link your local folder to a platform project.
+
+### 1) Sign in
+
+```bash
+smbls login
+```
+
+If you have multiple environments/servers configured, you can list/switch them:
+
+```bash
+smbls servers
+smbls servers --select
+```
+
+### 2) Create + link a new platform project (interactive)
+
+This creates the platform project, creates the local starter project, then links them.
+
+```bash
+smbls project create my-app --create-new
+```
+
+What gets written locally:
+
+- **`symbols.json`**: keeps the project key (legacy config used by multiple commands)
+- **`.symbols/config.json`**: stores the platform link (`projectKey`, `projectId`, `apiBaseUrl`, `branch`)
+
+### 3) Link an existing platform project to this folder
+
+Interactive picker:
+
+```bash
+smbls project link .
+```
+
+Or non-interactive:
+
+```bash
+smbls project link . --key your-project.symbo.ls
+# or
+smbls project link . --id <projectId>
+```
+
+---
+
+## The core “sync” commands you’ll use day-to-day
+
+### Fetch the latest platform project into files
+
+`fetch` downloads the latest project snapshot and can generate/update files under a `distDir`.
+
+```bash
+smbls fetch --update
+```
+
+Notes:
+
+- **Default output directory** (if you don’t set one) is `./smbls`.
+- You can set it once via:
+
+```bash
+smbls config --dist-dir ./smbls
+```
+
+### Push local changes to the platform
+
+Use this when you’ve edited locally and want to publish your changes upstream.
+
+```bash
+smbls push
+```
+
+### Sync (two-way) with conflict handling
+
+Use this when both local and remote changed and you want an interactive merge flow.
+
+```bash
+smbls sync
+```
+
+### Collaborate (watch + live syncing)
+
+Run in a separate terminal while you work to enable a collaboration workflow (watching local changes and syncing).
+
+```bash
+smbls collab
+```
+
+---
+
+## File assets (uploads/downloads) linked to a project
+
+These commands manage the project `files` map (upload, download, list, remove).
+
+```bash
+smbls files list
+smbls files upload
+smbls files download
+smbls files rm
+```
+
+---
+
+## If something fails: quick fixes
+
+- **Auth required / access denied**: run `smbls login` again.
+- **Missing project key**: ensure `symbols.json` has a `key` or link the folder via `smbls project link .`.
+- **Need more detail**: add `--verbose` where supported (for example on `project create`).
+
+---
+
+## Alternative: `smbls create` (simple scaffolding)
+
+If you only want the starter project and don’t care about platform linking yet:
+
+```bash
+smbls create my-app
+cd my-app
+npm start
+```
+
+---
+
+## Suggested “team” defaults (optional)
+
+- **Commit `symbols.json`**: it’s the minimal project identity/config used by the CLI.
+- **Decide on committing `.symbols/config.json`**: it contains the project link (`projectId`, `projectKey`, `apiBaseUrl`, `branch`). Some teams commit it for consistency; others treat it as local-only.
+
+---
+
+## Symbols Feedback Conventions
+
+Supplemental conventions are merged into [CLAUDE.md](CLAUDE.md).

package/symbols_mcp/skills/DESIGN_CRITIQUE.md

@@ -0,0 +1,64 @@
+The Design Critique Partner
+
+You are a Design Director at Apple reviewing work from your team.
+
+Perform a comprehensive design critique of the following:
+
+[DESIGN DESCRIPTION, WIREFRAME, OR UPLOADED DESIGN]
+
+Critique framework (be thorough but constructive):
+
+1. HEURISTIC EVALUATION
+   Evaluate against Nielsen's 10 heuristics:
+   □ Visibility of system status
+   □ Match between system and real world
+   □ User control and freedom
+   □ Consistency and standards
+   □ Error prevention
+   □ Recognition rather than recall
+   □ Flexibility and efficiency of use
+   □ Aesthetic and minimalist design
+   □ Help users recognize, diagnose, and recover from errors
+   □ Help and documentation
+
+   Score each 1-5 and provide specific examples.
+
+2. VISUAL HIERARCHY ANALYSIS
+   • What's the first thing users see? (Is it correct?)
+   • What's the call-to-action hierarchy?
+   • Are visual weights balanced?
+   • Is there adequate white space?
+
+3. TYPOGRAPHY AUDIT
+   • Font choices appropriate for brand?
+   • Type scale creates clear hierarchy?
+   • Line lengths optimal (45-75 characters)?
+   • Contrast sufficient for readability?
+
+4. COLOR ANALYSIS
+   • Palette supports brand personality?
+   • Sufficient contrast for accessibility (WCAG AA)?
+   • Color used meaningfully (not just decoratively)?
+   • Dark mode considerations?
+
+5. USABILITY CONCERNS
+   • Cognitive load assessment (too much information?)
+   • Interaction clarity (do users know what's clickable?)
+   • Mobile touch targets (minimum 44×44pt?)
+   • Form usability (label placement, validation)
+
+6. STRATEGIC ALIGNMENT
+   • Does this serve business goals?
+   • Does it serve user goals?
+   • Is the value proposition clear?
+   • Would this differentiate from competitors?
+
+7. PRIORITIZED RECOMMENDATIONS
+   • Critical (must fix before launch): [LIST]
+   • Important (fix in next iteration): [LIST]
+   • Polish (nice to have): [LIST]
+
+8. REDESIGN DIRECTION
+   Provide 2 alternative approaches with sketches described in words.
+
+Tone: Constructive, educational, actionable. This is a teaching moment.

package/symbols_mcp/skills/DESIGN_DIRECTION.md

@@ -0,0 +1,320 @@
+# AI Agent Context — Modern UI / UX Direction
+
+## Objective
+
+Generate visually striking, contemporary interfaces that demonstrate clarity, authority, and perceptual refinement. Output must optimize cognitive flow, aesthetic coherence, and interaction intuitiveness without introducing system implementation assumptions or design-system mechanics.
+
+This context governs visual direction, composition behavior, and user-experience reasoning only.
+
+---
+
+## Core Perceptual Goals
+
+### 1 — Immediate Comprehension
+
+Interfaces must communicate structure and purpose within seconds.
+
+- Primary action obvious without search
+- Information hierarchy visually evident
+- Navigation intent inferable without labels
+- No visual noise competing with task completion
+
+---
+
+### 2 — Cognitive Load Minimization
+
+Design reduces interpretation effort.
+
+- Avoid dense clustering of elements
+- Use whitespace to segment meaning
+- Present progressive disclosure of complexity
+- Prioritize recognition over recall
+
+---
+
+### 3 — Visual Authority
+
+UI must appear deliberate and engineered.
+
+- Balanced composition
+- Confident typographic scale
+- Stable alignment
+- Clear focal anchors
+
+Avoid:
+
+- Arbitrary decoration
+- Trend imitation without structural value
+- Visual gimmicks
+
+---
+
+### 4 — Emotional Tone
+
+Target tone:
+
+- Precise
+- Calm
+- Intelligent
+- Contemporary
+
+Avoid:
+
+- Playfulness unless product-specific
+- Excessive personality signaling
+- Novelty-first visual choices
+
+---
+
+## Visual Direction Framework
+
+### Composition Strategy
+
+Construct layouts around focal gravity.
+
+- Define primary visual center
+- Arrange secondary elements in orbit
+- Maintain directional eye flow
+- Avoid visual dead zones
+
+Preferred flows:
+
+- Top-down scanning
+- Z-pattern
+- Layered depth grouping
+
+---
+
+### Spatial Relationships
+
+Spacing conveys meaning.
+
+- Proximity indicates relation
+- Separation indicates conceptual boundary
+- Density signals priority
+- Openness signals optionality
+
+Never treat spacing as decoration.
+
+---
+
+### Hierarchy Signaling
+
+Hierarchy must be perceivable without reading text.
+
+Use:
+
+- Size contrast
+- Weight contrast
+- Positional prominence
+- Color emphasis
+- Depth layering
+
+Avoid relying solely on color changes.
+
+---
+
+### Depth & Layering
+
+Depth creates structural understanding.
+
+Modern approaches:
+
+- Soft elevation separation
+- Subtle translucency
+- Foreground isolation
+- Background de-emphasis
+
+Avoid:
+
+- Overlapping without hierarchy
+- Excessive blur
+- Artificial skeuomorphism
+
+---
+
+### Color Usage Philosophy
+
+Color directs attention and emotional framing.
+
+- Use restrained palettes
+- Reserve high saturation for action or importance
+- Maintain visual stability across screens
+- Prevent color dominance conflicts
+
+Avoid:
+
+- Rainbow distribution
+- Decorative gradients everywhere
+- Competing accent colors
+
+---
+
+### Typography Expression
+
+Typography establishes personality and clarity.
+
+- Confident scale transitions
+- Consistent rhythm
+- Strong headline anchoring
+- Comfortable reading density
+
+Avoid:
+
+- Typography treated as ornament
+- Excessive weight variation
+- Alignment inconsistency
+
+---
+
+## Interaction Direction
+
+### Behavioral Clarity
+
+Every interactive element must visually indicate affordance.
+
+- Clickable looks actionable
+- Draggable looks movable
+- Expandable looks expandable
+
+Ambiguity prohibited.
+
+---
+
+### Feedback Philosophy
+
+System responses must feel immediate and informative.
+
+- State changes visible
+- Action confirmation perceptible
+- Errors recoverable
+- Progress perceivable
+
+Avoid silent transitions.
+
+---
+
+### Motion Character
+
+Motion exists to communicate state or continuity.
+
+Appropriate uses:
+
+- Focus guidance
+- Structural transition
+- Causality explanation
+
+Avoid:
+
+- Decorative animation
+- Distracting motion
+- Excessive choreography
+
+---
+
+### Navigation Experience
+
+Navigation should create spatial orientation.
+
+- Predictable structure
+- Clear location awareness
+- Easy return paths
+- Minimal disorientation
+
+Avoid:
+
+- Hidden hierarchy
+- Mode confusion
+- Unexpected context shifts
+
+---
+
+## Responsiveness Experience Direction
+
+Design must preserve intent across environments.
+
+- Maintain hierarchy integrity
+- Preserve interaction accessibility
+- Ensure readability
+- Keep actions discoverable
+
+Avoid:
+
+- Content collapse hiding key functions
+- Layout fragmentation
+- Interaction shrinking
+
+---
+
+## Accessibility as UX Quality
+
+Accessibility treated as experience optimization.
+
+- Perceptual clarity
+- Motor accessibility
+- Cognitive simplicity
+- Readable contrast
+- Focus visibility
+
+Avoid treating accessibility as compliance-only.
+
+---
+
+## Error States & Empty States
+
+### Empty States
+
+- Provide direction
+- Reduce uncertainty
+- Encourage next action
+
+### Error States
+
+- Explain clearly
+- Enable recovery
+- Avoid alarm tone
+
+These states influence perceived maturity of the product.
+
+---
+
+## Visual Sophistication Indicators
+
+Generated UI should exhibit:
+
+- Intentional restraint
+- Structural balance
+- Clear priority signaling
+- Confident negative space
+- Subtle depth orchestration
+- Measured color emphasis
+- Typographic authority
+
+---
+
+## Common Model Mistakes to Prevent
+
+- Overcrowding layouts
+- Symmetry overuse
+- Center-alignment dominance
+- Excess shadow stacking
+- Trend dumping (multiple stylistic trends combined indiscriminately)
+- Decorative icons without meaning
+- Excess panels/cards
+- Inconsistent focal anchors
+- Emotional overstimulation
+- Visual indecision
+
+---
+
+## Expected Outcome Characteristics
+
+UI must demonstrate:
+
+- Immediate usability
+- Visual precision
+- Perceptual stability
+- Navigational predictability
+- Controlled expressiveness
+- Cohesive modern identity
+- Experience confidence

package/symbols_mcp/skills/DESIGN_SYSTEM_ARCHITECT.md

@@ -0,0 +1,64 @@
+The Design System Architect
+
+You are a Principal Designer at Apple, responsible for the Human Interface Guidelines.
+
+Create a comprehensive design system for [BRAND/PRODUCT NAME].
+
+Brand attributes:
+
+- Personality: [MINIMALIST/BOLD/PLAYFUL/PROFESSIONAL/LUXURY]
+- Primary emotion: [TRUST/EXCITEMENT/CALM/URGENCY]
+- Target audience: [DEMOGRAPHICS]
+
+Deliverables following Apple HIG principles:
+
+1. FOUNDATIONS
+   • Color system:
+   - Primary palette (6 colors with hex, RGB, HSL, accessibility ratings)
+   - Semantic colors (success, warning, error, info)
+   - Dark mode equivalents with contrast ratios
+   - Color usage rules (what each color means and when to use it)
+
+   • Typography:
+   - Primary font family with 9 weights (Display, Headline, Title, Body, Callout, Subheadline, Footnote, Caption)
+   - Type scale with exact sizes, line heights, letter spacing for desktop/tablet/mobile
+   - Font pairing strategy
+   - Accessibility: Minimum sizes for legibility
+
+   • Layout grid:
+   - 12-column responsive grid (desktop: 1440px, tablet: 768px, mobile: 375px)
+   - Gutter and margin specifications
+   - Breakpoint definitions
+   - Safe areas for notched devices
+
+   • Spacing system:
+   - Usage guidelines for each scale step
+
+2. COMPONENTS (Design 30+ components with variants)
+   • Navigation: Header, Tab bar, Sidebar, Breadcrumbs
+   • Input: Buttons (6 variants), Text fields, Dropdowns, Toggles, Checkboxes, Radio buttons, Sliders
+   • Feedback: Alerts, Toasts, Modals, Progress indicators, Skeleton screens
+   • Data display: Cards, Tables, Lists, Stats, Charts
+   • Media: Image containers, Video players, Avatars
+
+   For each component:
+   - Anatomy breakdown (parts and their names)
+   - All states (default, hover, active, disabled, loading, error)
+   - Usage guidelines (when to use, when NOT to use)
+   - Accessibility requirements (ARIA labels, keyboard navigation, focus states)
+   - Code-ready specifications (padding, margins, border-radius, shadows)
+
+3. PATTERNS
+   • Page templates: Landing page, Dashboard, Settings, Profile, Checkout
+   • User flows: Onboarding, Authentication, Search, Filtering, Empty states
+   • Feedback patterns: Success, Error, Loading, Empty
+
+4. TOKENS
+   • Complete design token structure the following Symbols instructions
+
+5. DOCUMENTATION
+   • Design principles (3 core principles with examples)
+   • Do's and Don'ts (10 examples with visual descriptions)
+   • Implementation guide for developers
+
+Format as a design system documentation that could be published immediately.