@forgespace/branding-mcp 0.4.0

package/src/lib/branding-core/generators/shadow-system.ts

@@ -0,0 +1,66 @@
+import type {
+  BrandStyle,
+  ColorTheme,
+  ShadowLevel,
+  ShadowLevelName,
+  ShadowSystem,
+} from '../../types.js';
+import { hexToHsl, hslToHex } from './color-palette.js';
+
+const LEVEL_CONFIGS: Record<
+  ShadowLevelName,
+  { y: number; blur: number; spread: number; opacity: number }
+> = {
+  none: { y: 0, blur: 0, spread: 0, opacity: 0 },
+  sm: { y: 1, blur: 2, spread: 0, opacity: 0.05 },
+  md: { y: 2, blur: 4, spread: -1, opacity: 0.08 },
+  lg: { y: 4, blur: 8, spread: -2, opacity: 0.1 },
+  xl: { y: 8, blur: 16, spread: -4, opacity: 0.12 },
+  '2xl': { y: 16, blur: 32, spread: -8, opacity: 0.15 },
+};
+
+function makeShadowColor(primaryHex: string, opacity: number): string {
+  const hsl = hexToHsl(primaryHex);
+  const tinted = hslToHex(hsl.h, Math.min(hsl.s, 30), 20);
+  const r = parseInt(tinted.slice(1, 3), 16);
+  const g = parseInt(tinted.slice(3, 5), 16);
+  const b = parseInt(tinted.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+}
+
+function buildLevel(
+  cfg: (typeof LEVEL_CONFIGS)[ShadowLevelName],
+  primaryHex: string,
+  dark: boolean
+): ShadowLevel {
+  const sign = dark ? -1 : 1;
+  const adjustedOpacity = dark ? cfg.opacity * 1.5 : cfg.opacity;
+  const color = makeShadowColor(primaryHex, adjustedOpacity);
+  const oY = cfg.y * sign;
+  const cssValue =
+    cfg.blur === 0
+      ? 'none'
+      : `${cfg.y === 0 ? 0 : `${oY}px`} ${oY === 0 ? '' : `${Math.abs(oY)}px `}${cfg.blur}px ${cfg.spread}px ${color}`.trim();
+  return {
+    offsetX: 0,
+    offsetY: oY,
+    blur: cfg.blur,
+    spread: cfg.spread,
+    color,
+    opacity: adjustedOpacity,
+    cssValue,
+  };
+}
+
+export function generateShadowSystem(
+  primaryHex = '#6B4CE6',
+  theme: ColorTheme = 'light',
+  _style?: BrandStyle
+): ShadowSystem {
+  const dark = theme === 'dark';
+  const levels = {} as Record<ShadowLevelName, ShadowLevel>;
+  for (const [name, cfg] of Object.entries(LEVEL_CONFIGS)) {
+    levels[name as ShadowLevelName] = buildLevel(cfg, primaryHex, dark);
+  }
+  return { levels };
+}

package/src/lib/branding-core/generators/spacing-scale.ts

@@ -0,0 +1,29 @@
+import type { SpacingScale } from '../../types.js';
+
+const SPACING_NAMES = [
+  '0',
+  '0.5',
+  '1',
+  '1.5',
+  '2',
+  '2.5',
+  '3',
+  '4',
+  '5',
+  '6',
+  '8',
+  '10',
+  '12',
+  '16',
+  '20',
+  '24',
+];
+
+export function generateSpacingScale(baseUnit = 4): SpacingScale {
+  const values: Record<string, string> = {};
+  for (const name of SPACING_NAMES) {
+    const multiplier = parseFloat(name);
+    values[name] = `${multiplier * baseUnit}px`;
+  }
+  return { unit: baseUnit, values };
+}

package/src/lib/branding-core/generators/typography-system.ts

@@ -0,0 +1,128 @@
+import type { FontCategory, TypeScaleRatio, TypeStep, TypographySystem } from '../../types.js';
+
+const SCALE_RATIOS: Record<TypeScaleRatio, number> = {
+  'minor-second': 1.067,
+  'major-second': 1.125,
+  'minor-third': 1.2,
+  'major-third': 1.25,
+  'perfect-fourth': 1.333,
+  'augmented-fourth': 1.414,
+  'perfect-fifth': 1.5,
+  'golden-ratio': 1.618,
+};
+
+const FONT_PAIRINGS: Record<FontCategory, Record<FontCategory, [string, string][]>> = {
+  'sans-serif': {
+    serif: [
+      ['Inter', 'Merriweather'],
+      ['Helvetica Neue', 'Georgia'],
+      ['Open Sans', 'Lora'],
+    ],
+    'sans-serif': [
+      ['Montserrat', 'Open Sans'],
+      ['Poppins', 'Inter'],
+      ['Raleway', 'Nunito'],
+    ],
+    monospace: [['Inter', 'JetBrains Mono']],
+    display: [['Inter', 'Playfair Display']],
+    handwriting: [['Inter', 'Caveat']],
+  },
+  serif: {
+    'sans-serif': [
+      ['Playfair Display', 'Source Sans 3'],
+      ['Merriweather', 'Open Sans'],
+      ['Lora', 'Inter'],
+    ],
+    serif: [
+      ['Playfair Display', 'Merriweather'],
+      ['Lora', 'Georgia'],
+    ],
+    monospace: [['Merriweather', 'Fira Code']],
+    display: [['Merriweather', 'Playfair Display']],
+    handwriting: [['Merriweather', 'Caveat']],
+  },
+  monospace: {
+    'sans-serif': [['JetBrains Mono', 'Inter']],
+    serif: [['Fira Code', 'Merriweather']],
+    monospace: [['JetBrains Mono', 'Fira Code']],
+    display: [['JetBrains Mono', 'Playfair Display']],
+    handwriting: [['JetBrains Mono', 'Caveat']],
+  },
+  display: {
+    'sans-serif': [
+      ['Playfair Display', 'Inter'],
+      ['Bebas Neue', 'Open Sans'],
+    ],
+    serif: [['Playfair Display', 'Merriweather']],
+    monospace: [['Playfair Display', 'JetBrains Mono']],
+    display: [['Bebas Neue', 'Playfair Display']],
+    handwriting: [['Playfair Display', 'Caveat']],
+  },
+  handwriting: {
+    'sans-serif': [['Caveat', 'Inter']],
+    serif: [['Caveat', 'Merriweather']],
+    monospace: [['Caveat', 'JetBrains Mono']],
+    display: [['Caveat', 'Playfair Display']],
+    handwriting: [['Caveat', 'Dancing Script']],
+  },
+};
+
+const STEP_NAMES = ['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl'];
+
+function pickPairing(headingCat: FontCategory, bodyCat: FontCategory): [string, string] {
+  const options = FONT_PAIRINGS[headingCat]?.[bodyCat];
+  if (!options?.length) return ['Inter', 'Inter'];
+  return options[Math.floor(Math.random() * options.length)];
+}
+
+function lineHeightForSize(size: number): string {
+  if (size <= 16) return '1.6';
+  if (size <= 24) return '1.5';
+  if (size <= 36) return '1.3';
+  return '1.2';
+}
+
+function letterSpacingForSize(size: number): string {
+  if (size <= 14) return '0.02em';
+  if (size <= 20) return '0em';
+  return '-0.01em';
+}
+
+function weightForStep(index: number, totalSteps: number): number {
+  const mid = Math.floor(totalSteps / 2);
+  if (index <= mid) return 400;
+  if (index <= mid + 2) return 600;
+  return 700;
+}
+
+export function generateTypographySystem(
+  headingCategory: FontCategory = 'sans-serif',
+  bodyCategory: FontCategory = 'serif',
+  scaleRatio: TypeScaleRatio = 'major-third',
+  baseSize = 16
+): TypographySystem {
+  const ratio = SCALE_RATIOS[scaleRatio];
+  const [headingFont, bodyFont] = pickPairing(headingCategory, bodyCategory);
+
+  const baseIndex = 2;
+  const steps: TypeStep[] = STEP_NAMES.map((name, i) => {
+    const exponent = i - baseIndex;
+    const size = Math.round(baseSize * Math.pow(ratio, exponent) * 100) / 100;
+    return {
+      name,
+      size: `${size}px`,
+      lineHeight: lineHeightForSize(size),
+      letterSpacing: letterSpacingForSize(size),
+      weight: weightForStep(i, STEP_NAMES.length),
+    };
+  });
+
+  return {
+    headingFont,
+    bodyFont,
+    monoFont: 'JetBrains Mono',
+    baseSize,
+    scaleRatio: ratio,
+    steps,
+  };
+}

package/src/lib/branding-core/index.ts

@@ -0,0 +1,28 @@
+export {
+  generateColorPalette,
+  checkContrast,
+  hslToHex,
+  hexToHsl,
+} from './generators/color-palette.js';
+export { generateTypographySystem } from './generators/typography-system.js';
+export { generateSpacingScale } from './generators/spacing-scale.js';
+export { generateShadowSystem } from './generators/shadow-system.js';
+export { generateBorderSystem } from './generators/border-system.js';
+export { generateMotionSystem } from './generators/motion-system.js';
+export { generateSvgLogo, defaultLogoConfig } from './generators/logo-generator.js';
+export { generateGradientSystem } from './generators/gradient-system.js';
+export { generateFavicons } from './generators/favicon-generator.js';
+export { generateOgImage } from './generators/og-image-generator.js';
+export { exportDesignTokens } from './exporters/design-tokens.js';
+export { exportCssVariables } from './exporters/css-variables.js';
+export { exportTailwindPreset } from './exporters/tailwind-preset.js';
+export { exportFigmaTokens } from './exporters/figma-tokens.js';
+export { exportReactTheme } from './exporters/react-theme.js';
+export { exportSassVariables } from './exporters/sass-variables.js';
+export { validateBrandConsistency } from './validators/brand-consistency.js';
+export { validateContrast } from './validators/contrast-checker.js';
+export { interpretFeedback } from './ai/brand-interpreter.js';
+export { interpretWithKeywords } from './ai/keyword-interpreter.js';
+export { applyIntent } from './ai/intent-applier.js';
+export type { BrandIntent, ColorIntent, TypographyIntent, InterpreterOptions } from './ai/types.js';
+export type { InterpreterStrategy } from './ai/brand-interpreter.js';

package/src/lib/branding-core/validators/brand-consistency.ts

@@ -0,0 +1,79 @@
+import type { BrandIdentity, BrandValidationIssue, BrandValidationResult } from '../../types.js';
+import { validateContrast } from './contrast-checker.js';
+
+function validateColorCompleteness(brand: BrandIdentity): BrandValidationIssue[] {
+  const issues: BrandValidationIssue[] = [];
+  const { colors } = brand;
+
+  if (!colors.primary.hex) {
+    issues.push({
+      severity: 'error',
+      element: 'color.primary',
+      message: 'Primary color is missing',
+    });
+  }
+  if (!colors.secondary.hex) {
+    issues.push({
+      severity: 'error',
+      element: 'color.secondary',
+      message: 'Secondary color is missing',
+    });
+  }
+  if (colors.neutral.length < 4) {
+    issues.push({
+      severity: 'warning',
+      element: 'color.neutral',
+      message: `Only ${colors.neutral.length} neutral shades defined (recommend 6-10)`,
+    });
+  }
+
+  return issues;
+}
+
+function validateTypography(brand: BrandIdentity): BrandValidationIssue[] {
+  const issues: BrandValidationIssue[] = [];
+  const { typography } = brand;
+
+  if (!typography.headingFont) {
+    issues.push({
+      severity: 'error',
+      element: 'typography.headingFont',
+      message: 'Heading font is missing',
+    });
+  }
+  if (!typography.bodyFont) {
+    issues.push({
+      severity: 'error',
+      element: 'typography.bodyFont',
+      message: 'Body font is missing',
+    });
+  }
+  if (typography.baseSize < 14 || typography.baseSize > 20) {
+    issues.push({
+      severity: 'warning',
+      element: 'typography.baseSize',
+      message: `Base size ${typography.baseSize}px is outside recommended range (14-20px)`,
+    });
+  }
+
+  return issues;
+}
+
+export function validateBrandConsistency(brand: BrandIdentity): BrandValidationResult {
+  const issues: BrandValidationIssue[] = [
+    ...validateColorCompleteness(brand),
+    ...validateContrast(brand),
+    ...validateTypography(brand),
+  ];
+
+  const errorCount = issues.filter((i) => i.severity === 'error').length;
+  const warningCount = issues.filter((i) => i.severity === 'warning').length;
+  const maxScore = 100;
+  const score = Math.max(0, maxScore - errorCount * 20 - warningCount * 5);
+
+  return {
+    valid: errorCount === 0,
+    score,
+    issues,
+  };
+}

package/src/lib/branding-core/validators/contrast-checker.ts

@@ -0,0 +1,37 @@
+import type { BrandIdentity, BrandValidationIssue } from '../../types.js';
+import { checkContrast } from '../generators/color-palette.js';
+
+export function validateContrast(brand: BrandIdentity): BrandValidationIssue[] {
+  const issues: BrandValidationIssue[] = [];
+  const white = '#ffffff';
+  const dark = '#1a1a1a';
+
+  const colorChecks = [
+    { name: 'primary', hex: brand.colors.primary.hex },
+    { name: 'secondary', hex: brand.colors.secondary.hex },
+    { name: 'accent', hex: brand.colors.accent.hex },
+  ];
+
+  for (const { name, hex } of colorChecks) {
+    const onWhite = checkContrast(hex, white);
+    const onDark = checkContrast(hex, dark);
+
+    if (!onWhite.aa && !onDark.aa) {
+      issues.push({
+        severity: 'error',
+        element: `color.${name}`,
+        message: `${name} color (${hex}) fails WCAG AA on both white and dark backgrounds`,
+        suggestion: 'Adjust lightness to achieve at least 4.5:1 contrast ratio',
+      });
+    } else if (!onWhite.aa) {
+      issues.push({
+        severity: 'warning',
+        element: `color.${name}`,
+        message: `${name} color (${hex}) fails WCAG AA on white (ratio: ${onWhite.ratio})`,
+        suggestion: 'Darken the color for better contrast on light backgrounds',
+      });
+    }
+  }
+
+  return issues;
+}

package/src/lib/branding-core/validators/token-schema.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+export const hexColorSchema = z
+  .string()
+  .regex(/^#[0-9a-fA-F]{6}$/, 'Must be a valid hex color (#RRGGBB)');
+
+export const colorHarmonySchema = z.enum([
+  'complementary',
+  'analogous',
+  'triadic',
+  'split-complementary',
+  'tetradic',
+  'monochromatic',
+]);
+
+export const colorThemeSchema = z.enum(['light', 'dark', 'both']);
+
+export const fontCategorySchema = z.enum([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'display',
+  'handwriting',
+]);
+
+export const typeScaleRatioSchema = z.enum([
+  'minor-second',
+  'major-second',
+  'minor-third',
+  'major-third',
+  'perfect-fourth',
+  'augmented-fourth',
+  'perfect-fifth',
+  'golden-ratio',
+]);
+
+export const exportFormatSchema = z.enum(['json', 'css', 'tailwind', 'figma', 'react', 'sass']);
+
+export const brandStyleSchema = z.enum([
+  'minimal',
+  'bold',
+  'elegant',
+  'playful',
+  'corporate',
+  'tech',
+  'organic',
+  'retro',
+]);
+
+export const brandDocFormatSchema = z.enum(['pdf', 'html']);

package/src/lib/config.ts

@@ -0,0 +1,13 @@
+export interface AppConfig {
+  logLevel: string;
+  nodeEnv: string;
+  anthropicApiKey?: string;
+}
+
+export function loadConfig(): AppConfig {
+  return {
+    logLevel: process.env.LOG_LEVEL ?? 'info',
+    nodeEnv: process.env.NODE_ENV ?? 'development',
+    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+  };
+}

package/src/lib/logger.ts

@@ -0,0 +1,12 @@
+import pino from 'pino';
+import { loadConfig } from './config.js';
+
+const config = loadConfig();
+
+export const logger = pino({
+  level: config.logLevel,
+  transport:
+    config.nodeEnv === 'development'
+      ? { target: 'pino/file', options: { destination: 2 } }
+      : undefined,
+});

package/src/lib/types.ts

@@ -0,0 +1,236 @@
+export type ColorHarmony =
+  | 'complementary'
+  | 'analogous'
+  | 'triadic'
+  | 'split-complementary'
+  | 'tetradic'
+  | 'monochromatic';
+
+export type ColorTheme = 'light' | 'dark' | 'both';
+
+export type FontCategory = 'serif' | 'sans-serif' | 'monospace' | 'display' | 'handwriting';
+
+export type TypeScaleRatio =
+  | 'minor-second'
+  | 'major-second'
+  | 'minor-third'
+  | 'major-third'
+  | 'perfect-fourth'
+  | 'augmented-fourth'
+  | 'perfect-fifth'
+  | 'golden-ratio';
+
+export type ExportFormat = 'json' | 'css' | 'tailwind' | 'figma' | 'react' | 'sass';
+
+export type BrandDocFormat = 'pdf' | 'html';
+
+export type BrandStyle =
+  | 'minimal'
+  | 'bold'
+  | 'elegant'
+  | 'playful'
+  | 'corporate'
+  | 'tech'
+  | 'organic'
+  | 'retro';
+
+export interface HslColor {
+  h: number;
+  s: number;
+  l: number;
+}
+
+export interface ColorSwatch {
+  name: string;
+  hex: string;
+  hsl: HslColor;
+  oklch?: { l: number; c: number; h: number };
+  usage: string;
+}
+
+export interface ContrastResult {
+  ratio: number;
+  aa: boolean;
+  aaLarge: boolean;
+  aaa: boolean;
+  aaaLarge: boolean;
+}
+
+export interface ColorPalette {
+  primary: ColorSwatch;
+  secondary: ColorSwatch;
+  accent: ColorSwatch;
+  neutral: ColorSwatch[];
+  semantic: {
+    success: ColorSwatch;
+    warning: ColorSwatch;
+    error: ColorSwatch;
+    info: ColorSwatch;
+  };
+  contrast: Record<string, ContrastResult>;
+}
+
+export interface TypeStep {
+  name: string;
+  size: string;
+  lineHeight: string;
+  letterSpacing: string;
+  weight: number;
+}
+
+export interface TypographySystem {
+  headingFont: string;
+  bodyFont: string;
+  monoFont: string;
+  baseSize: number;
+  scaleRatio: number;
+  steps: TypeStep[];
+}
+
+export interface SpacingScale {
+  unit: number;
+  values: Record<string, string>;
+}
+
+export interface LogoConfig {
+  text: string;
+  font: string;
+  fontSize: number;
+  color: string;
+  backgroundColor: string;
+  width: number;
+  height: number;
+  style?: BrandStyle;
+}
+
+export type LogoVariant = 'wordmark' | 'monogram' | 'abstract' | 'icon';
+
+export interface LogoOutput {
+  svg: string;
+  variants: Record<LogoVariant, string>;
+}
+
+export type GradientType = 'linear' | 'radial' | 'conic';
+export type GradientPresetName = 'hero' | 'button' | 'card' | 'text' | 'background';
+
+export interface GradientStop {
+  color: string;
+  position: number;
+}
+
+export interface Gradient {
+  type: GradientType;
+  angle?: number;
+  stops: GradientStop[];
+  cssValue: string;
+}
+
+export interface GradientSystem {
+  presets: Record<GradientPresetName, Gradient>;
+}
+
+export type FaviconSize = 16 | 32 | 180 | 512;
+
+export interface FaviconSet {
+  sizes: Record<FaviconSize, string>;
+}
+
+export type OgTemplate = 'default' | 'article' | 'social';
+
+export interface OgImageOutput {
+  template: OgTemplate;
+  svg: string;
+  width: number;
+  height: number;
+}
+
+export type ShadowLevelName = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export interface ShadowLevel {
+  offsetX: number;
+  offsetY: number;
+  blur: number;
+  spread: number;
+  color: string;
+  opacity: number;
+  cssValue: string;
+}
+
+export interface ShadowSystem {
+  levels: Record<ShadowLevelName, ShadowLevel>;
+}
+
+export type BorderRadiusName = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'circle';
+
+export interface BorderSystem {
+  radii: Record<BorderRadiusName, string>;
+  widths: { thin: string; medium: string; thick: string };
+}
+
+export type DurationName = 'instant' | 'fast' | 'normal' | 'slow' | 'slower';
+export type EasingName = 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce';
+
+export interface MotionSystem {
+  durations: Record<DurationName, string>;
+  easings: Record<EasingName, string>;
+  transitions: Record<string, string>;
+}
+
+export interface BrandIdentity {
+  id: string;
+  name: string;
+  tagline?: string;
+  industry: string;
+  style: BrandStyle;
+  colors: ColorPalette;
+  typography: TypographySystem;
+  spacing: SpacingScale;
+  shadows?: ShadowSystem;
+  borders?: BorderSystem;
+  motion?: MotionSystem;
+  gradients?: GradientSystem;
+  logo?: LogoOutput;
+  createdAt: string;
+}
+
+export interface DesignTokens {
+  $schema?: string;
+  color: Record<string, Record<string, { $value: string; $type: string }>>;
+  typography: Record<string, Record<string, { $value: string | number; $type: string }>>;
+  spacing: Record<string, { $value: string; $type: string }>;
+  shadow?: Record<string, { $value: string; $type: string }>;
+  border?: Record<string, { $value: string; $type: string }>;
+  motion?: Record<string, { $value: string; $type: string }>;
+  gradient?: Record<string, { $value: string; $type: string }>;
+}
+
+export interface BrandGenerationInput {
+  brandName: string;
+  industry: string;
+  style: BrandStyle;
+  tagline?: string;
+  colorPrefs?: {
+    baseColor?: string;
+    harmony?: ColorHarmony;
+    theme?: ColorTheme;
+  };
+  typographyPrefs?: {
+    mood?: string;
+    headingCategory?: FontCategory;
+    bodyCategory?: FontCategory;
+    scaleRatio?: TypeScaleRatio;
+  };
+}
+
+export interface BrandValidationResult {
+  valid: boolean;
+  score: number;
+  issues: BrandValidationIssue[];
+}
+
+export interface BrandValidationIssue {
+  severity: 'error' | 'warning' | 'info';
+  element: string;
+  message: string;
+  suggestion?: string;
+}