raven-mcp 1.0.0

package/src/data/principles/nielsen-heuristics.json

@@ -0,0 +1,258 @@
+[
+  {
+    "id": "visibility-of-system-status",
+    "name": "Visibility of System Status",
+    "category": "nielsen-heuristics",
+    "summary": "The design should always keep users informed about what is going on, through appropriate feedback within a reasonable amount of time.",
+    "description": "Users should never have to wonder about the current state of the system. Every action should produce visible, immediate feedback. Progress indicators, loading states, success confirmations, and error messages all serve this heuristic. The system should proactively communicate state changes rather than leaving users to guess.",
+    "implications": [
+      "Show loading indicators for any operation over 1 second",
+      "Provide progress bars for multi-step processes",
+      "Confirm successful actions with visual feedback (toast, check mark, color change)",
+      "Display real-time validation on form inputs",
+      "Show current location in navigation (breadcrumbs, active nav state)",
+      "Indicate unsaved changes before the user navigates away",
+      "Use skeleton screens instead of blank loading states"
+    ],
+    "violations": [
+      "A form submits with no visual feedback — user clicks again, creating duplicates",
+      "File upload with no progress bar — user doesn't know if it's working",
+      "No active state on navigation — user doesn't know which page they're on",
+      "Long-running process with no indication of progress or estimated time",
+      "Button click with no visual response (no disabled state, no spinner)"
+    ],
+    "applies_to": ["loading", "forms", "navigation", "feedback", "progress", "empty-states", "error-states"],
+    "sources": ["https://www.nngroup.com/articles/visibility-system-status/"]
+  },
+  {
+    "id": "match-real-world",
+    "name": "Match Between System and the Real World",
+    "category": "nielsen-heuristics",
+    "summary": "The design should speak the users' language. Use words, phrases, and concepts familiar to the user, rather than internal jargon.",
+    "description": "Information should appear in a natural and logical order, following real-world conventions. The interface should use language and metaphors the target users already understand. Icons should map to real-world objects users recognize. Workflows should follow real-world task sequences rather than system architecture.",
+    "implications": [
+      "Use domain-specific language your users actually use, not internal product terms",
+      "Order information following real-world conventions (dates, addresses, names)",
+      "Use icons and metaphors that map to physical-world objects users recognize",
+      "Design workflows that mirror real-world task sequences",
+      "Use natural language for labels and instructions, not technical jargon",
+      "Show amounts in user's local currency and date format"
+    ],
+    "violations": [
+      "Using 'repository' instead of 'project' for non-developer audiences",
+      "Error codes like 'ERR_404' instead of 'Page not found'",
+      "Technical field names like 'varchar' or 'uuid' visible to end users",
+      "Calendar that starts weeks on Monday in US-locale apps (or Sunday in European ones)",
+      "Using 'tenant' or 'instance' in user-facing copy"
+    ],
+    "applies_to": ["copy", "labels", "navigation", "forms", "error-states", "onboarding"],
+    "sources": ["https://www.nngroup.com/articles/match-system-real-world/"]
+  },
+  {
+    "id": "user-control-freedom",
+    "name": "User Control and Freedom",
+    "category": "nielsen-heuristics",
+    "summary": "Users often perform actions by mistake. They need a clearly marked 'emergency exit' to leave the unwanted action without having to go through an extended process.",
+    "description": "Users need to feel in control. Every destructive or significant action should be undoable. The system should provide clear ways to go back, cancel, or undo. Confirmation dialogs for irreversible actions. Easy navigation back to known states. Users should never feel trapped in a flow they didn't intend to enter.",
+    "implications": [
+      "Support undo/redo for all significant actions",
+      "Provide a clear 'Cancel' option on every modal and multi-step flow",
+      "Allow users to go back to previous steps in multi-step processes",
+      "Use 'soft delete' (trash/archive) instead of permanent deletion",
+      "Show confirmation dialogs only for truly irreversible actions",
+      "Let users exit onboarding flows and return later",
+      "Provide a 'Home' or logo link that always returns to a known state"
+    ],
+    "violations": [
+      "Permanent deletion with no undo or archive option",
+      "Multi-step wizard with no back button",
+      "Modal that can only be dismissed by completing the action",
+      "Onboarding flow that can't be skipped or paused",
+      "No way to unsend or edit a message after sending",
+      "Settings change that takes effect immediately with no revert option"
+    ],
+    "applies_to": ["modals", "forms", "navigation", "settings", "destructive-actions", "onboarding"],
+    "sources": ["https://www.nngroup.com/articles/user-control-and-freedom/"]
+  },
+  {
+    "id": "consistency-standards",
+    "name": "Consistency and Standards",
+    "category": "nielsen-heuristics",
+    "summary": "Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform and industry conventions.",
+    "description": "Jakob's Law applies here — users spend most of their time on other sites and apps. They expect your interface to work the same way. Internal consistency (within your product) and external consistency (with platform conventions) both matter. Design systems exist to enforce this. Breaking convention requires a very good reason.",
+    "implications": [
+      "Use standard platform patterns (hamburger menu, search icon, settings gear)",
+      "Keep terminology consistent across the entire product",
+      "Use the same visual treatment for the same type of action everywhere",
+      "Follow platform conventions for gestures, keyboard shortcuts, and navigation",
+      "Maintain a design system to enforce visual and interaction consistency",
+      "Use standard form patterns (labels above inputs, primary action on the right)"
+    ],
+    "violations": [
+      "Different words for the same action ('Remove' vs 'Delete' vs 'Trash')",
+      "Buttons that look different but do the same thing on different pages",
+      "Non-standard icons (using a heart icon for bookmarking)",
+      "Different navigation patterns on different pages of the same app",
+      "Custom scrollbar behavior that doesn't match OS conventions",
+      "Different date formats on different screens"
+    ],
+    "applies_to": ["buttons", "navigation", "forms", "icons", "copy", "design-system"],
+    "sources": ["https://www.nngroup.com/articles/consistency-and-standards/"]
+  },
+  {
+    "id": "error-prevention",
+    "name": "Error Prevention",
+    "category": "nielsen-heuristics",
+    "summary": "Good error messages are important, but the best designs carefully prevent problems from occurring in the first place.",
+    "description": "There are two types of errors: slips (unconscious mistakes from inattention) and mistakes (conscious errors from incorrect mental models). Prevent slips with good defaults, constraints, and confirmations. Prevent mistakes with clear instructions, affordances, and previews. Error prevention is always better than error recovery.",
+    "implications": [
+      "Use inline validation to catch errors before form submission",
+      "Provide sensible defaults for complex inputs",
+      "Use constrained inputs (dropdowns, date pickers) instead of free text where possible",
+      "Show a confirmation step before irreversible actions",
+      "Disable or hide actions that aren't available in the current context",
+      "Auto-save work to prevent data loss",
+      "Show previews of the result before the user commits to an action"
+    ],
+    "violations": [
+      "Free text input for dates instead of a date picker",
+      "No validation until the entire form is submitted",
+      "Destructive action button right next to the primary action with no confirmation",
+      "Allowing submission of obviously invalid data (negative quantities, past dates for future events)",
+      "No auto-save on long forms — a browser crash loses all work",
+      "Delete button with no confirmation or undo"
+    ],
+    "applies_to": ["forms", "validation", "destructive-actions", "inputs", "settings"],
+    "sources": ["https://www.nngroup.com/articles/slips/"]
+  },
+  {
+    "id": "recognition-over-recall",
+    "name": "Recognition Rather Than Recall",
+    "category": "nielsen-heuristics",
+    "summary": "Minimize the user's memory load by making elements, actions, and options visible. The user should not have to remember information from one part of the interface to another.",
+    "description": "Human short-term memory is limited (Miller's Law). Interfaces should present options visibly rather than requiring users to remember them. Recently used items, search suggestions, contextual help, and visible navigation all reduce cognitive load. Every time a user has to remember something, there's a chance for error.",
+    "implications": [
+      "Show recently used items and searches",
+      "Use descriptive labels instead of icon-only buttons",
+      "Provide search with autocomplete and suggestions",
+      "Show contextual help and tooltips for complex features",
+      "Display relevant information in context rather than requiring navigation",
+      "Use visual cues (color, icons, thumbnails) to aid recognition",
+      "Keep important actions visible, not buried in menus"
+    ],
+    "violations": [
+      "Icon-only toolbar with no labels or tooltips",
+      "Requiring users to remember codes or IDs from a previous screen",
+      "Hidden navigation that requires memorizing keyboard shortcuts",
+      "No search history or recent items",
+      "Complex settings with no preview of what they affect",
+      "Reference numbers shown once with no way to look them up later"
+    ],
+    "applies_to": ["navigation", "search", "forms", "icons", "tooltips", "dashboard"],
+    "sources": ["https://www.nngroup.com/articles/recognition-and-recall/"]
+  },
+  {
+    "id": "flexibility-efficiency",
+    "name": "Flexibility and Efficiency of Use",
+    "category": "nielsen-heuristics",
+    "summary": "Shortcuts — hidden from novice users — can speed up the interaction for the expert user so that the design can cater to both inexperienced and experienced users.",
+    "description": "Interfaces should serve both novices and experts. Accelerators like keyboard shortcuts, customizable workflows, and batch operations let power users work faster without overwhelming beginners. Progressive disclosure shows basic features first with advanced options available on demand. The system should be learnable but also efficient at scale.",
+    "implications": [
+      "Provide keyboard shortcuts for common actions",
+      "Support batch/bulk operations for repetitive tasks",
+      "Allow users to customize their workspace and workflows",
+      "Implement progressive disclosure — basic features first, advanced on demand",
+      "Support command palettes for power users (Cmd+K pattern)",
+      "Allow drag-and-drop as an alternative to menu-driven interactions",
+      "Remember user preferences and recent selections"
+    ],
+    "violations": [
+      "No keyboard shortcuts for any actions",
+      "Forcing users through a wizard for a task they do 50 times a day",
+      "No bulk selection or batch operations on lists",
+      "Expert features mixed in with beginner UI, making both worse",
+      "No way to save or template frequently used configurations",
+      "Search that requires exact matches with no fuzzy matching"
+    ],
+    "applies_to": ["navigation", "keyboard", "power-users", "customization", "search", "workflows"],
+    "sources": ["https://www.nngroup.com/articles/flexibility-efficiency-heuristic/"]
+  },
+  {
+    "id": "aesthetic-minimalist-design",
+    "name": "Aesthetic and Minimalist Design",
+    "category": "nielsen-heuristics",
+    "summary": "Interfaces should not contain information that is irrelevant or rarely needed. Every extra unit of information in an interface competes with the relevant units of information and diminishes their relative visibility.",
+    "description": "This is not about visual minimalism — it's about information minimalism. Every element on the screen should earn its place. Prioritize content that serves the user's primary task. Secondary information should be available on demand, not competing for attention. Visual hierarchy should make the most important content immediately clear. White space is a feature, not wasted space.",
+    "implications": [
+      "Prioritize content by user goals — primary task front and center",
+      "Use progressive disclosure to hide secondary information",
+      "Remove decorative elements that don't communicate meaning",
+      "Use generous whitespace to create visual hierarchy",
+      "Limit choices to reduce cognitive load (Hick's Law)",
+      "Show only the most relevant data; let users drill down for details",
+      "Every visual element should serve a purpose — decoration, distinction, or information"
+    ],
+    "violations": [
+      "Dashboard with 20+ metrics all given equal visual weight",
+      "Settings page showing every option at once with no grouping",
+      "Marketing copy mixed into a task-focused UI",
+      "Decorative animations that slow down task completion",
+      "Cluttered headers with too many navigation items",
+      "Showing database fields the user doesn't need to see"
+    ],
+    "applies_to": ["layout", "dashboard", "navigation", "content", "hierarchy", "whitespace"],
+    "sources": ["https://www.nngroup.com/articles/aesthetic-minimalist-design/"]
+  },
+  {
+    "id": "help-recover-errors",
+    "name": "Help Users Recognize, Diagnose, and Recover from Errors",
+    "category": "nielsen-heuristics",
+    "summary": "Error messages should be expressed in plain language (no error codes), precisely indicate the problem, and constructively suggest a solution.",
+    "description": "When errors happen, the user needs three things: what went wrong, why it went wrong, and how to fix it. Error messages should be written in human language, point to the specific field or action that caused the error, and provide a clear path to resolution. Never blame the user. Never show technical error codes without a human explanation.",
+    "implications": [
+      "Write error messages in plain, non-technical language",
+      "Point to the specific field or input that caused the error",
+      "Suggest a concrete next step to resolve the error",
+      "Use inline validation to show errors next to the relevant field",
+      "Provide a way to recover — retry, edit, go back, or contact support",
+      "Never blame the user ('Invalid input' vs 'Please enter a valid email')",
+      "Log technical details for developers but show human messages to users"
+    ],
+    "violations": [
+      "Generic 'An error occurred' with no details or recovery path",
+      "Technical error codes shown to end users (500 Internal Server Error)",
+      "Error messages that blame the user ('You entered invalid data')",
+      "Validation errors shown at the top of the page, far from the problem field",
+      "Error state with no way to retry or recover without refreshing",
+      "Red text with no explanation of what's wrong or how to fix it"
+    ],
+    "applies_to": ["error-states", "forms", "validation", "feedback", "copy"],
+    "sources": ["https://www.nngroup.com/articles/error-message-guidelines/"]
+  },
+  {
+    "id": "help-documentation",
+    "name": "Help and Documentation",
+    "category": "nielsen-heuristics",
+    "summary": "It's best if the system doesn't need any additional explanation. However, it may be necessary to provide documentation to help users understand how to complete their tasks.",
+    "description": "The best interface needs no documentation. But complex systems often do. When help is needed, it should be contextual (right where the user needs it), searchable, task-oriented (focused on concrete steps), concise, and easy to find. Help should be the last resort, not a crutch for bad design. Tooltips, onboarding tours, and inline guidance are all forms of help.",
+    "implications": [
+      "Provide contextual help tooltips next to complex features",
+      "Include a searchable help center or knowledge base",
+      "Write task-oriented documentation (how to accomplish X, not feature descriptions)",
+      "Offer onboarding tours for first-time users",
+      "Show inline hints for complex or infrequently used features",
+      "Provide example values in form fields (placeholder text)",
+      "Make help accessible without leaving the current context"
+    ],
+    "violations": [
+      "Complex feature with no documentation or tooltip explaining it",
+      "Help docs that are only accessible from a separate website",
+      "Documentation organized by feature, not by user task",
+      "No onboarding or guidance for first-time users",
+      "Tooltip text that's just the field label repeated",
+      "Help that requires reading a 10-page document for a simple task"
+    ],
+    "applies_to": ["tooltips", "onboarding", "documentation", "forms", "complex-features"],
+    "sources": ["https://www.nngroup.com/articles/help-and-documentation/"]
+  }
+]

package/src/data/principles/typography.json

@@ -0,0 +1,117 @@
+[
+  {
+    "id": "type-scale",
+    "name": "Typographic Scale",
+    "category": "typography",
+    "summary": "Use a mathematically consistent type scale to create harmonious size relationships.",
+    "description": "A type scale provides a set of predetermined font sizes based on a ratio (1.125, 1.200, 1.250, 1.333, 1.414, 1.500, 1.618). This creates visual harmony and reduces ad-hoc sizing decisions. Common scales: Minor Third (1.2) for compact UIs, Major Third (1.25) for general use, Perfect Fourth (1.333) for content-heavy sites, Golden Ratio (1.618) for editorial/marketing.",
+    "implications": [
+      "Choose a scale ratio based on content type (1.2 for apps, 1.25-1.333 for marketing)",
+      "Base size of 16px (1rem) for body text on web",
+      "Limit to 5-7 sizes in the scale — more creates noise",
+      "Use the scale for all text: headings, body, captions, labels",
+      "Define the scale in design tokens for consistency across the product",
+      "Adjust scale for mobile — tighter ratios (1.125-1.2) work better on small screens"
+    ],
+    "violations": [
+      "Ad-hoc font sizes (13px, 15px, 17px, 19px) with no systematic relationship",
+      "Too many distinct sizes on one page",
+      "Heading sizes too close together — no clear hierarchy",
+      "Scale too aggressive for the content type (1.618 on a dense data app)"
+    ],
+    "applies_to": ["typography", "hierarchy", "design-system", "headings", "body-text"],
+    "sources": ["https://typescale.com/", "https://alistapart.com/article/more-meaningful-typography/"]
+  },
+  {
+    "id": "line-height-spacing",
+    "name": "Line Height and Spacing",
+    "category": "typography",
+    "summary": "Proper line height and spacing dramatically impacts readability and scannability.",
+    "description": "Line height (leading) should increase with line length and decrease with font size. Body text: 1.4-1.6. Headings: 1.1-1.3. Captions/small text: 1.4-1.5. Paragraph spacing should be approximately equal to line height. Letter spacing (tracking) is generally left at default for body text but may need adjustment for all-caps text (add 0.05-0.1em) and large headings (tighten slightly).",
+    "implications": [
+      "Body text: line-height 1.5 (WCAG recommendation), range 1.4-1.6",
+      "Headings: line-height 1.1-1.3 (tighter for larger text)",
+      "All-caps text: add letter-spacing of 0.05-0.1em for readability",
+      "Large headings (32px+): tighten letter-spacing slightly (-0.01 to -0.03em)",
+      "Paragraph spacing: at least 1.5x the font size (WCAG)",
+      "Consistent spacing between all typographic elements"
+    ],
+    "violations": [
+      "Single line height (line-height: 1.0) on multi-line body text",
+      "All-caps text without added letter-spacing",
+      "Inconsistent line heights across the same text style",
+      "No paragraph spacing — text blocks run together"
+    ],
+    "applies_to": ["typography", "readability", "spacing", "accessibility", "content"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html"]
+  },
+  {
+    "id": "font-pairing",
+    "name": "Font Pairing",
+    "category": "typography",
+    "summary": "Combine typefaces with complementary characteristics for visual variety and hierarchy.",
+    "description": "Effective font pairing creates contrast and hierarchy without chaos. The safest approach: one serif + one sans-serif, or one display + one text face. Look for shared characteristics (x-height, letterform proportions) with contrasting styles (weight, width, classification). Most products need only 1-2 typefaces. Three is the maximum. System font stacks are increasingly preferred for performance.",
+    "implications": [
+      "Use at most 2-3 typefaces in a product",
+      "Pair typefaces with contrasting classification but similar proportions",
+      "Consider system font stacks for performance (Inter, -apple-system, system-ui)",
+      "One typeface for headings/display, one for body/UI — or one family with enough weights",
+      "Variable fonts offer weight/width flexibility with a single font file",
+      "Test pairings at all sizes — what works at 48px may not at 14px"
+    ],
+    "violations": [
+      "4+ different typefaces creating visual chaos",
+      "Two similar sans-serifs that don't create clear contrast",
+      "Display typeface used for body text (poor readability at small sizes)",
+      "Font loading flash causing layout shifts"
+    ],
+    "applies_to": ["typography", "branding", "design-system", "performance", "visual-design"],
+    "sources": ["https://fonts.google.com/knowledge/choosing_type"]
+  },
+  {
+    "id": "text-hierarchy",
+    "name": "Text Hierarchy",
+    "category": "typography",
+    "summary": "Create clear levels of importance through size, weight, color, and spacing.",
+    "description": "Visual hierarchy in text guides the reader through content in order of importance. Primary hierarchy tools: size (the strongest), weight (bold vs regular), color (dark vs muted), and spacing (generous around important items). A clear hierarchy means users can scan the page and immediately identify what's most important. Every text element should clearly belong to one level.",
+    "implications": [
+      "Use 3-4 distinct hierarchy levels: primary (heading), secondary (subheading), body, and muted",
+      "Size is the strongest hierarchy signal — use it for the most important distinction",
+      "Weight creates secondary hierarchy within the same size",
+      "Color (opacity/saturation) creates tertiary hierarchy — muted for less important text",
+      "Combine size + weight + color for maximum hierarchy contrast",
+      "Test hierarchy by squinting — the most important text should still be visible"
+    ],
+    "violations": [
+      "All text the same size and weight — no hierarchy",
+      "Too many hierarchy levels — 6+ sizes that blur the distinctions",
+      "Using only color to create hierarchy (fails for color-blind users)",
+      "Heading and body text too close in size — unclear distinction"
+    ],
+    "applies_to": ["typography", "hierarchy", "layout", "content", "headings", "labels"],
+    "sources": ["https://practicaltypography.com/"]
+  },
+  {
+    "id": "measure-line-length",
+    "name": "Measure (Line Length)",
+    "category": "typography",
+    "summary": "Optimal line length for body text is 45-75 characters per line.",
+    "description": "The 'measure' in typography refers to the width of a text block. Lines that are too long cause the reader's eye to lose its place when returning to the left margin. Lines that are too short break reading rhythm with too many line breaks. The ideal range is 45-75 characters (about 2-3 lowercase alphabets). For multi-column layouts, 40-50 characters per column. Set max-width on text containers, not just the parent.",
+    "implications": [
+      "Body text: 45-75 characters per line (max-width: 65ch is a good default)",
+      "Short-form text (cards, labels): 20-40 characters",
+      "Use max-width on text containers — not on the parent layout",
+      "Wider columns need larger text; narrower columns can use smaller text",
+      "Increase line-height if line length exceeds 65 characters",
+      "Left-align body text for Western languages — centered text is harder to read beyond 3 lines"
+    ],
+    "violations": [
+      "Full-width text spanning 1200px+ viewport — 120+ characters per line",
+      "Text constrained to 200px — constant line breaks, choppy reading",
+      "Centered text in paragraphs — hard to find the start of the next line",
+      "Justified text on the web (inconsistent word spacing)"
+    ],
+    "applies_to": ["typography", "layout", "readability", "responsive", "content"],
+    "sources": ["https://practicaltypography.com/line-length.html"]
+  }
+]

package/src/data/tokens/registry.json

@@ -0,0 +1,67 @@
+{
+  "systems": [
+    {
+      "id": "stripe",
+      "name": "Stripe",
+      "description": "Stripe's design system tokens — clean, professional fintech design with excellent typography and a signature purple accent.",
+      "category": "fintech",
+      "tags": ["professional", "clean", "accessible", "fintech"],
+      "url": "https://stripe.com",
+      "status": "available"
+    },
+    {
+      "id": "linear",
+      "name": "Linear",
+      "description": "Linear's design system tokens — dark-first, minimal, fast. Iconic developer productivity aesthetic.",
+      "category": "productivity",
+      "tags": ["dark", "minimal", "developer", "fast"],
+      "url": "https://linear.app",
+      "status": "available"
+    },
+    {
+      "id": "vercel",
+      "name": "Vercel",
+      "description": "Vercel's Geist design system — monochrome elegance with developer-first aesthetics.",
+      "category": "developer",
+      "tags": ["monochrome", "developer", "minimal", "elegant"],
+      "url": "https://vercel.com/geist",
+      "status": "planned"
+    },
+    {
+      "id": "shadcn",
+      "name": "shadcn/ui",
+      "description": "shadcn/ui component tokens — beautifully designed components using Radix and Tailwind CSS.",
+      "category": "component-library",
+      "tags": ["accessible", "customizable", "tailwind", "radix"],
+      "url": "https://ui.shadcn.com",
+      "status": "planned"
+    },
+    {
+      "id": "github-primer",
+      "name": "GitHub Primer",
+      "description": "GitHub's Primer design system — functional, accessible, scale-tested across one of the world's largest developer platforms.",
+      "category": "design-system",
+      "tags": ["accessible", "enterprise", "developer", "functional"],
+      "url": "https://primer.style",
+      "status": "planned"
+    },
+    {
+      "id": "notion",
+      "name": "Notion",
+      "description": "Notion's design tokens — warm, approachable, content-first design with playful illustrations.",
+      "category": "productivity",
+      "tags": ["warm", "content-first", "approachable", "illustrations"],
+      "url": "https://notion.so",
+      "status": "planned"
+    },
+    {
+      "id": "supabase",
+      "name": "Supabase",
+      "description": "Supabase's design tokens — dark-mode-first developer tool aesthetic with green accent.",
+      "category": "developer",
+      "tags": ["dark", "developer", "green-accent", "technical"],
+      "url": "https://supabase.com",
+      "status": "planned"
+    }
+  ]
+}

package/src/data/tokens/systems/linear.json

@@ -0,0 +1,134 @@
+{
+  "$name": "Linear",
+  "$description": "Linear design system tokens — dark-first, minimal, fast. Iconic developer productivity aesthetic.",
+  "color": {
+    "$type": "color",
+    "primary": { "$value": "#5E6AD2", "$description": "Linear purple — the signature brand color" },
+    "primary-light": { "$value": "#7B83EB", "$description": "Lighter purple for hover" },
+    "primary-dark": { "$value": "#4E5BBF", "$description": "Darker purple for active" },
+    "background": { "$value": "#191A23", "$description": "Dark background" },
+    "background-surface": { "$value": "#1F2028", "$description": "Slightly elevated surface" },
+    "background-raised": { "$value": "#25262F", "$description": "Raised surface (cards, panels)" },
+    "background-overlay": { "$value": "#2C2D3A", "$description": "Overlay background (modals)" },
+    "border": { "$value": "#2E2F3E", "$description": "Default border" },
+    "border-strong": { "$value": "#3E3F4E", "$description": "Strong border" },
+    "text-primary": { "$value": "#F2F2F2", "$description": "Primary text" },
+    "text-secondary": { "$value": "#8A8F98", "$description": "Secondary text" },
+    "text-tertiary": { "$value": "#5E6068", "$description": "Tertiary/muted text" },
+    "text-inverse": { "$value": "#191A23", "$description": "Text on light backgrounds" },
+    "accent-red": { "$value": "#EB5757", "$description": "Urgent/bug priority" },
+    "accent-orange": { "$value": "#F2994A", "$description": "High priority" },
+    "accent-yellow": { "$value": "#F2C94C", "$description": "Medium priority" },
+    "accent-green": { "$value": "#6FCF97", "$description": "Low priority / success" },
+    "accent-blue": { "$value": "#56CCF2", "$description": "No priority / info" },
+    "accent-purple": { "$value": "#BB6BD9", "$description": "Feature label" },
+    "success": { "$value": "#6FCF97", "$description": "Success state" },
+    "error": { "$value": "#EB5757", "$description": "Error state" },
+    "warning": { "$value": "#F2994A", "$description": "Warning state" },
+    "info": { "$value": "#56CCF2", "$description": "Info state" }
+  },
+  "color-light": {
+    "$type": "color",
+    "background": { "$value": "#FFFFFF", "$description": "Light mode background" },
+    "background-surface": { "$value": "#F7F7F8", "$description": "Light mode surface" },
+    "background-raised": { "$value": "#FFFFFF", "$description": "Light mode raised surface" },
+    "border": { "$value": "#E8E8EC", "$description": "Light mode border" },
+    "border-strong": { "$value": "#D4D4DB", "$description": "Light mode strong border" },
+    "text-primary": { "$value": "#1B1C26", "$description": "Light mode primary text" },
+    "text-secondary": { "$value": "#6B6F76", "$description": "Light mode secondary text" },
+    "text-tertiary": { "$value": "#9B9FA5", "$description": "Light mode tertiary text" }
+  },
+  "typography": {
+    "font-family": {
+      "$type": "fontFamily",
+      "body": { "$value": "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif", "$description": "Primary font — Inter for clean UI text" },
+      "display": { "$value": "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif", "$description": "Same family, different weight for display" },
+      "mono": { "$value": "\"JetBrains Mono\", \"Fira Code\", monospace", "$description": "Monospace for code and identifiers" }
+    },
+    "font-size": {
+      "$type": "dimension",
+      "2xs": { "$value": "10px", "$description": "Tiny — status badges" },
+      "xs": { "$value": "11px", "$description": "Extra small — metadata" },
+      "sm": { "$value": "12px", "$description": "Small — secondary labels" },
+      "base": { "$value": "13px", "$description": "Default body text (Linear uses 13px)" },
+      "md": { "$value": "14px", "$description": "Slightly larger body" },
+      "lg": { "$value": "16px", "$description": "Large body / small headings" },
+      "xl": { "$value": "18px", "$description": "Section headings" },
+      "2xl": { "$value": "22px", "$description": "Page headings" },
+      "3xl": { "$value": "28px", "$description": "Large headings" },
+      "4xl": { "$value": "36px", "$description": "Display text" }
+    },
+    "font-weight": {
+      "$type": "fontWeight",
+      "regular": { "$value": "400" },
+      "medium": { "$value": "500" },
+      "semibold": { "$value": "600" },
+      "bold": { "$value": "700" }
+    },
+    "line-height": {
+      "$type": "number",
+      "tight": { "$value": "1.2", "$description": "Headings" },
+      "snug": { "$value": "1.35", "$description": "Compact text" },
+      "normal": { "$value": "1.5", "$description": "Body text" },
+      "relaxed": { "$value": "1.6", "$description": "Long-form content" }
+    }
+  },
+  "spacing": {
+    "$type": "dimension",
+    "0": { "$value": "0px" },
+    "0.5": { "$value": "2px" },
+    "1": { "$value": "4px" },
+    "1.5": { "$value": "6px" },
+    "2": { "$value": "8px" },
+    "3": { "$value": "12px" },
+    "4": { "$value": "16px" },
+    "5": { "$value": "20px" },
+    "6": { "$value": "24px" },
+    "8": { "$value": "32px" },
+    "10": { "$value": "40px" },
+    "12": { "$value": "48px" },
+    "16": { "$value": "64px" }
+  },
+  "radius": {
+    "$type": "dimension",
+    "none": { "$value": "0px" },
+    "sm": { "$value": "4px", "$description": "Buttons, inputs" },
+    "md": { "$value": "6px", "$description": "Cards, panels" },
+    "lg": { "$value": "8px", "$description": "Modals, large cards" },
+    "xl": { "$value": "12px", "$description": "Large containers" },
+    "full": { "$value": "9999px", "$description": "Pills, avatars" }
+  },
+  "elevation": {
+    "sm": {
+      "$type": "shadow",
+      "$value": "0 1px 2px rgba(0, 0, 0, 0.3)",
+      "$description": "Subtle shadow — used sparingly in dark UI"
+    },
+    "md": {
+      "$type": "shadow",
+      "$value": "0 4px 12px rgba(0, 0, 0, 0.4)",
+      "$description": "Medium elevation — dropdowns"
+    },
+    "lg": {
+      "$type": "shadow",
+      "$value": "0 8px 24px rgba(0, 0, 0, 0.5)",
+      "$description": "High elevation — modals, command palette"
+    }
+  },
+  "motion": {
+    "duration": {
+      "$type": "duration",
+      "instant": { "$value": "50ms", "$description": "Micro-interactions" },
+      "fast": { "$value": "100ms", "$description": "Hover states, toggles" },
+      "normal": { "$value": "150ms", "$description": "Transitions, opacity changes" },
+      "slow": { "$value": "250ms", "$description": "Panel open/close" },
+      "slower": { "$value": "400ms", "$description": "Page transitions" }
+    },
+    "easing": {
+      "$type": "cubicBezier",
+      "default": { "$value": [0.25, 0.1, 0.25, 1], "$description": "Standard easing" },
+      "spring": { "$value": [0.34, 1.56, 0.64, 1], "$description": "Spring for microinteractions" },
+      "in-out": { "$value": [0.42, 0, 0.58, 1], "$description": "Symmetric in-out" }
+    }
+  }
+}