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
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.
color: #5e6ad2
font-size: 16px
transition: 0.2s ease
padding: 24px
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 philosophy
Minimal, disciplined, or expressive. Accent strategy. Monochrome ratio. Gradient policy.
Typography direction
Single/paired/multi typeface system. Scale ratio. Case patterns. Tracking rules.
Spacing philosophy
Grid detection and adherence. Whitespace stance. Density zones. Section rhythm.
Motion intent
Static, functional, or expressive. Duration constants. Easing rules. Reduced-motion.
Voice direction
Formality, perspective, CTA patterns. Active vs passive. Positive vs negative framing.
Component philosophy
Shape language. Elevation system. Border approach. Button tiers. Card consistency.
Layout direction
Hero style. Page narrative flow. Container rules. Alignment. Scroll depth.
Accessibility stance
Inclusive design vs compliance. Error recovery philosophy. Focus choreography.
Brand archetype
12 archetypes scored from weighted cross-module signals. Primary + secondary classification.
Cross-system rules
COLOR × TYPE. SPACE × MOTION. How systems interact. Change one, know what moves.
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.
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.
Everything built into v0.3.0. Each feature is independently tested, secured against XSS, and handles missing data gracefully.
Multi-page crawling
Crawl N pages. Converge patterns by cross-page frequency. System-level tokens weighted higher than page-specific.
LLM-powered inference
Send extracted data to Claude API. Heuristic rules are guardrails. The LLM writes the creative brief.
Design tokens
Semantic naming. CSS custom properties, Tailwind config, Style Dictionary. color-action, space-unit, font-display.
Decision trees
4 traversable trees for component, color, motion, spacing. Agents walk the tree for every choice.
Competitive positioning
Extract from multiple sites. Positioning map, differentiators, convergence warnings, comparison matrix.
Accessibility as direction
Not audit. Philosophy: inclusive design vs compliance. Error recovery. Focus choreography. Inclusion level.
Animation choreography
Stagger detection. Entrance/exit symmetry. Scroll behavior. Motion constants. Loop animation policy.
Content governance
Heading limits. Paragraph rules. Number formatting. Capitalization conventions. Terminology glossary.
Platform direction
React (exact Tailwind classNames). Email (safe font stacks). Mobile (touch targets, nav, gestures).
Drift monitoring
GitHub Action. Save baseline, detect drift on every deploy. New colors, broken grid, a11y regressions.
Visual hierarchy
Weight distribution. Primary action identification. Contrast ladder. Above-fold element audit.
Content formula
Problem-Solution, Feature-Proof, Feature-Led detection. Page arc mapping. Headline formula analysis.
Composition
Symmetry analysis. Full-bleed vs contained. Section alternation. Column usage. Vertical rhythm.
Iconography
Style (outlined/filled/duotone). Size consistency. Labeling strategy (labeled/icon-only).
Imagery philosophy
Treatment (rounded/sharp). Placement patterns. Overlay rules. Decorative vs content classification.
Micro-interactions
Button hover philosophy. Link hover. Focus transitions. Hover completeness audit.
Error / empty / loading
Error tone (apologetic/instructive/direct). Empty state type. Loading pattern (skeleton/spinner).
Creative brief
Prose, not data dump. "You're building for a brand that..." not "COLOR: minimal. VOICE: conversational."
Brand archetype
12 archetypes (Sage, Creator, Ruler, Hero...) classified from weighted signals across all modules.
Specific guardrails
"Use accent on one element per viewport" not "be consistent." Do's and don'ts from actual inference.
Install
Usage
# 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
| Flag | Purpose | Default |
|---|---|---|
--depth <n> | Crawl N internal pages for accuracy | 1 |
--llm | Claude API creative brief (needs ANTHROPIC_API_KEY) | off |
--tokens | Output CSS + Tailwind + Style Dictionary tokens | off |
--compare <url> | Competitive positioning analysis | — |
--baseline <path> | Check drift against saved baseline | — |
--save-baseline | Save current extraction as baseline | — |
--json | Output raw inference data | off |
-o <path> | Output file path | ./DIRECTION.md |
Programmatic API
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
What does directionmd actually extract?
How is this different from a design token extractor?
Does the LLM feature require an API key?
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?
--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?
--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.