GitHub
Creative direction inference engine · v0.3.0

Design is direction,
not decoration.

Great products have creative direction behind every pixel. directionmd reads any URL and infers that direction: not what things look like, but why. Then it gives your AI agent the vocabulary to make decisions that belong.

16 extraction passes · 22 inference modules · 13 source files · 85 tests passing

01
The Extraction

Before inference, before decision trees, directionmd runs 16 extraction passes against the live DOM. Each pass operates independently inside its own try/catch. If one fails, the rest continue. The tool always produces output.

$ npx directionmd https://example.com
copy
What tools extract
Raw values
border-radius: 8px
color: #5e6ad2
font-size: 16px
transition: 0.2s ease
padding: 24px
hex dumpsflat listsno context
What directionmd infers
Creative direction
Soft radius on interactive elements, sharp on containers. Color is earned, not given. Motion is functional, never decorative. Cards breathe with generous padding.
philosophydecisionsguardrails
02
The Inference

22 inference modules convert observed patterns into prescriptive principles. A pattern-to-principle engine, not a style extractor. Each module generates prose rules that guide ambiguous decisions.

Color

Color philosophy

Minimal, disciplined, or expressive. Accent strategy. Monochrome ratio. Gradient policy.

Type

Typography direction

Single/paired/multi typeface system. Scale ratio. Case patterns. Tracking rules.

Space

Spacing philosophy

Grid detection and adherence. Whitespace stance. Density zones. Section rhythm.

Motion

Motion intent

Static, functional, or expressive. Duration constants. Easing rules. Reduced-motion.

Voice

Voice direction

Formality, perspective, CTA patterns. Active vs passive. Positive vs negative framing.

Component

Component philosophy

Shape language. Elevation system. Border approach. Button tiers. Card consistency.

Layout

Layout direction

Hero style. Page narrative flow. Container rules. Alignment. Scroll depth.

A11y

Accessibility stance

Inclusive design vs compliance. Error recovery philosophy. Focus choreography.

Brand

Brand archetype

12 archetypes scored from weighted cross-module signals. Primary + secondary classification.

Synthesis

Cross-system rules

COLOR × TYPE. SPACE × MOTION. How systems interact. Change one, know what moves.

03
The Antidote

Flat rules don't scale. An agent reading "use 8px radius" doesn't know WHEN to use it. Decision trees give agents a traversable path for every ambiguous choice.

Decision tree: Component
What are you building?
  → Interactive element
    What does it do?
      → Triggers navigation
        Text link. Accent color, no background.
      → Triggers an action
        Primary action on this page?
          → Yes: Primary button. Filled accent. ONE per viewport.
          → No:  Secondary button. Ghost style. Same radius.
      → Accepts input
        Match input styling. Never rely on placeholder as label.
  → Container
    Needs visual separation?
      → With elevation: Card. Shadow level 1.
      → Subtle:        Background change. No shadow.
      → Structural:    Invisible wrapper. No styling.

4 trees generated: component, color, motion, spacing. Each one eliminates guesswork.

04
Full Capability Set

Everything built into v0.3.0. Each feature is independently tested, secured against XSS, and handles missing data gracefully.

01

Multi-page crawling

Crawl N pages. Converge patterns by cross-page frequency. System-level tokens weighted higher than page-specific.

02

LLM-powered inference

Send extracted data to Claude API. Heuristic rules are guardrails. The LLM writes the creative brief.

03

Design tokens

Semantic naming. CSS custom properties, Tailwind config, Style Dictionary. color-action, space-unit, font-display.

04

Decision trees

4 traversable trees for component, color, motion, spacing. Agents walk the tree for every choice.

05

Competitive positioning

Extract from multiple sites. Positioning map, differentiators, convergence warnings, comparison matrix.

06

Accessibility as direction

Not audit. Philosophy: inclusive design vs compliance. Error recovery. Focus choreography. Inclusion level.

07

Animation choreography

Stagger detection. Entrance/exit symmetry. Scroll behavior. Motion constants. Loop animation policy.

08

Content governance

Heading limits. Paragraph rules. Number formatting. Capitalization conventions. Terminology glossary.

09

Platform direction

React (exact Tailwind classNames). Email (safe font stacks). Mobile (touch targets, nav, gestures).

10

Drift monitoring

GitHub Action. Save baseline, detect drift on every deploy. New colors, broken grid, a11y regressions.

11

Visual hierarchy

Weight distribution. Primary action identification. Contrast ladder. Above-fold element audit.

12

Content formula

Problem-Solution, Feature-Proof, Feature-Led detection. Page arc mapping. Headline formula analysis.

13

Composition

Symmetry analysis. Full-bleed vs contained. Section alternation. Column usage. Vertical rhythm.

14

Iconography

Style (outlined/filled/duotone). Size consistency. Labeling strategy (labeled/icon-only).

15

Imagery philosophy

Treatment (rounded/sharp). Placement patterns. Overlay rules. Decorative vs content classification.

16

Micro-interactions

Button hover philosophy. Link hover. Focus transitions. Hover completeness audit.

17

Error / empty / loading

Error tone (apologetic/instructive/direct). Empty state type. Loading pattern (skeleton/spinner).

18

Creative brief

Prose, not data dump. "You're building for a brand that..." not "COLOR: minimal. VOICE: conversational."

19

Brand archetype

12 archetypes (Sage, Creator, Ruler, Hero...) classified from weighted signals across all modules.

20

Specific guardrails

"Use accent on one element per viewport" not "be consistent." Do's and don'ts from actual inference.

05
Get Started

Install

$ npm install -g directionmd
copy

Usage

Terminal
# Basic
directionmd https://example.com

# Multi-page crawl
directionmd https://example.com --depth 5

# LLM creative brief
ANTHROPIC_API_KEY=sk-... directionmd https://example.com --llm

# Design tokens
directionmd https://example.com --tokens

# Competitive analysis
directionmd https://example.com --compare https://competitor.com

# Drift monitoring
directionmd https://example.com --save-baseline ./baseline.json
directionmd https://example.com --baseline ./baseline.json

# Everything
ANTHROPIC_API_KEY=sk-... directionmd https://example.com \
  --depth 5 --llm --tokens --json \
  --compare https://competitor.com
FlagPurposeDefault
--depth <n>Crawl N internal pages for accuracy1
--llmClaude API creative brief (needs ANTHROPIC_API_KEY)off
--tokensOutput CSS + Tailwind + Style Dictionary tokensoff
--compare <url>Competitive positioning analysis
--baseline <path>Check drift against saved baseline
--save-baselineSave current extraction as baseline
--jsonOutput raw inference dataoff
-o <path>Output file path./DIRECTION.md

Programmatic API

app.js
import { direction } from "directionmd"

const result = await direction("https://example.com", {
  depth: 5, llm: true, tokens: true
})

result.markdown                // DIRECTION.md
result.inferences.archetype    // brand archetype
result.tokens.css              // CSS custom properties
result.tokens.tailwind         // Tailwind config
result.decisionTrees.component // traversable tree
result.platforms.react         // React/Tailwind direction
07
Questions
What does directionmd actually extract?
16 passes: identity, colors, typography, spacing, motion, voice/content, components, layout, a11y, responsive, tech stack, error/empty/loading states, visual hierarchy, icons, images, and composition. Each pass runs independently. If one fails, the rest continue.
How is this different from a design token extractor?
Token extractors give you values. directionmd gives you direction. Not "the button is #5e6ad2" but "one accent color is reserved for interactive elements. Using it on decorative elements dilutes its meaning." The output is a creative brief, not a color palette.
Does the LLM feature require an API key?
Yes. Set ANTHROPIC_API_KEY in your environment and pass --llm. Without it, the heuristic inference engine runs alone. The LLM adds a prose creative brief on top of the heuristic rules. It's optional and the tool works perfectly without it.
How does multi-page crawling work?
Pass --depth 5 to crawl 5 internal pages. The crawler discovers links from the homepage, prioritizes important pages (pricing, features, docs, about), extracts from each, then converges patterns. Colors, fonts, and spacing that appear on multiple pages are weighted higher. Page-specific patterns are discounted.
How does drift monitoring work?
Run --save-baseline ./baseline.json once to snapshot your design. Then use --baseline ./baseline.json to compare against it. The tool flags new colors, new fonts, grid adherence drops, contrast regressions, and reduced-motion removal. A GitHub Action is included that runs on every push/PR.
Is this free?
Yes. MIT licensed. Fully open source. The LLM feature uses the Anthropic API which has its own pricing, but the core tool is free.
Educational and experimental use only This tool reads publicly visible content and computed styles from rendered web pages. No proprietary code or non-public information is accessed. No ownership of any product identity or brand is claimed. Users are responsible for compliance with applicable terms of service.