Architecture

The CSEdge Portfolio DevKit is built around a zero-abstraction, native-first philosophy. Every design decision is intentional and tuned for developer velocity, AI compatibility, and long-term maintainability.

Core Layers

The platform is structured into four independent layers that compose seamlessly:

Design Tokens

CSS custom properties in globals.css define the entire visual language — spacing, radii, colors, and typography scales.

UI Primitives

Atomic components (Button, Card, Badge) are pure HTML+CSS with no runtime dependencies.

Template Engine

Templates are TypeScript functions that render complete HTML strings — zero framework lock-in.

CLI Tooling

The csedge CLI orchestrates scaffolding, component injection, and template selection from a terminal.

Directory Structure

A typical scaffolded project looks like this:

my-portfolio/
├── app/
│   ├── layout.tsx         # Root layout with theme/font providers
│   ├── page.tsx           # Landing page
│   └── docs/              # Optional docs if using the full platform
├── components/
│   ├── ui/                # Primitive components (Button, Card, Badge…)
│   └── sections/          # Page-level sections (Hero, About, Projects…)
├── styles/
│   ├── globals.css        # Design tokens & CSS reset
│   └── csedge-ui.css      # Auto-generated from `csedge add ui all`
├── templates/             # HTML-string template generators
├── bin/
│   └── csedge.mjs         # CLI entry point
└── csedge.json            # Configuration (theme, output paths, TS flag)

Template Engine

Templates in this devkit are pure TypeScript functions that receive structured data and return complete HTML strings. This means:

Templates are framework-agnostic — they run in Node.js, Edge runtime, or any JS environment
No virtual DOM, no hydration costs, no client-side JavaScript required for rendering
AI agents can reason about the full output because it's plain HTML
CSS is co-located with the template as an embedded <style> block

// templates/minimal.ts
export const minimalTemplate = (
  name: string,
  about: string,
  projects: Project[],
  theme: ThemeConfig
): string => {
  return `<!DOCTYPE html>
  <html lang="en">
    <head>
      <style>/* scoped CSS */</style>
    </head>
    <body><!-- semantic HTML --></body>
  </html>`;
};

CSS Variable System

All theming is powered by a single set of CSS custom properties. Dark/light mode is handled by toggling a data-theme attribute on the <html> element — no JavaScript class toggling required.

:root {
  --background: 0 0% 100%;
  --foreground: 222 84% 5%;
  --card: 0 0% 98%;
  --primary: 222 84% 5%;
  --secondary: 210 40% 96%;
  --muted-foreground: 215 16% 47%;
  --border: 214 32% 91%;
  --radius: 0.5rem;
}

[data-theme="dark"] {
  --background: 222 84% 5%;
  --foreground: 210 40% 98%;
  /* ... inverted values */
}

Design Principles

Zero Runtime Dependencies — No lodash, no moment, no class-variance-authority
Semantic HTML First — Every element is meaningful to screen readers and crawlers
CSS Modules Isolation — No global class conflicts, ever
TypeScript Native — Full type safety from the template data layer to the CLI flags
AI-Compatible ASTs — Minimal nesting depth for LLM context efficiency

Ready to dive into templates? Check out the Template Gallery or explore AI Integration for agent workflows.