Architecture

Understand how IntentCSS is structured internally and how prompts move through the generation pipeline.

Overview

IntentCSS is built around a modular architecture.

Each responsibility is isolated into its own component:

  • CLI
  • Parser
  • NLP Layer
  • Typo Correction
  • Confidence System
  • Intent Engine
  • Generators

This design makes the project easy to maintain, extend, and test.

High-Level Flow

TEXT
User Prompt
     │
     ▼
CLI
     │
     ▼
Typo Correction
     │
     ▼
Prompt Parser
     │
     ▼
NLP Extraction
     │
     ▼
Confidence Scoring
     │
     ▼
Intent Engine
     │
     ▼
Generator
     │
     ▼
Output

Example:

BASH
intentcss generate --prompt "large red button"

becomes:

TEXT
Intent:
  button

Modifiers:
  large
  red

Output:
  rounded-lg bg-red-600 px-6 py-3 text-lg text-white hover:bg-red-700

Project Structure

Current project layout:

TEXT
intentcss/
│
├── src/
│   ├── cli.ts
│   ├── engine.ts
│   ├── parser.ts
│   ├── nlp.ts
│   ├── typo.ts
│   ├── confidence.ts
│   ├── generator.ts
│   │
│   ├── intents/
│   │   ├── button.ts
│   │   ├── card.ts
│   │   ├── form.ts
│   │   ├── navbar.ts
│   │   ├── modal.ts
│   │   ├── sidebar.ts
│   │   ├── hero.ts
│   │   ├── footer.ts
│   │   └── index.ts
│   │
│   └── utils/
│       └── normalize.ts
│
├── tests/
│   ├── button.test.ts
│   ├── typo.test.ts
│   └── engine.test.ts
│
├── types/
│   ├── Intent.ts
│   ├── Parser.ts
│   ├── Generator.ts
│   └── Config.ts
│
└── dist/

CLI Layer

File:

TEXT
src/cli.ts

Responsibilities:

  • Parse command-line arguments
  • Execute commands
  • Display output
  • Handle errors

Example:

BASH
intentcss generate --prompt "blue button"

The CLI forwards the prompt into the generation pipeline.

Typo Correction

File:

TEXT
src/typo.ts

Responsibilities:

  • Detect misspelled words
  • Match known vocabulary
  • Correct prompts before parsing

Example:

TEXT
purpl buton

becomes:

TEXT
purple button

Parser

File:

TEXT
src/parser.ts

Responsibilities:

  • Normalize prompts
  • Split text into tokens
  • Extract structured data

Input:

TEXT
large red button

Output:

TS
{
  tokens: [
    "large",
    "red",
    "button"
  ]
}

NLP Layer

File:

TEXT
src/nlp.ts

Responsibilities:

  • Extract meaningful words
  • Ignore filler language
  • Improve intent detection

Example:

TEXT
make me a beautiful red button

Important words:

TEXT
beautiful
red
button

Confidence System

File:

TEXT
src/confidence.ts

Responsibilities:

  • Evaluate prompt quality
  • Score intent matches
  • Prevent invalid generation

Possible results:

TEXT
High
Medium
Low

Intent Engine

File:

TEXT
src/engine.ts

Responsibilities:

  • Match prompts to intents
  • Rank possible matches
  • Select the best generator

Example:

TEXT
button

resolves to:

TEXT
ButtonIntent

Intent Definitions

Directory:

TEXT
src/intents/

Each component is represented by its own intent.

Example:

TEXT
button.ts
card.ts
form.ts
navbar.ts
modal.ts
sidebar.ts
hero.ts
footer.ts

Each intent defines:

  • Name
  • Aliases
  • Keywords
  • Generator logic

Example:

TS
export const ButtonIntent = {
  name: "button",
  aliases: ["button", "btn"],
  keywords: ["button", "click"],
  generate() {}
};

Generator Layer

File:

TEXT
src/generator.ts

Responsibilities:

  • Produce Tailwind output
  • Produce CSS output
  • Format final responses

Supported targets:

TEXT
tailwind
css

Example:

BASH
intentcss generate --prompt "red button"

Tailwind:

TEXT
bg-red-600

CSS:

CSS
background-color: #dc2626;

Utility Layer

Directory:

TEXT
src/utils/

Contains reusable helper functions.

Current examples:

TEXT
normalize.ts

Responsibilities:

  • String normalization
  • Shared transformations
  • Internal helpers

Type System

Directory:

TEXT
types/

Contains shared TypeScript contracts.

Examples:

TEXT
Intent.ts
Generator.ts
Parser.ts
Config.ts

Benefits:

  • Strong typing
  • Better IDE support
  • Safer refactoring

Testing Architecture

Directory:

TEXT
tests/

Current test coverage:

TEXT
button.test.ts
engine.test.ts
typo.test.ts

Tests verify:

  • Intent generation
  • Typo correction
  • Engine behavior
  • Output consistency

Example:

BASH
npm test

Design Principles

IntentCSS follows several architectural goals.

Modular

Each feature lives in its own file.

Extensible

New intents can be added without modifying the engine.

Predictable

The same prompt should always generate the same result.

Testable

Core systems can be tested independently.

Lightweight

No unnecessary runtime complexity.

Future Architecture

Planned future additions include:

  • Plugin system
  • Custom intent loading
  • AI-assisted prompt suggestions
  • Visual preview engine
  • Configuration files
  • Framework integrations

Next Steps

Continue with:

  • Testing
  • Contributing
  • Development Guide
  • Supported Intents