@10up/block-renderer-preferences

Load and manage user preferences for AI block generation. Preferences guide AI assistants on preferred blocks, styles, and patterns.

Installation

npm install @10up/block-renderer-preferences
# or
pnpm add @10up/block-renderer-preferences

Overview

This package:

1. Loads preferences - From block-preferences.json or .blockrc.json
2. Validates with Zod - Ensures preference files are correctly formatted
3. Formats for AI prompts - Converts preferences to AI-friendly text
4. Provides defaults - Sensible defaults when no file exists

Usage

Load Preferences

Automatically find and load preferences from a directory:

import { loadPreferences } from '@10up/block-renderer-preferences';

const prefs = loadPreferences('/path/to/project');
// Searches for:
// - /path/to/project/block-preferences.json
// - /path/to/project/.blockrc.json
// - /path/to/project/.block-renderer/preferences.json

if (prefs) {
  console.log(prefs.preferredBlocks);
  console.log(prefs.avoidBlocks);
  console.log(prefs.styleGuide);
}

Load from Specific File

import { loadPreferencesFromFile } from '@10up/block-renderer-preferences';

const prefs = loadPreferencesFromFile('/path/to/custom-prefs.json');

Find Preferences File

import { findPreferencesFile } from '@10up/block-renderer-preferences';

const filePath = findPreferencesFile('/path/to/project');
// Returns path to preferences file or null if not found

Create Default Preferences

import { createDefaultPreferences } from '@10up/block-renderer-preferences';

const defaults = createDefaultPreferences();
// Returns sensible default configuration

Merge Preferences

Combine multiple preference sources:

import { mergePreferences, createDefaultPreferences } from '@10up/block-renderer-preferences';

const defaults = createDefaultPreferences();
const userPrefs = loadPreferencesFromFile('/path/to/prefs.json');
const merged = mergePreferences(defaults, userPrefs);

Format for AI Prompts

import { formatPreferencesForPrompt } from '@10up/block-renderer-preferences';

const promptSection = formatPreferencesForPrompt(prefs);
// Returns formatted markdown for AI system prompt

Preferences Schema

BlockPreferencesConfig

The main configuration object:

interface BlockPreferencesConfig {
  // Block preferences
  blocks?: BlocksPreferences;

  // Layout preferences
  layout?: LayoutPreferences;

  // Typography preferences
  typography?: TypographyPreferences;

  // Color preferences
  colors?: ColorPreferences;

  // Spacing preferences
  spacing?: SpacingPreferences;

  // Image preferences
  images?: ImagePreferences;

  // Style guide
  styleGuide?: StyleGuide;

  // Brand guidelines
  brand?: BrandGuideline;
}

BlocksPreferences

interface BlocksPreferences {
  /** Blocks to prefer when multiple options exist */
  preferred?: string[];
  /** Blocks to avoid using */
  avoid?: string[];
  /** Default block for text content */
  defaultText?: string;
  /** Default container block */
  defaultContainer?: string;
}

LayoutPreferences

interface LayoutPreferences {
  /** Default layout type for groups */
  defaultType?: 'constrained' | 'flex' | 'flow' | 'grid';
  /** Maximum content width */
  maxWidth?: string;
  /** Default alignment */
  defaultAlign?: 'left' | 'center' | 'right' | 'wide' | 'full';
}

TypographyPreferences

interface TypographyPreferences {
  /** Use semantic heading levels */
  useSemanticHeadings?: boolean;
  /** Maximum heading level to use */
  maxHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
  /** Default font size */
  defaultFontSize?: string;
}

ColorPreferences

interface ColorPreferences {
  /** Preferred color tokens to use */
  preferred?: string[];
  /** Colors to avoid */
  avoid?: string[];
  /** Default background color */
  defaultBackground?: string;
  /** Default text color */
  defaultText?: string;
}

SpacingPreferences

interface SpacingPreferences {
  /** Default spacing token */
  default?: string;
  /** Preferred spacing scale */
  scale?: string[];
}

ImagePreferences

interface ImagePreferences {
  /** Preferred image sizes */
  preferredSizes?: string[];
  /** Default aspect ratio */
  defaultAspectRatio?: string;
  /** Always include alt text */
  requireAlt?: boolean;
}

StyleGuide

interface StyleGuide {
  /** Custom style rules */
  rules?: string[];
  /** Preferred patterns by category */
  patternsByCategory?: Record<string, string[]>;
  /** Patterns to avoid */
  avoidPatterns?: string[];
}

BrandGuideline

interface BrandGuideline {
  /** Brand name */
  name?: string;
  /** Brand description */
  description?: string;
  /** Voice and tone guidelines */
  voiceTone?: string[];
}

Example Configuration

{
  "blocks": {
    "preferred": ["core/group", "core/columns"],
    "avoid": ["core/freeform", "core/html"],
    "defaultText": "core/paragraph",
    "defaultContainer": "core/group"
  },
  "layout": {
    "defaultType": "constrained",
    "defaultAlign": "wide"
  },
  "typography": {
    "useSemanticHeadings": true,
    "maxHeadingLevel": 4
  },
  "colors": {
    "preferred": ["primary", "secondary", "base", "contrast"],
    "avoid": ["error", "warning"]
  },
  "spacing": {
    "default": "50",
    "scale": ["30", "40", "50", "60", "70"]
  },
  "images": {
    "preferredSizes": ["large", "full"],
    "requireAlt": true
  },
  "styleGuide": {
    "rules": [
      "Always use constrained layout for content groups",
      "Prefer flex layout for button containers",
      "Use consistent spacing throughout sections"
    ],
    "patternsByCategory": {
      "hero": ["theme/hero-centered", "theme/hero-split"]
    },
    "avoidPatterns": ["theme/deprecated-banner"]
  },
  "brand": {
    "name": "Acme Corp",
    "voiceTone": [
      "Professional but approachable",
      "Clear and concise",
      "Helpful and supportive"
    ]
  }
}

Complete Exports

Functions

| Function | Description | |----------|-------------| | loadPreferences(directory) | Auto-detect and load preferences | | loadPreferencesFromFile(filePath) | Load from specific file | | findPreferencesFile(directory) | Find preferences file path | | createDefaultPreferences() | Create default configuration | | mergePreferences(base, override) | Merge preference objects | | formatPreferencesForPrompt(prefs) | Format for AI prompt |

Types

| Type | Description | |------|-------------| | BlockPreferencesConfig | Main configuration type | | BlocksPreferences | Block selection preferences | | LayoutPreferences | Layout preferences | | TypographyPreferences | Typography preferences | | ColorPreferences | Color preferences | | SpacingPreferences | Spacing preferences | | ImagePreferences | Image preferences | | StyleGuide | Style guide rules | | BrandGuideline | Brand guidelines | | Preferences | Alias for BlockPreferencesConfig |

Zod Schemas

| Schema | Description | |--------|-------------| | blockPreferencesConfigSchema | Main config schema | | blockPreferencesSchema | Block preferences schema | | layoutPreferencesSchema | Layout preferences schema | | typographyPreferencesSchema | Typography preferences schema | | colorPreferencesSchema | Color preferences schema | | spacingPreferencesSchema | Spacing preferences schema | | imagePreferencesSchema | Image preferences schema | | styleGuideSchema | Style guide schema | | brandGuidelineSchema | Brand guideline schema | | preferencesSchema | Alias for main schema |

License

MIT