@forgrit/design-engine

A standalone, pure-TypeScript + Zod design generation engine. Produces 1,000+ structurally distinct enterprise designs through a 4-layer combinatorial system: Grammars + Renderers + Themes + Recipes.

Status: early-access (v0.x). Pre-1.0 releases may include breaking changes in minor bumps until the API stabilizes at v1.0.0.

Zero framework dependencies. Uses only zod and Node's built-in crypto. No NestJS. No Prisma. No browser bundle. Node 20+.

What's in the box

The package is organized as a 4-layer combinatorial design system plus 4 supporting layers:

Layer 1 — Structural Grammars (src/grammars/)

Shell grammars + page skeletons define WHERE components can be placed.

• SHELL_GRAMMARS, ShellGrammarRegistry, ShellGrammarSchema
• PAGE_SKELETONS, PageSkeletonRegistry, PageSkeletonSchema
• Responsive zone collapse rules (mobile/tablet/desktop transitions)

Layer 2 — Component Renderers (src/renderers/)

8 renderer families produce HTML from design tokens.

• HEADER_RENDERERS, SIDEBAR_RENDERERS, CARD_RENDERERS, TABLE_RENDERERS
• METRIC_RENDERERS, FORM_RENDERERS, CHART_RENDERERS, TOOLBAR_RENDERERS
• RendererRegistry for ad-hoc lookups

Layer 3 — Theme Engine (src/themes/)

Color, typography, spacing, radius, shadow, elevation, animation, borders — plus quality gates and registries.

• Token schemas: ColorTokensSchema, TypographySystemSchema, SpacingRhythmSchema, RadiusSystemSchema, ShadowTokensSchema, ElevationPhilosophySchema, etc.
• Data: COLOR_PALETTES, TYPOGRAPHY_SYSTEMS, SPACING_RHYTHMS, RADIUS_SYSTEMS, ELEVATION_PHILOSOPHIES, THEME_CATALOG, ThemeRegistry
• Engine: generateTheme, shiftColor, varyPalette, varyShadows, scaleShadows
• Quality gates: checkWcagAA, checkReadability, checkVisualHarmony, runQualityGates
• Selection: getCompatibleCategories, selectContrastingTheme, mapNavModelToLayout, getCornerRadiusForDensity

Layer 4 — Recipe Engine (src/recipes/)

DESIGN_RECIPES is the catalog of pre-validated combinations. Pick a recipe + theme = a complete design system.

• DESIGN_RECIPES, getRecipeById, getRecipesByCategory, getRecipesByPack
• Selection: RecipeSelector, DiversityValidator, ExclusionIndex
• Scoring: CoherenceScorer, DistanceScorer, DesignFingerprintGenerator

Composition (src/composition/)

Translate a recipe + theme into renderable component graphs + responsive layouts.

• ComponentGraphBuilder — recipe → component graph
• ResponsiveContractBuilder — graph → breakpoint layouts
• LayoutMutationEngine — apply mutations for variant exploration
• DesignDNABuilder + VariantGenerator + VariantExplainer — variant pipeline

Scoring (src/scoring/)

Quantify design quality.

• UXScorer — cognitive load + accessibility + interaction density
• runComprehensiveGates — full quality report

Intelligence (src/intelligence/)

Rule-based intent reasoning + golden-prompt evaluation + failure taxonomy.

• RuleBasedIntelligence + intentToCriteria
• GOLDEN_PROMPTS, BaselineEvalRunner
• FailureTaxonomist

Utilities (src/utils/)

Color math + similarity metrics + deterministic seeds.

• hexToRGB, rgbToHex, hexToHSL, hslToHex
• relativeLuminance, contrastRatio (WCAG)
• cosineSimilarity, hammingDistance
• deterministicSeed, deriveSeed

What it's NOT

• Not a NestJS module. Consume via direct imports. A future @forgrit/design-engine-nestjs adapter may ship later.
• Not a browser-side renderer. CJS Node-only in v0.1.0. No UMD or ESM bundle.
• Not a screenshot/preview-render service. That responsibility is reserved for a future @forgrit/preview-render package.
• Not the dormant *-variant/ folders inside the ForGrit monorepo. Those are scaffold experiments that don't ship — the runtime truth is the 4 layers documented above, not the unpublished scaffolding.

Install

npm install @forgrit/design-engine
# or
pnpm add @forgrit/design-engine
# or
yarn add @forgrit/design-engine

Requires Node 20+.

Quick start

import {
  DESIGN_RECIPES,
  getRecipeById,
  THEME_CATALOG,
  ThemeRegistry,
} from '@forgrit/design-engine';

// Browse the recipe catalog
console.log('Total recipes:', DESIGN_RECIPES.length);

// Look up a specific recipe by id
const recipe = getRecipeById(DESIGN_RECIPES[0]!.id);
console.log('Recipe:', recipe?.id, recipe?.appCategory);

// Browse the theme catalog
console.log('Total themes:', THEME_CATALOG.length);

API surface

The package exports ~120 top-level symbols across the 8 layers above. All exports are tree-shake-friendly (no side-effectful imports).

Browse the TypeScript declaration files (dist/**/*.d.ts) in your editor for the complete surface. Every public schema, type, and function is documented inline.

License

MIT — see LICENSE.

Links

• npm: https://www.npmjs.com/package/@forgrit/design-engine
• Source: https://github.com/forgrit-ai/forgrit/tree/main/lifecycle/3-design/design-engine
• Issues: https://github.com/forgrit-ai/forgrit/issues
• ForGrit: https://forgrit.ai

Sibling packages

Other public ForGrit packages:

• @forgrit/blueprint — app-spec format and blueprint helpers
• @forgrit/llm-cost — credit ledger primitives + cost estimators + the 7 LLM cost design rules